The main include for the AXAudio interface and its associated functions. More...

Typedefs
typedef struct _AXAudioOutput	AXAudioOutput
	Opaque structure for the AXAudioOutput.

typedef struct _AXAudioStream	AXAudioStream
	Opaque structure for the AXAudioStream.

typedef struct _AXAudioFrame	AXAudioFrame
	Opaque structure for the AXAudioFrame.

Enumerations
enum	AXAudioChannel { AX_AUDIO_CHANNEL_MONO, AX_AUDIO_CHANNEL_STEREO }

enum	AXAudioCodec { AX_AUDIO_PCM_16, AX_AUDIO_G711, AX_AUDIO_G726, AX_AUDIO_AAC, AX_AUDIO_OPUS }

Functions
guint	ax_audio_get_sources (guint **sources)
	Retrieve a numbered list of audio sources. More...

gboolean	ax_audio_get_channel_capability (guint audio_source, AXAudioChannel *channel_cap)
	Retrieve the channel capability of the audio source. More...

gint	ax_audio_get_codecs (AXAudioCodec **codecs)
	Retrieve a list of available codecs. More...

gint	ax_audio_get_samplerates (gint samplerates, AXAudioCodec codec, GError error)
	Retrieve a list of available sample rates for the specified codec. More...

gint	ax_audio_get_bitrates (guint bitrates, AXAudioCodec codec, gint samplerate, GError error)
	Retrieve a list of available bit rates for the specified codec and sample rate. More...

AXAudioOutput *	ax_audio_open_output_pcm_16 (gint audio_sink, gint samplerate, AXAudioChannel channel, GError **error)
	Open a raw signed PCM16 audio output. More...

gboolean	ax_audio_output_play_pcm_16 (AXAudioOutput output, const AXAudioFrame frame, GError **error)
	Play raw signed PCM16 audio data. Interleaved LRLRLR if more than one channel is supported. This function will block until the whole frame is played. More...

gboolean	ax_audio_output_close_pcm_16 (AXAudioOutput output, GError *error)
	Close the raw signed PCM16 audio output. More...

AXAudioStream *	ax_audio_open_pcm_16_stream (gint audio_source, gint samplerate, AXAudioChannel channel, GError **error)
	Open a new raw signed PCM 16 audio stream. More...

AXAudioStream *	ax_audio_open_opus_stream (gint bitrate, gint samplerate, gint audio_source, AXAudioChannel channel, GError **error)
	Open a new Opus audio stream. More...

AXAudioStream *	ax_audio_open_aac_stream (gint bitrate, gint samplerate, gint audio_source, AXAudioChannel channel, GError **error)
	Open a new AAC audio stream. More...

AXAudioStream *	ax_audio_open_g711_stream (gint audio_source, GError **error)
	Open a new G.711 audio stream. More...

AXAudioStream *	ax_audio_open_g726_stream (gint bitrate, gint audio_source, GError **error)
	Open a new G.726 audio stream. More...

gboolean	ax_audio_stream_close (AXAudioStream stream, GError *error)
	Close a running audio stream. More...

gboolean	ax_audio_stream_get_channel_capability (const AXAudioStream stream, AXAudioChannel channel_cap)
	Retrieve the channel capability of the audio stream, for example AX_AUDIO_CHANNEL_MONO. More...

guint	ax_audio_stream_get_bit_depth (const AXAudioStream *stream)
	Retrieve the bit depth of the audio stream. More...

guint	ax_audio_stream_get_bitrate (const AXAudioStream *stream)
	Retrieve the bit rate of the audio stream. More...

guint	ax_audio_stream_get_samplerate (const AXAudioStream *stream)
	Retrieve the sample rate of the audio stream. More...

guint	ax_audio_stream_get_period_time (const AXAudioStream *stream)
	Retrieve the time between two successive audio frames. More...

gboolean	ax_audio_stream_get_codec (const AXAudioStream stream, AXAudioCodec codec)
	Retrieve the codec for the audio stream. More...

AXAudioFrame *	ax_audio_stream_get_frame (const AXAudioStream stream, GError *error)
	Retreive an audio frame from an open audio stream. More...

AXAudioFrame *	ax_audio_frame_copy (const AXAudioFrame *frame)
	Copy an audio frame from an open audio stream. More...

AXAudioFrame *	ax_audio_frame_new (void)
	Create an empty AXAudioFrame structure. More...

gboolean	ax_audio_frame_set_data (AXAudioFrame frame, gpointer data, gint size, GFreeFunc free_function, GError *error)
	Set the data content of the AXAudioFrame. More...

