You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
164 lines
7.1 KiB
164 lines
7.1 KiB
/*
|
|
* 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_ */
|
|
|