# Audio stream **Detailed Description** This section contains APIs related to Audio Stream operation. - *group* Telematics\_audio\_stream - Typedefs - using ChannelTypeMask = int - Describes the arrangment of audio samples in a given audio frame through ChannelType. - using GetStreamDeviceResponseCb = std::function<void(std::vector<DeviceType> devices, telux::common::ErrorCode error)> - Invoked to pass the list of the audio devices associated with the stream. Used in conjunction with IAudioStream::getDevice(). - Param devices: - **[in]** List of the devices - Param error: - **[in]** telux::common::ErrorCode::SUCCESS if the device list is is sent successfully, otherwise, an appropriate error code - using GetStreamVolumeResponseCb = std::function<void(StreamVolume volume, telux::common::ErrorCode error)> - Invoked to pass the current volume level of the audio device. Used in conjunction with IAudioStream::getVolume(). - Param volume: - **[in]** Details of the volume - Param error: - **[in]** telux::common::ErrorCode::SUCCESS if the volume level is read successfully, otherwise, an appropriate error code - using GetStreamMuteResponseCb = std::function<void(StreamMute mute, telux::common::ErrorCode error)> - Invoked to pass the current mute state of the stream. Used in conjunction with IAudioStream::getMute(). - Param mute: - **[in]** Details about the mute state - Param error: - **[in]** telux::common::ErrorCode::SUCCESS if the mute state is read successfully, otherwise, an appropriate error code - using WriteResponseCb = std::function<void(std::shared\_ptr<IStreamBuffer> buffer, uint32\_t bytesWritten, telux::common::ErrorCode error)> - Used in conjunction with IAudioPlayStream::write(). Invoked to pass the audio data length (in bytes) played from the given buffer. Application can clear the contents of the buffer by calling IAudioBuffer::reset() before reusing it for the subsequent write operation. - Param buffer: - **[in]** Buffer passed in the call to IAudioPlayStream::write() - Param error: - **[in]** telux::common::ErrorCode::SUCCESS if the playback was successful, otherwise, an appropriate error code - using ReadResponseCb = std::function<void(std::shared\_ptr<IStreamBuffer> buffer, telux::common::ErrorCode error)> - Used in conjunction with IAudioCaptureStream::read(). Invoked to pass the captured audio samples. The IAudioBuffer::getDataSize() gives the length of the data (in bytes). After the samples have been processed by the application, it can clear the contents of the buffer by calling IAudioBuffer::reset(). - Param buffer: - **[in]** Buffer passed in the call to IAudioCaptureStream::read() - Param error: - **[in]** telux::common::ErrorCode::SUCCESS if the capture was successful, otherwise, an appropriate error code Enums - enum Direction - Used for an in-call playback/capture and HPCM use cases. Represents the direction of the audio data flow. *Values:* - enumerator RX - Indicates voice downlink path (cellular network to a device) - enumerator TX - Indicates voice uplink path (device to a cellular network) - enum ChannelType - Adds positional perspective to the audio data in a given audio frame. For example, in a 2-speaker audio system, ChannelType::LEFT may represent audio played on speaker-1 while ChannelType::RIGHT represents audio played on speaker-2. *Values:* - enumerator LEFT - Specifies the left channel - enumerator RIGHT - Specifies the right channel - enum AudioFormat - Specifies how audio data is represented (for example, endianness and number of bits) for storage or exchanging among various audio software and hardware layers. *Values:* - enumerator UNKNOWN - Default format (invalid) - enumerator PCM\_16BIT\_SIGNED - PCM signed 16 bits - enumerator AMRNB - Adaptive multirate narrow band format - enumerator AMRWB - Adaptive multirate wide band format - enumerator AMRWB\_PLUS - Extended adaptive multirate wide band format - enum DtmfLowFreq - When generating a DTMF tone, defines the value of the low frequency component. *Values:* - enumerator FREQ\_697 - 697 Hz - enumerator FREQ\_770 - 770 Hz - enumerator FREQ\_852 - 852 Hz - enumerator FREQ\_941 - 941 Hz - enum DtmfHighFreq - When generating a DTMF tone, defines the value of the high frequency component. *Values:* - enumerator FREQ\_1209 - 1209 Hz - enumerator FREQ\_1336 - 1336 Hz - enumerator FREQ\_1477 - 1477 Hz - enumerator FREQ\_1633 - 1633 Hz - enum StopType - Defines the behavior for how a compressed audio format playback should be finished. *Values:* - enumerator FORCE\_STOP - Stop playing immediately and discard all pending audio samples - enumerator STOP\_AFTER\_PLAY - Stop playing after all samples in the pipeline have been played - struct ChannelVolume - Defines the volume levels for a given audio channel. Public Members - ChannelType channelType - ChannelType to which the volume level is associated. - float vol - Volume level — minimum 0.0 and maximum 1.0 - struct StreamVolume - Defines the volume levels for the audio device. Public Members - std::vector<ChannelVolume> volume - List of the volume levels per channel, specified by ChannelVolume - StreamDirection dir - StreamDirection associated with the device - struct StreamMute - Specifies the mute state of the audio device. Public Members - bool enable - True if the device is muted, False if the device is unmuted - StreamDirection dir - StreamDirection associated with the device - struct DtmfTone - Defines the characteristics of the DTMF tone. Public Members - DtmfLowFreq lowFreq - Lower frequency associated with the DTMF tone - DtmfHighFreq highFreq - Higher frequency associated with the DTMF tone - StreamDirection direction - StreamDirection associated with the stream - class IVoiceListener : public telux::common::ISDKListener - Listener for a DTMF tone detected event on a StreamType::VOICE\_CALL stream. Public Functions - inline virtual void onDtmfToneDetection(DtmfTone dtmfTone) - Called when a DTMF tone is detected on a StreamType::VOICE\_CALL stream. Used in conjuction with IAudioVoiceStream::registerListener(). - Parameters: - **dtmfTone** – **[in]** Contains details of the tone detected - inline virtual ~IVoiceListener() - Destructor of the IVoiceListener. - class IPlayListener : public telux::common::ISDKListener - Listener for events on a playback stream. Public Functions - inline virtual void onReadyForWrite() - Called when the audio pipeline is ready to accept the next buffer to play during compressed playback. - inline virtual void onPlayStopped() - Called when the compressed playback has stopped. The stream should be deleted only after this has been called. - inline virtual ~IPlayListener() - Destructor of IPlayListener. - class IAudioBuffer - Represents the buffer containing the audio data for playback when used with the StreamType::PLAY stream. Represents the audio data received when used with the StreamType::CAPTURE stream. Subclassed by telux::audio::IStreamBuffer Public Functions - virtual size\_t getMinSize() = 0 - For the StreamType::PLAY stream, specifies the optimal number of bytes that must be sent for playback. For the StreamType::CAPTURE stream, specifies the optimal number of bytes that can be read. - Returns: - Optimal size (in bytes) - virtual size\_t getMaxSize() = 0 - For the StreamType::PLAY stream, specifies the maximum number of bytes that can be sent for playback. For the StreamType::CAPTURE stream, specifies the maximum number of bytes that can be read. - Returns: - Maximum size (in bytes) - virtual uint8\_t \*getRawBuffer() = 0 - Gives the managed raw buffer. It is freed when IAudioBuffer is destructed. For the StreamType::PLAY stream, the actual audio samples should be copied into this raw buffer for playback. For the StreamType::CAPTURE stream, the actual audio contents are obtained from this buffer. - Returns: - Managed raw buffer - virtual uint32\_t getDataSize() = 0 - For the StreamType::CAPTURE stream, specifies how many bytes were read. Not used for the StreamType::PLAY stream. - Returns: - Size of the valid data bytes in the raw buffer - virtual void setDataSize(uint32\_t size) = 0 - For the StreamType::PLAY stream, specifies how many bytes should be played. Not used for the StreamType::CAPTURE stream. - Returns: - Size of the valid data bytes in the raw buffer - virtual telux::common::Status reset() = 0 - Clears the contents of the managed raw buffer. - Returns: - telux::common::Status::SUCCESS if the buffer is cleared successfully, otherwise, an appropriate error code - inline virtual ~IAudioBuffer() - Destructor of the IAudioBuffer. - class IStreamBuffer : public virtual telux::audio::IAudioBuffer - Implements the IAudioBuffer interface to give contexual meaning to its methods based on the StreamType type associated with the stream, with which this buffer will be used. Public Functions - inline virtual ~IStreamBuffer() - Destructor of the IStreamBuffer. - class IAudioStream - Base class for all audio stream types. Contains the common properties and methods. Subclassed by telux::audio::IAudioCaptureStream, telux::audio::IAudioLoopbackStream, telux::audio::IAudioPlayStream, telux::audio::IAudioToneGeneratorStream, telux::audio::IAudioVoiceStream Public Functions - virtual StreamType getType() = 0 - Gets the StreamType associated with the stream. - Returns: - Type of the stream - virtual telux::common::Status setDevice(std::vector<DeviceType> devices, telux::common::ResponseCallback callback = nullptr) = 0 - Associates the given audio device with the stream. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. For StreamType::VOICE\_CALL, the stream must be started using IAudioVoiceStream::startAudio() to make the device effective. - Parameters: - - **devices** – **[in]** List of the audio devices to use with the stream - **callback** – **[in]** Optional, invoked to confirm if the device is associated - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status getDevice(GetStreamDeviceResponseCb callback = nullptr) = 0 - Gets the list of the audio devices associated with the stream. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. - Parameters: - **callback** – **[in]** Mandatory, invoked to pass the associated device - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status setVolume(StreamVolume volume, telux::common::ResponseCallback callback = nullptr) = 0 - Sets the volume level of the audio device. For StreamType::VOICE\_CALL and StreamType::PLAY, direction must be StreamDirection::RX. For StreamType::CAPTURE, direction must be StreamDirection::TX. If the stream was created with ChannelType::LEFT, ChannelType::LEFT must be specified in StreamVolume. If the stream was created with ChannelType::RIGHT, ChannelType::RIGHT must be specified in StreamVolume. If the stream contains both channels, both channels must be given in StreamVolume. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. - Parameters: - - **volume** – **[in]** Specifies the volume level and the stream’s direction - **callback** – **[in]** Optional, invoked to confirm if the volume level is set - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status getVolume(StreamDirection dir, GetStreamVolumeResponseCb callback = nullptr) = 0 - Gets the current volume level of the audio device. For StreamType::VOICE\_CALL and StreamType::PLAY, direction must be StreamDirection::RX. For StreamType::CAPTURE, direction must be StreamDirection::TX. If the stream was created with ChannelType::LEFT, ChannelType::LEFT must be specified in StreamVolume. If the stream was created with ChannelType::RIGHT, ChannelType::RIGHT must be specified in StreamVolume. If the stream contains both channels, both channels must be given in StreamVolume. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. - Parameters: - - **dir** – **[in]** Direction of the stream associated with the device - **callback** – **[in]** Mandatory, invoked to pass the volume read - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status setMute(StreamMute mute, telux::common::ResponseCallback callback = nullptr) = 0 - Mute or unmute the stream as specified by the StreamMute provided. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. For StreamType::VOICE\_CALL, the stream must be started using IAudioVoiceStream::startAudio() before setting the mute state. - Parameters: - - **mute** – **[in]** Defines the stream is to be muted or unmuted - **callback** – **[in]** Optional, invoked to confirm if the stream is muted/unmuted - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status getMute(StreamDirection dir, GetStreamMuteResponseCb callback = nullptr) = 0 - Gets the current mute state of the audio stream. Applicable for StreamType::VOICE\_CALL, StreamType::PLAY, and StreamType::CAPTURE only. For StreamType::VOICE\_CALL, the stream must be started using IAudioVoiceStream::startAudio() before reading the mute state. - Parameters: - - **dir** – **[in]** Direction of the stream - **callback** – **[in]** Mandatory, invoked to pass the mute state - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - inline virtual ~IAudioStream() - Destructor of the IAudioStream. - class IAudioVoiceStream : public virtual telux::audio::IAudioStream - Represents the stream created with the StreamType::VOICE\_CALL type. Provides methods to establish a voice call on a cellular network, and play and detect DTMF tones. Public Functions - virtual telux::common::Status startAudio(telux::common::ResponseCallback callback = nullptr) = 0 - Starts a voice call stream. - Parameters: - **callback** – **[in]** Optional, invoked to confirm if the stream has started - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status stopAudio(telux::common::ResponseCallback callback = nullptr) = 0 - Stops a voice call stream. - Parameters: - **callback** – **[in]** Optional, invoked to confirm if the stream has stopped - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status playDtmfTone(DtmfTone dtmfTone, uint16\_t duration, uint16\_t gain, telux::common::ResponseCallback callback = nullptr) = 0 - Generates a DTMF tone on a local device (on RX path) associated with the active voice call stream. - Parameters: - - **dtmfTone** – **[in]** Specifies the tone’s properties - **duration** – **[in]** Duration (in milliseconds) for which the tone is played. Set it to INFINITE\_TONE\_DURATION to play indefinitely - **gain** – **[in]** Volume level of the tone, valid value range is 0 to 4000 - **callback** – **[in]** Optional, invoked to confirm if the tone play has started - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status stopDtmfTone(StreamDirection direction, telux::common::ResponseCallback callback = nullptr) = 0 - If IAudioVoiceStream::playDtmfTone() was called with the duration set to INFINITE\_DTMF\_DURATION, then this method stops playing the DTMF tone. - Parameters: - - **direction** – **[in]** Direction of the stream - **callback** – **[in]** Optional, invoked to confirm if the tone play has stopped - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status registerListener(std::weak\_ptr<IVoiceListener> listener, telux::common::ResponseCallback callback = nullptr) = 0 - Registers the given listener to get notified whenever a DTMF tone is detected on a voice call stream. Used in conjunction with IVoiceListener::onDtmfToneDetection(). - Parameters: - - **listener** – **[in]** Receives the DTMF tone detected event - **callback** – **[in]** Optional, invoked to confirm if the registration is successful - Returns: - telux::common::Status::SUCCESS if the listener is registered, otherwise, an appropriate error code - virtual telux::common::Status deRegisterListener(std::weak\_ptr<IVoiceListener> listener) = 0 - Unregisters the given listener registered with IAudioVoiceStream::registerListener(). - Parameters: - **listener** – **[in]** Listener to unregister - Returns: - telux::common::Status::SUCCESS if the listener is unregistered, otherwise, an appropriate error code - inline virtual ~IAudioVoiceStream() - Destructor of the IAudioVoiceStream. - class IAudioPlayStream : public virtual telux::audio::IAudioStream - Represents the stream created with the StreamType::PLAY type. Provides the methods to play the audio. Public Functions - virtual std::shared\_ptr<IStreamBuffer> getStreamBuffer() = 0 - Gets an audio buffer containing the audio samples to play. - Returns: - IStreamBuffer instance or nullptr if memory allocation fails - virtual telux::common::Status write(std::shared\_ptr<IStreamBuffer> buffer, WriteResponseCb callback = nullptr) = 0 - Sends the audio data for playback. First write starts the playback operation. For uncompressed playback (for example, AudioFormat::PCM\_16BIT\_SIGNED), the next buffer can be sent the moment telux::common::ErrorCode::SUCCESS is received by WriteResponseCb. For compressed playback (for example, AudioFormat::AMR\*), the next buffer should be sent only after both; (a) telux::common::ErrorCode::SUCCESS is received by WriteResponseCb (indicating that the current buffer has been pushed in the pipeline for playback) and (b) IPlayListener::onReadyForWrite() has been invoked (indicating that the pipeline can accommodate the next buffer). - Parameters: - - **buffer** – **[in]** Contains the audio data to play - **callback** – **[in]** Optional, invoked to confirm if the data is played successfully - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status stopAudio(StopType stopType, telux::common::ResponseCallback callback = nullptr) = 0 - Finishes the ongoing compressed playback in a way specified by the StopType provided. - Parameters: - - **callback** – **[in]** Optional, invoked to confirm if the playback has finished - **stopType** – **[in]** Defines how to finish playback - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status registerListener(std::weak\_ptr<IPlayListener> listener) = 0 - Registers the given listener to receive events; (a) pipeline is ready to accept the next buffer for compressed playback (b) compressed playback has stopped. Events are received by the listener implementing the IPlayListener interface. - Parameters: - **listener** – **[in]** Receives the playstream events - Returns: - telux::common::Status::SUCCESS if the listener is registered, otherwise, an appropriate error code - virtual telux::common::Status deRegisterListener(std::weak\_ptr<IPlayListener> listener) = 0 - Unregisters the given listener registered with IAudioPlayStream::registerListener(). - Parameters: - **listener** – **[in]** Listener to unregister - Returns: - telux::common::Status::SUCCESS if the listener is unregistered, otherwise, an appropriate error code - inline virtual ~IAudioPlayStream() - Destructor of the IAudioPlayStream. - class IAudioCaptureStream : public virtual telux::audio::IAudioStream - Represents the stream created with the StreamType::CAPTURE type. Provides the methods to read the captured audio. Public Functions - virtual std::shared\_ptr<IStreamBuffer> getStreamBuffer() = 0 - Gets an audio buffer that will contain the audio data read. - Returns: - IStreamBuffer instance or nullptr if memory allocation fails - virtual telux::common::Status read(std::shared\_ptr<IStreamBuffer> buffer, uint32\_t bytesToRead, ReadResponseCb callback = nullptr) = 0 - Read the audio data from the source device associated with this stream. Data captured will be received by the ReadResponseCb callback. First read call starts the capture operation. - Parameters: - - **buffer** – **[in]** Buffer in which data should be read - **bytesToRead** – **[in]** Length of the data (in bytes) to read - **callback** – **[in]** Mandatory, receives the captured data - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - inline virtual ~IAudioCaptureStream() - Destructor of the IAudioCaptureStream. - class IAudioLoopbackStream : public virtual telux::audio::IAudioStream - Represents the stream created with the StreamType::LOOPBACK type. Provides the methods to start and stop the audio loopback operation. Public Functions - virtual telux::common::Status startLoopback(telux::common::ResponseCallback callback = nullptr) = 0 - Starts looping back the audio between the source and sink devices associated with this stream. - Parameters: - **callback** – **[in]** Optional, invoked to confirm if the loopback has started - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status stopLoopback(telux::common::ResponseCallback callback = nullptr) = 0 - Starts looping back the audio between the source and sink devices associated with this stream. - Parameters: - **callback** – **[in]** Optional, invoked to confirm if the loopback has stopped - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - inline virtual ~IAudioLoopbackStream() - Destructor of the IAudioLoopbackStream. - class IAudioToneGeneratorStream : public virtual telux::audio::IAudioStream - Represents the stream created with the StreamType::TONE\_GENERATOR type. Provides the methods to play an audio tone. Public Functions - virtual telux::common::Status playTone(std::vector<uint16\_t> freq, uint16\_t duration, uint16\_t gain, telux::common::ResponseCallback callback = nullptr) = 0 - Plays an audio tone with the given parameters. - Parameters: - - **freq** – **[in]** Frequency of the tone. For single tone, freq[0] should be provided. For dual tone, both freq[0] and freq[1] should be provided. - **duration** – **[in]** Duration (in milliseconds) for which the tone is played. Set it to INFINITE\_TONE\_DURATION to play indefinitely - **gain** – **[in]** Defines the volume level of the tone, valid value range is 0 to 4000 - **callback** – **[in]** Optional, invoked to confirm if the tone play started - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - virtual telux::common::Status stopTone(telux::common::ResponseCallback callback = nullptr) = 0 - If the IAudioToneGeneratorStream::playTone() was called with the INFINITE\_TONE\_DURATION duration, then this method stops playing the tone. - Parameters: - **callback** – **[in]** Optional, invoked to confirm if the tone play has stopped - Returns: - telux::common::Status::SUCCESS if the request is initiated successfully, otherwise, an appropriate error code - inline virtual ~IAudioToneGeneratorStream() - Destructor of the IAudioToneGeneratorStream. Last Published: Apr 14, 2026 Previous Topic telux::audio::IAudioDevice Next Topic Transcoder