version 2.8
gaudio.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gaudio/gaudio.h
10  *
11  * @addtogroup GAUDIO
12  *
13  * @brief Module to handle audio recording and play-back
14  *
15  * @{
16  */
17 
18 #ifndef _GAUDIO_H
19 #define _GAUDIO_H
20 
21 #include "../../gfx.h"
22 
23 #if GFX_USE_GAUDIO || defined(__DOXYGEN__)
24 
25 /* Include the driver defines */
26 #if GAUDIO_NEED_PLAY
27  #include "gaudio_play_config.h"
28 #endif
29 #if GAUDIO_NEED_RECORD
30  #include "gaudio_record_config.h"
31 #endif
32 
33 /*===========================================================================*/
34 /* Type definitions */
35 /*===========================================================================*/
36 
37 // Event types for GAUDIO
38 #define GEVENT_AUDIO_PLAY (GEVENT_GAUDIO_FIRST+0)
39 #define GEVENT_AUDIO_RECORD (GEVENT_GAUDIO_FIRST+1)
40 
41 #if GFX_USE_GEVENT || defined(__DOXYGEN__)
42  /**
43  * @brief The Audio play event structure.
44  * @{
45  */
46  typedef struct GEventAudioPlay_t {
47  /**
48  * @brief The type of this event (GEVENT_AUDIO_PLAY)
49  */
50  GEventType type;
51  /**
52  * @brief The event flags
53  */
54  uint16_t flags;
55  /**
56  * @brief The event flag values.
57  * @{
58  */
59  #define GAUDIO_PLAY_LOSTEVENT 0x0001 /**< @brief The last GEVENT_AUDIO_PLAY event was lost */
60  #define GAUDIO_PLAY_PLAYING 0x0002 /**< @brief The audio out system is currently playing */
61  #define GAUDIO_PLAY_FREEBLOCK 0x0004 /**< @brief An audio buffer has been freed */
62  /** @} */
64  /** @} */
65 
66  /**
67  * @brief The Audio record event structure.
68  * @{
69  */
70  typedef struct GEventAudioRecord_t {
71  /**
72  * @brief The type of this event (GEVENT_AUDIO_RECORD)
73  */
74  GEventType type;
75  /**
76  * @brief The event flags
77  */
78  uint16_t flags;
79  /**
80  * @brief The event flag values.
81  * @{
82  */
83  #define GAUDIO_RECORD_LOSTEVENT 0x0001 /**< @brief The last GEVENT_AUDIO_IN event was lost */
84  #define GAUDIO_RECORD_RECORDING 0x0002 /**< @brief The audio recording system is currently recording */
85  #define GAUDIO_RECORD_GOTBUFFER 0x0004 /**< @brief An audio buffer is ready for processing */
86  #define GAUDIO_RECORD_STALL 0x0008 /**< @brief The recording process has stalled due to no free buffers */
87  /** @} */
89  /** @} */
90 #endif
91 
92 /*===========================================================================*/
93 /* External declarations. */
94 /*===========================================================================*/
95 
96 #ifdef __cplusplus
97 extern "C" {
98 #endif
99 
100 #if GAUDIO_NEED_PLAY || defined(__DOXYGEN__)
101  /**
102  * @brief Set the audio device to play on the specified channel and with the specified
103  * sample frequency.
104  * @return TRUE is successful, FALSE if the driver doesn't accept those parameters.
105  *
106  * @param[in] channel The audio output channel to use. Can be set from 0 to GAUDIO_PLAY_NUM_CHANNELS - 1
107  * @param[in] frequency The audio sample rate in samples per second
108  * @param[in] format The audio sample format
109  *
110  * @note Some channels are mono, and some are stereo. See your driver config file
111  * to determine which channels to use and whether they are stereo or not.
112  * @note Only one channel can be playing at a time. Calling this will stop any
113  * currently playing channel.
114  *
115  * @api
116  */
117  bool_t gaudioPlayInit(uint16_t channel, uint32_t frequency, ArrayDataFormat format);
118 
119  /**
120  * @brief Play the specified sample data.
121  * @details The sample data is output to the audio channel. On completion the buffer is returned to the free-list.
122  * @pre @p gaudioPlayInit must have been called first to set the channel and sample frequency.
123  *
124  * @param[in] paud The audio sample buffer to play. It can be NULL (used to restart paused audio)
125  *
126  * @note Calling this will cancel any pause.
127  * @note Before calling this function the len field of the GDataBuffer structure must be
128  * specified (in bytes).
129  * @note For stereo channels the sample data is interleaved in the buffer.
130  * @note This call returns before the data has completed playing. Subject to available buffers (which
131  * can be obtained from the free-list), any number of buffers may be played. They will be queued
132  * for playing in the order they are supplied to this routine and played when previous buffers are
133  * complete. In this way continuous playing can be obtained without audio gaps.
134  *
135  * @api
136  */
137  void gaudioPlay(GDataBuffer *paud);
138 
139  /**
140  * @brief Pause any currently playing sounds.
141  *
142  * @note If nothing is currently playing this routine does nothing. To restart playing call @p gaudioPlay()
143  * with or without a new sample buffer.
144  * @note Some drivers will not respond until a buffer boundary.
145  *
146  * @api
147  */
148  void gaudioPlayPause(void);
149 
150  /**
151  * @brief Stop any currently playing sounds.
152  *
153  * @note This stops any playing sounds and returns any currently queued buffers back to the free-list.
154  * @note Some drivers will not respond until a buffer boundary.
155  *
156  * @api
157  */
158  void gaudioPlayStop(void);
159 
160  /**
161  * @brief Set the output volume.
162  * @return TRUE if successful.
163  *
164  * @param[in] vol 0->255 (0 = muted)
165  *
166  * @note Some drivers may not support this. They will return FALSE.
167  * @note For stereo devices, both channels are set to the same volume.
168  *
169  * @api
170  */
171  bool_t gaudioPlaySetVolume(uint8_t vol);
172 
173  #if GFX_USE_GEVENT || defined(__DOXYGEN__)
174  /**
175  * @brief Turn on sending results to the GEVENT sub-system.
176  * @details Returns a GSourceHandle to listen for GEVENT_AUDIO_OUT events.
177  *
178  * @note The audio output will not use the GEVENT system unless this is
179  * called first. This saves processing time if the application does
180  * not want to use the GEVENT sub-system for audio output.
181  * Once turned on it can only be turned off by calling @p gaudioPlayInit() again.
182  * @note The audio output is capable of signaling via this method and other methods
183  * at the same time.
184  *
185  * @return The GSourceHandle
186  *
187  * @api
188  */
189  GSourceHandle gaudioPlayGetSource(void);
190  #endif
191 
192  /**
193  * @brief Wait for any currently playing sounds to complete
194  * @return TRUE if there is now nothing playing or FALSE if the timeout is exceeded
195  *
196  * @param[in] ms The maximum amount of time in milliseconds to wait for playing to complete.
197  *
198  * @api
199  */
200  bool_t gaudioPlayWait(delaytime_t ms);
201 #endif
202 
203 #if GAUDIO_NEED_RECORD || defined(__DOXYGEN__)
204  /**
205  * @brief Initialise (but not start) the Audio Recording sub-system.
206  * @details Returns FALSE for an invalid channel or other invalid parameter.
207  *
208  * @param[in] channel The channel to convert. Can be set from 0 to GAUDIO_RECORD_NUM_CHANNELS - 1
209  * @param[in] frequency The sample frequency
210  * @param[in] format The audio sample format requested
211  *
212  * @note Only one channel is active at a time. If an audio input is running it will be stopped.
213  * The Event subsystem is disconnected from the audio subsystem and any binary semaphore
214  * event is forgotten.
215  * @note Some channels may be stereo channels which return twice as much sample data with
216  * the left and right channel data interleaved. Other channels may be mono channels.
217  * Where stereo channels exist the low level driver may also
218  * offer the left and right channels separately.
219  * @note Due to a bug in Chibi-OS each buffer on the free-list must contain an even number of
220  * samples and for stereo devices it must hold a number of samples that is evenly divisible by 4.
221  * This requirement applies only to ChibiOS where the audio driver uses
222  * a ChibiOS hal driver like the cpu ADC driver. This applies even it is used indirectly via
223  * the uGFX GADC driver.
224  * @note The number of samples for stereo devices will be double the number of conversions.
225  * Make sure you allocate your buffers large enough. Each channel is then interleaved
226  * into the provided buffer.
227  *
228  * @return FALSE if invalid channel or parameter
229  *
230  * @api
231  */
232  bool_t gaudioRecordInit(uint16_t channel, uint32_t frequency, ArrayDataFormat format);
233 
234  /**
235  * @brief Start the audio recording.
236  * @pre It must have been initialised first with @p gaudioRecordInit()
237  *
238  * @api
239  */
240  void gaudioRecordStart(void);
241 
242  /**
243  * @brief Stop the audio recording.
244  *
245  * @note All audio recording data that has not yet been retrieved is automatically
246  * returned to the free-list.
247  * @api
248  */
249  void gaudioRecordStop(void);
250 
251  /**
252  * @brief Get a filled audio buffer from the recording list
253  * @return A GDataBuffer pointer or NULL if the timeout is exceeded
254  *
255  * @param[in] ms The maximum amount of time in milliseconds to wait for data if some is not currently available.
256  *
257  * @note After processing the audio data, your application must return the buffer to the free-list so that
258  * it can be used to record more audio into. This can be done via the play list using @p gaudioPlay() or
259  * directly using @p gfxBufferRelease().
260  * @note A buffer may be returned to the free-list before you have finished processing it provided you finish
261  * processing it before GADC re-uses it. This is useful when RAM usage is critical to reduce the number
262  * of buffers required. It works before the free list is a FIFO queue and therefore buffers are kept
263  * in the queue as long as possible before they are re-used.
264  *
265  * @api
266  */
267  GDataBuffer *gaudioRecordGetData(delaytime_t ms);
268 
269  #if GFX_USE_GEVENT || defined(__DOXYGEN__)
270  /**
271  * @brief Turn on sending results to the GEVENT sub-system.
272  * @details Returns a GSourceHandle to listen for GEVENT_AUDIO_RECORD events.
273  *
274  * @note Audio recording will not use the GEVENT system unless this is
275  * called first. This saves processing time if the application does
276  * not want to use the GEVENT sub-system for audio recording.
277  * Once turned on it can only be turned off by calling @p gaudioRecordInit() again.
278  * @note The audio input is capable of signaling via this and other methods
279  * at the same time.
280  *
281  * @return The GSourceHandle
282  *
283  * @api
284  */
285  GSourceHandle gaudioRecordGetSource(void);
286  #endif
287 #endif
288 
289 #ifdef __cplusplus
290 }
291 #endif
292 
293 #endif /* GFX_USE_GAUDIO */
294 
295 #endif /* _GAUDIO_H */
296 /** @} */
297 
bool_t gaudioRecordInit(uint16_t channel, uint32_t frequency, ArrayDataFormat format)
Initialise (but not start) the Audio Recording sub-system.
struct GEventAudioPlay_t GEventAudioPlay
The Audio play event structure.
GDataBuffer * gaudioRecordGetData(delaytime_t ms)
Get a filled audio buffer from the recording list.
A Data Buffer Queue.
Definition: gqueue.h:78
GEventType type
The type of this event (GEVENT_AUDIO_RECORD)
Definition: gaudio.h:74
struct GEventAudioRecord_t GEventAudioRecord
The Audio record event structure.
bool_t gaudioPlayWait(delaytime_t ms)
Wait for any currently playing sounds to complete.
uint16_t flags
The event flags.
Definition: gaudio.h:78
GEventType type
The type of this event (GEVENT_AUDIO_PLAY)
Definition: gaudio.h:50
void gaudioRecordStop(void)
Stop the audio recording.
bool_t gaudioPlaySetVolume(uint8_t vol)
Set the output volume.
void gaudioPlay(GDataBuffer *paud)
Play the specified sample data.
GSourceHandle gaudioPlayGetSource(void)
Turn on sending results to the GEVENT sub-system.
uint16_t flags
The event flags.
Definition: gaudio.h:54
GSourceHandle gaudioRecordGetSource(void)
Turn on sending results to the GEVENT sub-system.
void gaudioRecordStart(void)
Start the audio recording.
enum ArrayDataFormat_e ArrayDataFormat
Sample data formats.
void gaudioPlayPause(void)
Pause any currently playing sounds.
The Audio record event structure.
Definition: gaudio.h:70
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...
The Audio play event structure.
Definition: gaudio.h:46
void gaudioPlayStop(void)
Stop any currently playing sounds.