gboolean	ax_audio_frame_set_timestamp (AXAudioFrame frame, guint64 timestamp, GError *error)
	Set the timestamp of the AXAudioFrame. More...

gpointer	ax_audio_frame_get_data (const AXAudioFrame *frame)
	Retrieve the data from the AXAudioFrame. More...

guint	ax_audio_frame_get_size (const AXAudioFrame *frame)
	Retrieve the data size in bytes from the AXAudioFrame. The size is the total size, that is the sum of all channel data. More...

guint64	ax_audio_frame_get_timestamp (const AXAudioFrame *frame)
	Retrieve the timestamp in nanoseconds from the AXAudioFrame. More...

void	ax_audio_frame_free (AXAudioFrame *frame)
	Free the AXAudioFrame retrieved from ax_audio_get_frame() or ax_audio_frame_new(). More...

Detailed Description

The main include for the AXAudio interface and its associated functions.

Purpose

The AXAudio library is used to set up and manage audio streams. The API contains functions for opening audio streams, retrieving audio frames from the streams and retrieving audio data from the frames as well as functions for getting information from the Axis product about supported audio sources, codecs, bit rates and sample rates.

The intended workflow is as follows: First, set up an audio stream by calling one of the open audio stream functions, for example ax_audio_open_pcm_16_stream(). Then call ax_audio_get_frame() iteratively to retrieve audio frames. Typically, one audio frame is returned every 64 ms. To retrieve audio data, use ax_audio_frame_get_data().

Enumeration Type Documentation

◆ AXAudioChannel

enum AXAudioChannel

Defines the possible channel modes.

Enumerator
AX_AUDIO_CHANNEL_MONO	Mono channel mode
AX_AUDIO_CHANNEL_STEREO	Stereo channel mode

◆ AXAudioCodec

enum AXAudioCodec

Defines the possible audio codecs.

Enumerator
AX_AUDIO_PCM_16	PCM, 16bit per sample
AX_AUDIO_G711	G.711
AX_AUDIO_G726	G.726
AX_AUDIO_AAC	Advanced Audio Coding (AAC)
AX_AUDIO_OPUS	Opus

Function Documentation

◆ ax_audio_get_sources()

guint ax_audio_get_sources ( guint ** sources )

Retrieve a numbered list of audio sources.

Parameters

audio_sources List of audio sources. Must be freed by the caller.

Returns: The number of audio sources.

◆ ax_audio_get_channel_capability()

gboolean ax_audio_get_channel_capability	(	guint	audio_source,
		AXAudioChannel *	channel_cap
	)

Retrieve the channel capability of the audio source.

Parameters

audio_source	The audio source.
channel_cap	The channel capability.

Returns: TRUE if channel capability could be returned, FALSE otherwise.

◆ ax_audio_get_codecs()

gint ax_audio_get_codecs ( AXAudioCodec ** codecs )

Retrieve a list of available codecs.

Parameters

codecs List of codecs. Must be freed by the caller.

Returns: The number of available codecs, or 0 if codecs is NULL.

References AX_AUDIO_AAC, AX_AUDIO_G711, AX_AUDIO_G726, AX_AUDIO_OPUS, and AX_AUDIO_PCM_16.

◆ ax_audio_get_samplerates()

gint ax_audio_get_samplerates	(	gint **	samplerates,
		AXAudioCodec	codec,
		GError **	error
	)

Retrieve a list of available sample rates for the specified codec.

Parameters

samplerates	List of sample rates. Must be freed by the caller.
codec	The codec to list sample rates for.

Returns: The number of listed sample rates or -1 if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_AAC, AX_AUDIO_CODEC_ERROR, AX_AUDIO_ERROR, AX_AUDIO_G711, AX_AUDIO_G726, AX_AUDIO_OPUS, AX_AUDIO_PARAM_ERROR, and AX_AUDIO_PCM_16.

◆ ax_audio_get_bitrates()

gint ax_audio_get_bitrates	(	guint **	bitrates,
		AXAudioCodec	codec,
		gint	samplerate,
		GError **	error
	)

Retrieve a list of available bit rates for the specified codec and sample rate.

Parameters

bitrates	List of bit rates. Must be freed by the caller.
codec	The codec to list bit rates for.
samplerate	The sample rate to list bit rates for. For example 16000 samples per second.

Returns: The number of listed bit rates or -1 if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_AAC, AX_AUDIO_CODEC_ERROR, AX_AUDIO_ERROR, AX_AUDIO_G711, AX_AUDIO_G726, AX_AUDIO_OPUS, AX_AUDIO_PARAM_ERROR, AX_AUDIO_PCM_16, and AX_AUDIO_SAMPLE_RATE_ERROR.

