xref: /aosp_15_r20/external/libldac/abr/inc/ldacBT_abr.h (revision aef9bcd9217ad2365ebc8e70efaf94b64e04df14)

/*
 * Copyright (C) 2014 - 2017 Sony Corporation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _LDACBT_ABR_H_
#define _LDACBT_ABR_H_

/* This file contains the definitions, declarations and macros for an implementation of
 * LDAC Adaptive Bit Rate (hereinafter ABR) processing.
 *
 * The basic flow of the ABR processing is as follows:
 * - The program creates a handle of LDAC ABR API using ldac_ABR_get_handle().
 * - The program initializes the handle by setting the ldac_ABR_Proc() call interval to
 *   ldac_ABR_Init().
 *       The interval shall be as short as possible at the timing without accumulation
 *       of packet in the buffer if propagation environment is fine.
 * - The program reinitializes the handle by calling ldac_ABR_Init() again when the
 *   state of the TX queue changes greatly, such as clearing the queue.
 * - If the program demands to control the thresholds, then ldac_ABR_set_thresholds()
 *   should be called.
 * - The program sets flagEnable to "1" when allowing LDAC encode bitrate to be
 *   adjusted by ABR, and sets it to "0" if it is not allowed.
 * - The program calls ldac_ABR_Proc() at the interval set to ldac_ABR_Init() even if
 *   flagEnable is "0".
 *       The program passes TxQueueDepth and flagEnable to ldac_ABR_Proc() at this call,
 *       LDAC encode bitrate is adjusted only when flagEnable is "1".
 *       Otherwise, the internal parameters are updated and analyzed then returned.
 *       The ABR handle adjusts eqmid based on TxQueueDepth which is passed from the program.
 *       The ABR handle calls LDAC encode API ldacBT_alter_eqmid_priority() to adjust eqmid.
 *       The ABR handle calls LDAC encode API ldacBT_get_eqmid() to get current eqmid.
 * - The handle may be released with ldac_ABR_free_handle().
 *
 * Notes on debugging LDAC ABR:
 * The meaning of "works fine" is that the bit rate will be low in case of bad radio situation
 * and high in case of good radio situation.
 *
 * The bit rate transition can be debug by checking logcat messages from LDAC ABR library which
 * built with the following changes in Android.bp:
 *  - Adding "liblog" to shared_libs.
 *  - Adding "-DLOCAL_DEBUG" to cflags.
 * The messages are formated as follows:
 *       [LDAC ABR] - abrQualityModeID : 0 -- eqmid : 0 -- TxQue : 0
 *     where abrQualityModeID and eqmid related to the current bit rate and TxQue shows the depth
 *     of current Tx queue.
 *     The relationship between abrQualityModeID, eqmid and the bit rate is described in
 *     "ldacBT_abr.c".
 *
 * The bit rate transition can be estimated/debug by listening to the audio played on the SNK
 * device. This method cannot use to confirm the details of the bit rate transition, but useful
 * to know how LDAC ABR algorithm works in a field test without checking the log.
 * To try this method, rebuilding of the "libldacBT_enc" library with the following change in
 * Android.bp is required:
 *  - Adding "-DUSE_LDAC_ENC_SETTING_FOR_ABR_DEBUG" to cflags.
 * By defining the above macro, the lower the bit rate, the greatly lower the bandwidth of the audio
 * played on the SNK device. Therefore, the audio played on the SNK device will sounds like a
 * low-pass filtered sound when the bit rate is low and will sounds as usual when the bit rate is
 * enough high. It is recommend using sound such as white noise to hear those changes for the first
 * time.
 *
 * IMPORTANT:
 * These libraries modified as described above shall be used only to confirm the bit rate transition
 * and SHALL NOT BE USED FOR FINAL PRODUCTS.
 */

