/*
* 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_ */