• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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