version 2.8
GAUDIO

Detailed Description

Module to handle audio recording and play-back.

Data Structures

struct  GEventAudioPlay_t
 The Audio play event structure. More...
 
struct  GEventAudioRecord_t
 The Audio record event structure. More...
 

Modules

 Driver Playback
 Playback driver interface for the GAUDIO module.
 
 Driver Recording
 Recording driver interface for the GAUDIO module.
 

Functions

bool_t gaudioPlayInit (uint16_t channel, uint32_t frequency, ArrayDataFormat format)
 Set the audio device to play on the specified channel and with the specified sample frequency. More...
 
void gaudioPlay (GDataBuffer *paud)
 Play the specified sample data. More...
 
void gaudioPlayPause (void)
 Pause any currently playing sounds. More...
 
void gaudioPlayStop (void)
 Stop any currently playing sounds. More...
 
bool_t gaudioPlaySetVolume (uint8_t vol)
 Set the output volume. More...
 
GSourceHandle gaudioPlayGetSource (void)
 Turn on sending results to the GEVENT sub-system. More...
 
bool_t gaudioPlayWait (delaytime_t ms)
 Wait for any currently playing sounds to complete. More...
 
bool_t gaudioRecordInit (uint16_t channel, uint32_t frequency, ArrayDataFormat format)
 Initialise (but not start) the Audio Recording sub-system. More...
 
void gaudioRecordStart (void)
 Start the audio recording. More...
 
void gaudioRecordStop (void)
 Stop the audio recording. More...
 
GDataBuffergaudioRecordGetData (delaytime_t ms)
 Get a filled audio buffer from the recording list. More...
 
GSourceHandle gaudioRecordGetSource (void)
 Turn on sending results to the GEVENT sub-system. More...
 
typedef struct GEventAudioPlay_t GEventAudioPlay
 The Audio play event structure. More...
 
typedef struct GEventAudioRecord_t GEventAudioRecord
 The Audio record event structure. More...
 

GAUDIO Functionality to be included

#define GAUDIO_NEED_PLAY   FALSE
 Audio Play capability is needed. More...
 
#define GAUDIO_NEED_RECORD   FALSE
 Audio Recording capability is needed. More...
 

Function Documentation

void gaudioPlay ( GDataBuffer paud)

Play the specified sample data.

The sample data is output to the audio channel. On completion the buffer is returned to the free-list.

Precondition
gaudioPlayInit must have been called first to set the channel and sample frequency.
Parameters
[in]paudThe audio sample buffer to play. It can be NULL (used to restart paused audio)
Note
Calling this will cancel any pause.
Before calling this function the len field of the GDataBuffer structure must be specified (in bytes).
For stereo channels the sample data is interleaved in the buffer.
This call returns before the data has completed playing. Subject to available buffers (which can be obtained from the free-list), any number of buffers may be played. They will be queued for playing in the order they are supplied to this routine and played when previous buffers are complete. In this way continuous playing can be obtained without audio gaps.
Function Class:
Normal API, this function can be invoked by regular system threads.
GSourceHandle gaudioPlayGetSource ( void  )

Turn on sending results to the GEVENT sub-system.

Returns a GSourceHandle to listen for GEVENT_AUDIO_OUT events.

Note
The audio output will not use the GEVENT system unless this is called first. This saves processing time if the application does not want to use the GEVENT sub-system for audio output. Once turned on it can only be turned off by calling gaudioPlayInit() again.
The audio output is capable of signaling via this method and other methods at the same time.
Returns
The GSourceHandle
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gaudioPlayInit ( uint16_t  channel,
uint32_t  frequency,
ArrayDataFormat  format 
)

Set the audio device to play on the specified channel and with the specified sample frequency.

Returns
TRUE is successful, FALSE if the driver doesn't accept those parameters.
Parameters
[in]channelThe audio output channel to use. Can be set from 0 to GAUDIO_PLAY_NUM_CHANNELS - 1
[in]frequencyThe audio sample rate in samples per second
[in]formatThe audio sample format
Note
Some channels are mono, and some are stereo. See your driver config file to determine which channels to use and whether they are stereo or not.
Only one channel can be playing at a time. Calling this will stop any currently playing channel.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gaudioPlayPause ( void  )

Pause any currently playing sounds.

