libguac  1.0.0
Data Structures | Functions
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_streamguac_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. More...
 
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. More...
 
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. More...
 
void guac_audio_stream_free (guac_audio_stream *stream)
 Closes and frees the given audio stream. More...
 
void guac_audio_stream_write_pcm (guac_audio_stream *stream, const unsigned char *data, int length)
 Writes PCM data to the given audio stream. More...
 
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. More...
 

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
audioThe guac_audio_stream associated with the Guacamole connection being joined.
userThe 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
clientThe 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.
encoderThe guac_audio_encoder to use when encoding audio, or NULL if libguac should select an appropriate built-in encoder on its own.
rateThe number of samples per second of PCM data sent to this stream.
channelsThe number of audio channels per sample of PCM data. Legal values are 1 or 2.
bpsThe 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.

◆ 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
streamThe 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
streamThe 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
audioThe guac_audio_stream to reset.
encoderThe guac_audio_encoder to use when encoding audio, or NULL to leave this unchanged.
rateThe number of samples per second of PCM data sent to this stream.
channelsThe number of audio channels per sample of PCM data. Legal values are 1 or 2.
bpsThe 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
streamThe guac_audio_stream to write PCM data through.
dataThe PCM data to write.
lengthThe number of bytes of PCM data provided.