Module to handle audio recording and play-back.
◆ gaudioPlay()
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] | paud | The 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.
◆ gaudioPlayGetSource()
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.
◆ gaudioPlayInit()
gBool gaudioPlayInit |
( |
gU16 |
channel, |
|
|
gU32 |
frequency, |
|
|
ArrayDataFormat |
format |
|
) |
| |
Set the audio device to play on the specified channel and with the specified sample frequency.
- Returns
- gTrue is successful, gFalse if the driver doesn't accept those parameters.
- Parameters
-
[in] | channel | The audio output channel to use. Can be set from 0 to GAUDIO_PLAY_NUM_CHANNELS - 1 |
[in] | frequency | The audio sample rate in samples per second |
[in] | format | The 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.
◆ gaudioPlayPause()
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.
◆ gaudioPlaySetVolume()
gBool gaudioPlaySetVolume |
( |
gU8 |
vol | ) |
|
Set the output volume.
- Returns
- gTrue if successful.
- Parameters
-
[in] | vol | 0->255 (0 = muted) |
- Note
- Some drivers may not support this. They will return gFalse.
-
For stereo devices, both channels are set to the same volume.
- Function Class: Normal API, this function can be invoked by regular system threads.
◆ gaudioPlayStop()
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.
◆ gaudioPlayWait()
gBool gaudioPlayWait |
( |
gDelay |
ms | ) |
|
Wait for any currently playing sounds to complete.
- Returns
- gTrue if there is now nothing playing or gFalse if the timeout is exceeded
- Parameters
-
[in] | ms | The 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.
◆ gaudioRecordGetData()
Get a filled audio buffer from the recording list.
- Returns
- A GDataBuffer pointer or NULL if the timeout is exceeded
- Parameters
-
[in] | ms | The 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.
◆ gaudioRecordGetSource()
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.
◆ gaudioRecordInit()
gBool gaudioRecordInit |
( |
gU16 |
channel, |
|
|
gU32 |
frequency, |
|
|
ArrayDataFormat |
format |
|
) |
| |
Initialise (but not start) the Audio Recording sub-system.
Returns gFalse for an invalid channel or other invalid parameter.
- Parameters
-
[in] | channel | The channel to convert. Can be set from 0 to GAUDIO_RECORD_NUM_CHANNELS - 1 |
[in] | frequency | The sample frequency |
[in] | format | The 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
- gFalse if invalid channel or parameter
- Function Class: Normal API, this function can be invoked by regular system threads.
◆ gaudioRecordStart()
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.
◆ gaudioRecordStop()
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.
◆ GAUDIO_NEED_PLAY
#define GAUDIO_NEED_PLAY GFXOFF |
◆ GAUDIO_NEED_RECORD
#define GAUDIO_NEED_RECORD GFXOFF |
◆ GEventAudioPlay
The Audio play event structure.
◆ GEventAudioRecord
The Audio record event structure.