◆ ax_audio_open_output_pcm_16()

AXAudioOutput* ax_audio_open_output_pcm_16	(	gint	audio_sink,
		gint	samplerate,
		AXAudioChannel	channel,
		GError **	error
	)

Open a raw signed PCM16 audio output.

Parameters

audio_sink	Optional. Audio sink. Set to -1 to use default sink.
samplerate	The sample rate. For example 16000 samples per second.
channel	Channel AXAudioChannel. For example AX_AUDIO_CHANNEL_MONO.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the output or NULL if failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_PCM_16.

◆ ax_audio_output_play_pcm_16()

gboolean ax_audio_output_play_pcm_16	(	AXAudioOutput *	output,
		const AXAudioFrame *	frame,
		GError **	error
	)

Play raw signed PCM16 audio data. Interleaved LRLRLR if more than one channel is supported. This function will block until the whole frame is played.

Parameters

output	The structure associated with the output.
frame	An AXAudioFrame structure.
error	Return location for a GError or NULL.

Returns: Return TRUE if a frame could be successfully played or FALSE if it failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_output_close_pcm_16()

gboolean ax_audio_output_close_pcm_16	(	AXAudioOutput *	output,
		GError **	error
	)

Close the raw signed PCM16 audio output.

Parameters

output	The structure associated with the output.
error	Return location for a GError or NULL.

Returns: Return TRUE if the output could be closed or FALSE if it failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_open_pcm_16_stream()

AXAudioStream* ax_audio_open_pcm_16_stream	(	gint	audio_source,
		gint	samplerate,
		AXAudioChannel	channel,
		GError **	error
	)

Open a new raw signed PCM 16 audio stream.

This function will open a raw signed Pulse Code Modulation (PCM) 16 audio stream. Bit rate and sample rate depend on system settings. If stereo mode is used, the stream will be interleaved as LRLRLR.

Parameters

audio_source	Optional. Audio source. Set to -1 to use default source.
samplerate	Optional. Sample rate, for example 16000 samples per second. Set to -1 to use default sample rate.
channel	Channel AXAudioChannel. For example AX_AUDIO_CHANNEL_MONO.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the stream or NULL if failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_PCM_16.

◆ ax_audio_open_opus_stream()

AXAudioStream* ax_audio_open_opus_stream	(	gint	bitrate,
		gint	samplerate,
		gint	audio_source,
		AXAudioChannel	channel,
		GError **	error
	)

Open a new Opus audio stream.

This function will open an Opus-encoded audio stream. Supported bit rates depend on the sample rate.

Parameters

bitrate	Optional. Bit rate, for example 32000 bits per second. Set to -1 to use default bit rate.
samplerate	Optional. Sample rate, for example 16000 samples per second. Set to -1 to use default sample rate.
audio_source	Optional. Audio source. Set to -1 to use default source.
channel	Channel AXAudioChannel. For example AX_AUDIO_CHANNEL_MONO.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the stream or NULL if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_OPUS.

◆ ax_audio_open_aac_stream()

AXAudioStream* ax_audio_open_aac_stream	(	gint	bitrate,
		gint	samplerate,
		gint	audio_source,
		AXAudioChannel	channel,
		GError **	error
	)

Open a new AAC audio stream.

This function will open an AAC-encoded audio stream. Supported bit rates depend on the sample rate: sample rate 8 kHz supports 8, 12, 16 and 32 kbit/s sample rate 16 kHz supports 12, 16, 32 and 64 kbit/s The stream will contain an ADTS header for each frame.

Parameters

bitrate	Optional. Bit rate, for example 32000 bits per second. Set to -1 to use default bit rate.
samplerate	Optional. Sample rate, for example 16000 samples per second. Set to -1 to use default sample rate.
audio_source	Optional. Audio source. Set to -1 to use default source.
channel	Channel AXAudioChannel. For example AX_AUDIO_CHANNEL_MONO.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the stream or NULL if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_AAC.

◆ ax_audio_open_g711_stream()

AXAudioStream* ax_audio_open_g711_stream	(	gint	audio_source,
		GError **	error
	)

Open a new G.711 audio stream.

This function will open a G.711-encoded audio stream. Bit rate is 64 kbit/s and sample rate is 8 kHz. Only mono audio is supported.

Parameters

audio_source	Optional. Audio source. Set to -1 to use default source.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the stream or NULL if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_CHANNEL_MONO, and AX_AUDIO_G711.

◆ ax_audio_open_g726_stream()

AXAudioStream* ax_audio_open_g726_stream	(	gint	bitrate,
		gint	audio_source,
		GError **	error
	)

Open a new G.726 audio stream.

