audio.h File Reference

Provides functions and structures used for providing simple streaming audio. More...

Go to the source code of this file.

Data Structures
struct	guac_audio_encoder
	Arbitrary audio codec encoder. More...
struct	guac_audio_stream
	Basic audio stream. More...

Functions
guac_audio_stream *	guac_audio_stream_alloc (guac_client *client, guac_audio_encoder *encoder, int rate, int channels, int bps)
	Allocates a new audio stream at the client level which encodes audio data using the given encoder.
void	guac_audio_stream_reset (guac_audio_stream *audio, guac_audio_encoder *encoder, int rate, int channels, int bps)
	Resets the given audio stream, switching to the given encoder, rate, channels, and bits per sample.
void	guac_audio_stream_add_user (guac_audio_stream *audio, guac_user *user)
	Notifies the given audio stream that a user has joined the connection.
void	guac_audio_stream_free (guac_audio_stream *stream)
	Closes and frees the given audio stream.
void	guac_audio_stream_write_pcm (guac_audio_stream *stream, const unsigned char *data, int length)
	Writes PCM data to the given audio stream.
void	guac_audio_stream_flush (guac_audio_stream *stream)
	Flushes the underlying audio buffer, if any, ensuring that all audio previously written via guac_audio_stream_write_pcm() has been encoded and sent to the client.

Detailed Description

Provides functions and structures used for providing simple streaming audio.

Function Documentation

guac_audio_stream_add_user()

void guac_audio_stream_add_user	(	guac_audio_stream *	audio,
		guac_user *	user )

Notifies the given audio stream that a user has joined the connection.

The audio stream itself may need to be restarted. and the audio stream will need to be created for the new user to ensure they can properly handle future data received along the stream.

Parameters

audio	The guac_audio_stream associated with the Guacamole connection being joined.
user	The user that has joined the Guacamole connection.

guac_audio_stream_alloc()

guac_audio_stream * guac_audio_stream_alloc	(	guac_client *	client,
		guac_audio_encoder *	encoder,
		int	rate,
		int	channels,
		int	bps )

Allocates a new audio stream at the client level which encodes audio data using the given encoder.

If NULL is specified for the encoder, an appropriate encoder will be selected based on the encoders built into libguac and the level of support declared by users associated with the given guac_client. The PCM format specified here (via rate, channels, and bps) must be the format used for all PCM data provided to the audio stream. The format may only be changed using guac_audio_stream_reset().

If a new user joins the connection after the audio stream is created, that user will not be aware of the existence of the audio stream, and guac_audio_stream_add_user() will need to be invoked to recreate the stream for the new user.

Parameters

client	The guac_client for which this audio stream is being allocated. The connection owner is given priority when determining the level of audio support. It is currently assumed that all other joining users on the connection will have the same level of audio support.
encoder	The guac_audio_encoder to use when encoding audio, or NULL if libguac should select an appropriate built-in encoder on its own.
rate	The number of samples per second of PCM data sent to this stream.
channels	The number of audio channels per sample of PCM data. Legal values are 1 or 2.
bps	The number of bits per sample per channel for PCM data. Legal values are 8 or 16.

Returns

The newly allocated guac_audio_stream, or NULL if no audio stream could be allocated due to lack of support on the part of the connecting Guacamole client or due to reaching the maximum number of active streams.

guac_audio_stream_flush()

void guac_audio_stream_flush

(

guac_audio_stream *

stream

)

Flushes the underlying audio buffer, if any, ensuring that all audio previously written via guac_audio_stream_write_pcm() has been encoded and sent to the client.

Parameters

stream

The guac_audio_stream whose audio buffers should be flushed.

guac_audio_stream_free()

void guac_audio_stream_free

(

guac_audio_stream *

stream

)

Closes and frees the given audio stream.

Parameters

stream

The guac_audio_stream to free.

guac_audio_stream_reset()

void guac_audio_stream_reset	(	guac_audio_stream *	audio,
		guac_audio_encoder *	encoder,
		int	rate,
		int	channels,
		int	bps )

Resets the given audio stream, switching to the given encoder, rate, channels, and bits per sample.

If NULL is specified for the encoder, the encoder is left unchanged. If the encoder, rate, channels, and bits per sample are all identical to the current settings, this function has no effect.

Parameters

audio	The guac_audio_stream to reset.
encoder	The guac_audio_encoder to use when encoding audio, or NULL to leave this unchanged.
rate	The number of samples per second of PCM data sent to this stream.
channels	The number of audio channels per sample of PCM data. Legal values are 1 or 2.
bps	The number of bits per sample per channel for PCM data. Legal values are 8 or 16.

guac_audio_stream_write_pcm()

void guac_audio_stream_write_pcm	(	guac_audio_stream *	stream,
		const unsigned char *	data,
		int	length )

Writes PCM data to the given audio stream.

This PCM data will be automatically encoded by the audio encoder associated with this stream. The PCM data must be 2-channel, 44100 Hz, with signed 16-bit samples.

Parameters

stream	The guac_audio_stream to write PCM data through.
data	The PCM data to write.
length	The number of bytes of PCM data provided.