Difference between revisions of "GAUDIO"
(→Volume) |
(→API reference) |
||
| (27 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
The GAUDIO module provides high level API for handling audio in- and output. The module provides built-in decoders but does also allow to use external codecs. See [[#External decoder]]. | The GAUDIO module provides high level API for handling audio in- and output. The module provides built-in decoders but does also allow to use external codecs. See [[#External decoder]]. | ||
| + | |||
| + | Several drivers are provided to play and record data through different hardware peripherals. Any thing from a simple PWM output up to an external codec is supported. | ||
== API reference == | == API reference == | ||
| − | The API reference of the GAUDIO module can be found [http://ugfx.org/ | + | The API reference of the GAUDIO module can be found [http://api.ugfx.org/group___g_a_u_d_i_o.html here]. |
| + | |||
| + | == Board file == | ||
| + | The GAUDIO module requires a [[Board_File|board file]] to communicate with the hardware. One board file is needed for audio output and one for audio input. See [[Board_File|board file]]. | ||
| + | |||
| + | == GDataBuffer == | ||
| + | <code>GDataBuffer</code> is the container that is used to hold, manipulate and pass audio data. The buffer is provided and handled by the [[GQUEUE]] module. | ||
| + | |||
| + | The main idea is to create a pool of buffers using <code>gfxBufferAlloc(num, size)</code> where ''num'' is the number of buffers and ''size'' the size per buffer. The user does then fill the buffers sequentially with the audio data and passes them to <code>gaudioPlay()</code> - one after another. As soon as the audio data inside a buffer has been processed, the <code>gaudioPlay()</code> routine will automatically free the buffer so the user can fill it with new data. | ||
| + | |||
| + | For more information, see [[GQUEUE#Buffers]]. | ||
== Play back == | == Play back == | ||
| − | Before any audio can be played, the audio device has to be initialized using <code>gaudioPlayInit()</code>. | + | Before any audio can be played, the audio device has to be initialized using <code>gaudioPlayInit()</code>. The audio channel, the sample format and the sample frequency are set by this function call. If using an external decoder, see [[#External_decoder]]. |
| − | After initialization, <code>gaudioPlay()</code> can be used to output audio data. The function takes a pointer to a | + | After successful initialization, <code>gaudioPlay()</code> can be used to output audio data. The function takes a pointer to a [[#GDataBuffer|GDataBuffer]] that holds the audio data to play in the format that has been set by the initialization call. The passed buffer will be freed by the function after the audio content of the buffer has been processed. |
| + | The following is an overview of the process: | ||
| + | # Allocate buffers using <code>gxfBufferAlloc()</code> | ||
| + | # Fill buffers with audio data | ||
| + | # Pass the first buffer to <code>gaudioPlay()</code> | ||
| + | # Wait until a buffer has been freed. <code>gfxBufferGet()</code> will point to the next free buffer that can be prepared. | ||
| + | # Goto step 3. Repeat until the entire audio file has been played. | ||
| + | # For the last buffer, use <code>gaudioPlayWait()</code> to ensure that it has been played completely. | ||
<code>gaudioPause()</code> can be used to pause any current audio output. Resuming after a pause is done calling <code>gaudioPlay()</code> without any sample buffer reference. | <code>gaudioPause()</code> can be used to pause any current audio output. Resuming after a pause is done calling <code>gaudioPlay()</code> without any sample buffer reference. | ||
Calling <code>gaudioStop()</code> will completely stop a current audio playback. | Calling <code>gaudioStop()</code> will completely stop a current audio playback. | ||
| + | |||
| + | <code>gaudioPlayWait()</code> is used to make sure that the playback is complete. The function will poll for the given timeout (parameter) and return <code>TRUE</code> as soon as nothing is playing anymore or <code>FALSE</code> as soon as the timeout is exceeded. | ||
=== Volume === | === Volume === | ||
| Line 21: | Line 42: | ||
If your audio output devices does have an internal processor to decode audio formats, use <code>GAUDIO_PLAY_FORMAT_FILE</code> as the third parameter for <code>gaudioPlayInit()</code>. The GAUDIO module will simply pass the audio data unmodified to the audio device. | If your audio output devices does have an internal processor to decode audio formats, use <code>GAUDIO_PLAY_FORMAT_FILE</code> as the third parameter for <code>gaudioPlayInit()</code>. The GAUDIO module will simply pass the audio data unmodified to the audio device. | ||
| − | === | + | === GEVENT integration === |
| − | + | The GAUDIO module can optionally be configured to send events through the [[GEVENT]] module. If this feature is enabled by calling <code>gaudioPlayGetSource()</code>, the GAUDIO module will send the following events: | |
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Event !! Description | ||
| + | |- | ||
| + | | GAUDIO_PLAY_PLAYING || The audio output system has started to play. | ||
| + | |- | ||
| + | | GAUDIO_PLAY_FREEBLOCK || An audio buffer has been free'd. | ||
| + | |- | ||
| + | | GAUDIO_PLAY_LOSTEVENT || The last audio play event was lost. | ||
| + | |} | ||
== Record == | == Record == | ||
| − | + | Before any audio can be recorded, the audio device has to be initialized using <code>gaudioRecordInit()</code>. The audio channel, the sample format and the sample frequency are set by this function call. | |
| + | |||
| + | After successful initialization, audio recording can be started using <code>gaudioRecordStart()</code>. The recorded audio data can be retrieved using <code>gaudioRecordGetData()</code>. After processing, the user has to manually free the corresponding buffer using <code>gfxBufferRelease()</code>. | ||
| + | |||
| + | Calling <code>gaudioRecordStop()</code> will stop the audio recording. All audio recording data that has not yet been retrieved is automatically freed. | ||
| + | |||
| + | === GEVENT integration === | ||
| + | The GAUDIO module can optionally be configured to send events through the [[GEVENT]] module. If this feature is enabled by calling <code>gaudioRecordGetSource()</code>, the GAUDIO module will send the following events: | ||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Event !! Description | ||
| + | |- | ||
| + | | GAUDIO_RECORD_RECORDING || The audio input system is has started to record. | ||
| + | |- | ||
| + | | GAUDIO_RECORD_GOTBUFFER || An audio buffer is ready for processing. | ||
| + | |- | ||
| + | | GAUDIO_RECORD_STALL || The audio recording has been stalled due to no free buffers. | ||
| + | |- | ||
| + | |GAUDIO_RECORD_LOSTEVENT || The last audio record event was lost. | ||
| + | |} | ||
[[Category:Module]] | [[Category:Module]] | ||
Latest revision as of 15:50, 4 February 2016
The GAUDIO module provides high level API for handling audio in- and output. The module provides built-in decoders but does also allow to use external codecs. See #External decoder.
Several drivers are provided to play and record data through different hardware peripherals. Any thing from a simple PWM output up to an external codec is supported.
Contents
API reference
The API reference of the GAUDIO module can be found here.
Board file
The GAUDIO module requires a board file to communicate with the hardware. One board file is needed for audio output and one for audio input. See board file.
GDataBuffer
GDataBuffer is the container that is used to hold, manipulate and pass audio data. The buffer is provided and handled by the GQUEUE module.
The main idea is to create a pool of buffers using gfxBufferAlloc(num, size) where num is the number of buffers and size the size per buffer. The user does then fill the buffers sequentially with the audio data and passes them to gaudioPlay() - one after another. As soon as the audio data inside a buffer has been processed, the gaudioPlay() routine will automatically free the buffer so the user can fill it with new data.
For more information, see GQUEUE#Buffers.
Play back
Before any audio can be played, the audio device has to be initialized using gaudioPlayInit(). The audio channel, the sample format and the sample frequency are set by this function call. If using an external decoder, see #External_decoder.
After successful initialization, gaudioPlay() can be used to output audio data. The function takes a pointer to a GDataBuffer that holds the audio data to play in the format that has been set by the initialization call. The passed buffer will be freed by the function after the audio content of the buffer has been processed.
The following is an overview of the process:
- Allocate buffers using
gxfBufferAlloc() - Fill buffers with audio data
- Pass the first buffer to
gaudioPlay() - Wait until a buffer has been freed.
gfxBufferGet()will point to the next free buffer that can be prepared. - Goto step 3. Repeat until the entire audio file has been played.
- For the last buffer, use
gaudioPlayWait()to ensure that it has been played completely.
gaudioPause() can be used to pause any current audio output. Resuming after a pause is done calling gaudioPlay() without any sample buffer reference.
Calling gaudioStop() will completely stop a current audio playback.
gaudioPlayWait() is used to make sure that the playback is complete. The function will poll for the given timeout (parameter) and return TRUE as soon as nothing is playing anymore or FALSE as soon as the timeout is exceeded.
Volume
The playback volume can be adjusted using gaudioSetVolume(). However, not every driver might implement this feature. The function will return FALSE in that case.
For stereo devices, both channels are set to the same volume.
External decoder
If your audio output devices does have an internal processor to decode audio formats, use GAUDIO_PLAY_FORMAT_FILE as the third parameter for gaudioPlayInit(). The GAUDIO module will simply pass the audio data unmodified to the audio device.
GEVENT integration
The GAUDIO module can optionally be configured to send events through the GEVENT module. If this feature is enabled by calling gaudioPlayGetSource(), the GAUDIO module will send the following events:
| Event | Description |
|---|---|
| GAUDIO_PLAY_PLAYING | The audio output system has started to play. |
| GAUDIO_PLAY_FREEBLOCK | An audio buffer has been free'd. |
| GAUDIO_PLAY_LOSTEVENT | The last audio play event was lost. |
Record
Before any audio can be recorded, the audio device has to be initialized using gaudioRecordInit(). The audio channel, the sample format and the sample frequency are set by this function call.
After successful initialization, audio recording can be started using gaudioRecordStart(). The recorded audio data can be retrieved using gaudioRecordGetData(). After processing, the user has to manually free the corresponding buffer using gfxBufferRelease().
Calling gaudioRecordStop() will stop the audio recording. All audio recording data that has not yet been retrieved is automatically freed.
GEVENT integration
The GAUDIO module can optionally be configured to send events through the GEVENT module. If this feature is enabled by calling gaudioRecordGetSource(), the GAUDIO module will send the following events:
| Event | Description |
|---|---|
| GAUDIO_RECORD_RECORDING | The audio input system is has started to record. |
| GAUDIO_RECORD_GOTBUFFER | An audio buffer is ready for processing. |
| GAUDIO_RECORD_STALL | The audio recording has been stalled due to no free buffers. |
| GAUDIO_RECORD_LOSTEVENT | The last audio record event was lost. |
