exhale Wiki :: Application Programming Interface (API)
The following is a description of the public C/C++ functions exported by the exhale library for use by external applications, representing exhale's application programming interface (API). These functions are described in the order in which they must be called. The exact function and ExhaleEncAPI class prototypes are declared in the header file exhaleDecl.h provided in the include subdirectory of the exhale source distribution.
ExhaleEncAPI* exhaleCreate()
C declaration
ExhaleEncAPI* exhaleCreate(int32_t* const inputPcmData, unsigned char* const outputAuData, const unsigned sampleRate, const unsigned numChannels, const unsigned frameLength, const unsigned indepPeriod, const unsigned varBitRateMode, const bool useNoiseFilling, const bool useEcodisExt);
C++ class declaration
none (class constructor)
Purpose
create an ExhaleEncAPI object and return a pointer to it. The following parameters are available for configuration of the encoder instance:
- inputPcmData: pointer to a signed 32-bit integer buffer from which the uncompressed, unpacked, channel-interleaved, 24-bit PCM audio data (sample value range -8388608..8388607, one sample value per integer value) will be read.
- outputAuData: pointer to an unsigned 8-bit integer buffer to which the compressed access unit (AU, raw frame-wise encoded audio) data will be written by the encoder. The buffer must be at least (6144/8)*numChannels bytes large.
- sampleRate: audio input and output sampling rate in Hertz (Hz). Note that not all sampling rates are supported. Recommended rates are 96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, and 7350.
- numChannels: number of channels in the input PCM audio data. Must be between 1 (mono) and 8 (7.1 surround), or 0 to indicate two-channel input which will be encoded channel-independently in dual-mono two-SCE configuration.
- frameLength: number of audio samples per channel and encoded frame. Must equal 1024 in exhale 1.0.x. Since exhale 1.1.0: Passing 2048 results in encoding with 2:1 Spectral Band Replication (SBR) enabled.
- indepPeriod: random-access (also called "tune-in") period for broadcasting and streaming purposes, particularly when the audio is accompanied by video. Recommended values are 45 with 25 or 50-Hz video (Europe, Asia) and 50 with 30 or 60-Hz video (North America).
- varBitRateMode: the CVBR mode controlling the overall bit-rate. See the FAQ for details. Must be between 0 (lowest rate) and 9 (highest rate). Note that mode 0 is not intended for content production, use it only for scientific research.
- useNoiseFilling: enable (true) or disable (false) the noise substitution functionality provided by the ISO/IEC 23003-3 standard. It is recommended to enable this feature for best possible audio quality especially at the low bit-rate modes.
- useEcodisExt: additional, reserved parameter for future use. Currently ignored, should be set to false.
Return value
the pointer to the newly created ExhaleEncAPI object
unsigned exhaleInitEncoder()
C declaration
unsigned exhaleInitEncoder(ExhaleEncAPI* exhaleEnc, unsigned char* const audioConfigBuffer, uint32_t* const audioConfigBytes);
C++ class declaration
unsigned ExhaleEncAPI::initEncoder(unsigned char* const audioConfigBuffer, uint32_t* const audioConfigBytes = NULL);
Purpose
initialize an ExhaleEncAPI object for encoding and allocate dynamic object memory. Also checks the validity of the parameters given to exhaleCreate() and, upon success, generates AudioSpecificConfig (ASC, including UsacConfig) data for the bit-stream header. The following parameters are available for storage of this data:
- audioConfigBuffer: pointer to an unsigned 8-bit integer buffer to which the ASC data will be written. The buffer must be at least 16 bytes large. May be
NULL, in which case no ASC is generated. - audioConfigBytes: pointer to a single unsigned 32-bit integer to which the byte-size of the ASC data is written. Optional parameter, may be
NULL, in which case the size information is discarded.
Since exhale 1.0.1: If, when calling this function, the integer pointed to by audioConfigBytes is nonzero, that integer is interpreted as program loudnessInfo payload according to ISO/IEC 23003-4, Dynamic Range Control (DRC), and included in the UsacConfig data generated by this function. The bits of the nonzero integer pointed to by audioConfigBytes are interpreted as follows:
| Bit Offset | Number of Bits | Syntax Element (Specification Table in ISO/IEC 23003-4) |
|---|---|---|
| 31-30 | 2 | not used, should equal 0 |
| 29-18 | 12 | bsSamplePeakLevel, peak level of audio program (Table A.46) |
| 17-14 | 4 | methodDefinition, must be between 1 and 9 (Table A.49) |
| 13-6 | 8 | methodValue, loudness level of audio program (Table A.48) |
| 5-2 | 4 | measurementSystem, must be between 1 and 6 (Table A.50) |
| 1-0 | 2 | reliability, should equal 3, should not equal 0 (Table A.51) |
Return value
zero (0) upon success, or nonzero (1-255 or 65535) in case of an error or if the exhaleEnc pointer is NULL
unsigned exhaleEncodeLookahead()
C declaration
unsigned exhaleEncodeLookahead(ExhaleEncAPI* exhaleEnc);
C++ class declaration
unsigned ExhaleEncAPI::encodeLookahead( );
Purpose
encode the first (lookahead) frame with an ExhaleEncAPI object. Requires frameLength*numChannels new audio samples in inputPcmData, returns the AU in outputAuData (see exhaleCreate()).
Return value
the byte-size (2 < b < 65535) of the AU upon success, or nonzero (1, 2 or 65535) in case of an error or if the exhaleEnc pointer is NULL
unsigned exhaleEncodeFrame()
C declaration
unsigned exhaleEncodeFrame(ExhaleEncAPI* exhaleEnc);
C++ class declaration
unsigned ExhaleEncAPI::encodeFrame( );
Purpose
encode a regular PCM audio frame with an ExhaleEncAPI object. Requires frameLength*numChannels new audio samples in inputPcmData, returns the AU in outputAuData (see exhaleCreate()).
Return value
the byte-size (2 < b < 65535) of the AU upon success, or nonzero (1, 2 or 65535) in case of an error or if the exhaleEnc pointer is NULL
unsigned exhaleDelete()
C declaration
unsigned exhaleDelete(ExhaleEncAPI* exhaleEnc);
C++ class declaration
ExhaleEncAPI::~ExhaleEncAPI( ); (class destructor)
Purpose
free all dynamic memory allocated by an ExhaleEncAPI object. After calling this function, the exhaleEnc pointer can be set to NULL or the return value of a new call to exhaleCreate().
Return value
zero (0) upon success, or nonzero (65535) if the exhaleEnc pointer is NULL