Note
If nothing is currently playing this routine does nothing. To restart playing call gaudioPlay() with or without a new sample buffer.
Some drivers will not respond until a buffer boundary.
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gaudioPlaySetVolume ( uint8_t  vol)

Set the output volume.

Returns
TRUE if successful.
Parameters
[in]vol0->255 (0 = muted)
Note
Some drivers may not support this. They will return FALSE.
For stereo devices, both channels are set to the same volume.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gaudioPlayStop ( void  )

Stop any currently playing sounds.

Note
This stops any playing sounds and returns any currently queued buffers back to the free-list.
Some drivers will not respond until a buffer boundary.
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gaudioPlayWait ( delaytime_t  ms)

Wait for any currently playing sounds to complete.

Returns
TRUE if there is now nothing playing or FALSE if the timeout is exceeded
Parameters
[in]msThe maximum amount of time in milliseconds to wait for playing to complete.
Function Class:
Normal API, this function can be invoked by regular system threads.
GDataBuffer* gaudioRecordGetData ( delaytime_t  ms)

Get a filled audio buffer from the recording list.

Returns
A GDataBuffer pointer or NULL if the timeout is exceeded
Parameters
[in]msThe maximum amount of time in milliseconds to wait for data if some is not currently available.
Note
After processing the audio data, your application must return the buffer to the free-list so that it can be used to record more audio into. This can be done via the play list using gaudioPlay() or directly using gfxBufferRelease().
A buffer may be returned to the free-list before you have finished processing it provided you finish processing it before GADC re-uses it. This is useful when RAM usage is critical to reduce the number of buffers required. It works before the free list is a FIFO queue and therefore buffers are kept in the queue as long as possible before they are re-used.
Function Class:
Normal API, this function can be invoked by regular system threads.
GSourceHandle gaudioRecordGetSource ( void  )

Turn on sending results to the GEVENT sub-system.

Returns a GSourceHandle to listen for GEVENT_AUDIO_RECORD events.

Note
Audio recording will not use the GEVENT system unless this is called first. This saves processing time if the application does not want to use the GEVENT sub-system for audio recording. Once turned on it can only be turned off by calling gaudioRecordInit() again.
The audio input is capable of signaling via this and other methods at the same time.
Returns
The GSourceHandle
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gaudioRecordInit ( uint16_t  channel,
uint32_t  frequency,
ArrayDataFormat  format 
)

Initialise (but not start) the Audio Recording sub-system.

Returns FALSE for an invalid channel or other invalid parameter.

Parameters
[in]channelThe channel to convert. Can be set from 0 to GAUDIO_RECORD_NUM_CHANNELS - 1
[in]frequencyThe sample frequency
[in]formatThe audio sample format requested
Note
Only one channel is active at a time. If an audio input is running it will be stopped. The Event subsystem is disconnected from the audio subsystem and any binary semaphore event is forgotten.
Some channels may be stereo channels which return twice as much sample data with the left and right channel data interleaved. Other channels may be mono channels. Where stereo channels exist the low level driver may also offer the left and right channels separately.
Due to a bug in Chibi-OS each buffer on the free-list must contain an even number of samples and for stereo devices it must hold a number of samples that is evenly divisible by 4. This requirement applies only to ChibiOS where the audio driver uses a ChibiOS hal driver like the cpu ADC driver. This applies even it is used indirectly via the uGFX GADC driver.
The number of samples for stereo devices will be double the number of conversions. Make sure you allocate your buffers large enough. Each channel is then interleaved into the provided buffer.
Returns
FALSE if invalid channel or parameter
Function Class:
Normal API, this function can be invoked by regular system threads.
void gaudioRecordStart ( void  )

Start the audio recording.

Precondition
It must have been initialised first with gaudioRecordInit()
Function Class:
Normal API, this function can be invoked by regular system threads.
void gaudioRecordStop ( void  )

Stop the audio recording.

Note
All audio recording data that has not yet been retrieved is automatically returned to the free-list.
Function Class:
Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

#define GAUDIO_NEED_PLAY   FALSE

Audio Play capability is needed.

Definition at line 27 of file gaudio_options.h.

#define GAUDIO_NEED_RECORD   FALSE

Audio Recording capability is needed.

Definition at line 33 of file gaudio_options.h.

Typedef Documentation

The Audio play event structure.

The Audio record event structure.