This function will open a G.726-encoded audio stream. Supported bit rates are: 24 and 32 kbit/s. Sample rate is 8 kHz. Only mono audio is supported.

Parameters

bitrate	Optional. Bit rate, for exmaple 32000 bits per second. Set to -1 to use default bit rate.
audio_source	Optional. Audio source. Set to -1 to use default source.
error	Return location for a GError or NULL.

Returns: An opaque structure associated with the stream or NULL if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_CHANNEL_MONO, AX_AUDIO_ERROR, AX_AUDIO_G726, and AX_AUDIO_GENERIC_ERROR.

◆ ax_audio_stream_close()

gboolean ax_audio_stream_close	(	AXAudioStream *	stream,
		GError **	error
	)

Close a running audio stream.

The function closes the specified audio stream.

Parameters

stream	The structure associated with the stream.
error	Return the location for a GError or NULL.

Returns: Return TRUE if stream could be closed or FALSE if it failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_CONNECT_ERROR, AX_AUDIO_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_stream_get_channel_capability()

gboolean ax_audio_stream_get_channel_capability	(	const AXAudioStream *	stream,
		AXAudioChannel *	channel_cap
	)

Retrieve the channel capability of the audio stream, for example AX_AUDIO_CHANNEL_MONO.

Parameters

stream	The structure associated with the stream.
channel_cap	The channel capability.

Returns: TRUE if channel capability could be returned, FALSE otherwise.

◆ ax_audio_stream_get_bit_depth()

guint ax_audio_stream_get_bit_depth ( const AXAudioStream * stream )

Retrieve the bit depth of the audio stream.

Parameters

stream The structure associated with the stream.

Returns: The bit depth of the audio stream, for example 8 bits for G.711. Or 0 if stream is NULL.

Examples:: axaudioexample.c.

◆ ax_audio_stream_get_bitrate()

guint ax_audio_stream_get_bitrate ( const AXAudioStream * stream )

Retrieve the bit rate of the audio stream.

Parameters

stream The structure associated with the stream.

Returns: The bit rate of the audio stream, for example 64000 bits per second. Or 0 if stream is NULL.

◆ ax_audio_stream_get_samplerate()

guint ax_audio_stream_get_samplerate ( const AXAudioStream * stream )

Retrieve the sample rate of the audio stream.

Parameters

stream The structure associated with the stream.

Returns: The sample rate of the audio stream, for example 16000 samples per second. Or 0 if stream is NULL.

Examples:: axaudioexample.c.

◆ ax_audio_stream_get_period_time()

guint ax_audio_stream_get_period_time ( const AXAudioStream * stream )

Retrieve the time between two successive audio frames.

Parameters

stream The structure associated with the stream.

Returns: Time in milliseconds, for example 64 ms. Or 0 if stream is NULL.

◆ ax_audio_stream_get_codec()

gboolean ax_audio_stream_get_codec	(	const AXAudioStream *	stream,
		AXAudioCodec *	codec
	)

Retrieve the codec for the audio stream.

Parameters

stream	The structure associated with the stream.
codec	The codec, for example AX_AUDIO_AAC.

Returns: TRUE if codec could be returned, FALSE otherwise.

◆ ax_audio_stream_get_frame()

AXAudioFrame* ax_audio_stream_get_frame	(	const AXAudioStream *	stream,
		GError **	error
	)

Retreive an audio frame from an open audio stream.

The function will return a frame with audio data from the audio stream. In addition to audio data, the frame contains a timestamp and the size of the audio data. The frame should be freed after use. Use ax_audio_frame_free to free the frame. The ax_audio_stream_get_frame function call will block other calls until the audio data arrives. The block time is typical 64 ms if the function is called as soon as the audio data from the previous function call is returned. The audio buffer is 500 ms; older frames will be dropped.

Parameters

stream	The structure associated with the stream.
error	Return location for a GError or NULL.

Returns: An AXAudioFrame structure, or NULL if stream is NULL. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_CONNECT_ERROR, AX_AUDIO_ERROR, AX_AUDIO_GENERIC_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_frame_copy()

AXAudioFrame* ax_audio_frame_copy ( const AXAudioFrame * frame )

Copy an audio frame from an open audio stream.

The function will copy an audio frame. The returned frame copy must be freed with ax_audio_frame_free() after use.

Parameters

frame The AXAudioFrame to copy data from.

Returns: An AXAudioFrame structure, or NULL if frame is NULL.

◆ ax_audio_frame_new()

AXAudioFrame* ax_audio_frame_new ( void )

Create an empty AXAudioFrame structure.

This function will create an empty AXAudioFrame. The created AXAudioFrame must be freed with ax_audio_frame_free() after use.

