1 /* 2 * Copyright (C) 2014 - 2017 Sony Corporation 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef _LDACBT_ABR_H_ 18 #define _LDACBT_ABR_H_ 19 20 /* This file contains the definitions, declarations and macros for an implementation of 21 * LDAC Adaptive Bit Rate (hereinafter ABR) processing. 22 * 23 * The basic flow of the ABR processing is as follows: 24 * - The program creates a handle of LDAC ABR API using ldac_ABR_get_handle(). 25 * - The program initializes the handle by setting the ldac_ABR_Proc() call interval to 26 * ldac_ABR_Init(). 27 * The interval shall be as short as possible at the timing without accumulation 28 * of packet in the buffer if propagation environment is fine. 29 * - The program reinitializes the handle by calling ldac_ABR_Init() again when the 30 * state of the TX queue changes greatly, such as clearing the queue. 31 * - If the program demands to control the thresholds, then ldac_ABR_set_thresholds() 32 * should be called. 33 * - The program sets flagEnable to "1" when allowing LDAC encode bitrate to be 34 * adjusted by ABR, and sets it to "0" if it is not allowed. 35 * - The program calls ldac_ABR_Proc() at the interval set to ldac_ABR_Init() even if 36 * flagEnable is "0". 37 * The program passes TxQueueDepth and flagEnable to ldac_ABR_Proc() at this call, 38 * LDAC encode bitrate is adjusted only when flagEnable is "1". 39 * Otherwise, the internal parameters are updated and analyzed then returned. 40 * The ABR handle adjusts eqmid based on TxQueueDepth which is passed from the program. 41 * The ABR handle calls LDAC encode API ldacBT_alter_eqmid_priority() to adjust eqmid. 42 * The ABR handle calls LDAC encode API ldacBT_get_eqmid() to get current eqmid. 43 * - The handle may be released with ldac_ABR_free_handle(). 44 * 45 * Notes on debugging LDAC ABR: 46 * The meaning of "works fine" is that the bit rate will be low in case of bad radio situation 47 * and high in case of good radio situation. 48 * 49 * The bit rate transition can be debug by checking logcat messages from LDAC ABR library which 50 * built with the following changes in Android.bp: 51 * - Adding "liblog" to shared_libs. 52 * - Adding "-DLOCAL_DEBUG" to cflags. 53 * The messages are formated as follows: 54 * [LDAC ABR] - abrQualityModeID : 0 -- eqmid : 0 -- TxQue : 0 55 * where abrQualityModeID and eqmid related to the current bit rate and TxQue shows the depth 56 * of current Tx queue. 57 * The relationship between abrQualityModeID, eqmid and the bit rate is described in 58 * "ldacBT_abr.c". 59 * 60 * The bit rate transition can be estimated/debug by listening to the audio played on the SNK 61 * device. This method cannot use to confirm the details of the bit rate transition, but useful 62 * to know how LDAC ABR algorithm works in a field test without checking the log. 63 * To try this method, rebuilding of the "libldacBT_enc" library with the following change in 64 * Android.bp is required: 65 * - Adding "-DUSE_LDAC_ENC_SETTING_FOR_ABR_DEBUG" to cflags. 66 * By defining the above macro, the lower the bit rate, the greatly lower the bandwidth of the audio 67 * played on the SNK device. Therefore, the audio played on the SNK device will sounds like a 68 * low-pass filtered sound when the bit rate is low and will sounds as usual when the bit rate is 69 * enough high. It is recommend using sound such as white noise to hear those changes for the first 70 * time. 71 * 72 * IMPORTANT: 73 * These libraries modified as described above shall be used only to confirm the bit rate transition 74 * and SHALL NOT BE USED FOR FINAL PRODUCTS. 75 */ 76 77 #ifdef __cplusplus 78 extern "C" { 79 #endif 80 81 #ifndef LDAC_ABR_API 82 #define LDAC_ABR_API 83 #endif /* LDAC_ABR_API */ 84 85 #include <ldacBT.h> /* HANDLE_LDAC_BT */ 86 87 /* LDAC ABR handle type*/ 88 typedef struct _ldacbt_abr_param * HANDLE_LDAC_ABR; 89 90 /* Allocation of LDAC ABR handle. 91 * Format 92 * HANDLE_LDAC_ABR ldacBT_get_handle( void ); 93 * Arguments 94 * None. 95 * Return value 96 * HANDLE_LDAC_ABR for success, NULL for failure. 97 */ 98 LDAC_ABR_API HANDLE_LDAC_ABR ldac_ABR_get_handle(void); 99 100 /* Release of LDAC ABR handle. 101 * Format 102 * void ldac_ABR_free_handle( HANDLE_LDAC_ABR ); 103 * Arguments 104 * hLdacAbr HANDLE_LDAC_ABR LDAC ABR handle. 105 * Return value 106 * None. 107 */ 108 LDAC_ABR_API void ldac_ABR_free_handle(HANDLE_LDAC_ABR hLdacAbr); 109 110 /* Initialize LDAC ABR. 111 * Format 112 * int ldac_ABR_Init( HANDLE_LDAC_ABR, unsigned int ); 113 * Arguments 114 * hLdacAbr HANDLE_LDAC_ABR LDAC ABR handle. 115 * interval_ms unsigned int interval in ms for calling ldac_ABR_Proc(). 116 * interval of 1ms to 500ms is valid. 117 * Return value 118 * int: 0 for success, -1 for failure. 119 */ 120 LDAC_ABR_API int ldac_ABR_Init(HANDLE_LDAC_ABR hLdacAbr, unsigned int interval_ms); 121 122 /* Setup thresholds for LDAC ABR. 123 * Format 124 * int ldac_ABR_set_thresholds( HANDLE_LDAC_ABR, unsigned int, unsigned int, unsigned int ); 125 * Arguments 126 * hLdacAbr HANDLE_LDAC_ABR LDAC ABR handle. 127 * thCritical unsigned int threshold for critical TxQueueDepth status. 128 * thDangerousTrend unsigned int threshold for dangerous trend of TxQueueDepth. 129 * thSafety4HQSQ unsigned int safety threshold for LDACBT_EQMID_HQ and 130 * LDACBT_EQMID_SQ. 131 * Return value 132 * int: 0 for success, -1 for failure. 133 * Remarks 134 * Those thresholds should be the number of packets stored in the TX queue and should be 135 * greater than 0. 136 * The thCritical and thDangerousTrend are used for all eqmid and thSafety4HQSQ is used 137 * only for LDACBT_EQMID_HQ and LDACBT_EQMID_SQ. Therefore, those thresholds must satisfy 138 * the following releationship: 139 * thCritical >= thDangerousTrend >= thSafety4HQSQ 140 */ 141 LDAC_ABR_API int ldac_ABR_set_thresholds(HANDLE_LDAC_ABR hLdacAbr, unsigned int thCritical, 142 unsigned int thDangerousTrend, unsigned int thSafety4HQSQ); 143 144 /* LDAC ABR main process. 145 * Format 146 * int ldac_ABR_Proc( HANDLE_LDAC_BT, HANDLE_LDAC_ABR, unsigned int, unsigned int ); 147 * Arguments 148 * hLdacBt HANDLE_LDAC_BT LDAC handle. 149 * hLdacAbr HANDLE_LDAC_ABR LDAC ABR handle. 150 * TxQueueDepth unsigned int depth of TX queue. 151 * flagEnable unsigned int flag indicating whether ABR is allowed to adjust LDAC 152 * encode bitrate 153 * Return value 154 * int: updated Encode Quality Mode Index for success, -1 for failure. 155 */ 156 LDAC_ABR_API int ldac_ABR_Proc(HANDLE_LDAC_BT hLdacBt, HANDLE_LDAC_ABR hLdacAbr, 157 unsigned int TxQueueDepth, unsigned int flagEnable); 158 #ifdef __cplusplus 159 } 160 #endif 161 162 #endif /* _LDACBT_ABR_H_ */ 163 164