Block audio encoder interface. More...

#include <BlockAudioEncoderInterface.h>

Inheritance diagram for alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface:

Public Types
using	Byte = unsigned char
	Byte data type. More...

using	Bytes = std::vector< Byte >
	Byte array data type for encoding output. More...

Public Member Functions
virtual bool	init (avsCommon::utils::AudioFormat inputFormat)=0
	Pre-initialize the encoder. More...

virtual size_t	getInputFrameSize ()=0

virtual size_t	getOutputFrameSize ()=0
	Provide maximum output frame size. More...

virtual bool	requiresFullyRead ()=0
	Return if input must contain full frame. More...

virtual avsCommon::utils::AudioFormat	getAudioFormat ()=0
	Return output audio format. More...

virtual std::string	getAVSFormatName ()=0
	AVS format name for encoded audio. More...

virtual bool	start (Bytes &preamble)=0
	Start the encoding session. More...

virtual bool	processSamples (Bytes::const_iterator begin, Bytes::const_iterator end, Bytes &buffer)=0
	Encode a block of audio. More...

virtual bool	flush (Bytes &buffer)=0
	Flush buffered data if any. More...

virtual void	close ()=0
	Close encoding session. More...

virtual	~BlockAudioEncoderInterface ()=default

Detailed Description

Block audio encoder interface.

Block audio encoder provides a generic interface for converting audio stream data. The encoding is performed within a session that is started with init() call and ends with close().

After initialization block audio encoding has the following stages:

start operation to generate encoded data prologue.
sequential encoding operations to encode input and generated encoded output.
flush operation to generate encoded data epilogue.

auto encoder = ...
encoder->init(inputAudioFormat);
...
encoder->start(outputBuffer);
writeOutputData(outputBuffer);
while (hasMoreData()) {
  encoder->processSamples(inputData, inputDataSize, outputBuffer);
  writeOutputData(outputBuffer);
}
encoder->flush(outputBuffer);
writeOutputData(outputBuffer);
encoder->close();

After call to close() the encoder instance can be reused for another encoding operation.

See also: AudioEncoderInterface

Member Typedef Documentation

◆ Byte

using alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::Byte = unsigned char

Byte data type.

◆ Bytes

using alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::Bytes = std::vector<Byte>

Byte array data type for encoding output.

Constructor & Destructor Documentation

◆ ~BlockAudioEncoderInterface()

virtual alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::~BlockAudioEncoderInterface ( )

virtualdefault

Destructor.

Member Function Documentation

◆ close()

virtual void alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::close ( )

pure virtual

Close encoding session.

Notify end of the session. Any backend library then may be deinitialized so it cleans memory and threads.

◆ flush()

virtual bool alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::flush ( Bytes & buffer )

pure virtual

Flush buffered data if any.

This method appends any encoded data to buffer.

Parameters

[out] buffer Buffer for appending data. The buffer contents is not modified on error.

Returns: true when success.

◆ getAudioFormat()

virtual avsCommon::utils::AudioFormat alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::getAudioFormat ( )

pure virtual

Return output audio format.

Method returns AudioFormat that describes encoded output.

Note: The number of channels in the resulting format is known only after encoding operation has started.

Returns: The AudioFormat describes the encoded audio stream.

◆ getAVSFormatName()

virtual std::string alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::getAVSFormatName ( )

pure virtual

AVS format name for encoded audio.

Method returns string interpretation of the output format, that AVS cloud service can recognize.

Returns: Output format string.

See also: https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/speechrecognizer.html#recognize

◆ getInputFrameSize()

virtual size_t alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::getInputFrameSize ( )

pure virtual

The maximum number of sample can be processed at the same time. In other words, this will limit input stream buffering. Thus number of samples of processSamples() call will never exceeds this limit.

Returns: The number of sample (in words).

◆ getOutputFrameSize()

virtual size_t alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::getOutputFrameSize ( )

pure virtual

Provide maximum output frame size.

The method provides an estimate for an output frame size in bytes. This value is used to allocate necessary buffer space in output audio stream.

Returns: The maximum output length (in bytes).

◆ init()

virtual bool alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::init ( avsCommon::utils::AudioFormat inputFormat )

pure virtual

Pre-initialize the encoder.

Pre-initialization before actual encoding session has began. Note that this function will be called everytime before new encoding session is starting.

Note: Encoder may change some output parameters after this call, and consumers should check getAVSFormatName() after calling this method.

Parameters

[in] inputFormat The AudioFormat describes the audio format of the future incoming PCM frames.

Returns: true when initialization success.

◆ processSamples()

virtual bool alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::processSamples	(	Bytes::const_iterator	begin,
		Bytes::const_iterator	end,
		Bytes &	buffer
	)

pure virtual

Encode a block of audio.

This method encodes a block of input audio samples. The samples are provided in a form of byte array restricted by begin and end iterator arguments. The input bytes must represent complete samples, and each sample size is be known via AudioFormat used with init() call. If requiresFullyRead() returns true, the number of samples must be equal to getInputFrameSize(). If requiresFullyRead() returns false, the number of samples must be greater then zero and not more than getInputFrameSize().

This method can be called any number of times after start() has been called.

Parameters

[in]	begin	Bytes iterator for the first byte of samples. This parameter must be less then end, or the method will fail with an error.
[in]	end	Bytes iterator for the end of sample array. This parameter must be greater then begin, or the method will fail with an error.
[out]	buffer	Output buffer for encoded data.

Returns: true when success.

◆ requiresFullyRead()

virtual bool alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::requiresFullyRead ( )

pure virtual

Return if input must contain full frame.

Determine whether input stream should be fully buffered with the maximum number of samples provided at getInputFrameSize() function. This value will change the behavior of how processSamples is called during the encoding session. This is useful when backend encoder requires fixed length of input samples.

In case the encoding session has been shutdown before the buffer is filled fully, this will cause any partial data to be discarded (e.g. AudioEncoderInterface::stopEncoding() has been called, or reaches the end of the data stream).

Returns: true if processSamples should be called with fixed length of input samples during the session.

◆ start()

virtual bool alexaClientSDK::audioEncoderInterfaces::BlockAudioEncoderInterface::start ( Bytes & preamble )

pure virtual

Start the encoding session.

This function starts a new encoding session after a call to init(). If block audio encoder produces some data, it can be returned through preamble buffer.

After the session is started, user can call processSamples() until session is closed with close() call.

Parameters

[out] preamble Destination buffer for encoding preamble output. The method will append preamble bytes to preamble if needed. On error preamble is not modified.

Returns: true when success.

The documentation for this class was generated from the following file:

/workplace/avs-device-sdk/core/AudioEncoder/AudioEncoderInterfaces/include/acsdk/AudioEncoderInterfaces/BlockAudioEncoderInterface.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Byte

◆ Bytes

Constructor & Destructor Documentation

◆ ~BlockAudioEncoderInterface()

Member Function Documentation

◆ close()

◆ flush()

◆ getAudioFormat()

◆ getAVSFormatName()

◆ getInputFrameSize()

◆ getOutputFrameSize()

◆ init()

◆ processSamples()

◆ requiresFullyRead()

◆ start()