Returns: An AXAudioFrame structure.

Examples:: axaudioexample.c.

◆ ax_audio_frame_set_data()

gboolean ax_audio_frame_set_data	(	AXAudioFrame *	frame,
		gpointer	data,
		gint	size,
		GFreeFunc	free_function,
		GError **	error
	)

Set the data content of the AXAudioFrame.

This function will set the audio data part of the AXAudioFrame structure. Any existing audio data will be replaced. If a free function was specified for the old data, the old data will be freed.

Parameters

frame	The AXAudioFrame structure.
data	The audio data.
size	Audio data size in bytes.
free_function	The free function for the data. If NULL the data will not be freed. If specified, the data will be freed when ax_audio_frame_free is called.

Returns: Return TRUE if data could be set or FALSE if failed. See ax_parameter_error.h for possible errors.

Examples:: axaudioexample.c.

References AX_AUDIO_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_frame_set_timestamp()

gboolean ax_audio_frame_set_timestamp	(	AXAudioFrame *	frame,
		guint64	timestamp,
		GError **	error
	)

Set the timestamp of the AXAudioFrame.

This function will set the timestamp of the AXAudioFrame structure.

Parameters

frame	The AXAudioFrame structure.
timestamp	Timestamp in microseconds.

Returns: Return TRUE if timestamp could be set or FALSE if failed. See ax_parameter_error.h for possible errors.

References AX_AUDIO_ERROR, and AX_AUDIO_PARAM_ERROR.

◆ ax_audio_frame_get_data()

gpointer ax_audio_frame_get_data ( const AXAudioFrame * frame )

Retrieve the data from the AXAudioFrame.

This function returns the audio data. For PCM streams the data is optimally aligned in memory.

Parameters

frame The AXAudioFrame to retrieve data from.

Returns: A pointer to the data, or NULL if frame is NULL.

Examples:: axaudioexample.c.

◆ ax_audio_frame_get_size()

guint ax_audio_frame_get_size ( const AXAudioFrame * frame )

Retrieve the data size in bytes from the AXAudioFrame. The size is the total size, that is the sum of all channel data.

Parameters

frame The AXAudioFrame to retrieve data size from.

Returns: The size of the data, or 0 if frame is NULL.

Examples:: axaudioexample.c.

◆ ax_audio_frame_get_timestamp()

guint64 ax_audio_frame_get_timestamp ( const AXAudioFrame * frame )

Retrieve the timestamp in nanoseconds from the AXAudioFrame.

The returned value is in nanoseconds for the system uptime (CLOCK_MONOTONIC).

Parameters

frame The AXAudioFrame to retrieve timestamp from.

Returns: The timestamp in nanoseconds, or 0 if frame is NULL.

Examples:: axaudioexample.c.

◆ ax_audio_frame_free()

void ax_audio_frame_free ( AXAudioFrame * frame )

Free the AXAudioFrame retrieved from ax_audio_get_frame() or ax_audio_frame_new().

Parameters

frame Pointer to the AXAudioFrame received from ax_audio_get_frame()

Returns: void

Examples:: axaudioexample.c.

Typedefs

Enumerations

Functions

Detailed Description

Purpose

Enumeration Type Documentation

◆ AXAudioChannel

◆ AXAudioCodec

Function Documentation

◆ ax_audio_get_sources()

◆ ax_audio_get_channel_capability()

◆ ax_audio_get_codecs()

◆ ax_audio_get_samplerates()

◆ ax_audio_get_bitrates()

◆ ax_audio_open_output_pcm_16()

◆ ax_audio_output_play_pcm_16()

◆ ax_audio_output_close_pcm_16()

◆ ax_audio_open_pcm_16_stream()

◆ ax_audio_open_opus_stream()

◆ ax_audio_open_aac_stream()

◆ ax_audio_open_g711_stream()

◆ ax_audio_open_g726_stream()

◆ ax_audio_stream_close()

◆ ax_audio_stream_get_channel_capability()

◆ ax_audio_stream_get_bit_depth()

◆ ax_audio_stream_get_bitrate()

◆ ax_audio_stream_get_samplerate()

◆ ax_audio_stream_get_period_time()

◆ ax_audio_stream_get_codec()

◆ ax_audio_stream_get_frame()

◆ ax_audio_frame_copy()

◆ ax_audio_frame_new()

◆ ax_audio_frame_set_data()

◆ ax_audio_frame_set_timestamp()

◆ ax_audio_frame_get_data()

◆ ax_audio_frame_get_size()

◆ ax_audio_frame_get_timestamp()

◆ ax_audio_frame_free()