290 lines
10 KiB
C
290 lines
10 KiB
C
/*
|
|
* This file is subject to the terms of the GFX License. If a copy of
|
|
* the license was not distributed with this file, you can obtain one at:
|
|
*
|
|
* http://ugfx.io/license.html
|
|
*/
|
|
|
|
/**
|
|
* @file src/gaudio/gaudio.h
|
|
*
|
|
* @addtogroup GAUDIO
|
|
*
|
|
* @brief Module to handle audio recording and play-back
|
|
*
|
|
* @{
|
|
*/
|
|
|
|
#ifndef _GAUDIO_H
|
|
#define _GAUDIO_H
|
|
|
|
#include "../../gfx.h"
|
|
|
|
#if GFX_USE_GAUDIO || defined(__DOXYGEN__)
|
|
|
|
/* Include the driver defines */
|
|
#if GAUDIO_NEED_PLAY
|
|
#include "gaudio_play_config.h"
|
|
#endif
|
|
#if GAUDIO_NEED_RECORD
|
|
#include "gaudio_record_config.h"
|
|
#endif
|
|
|
|
/*===========================================================================*/
|
|
/* Type definitions */
|
|
/*===========================================================================*/
|
|
|
|
// Event types for GAUDIO
|
|
#define GEVENT_AUDIO_PLAY (GEVENT_GAUDIO_FIRST+0)
|
|
#define GEVENT_AUDIO_RECORD (GEVENT_GAUDIO_FIRST+1)
|
|
|
|
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
|
|
/**
|
|
* @brief The Audio play event structure.
|
|
* @{
|
|
*/
|
|
typedef struct GEventAudioPlay_t {
|
|
/**
|
|
* @brief The type of this event (GEVENT_AUDIO_PLAY)
|
|
*/
|
|
GEventType type;
|
|
/**
|
|
* @brief The event flags
|
|
*/
|
|
gU16 flags;
|
|
/**
|
|
* @brief The event flag values.
|
|
* @{
|
|
*/
|
|
#define GAUDIO_PLAY_LOSTEVENT 0x0001 /**< @brief The last GEVENT_AUDIO_PLAY event was lost */
|
|
#define GAUDIO_PLAY_PLAYING 0x0002 /**< @brief The audio out system is currently playing */
|
|
#define GAUDIO_PLAY_FREEBLOCK 0x0004 /**< @brief An audio buffer has been freed */
|
|
/** @} */
|
|
} GEventAudioPlay;
|
|
/** @} */
|
|
|
|
/**
|
|
* @brief The Audio record event structure.
|
|
* @{
|
|
*/
|
|
typedef struct GEventAudioRecord_t {
|
|
/**
|
|
* @brief The type of this event (GEVENT_AUDIO_RECORD)
|
|
*/
|
|
GEventType type;
|
|
/**
|
|
* @brief The event flags
|
|
*/
|
|
gU16 flags;
|
|
/**
|
|
* @brief The event flag values.
|
|
* @{
|
|
*/
|
|
#define GAUDIO_RECORD_LOSTEVENT 0x0001 /**< @brief The last GEVENT_AUDIO_IN event was lost */
|
|
#define GAUDIO_RECORD_RECORDING 0x0002 /**< @brief The audio recording system is currently recording */
|
|
#define GAUDIO_RECORD_GOTBUFFER 0x0004 /**< @brief An audio buffer is ready for processing */
|
|
#define GAUDIO_RECORD_STALL 0x0008 /**< @brief The recording process has stalled due to no free buffers */
|
|
/** @} */
|
|
} GEventAudioRecord;
|
|
/** @} */
|
|
#endif
|
|
|
|
/*===========================================================================*/
|
|
/* External declarations. */
|
|
/*===========================================================================*/
|
|
|
|
#if GAUDIO_NEED_PLAY || defined(__DOXYGEN__)
|
|
/**
|
|
* @brief Set the audio device to play on the specified channel and with the specified
|
|
* sample frequency.
|
|
* @return gTrue is successful, gFalse if the driver doesn't accept those parameters.
|
|
*
|
|
* @param[in] channel The audio output channel to use. Can be set from 0 to GAUDIO_PLAY_NUM_CHANNELS - 1
|
|
* @param[in] frequency The audio sample rate in samples per second
|
|
* @param[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.
|
|
* @note Only one channel can be playing at a time. Calling this will stop any
|
|
* currently playing channel.
|
|
*
|
|
* @api
|
|
*/
|
|
gBool gaudioPlayInit(gU16 channel, gU32 frequency, ArrayDataFormat format);
|
|
|
|
/**
|
|
* @brief Play the specified sample data.
|
|
* @details The sample data is output to the audio channel. On completion the buffer is returned to the free-list.
|
|
* @pre @p gaudioPlayInit must have been called first to set the channel and sample frequency.
|
|
*
|
|
* @param[in] paud The audio sample buffer to play. It can be NULL (used to restart paused audio)
|
|
*
|
|
* @note Calling this will cancel any pause.
|
|
* @note Before calling this function the len field of the GDataBuffer structure must be
|
|
* specified (in bytes).
|
|
* @note For stereo channels the sample data is interleaved in the buffer.
|
|
* @note 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.
|
|
*
|
|
* @api
|
|
*/
|
|
void gaudioPlay(GDataBuffer *paud);
|
|
|
|
/**
|
|
* @brief Pause any currently playing sounds.
|
|
*
|
|
* @note If nothing is currently playing this routine does nothing. To restart playing call @p gaudioPlay()
|
|
* with or without a new sample buffer.
|
|
* @note Some drivers will not respond until a buffer boundary.
|
|
*
|
|
* @api
|
|
*/
|
|
void gaudioPlayPause(void);
|
|
|
|
/**
|
|
* @brief Stop any currently playing sounds.
|
|
*
|
|
* @note This stops any playing sounds and returns any currently queued buffers back to the free-list.
|
|
* @note Some drivers will not respond until a buffer boundary.
|
|
*
|
|
* @api
|
|
*/
|
|
void gaudioPlayStop(void);
|
|
|
|
/**
|
|
* @brief Set the output volume.
|
|
* @return gTrue if successful.
|
|
*
|
|
* @param[in] vol 0->255 (0 = muted)
|
|
*
|
|
* @note Some drivers may not support this. They will return gFalse.
|
|
* @note For stereo devices, both channels are set to the same volume.
|
|
*
|
|
* @api
|
|
*/
|
|
gBool gaudioPlaySetVolume(gU8 vol);
|
|
|
|
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
|
|
/**
|
|
* @brief Turn on sending results to the GEVENT sub-system.
|
|
* @details 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 @p gaudioPlayInit() again.
|
|
* @note The audio output is capable of signaling via this method and other methods
|
|
* at the same time.
|
|
*
|
|
* @return The GSourceHandle
|
|
*
|
|
* @api
|
|
*/
|
|
GSourceHandle gaudioPlayGetSource(void);
|
|
#endif
|
|
|
|
/**
|
|
* @brief Wait for any currently playing sounds to complete
|
|
* @return gTrue if there is now nothing playing or gFalse if the timeout is exceeded
|
|
*
|
|
* @param[in] ms The maximum amount of time in milliseconds to wait for playing to complete.
|
|
*
|
|
* @api
|
|
*/
|
|
gBool gaudioPlayWait(gDelay ms);
|
|
#endif
|
|
|
|
#if GAUDIO_NEED_RECORD || defined(__DOXYGEN__)
|
|
/**
|
|
* @brief Initialise (but not start) the Audio Recording sub-system.
|
|
* @details Returns gFalse for an invalid channel or other invalid parameter.
|
|
*
|
|
* @param[in] channel The channel to convert. Can be set from 0 to GAUDIO_RECORD_NUM_CHANNELS - 1
|
|
* @param[in] frequency The sample frequency
|
|
* @param[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.
|
|
* @note 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.
|
|
* @note 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.
|
|
* @note 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.
|
|
*
|
|
* @return gFalse if invalid channel or parameter
|
|
*
|
|
* @api
|
|
*/
|
|
gBool gaudioRecordInit(gU16 channel, gU32 frequency, ArrayDataFormat format);
|
|
|
|
/**
|
|
* @brief Start the audio recording.
|
|
* @pre It must have been initialised first with @p gaudioRecordInit()
|
|
*
|
|
* @api
|
|
*/
|
|
void gaudioRecordStart(void);
|
|
|
|
/**
|
|
* @brief Stop the audio recording.
|
|
*
|
|
* @note All audio recording data that has not yet been retrieved is automatically
|
|
* returned to the free-list.
|
|
* @api
|
|
*/
|
|
void gaudioRecordStop(void);
|
|
|
|
/**
|
|
* @brief Get a filled audio buffer from the recording list
|
|
* @return A GDataBuffer pointer or NULL if the timeout is exceeded
|
|
*
|
|
* @param[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 @p gaudioPlay() or
|
|
* directly using @p gfxBufferRelease().
|
|
* @note 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.
|
|
*
|
|
* @api
|
|
*/
|
|
GDataBuffer *gaudioRecordGetData(gDelay ms);
|
|
|
|
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
|
|
/**
|
|
* @brief Turn on sending results to the GEVENT sub-system.
|
|
* @details 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 @p gaudioRecordInit() again.
|
|
* @note The audio input is capable of signaling via this and other methods
|
|
* at the same time.
|
|
*
|
|
* @return The GSourceHandle
|
|
*
|
|
* @api
|
|
*/
|
|
GSourceHandle gaudioRecordGetSource(void);
|
|
#endif
|
|
#endif
|
|
|
|
#endif /* GFX_USE_GAUDIO */
|
|
|
|
#endif /* _GAUDIO_H */
|
|
/** @} */
|
|
|