#ifdef __cplusplus
extern "C" {
#endif

#ifndef LDAC_ABR_API
#define LDAC_ABR_API
#endif /* LDAC_ABR_API */

#include <ldacBT.h> /* HANDLE_LDAC_BT */

/* LDAC ABR handle type*/
typedef struct _ldacbt_abr_param * HANDLE_LDAC_ABR;

/* Allocation of LDAC ABR handle.
 *  Format
 *      HANDLE_LDAC_ABR  ldacBT_get_handle( void );
 *  Arguments
 *      None.
 *  Return value
 *      HANDLE_LDAC_ABR for success, NULL for failure.
 */
LDAC_ABR_API HANDLE_LDAC_ABR ldac_ABR_get_handle(void);

/* Release of LDAC ABR handle.
 *  Format
 *      void  ldac_ABR_free_handle( HANDLE_LDAC_ABR );
 *  Arguments
 *      hLdacAbr    HANDLE_LDAC_ABR    LDAC ABR handle.
 *  Return value
 *      None.
 */
LDAC_ABR_API void ldac_ABR_free_handle(HANDLE_LDAC_ABR hLdacAbr);

/* Initialize LDAC ABR.
 *  Format
 *      int  ldac_ABR_Init( HANDLE_LDAC_ABR, unsigned int );
 *  Arguments
 *      hLdacAbr        HANDLE_LDAC_ABR    LDAC ABR handle.
 *      interval_ms     unsigned int       interval in ms for calling ldac_ABR_Proc().
 *                                         interval of 1ms to 500ms is valid.
 *  Return value
 *      int: 0 for success, -1 for failure.
 */
LDAC_ABR_API int ldac_ABR_Init(HANDLE_LDAC_ABR hLdacAbr, unsigned int interval_ms);

/* Setup thresholds for LDAC ABR.
 *  Format
 *      int ldac_ABR_set_thresholds( HANDLE_LDAC_ABR, unsigned int, unsigned int, unsigned int );
 *  Arguments
 *      hLdacAbr            HANDLE_LDAC_ABR  LDAC ABR handle.
 *      thCritical          unsigned int     threshold for critical TxQueueDepth status.
 *      thDangerousTrend    unsigned int     threshold for dangerous trend of TxQueueDepth.
 *      thSafety4HQSQ       unsigned int     safety threshold for LDACBT_EQMID_HQ and
 *                                           LDACBT_EQMID_SQ.
 *  Return value
 *      int: 0 for success, -1 for failure.
 *  Remarks
 *    Those thresholds should be the number of packets stored in the TX queue and should be
 *    greater than 0.
 *    The thCritical and thDangerousTrend are used for all eqmid and thSafety4HQSQ is used
 *    only for LDACBT_EQMID_HQ and LDACBT_EQMID_SQ. Therefore, those thresholds must satisfy
 *    the following releationship:
 *        thCritical >= thDangerousTrend >= thSafety4HQSQ
 */
LDAC_ABR_API int ldac_ABR_set_thresholds(HANDLE_LDAC_ABR hLdacAbr, unsigned int thCritical,
                                    unsigned int thDangerousTrend, unsigned int thSafety4HQSQ);

/* LDAC ABR main process.
 *  Format
 *      int  ldac_ABR_Proc( HANDLE_LDAC_BT, HANDLE_LDAC_ABR, unsigned int, unsigned int );
 *  Arguments
 *      hLdacBt        HANDLE_LDAC_BT    LDAC handle.
 *      hLdacAbr       HANDLE_LDAC_ABR   LDAC ABR handle.
 *      TxQueueDepth   unsigned int      depth of TX queue.
 *      flagEnable     unsigned int      flag indicating whether ABR is allowed to adjust LDAC
 *                                       encode bitrate
 *  Return value
 *      int: updated Encode Quality Mode Index for success, -1 for failure.
 */
LDAC_ABR_API int ldac_ABR_Proc(HANDLE_LDAC_BT hLdacBt, HANDLE_LDAC_ABR hLdacAbr,
                                 unsigned int TxQueueDepth, unsigned int flagEnable);
#ifdef __cplusplus
}
#endif

#endif /* _LDACBT_ABR_H_ */