audio.h

Go to the documentation of this file.

/************************************************************************//**
 * \file heivs/audio.h
 *
 * \brief ARMEBS4 audio
 *
 * \author marc dot pignat at hevs dot ch & Pascal Sartoretti (sap at hevs dot ch)
 * \addtogroup libheivs_stm32_audio Audio
 * \ingroup libheivs_stm32
 * @{
 *
 * == Full-duplex notes ==
 * Full duplex is possible usint Audio_Stream_* function.
 * * Audio_Stream_Play_Init must be called before Audio_Stream_Record_Init
 * * Audio_Stream_Stop will "pause" audio recording, but Audio_Stream_Pause can
 *   be used.
 * \see trunk/demos/audio_stream_demo
 *
 ***************************************************************************/

#ifndef HEIVS_AUDIO_H
#define HEIVS_AUDIO_H

#include "heivs/error.h"

#ifdef __cplusplus
    extern "C" {
#endif

/************************************************************************//**
 *  \brief Audio initialization
 *
 *  \param fs the sampling frequency (96000,48000,44100,32000,16000,8000)
 *  \param sample_size (32,24 or 16 bit)
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_Init(uint32_t fs, uint32_t sample_size);

/************************************************************************//**
 *  \brief Play a sine sound at a given frequency.
 *
 *  \param freq Frequency of sine. \see note_e
 *  \param duration duration in milliseconds
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_PlaySin(uint16_t freq, uint16_t duration);

/************************************************************************//**
 *  \brief Set the volume for speaker output
 *
 *  \param volume Volume to set (0 is mute, 255 is max)
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_SetVolumeSpeaker(uint8_t volume);

/************************************************************************//**
 *  \brief Set the volume for headphone output
 *
 *  \param volume Volume to set (0 is mute, 255 is max) *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_SetVolumeHeadphone(uint8_t volume);

/************************************************************************//**
 *  \brief Record a sound (polling mode)
 *
 *  \param dataBuf Data buffer of sound to record
 *  \param length byte length of the buffer
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_Record(int16_t * dataBuf, uint32_t length);

/************************************************************************//**
 *  \brief Play a sound (polling mode)
 *
 *  \param dataBuf Data buffer of sound to record
 *  \param length byte length of the buffer
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_Play(const int16_t * dataBuf, uint32_t length);

/************************************************************************//**
 *  \brief Play a sound (DMA version)
 *
 *  \param data the buffer
 *  \param length byte length of the buffer
 *  \param done_handler Function to be called when the sound has finished (will be called from interrupt context), can be NULL.
 *
 *  \return NO_ERROR for no problem, ERROR_AGAIN when busy, another error if any
 *
 *  \see Audio_DMA_Play_Status
 ***************************************************************************/
status_e Audio_DMA_Play(const void *data, uint32_t length, void (*done)(const void *));

/************************************************************************//**
 *  \brief Is Audio_DMA_Play finished?
 *
 *  \return ERROR_AGAIN if the sound has not finished playing, NO_ERROR when finished
 *
 *  \see Audio_DMA_Play
 ***************************************************************************/
status_e Audio_DMA_Play_Status(void);

/************************************************************************//**
 *  \brief Audio stream play initialization
 *
 *  \param length byte length of each buffer
 *  \param buffer0 the first buffer to be played
 *  \param buffer1 the second buffer to be played
 *  \param done the handler called after a buffer has been played. Called in interrupt context. can be NULL if not used
 *
 *  \return NO_ERROR for no problem
 *
 *  \warning buffer0 and buffer1 are expected to exist until \see Audio_Stream_Play_Stop
 *
 *  The DMA will play alternatively buffer0 and buffer1. \see Audio_Stream_Play
 *  will be used to replace the next buffer.
 *
 *  The stream will be *Paused* after this function
 *
 ***************************************************************************/
status_e Audio_Stream_Play_Init(uint32_t length, void *buffer0, void *buffer1, void (*done)(const void *));

/************************************************************************//**
 *  \brief Audio stream play buffer
 *  \param data buffer to be played
 *  \return NO_ERROR for no problem
 *
 *  \see Audio_Stream_Status
 *
 *  \warning This function will block unless Audio_Stream_Play_Status has returned NO_ERROR
 ***************************************************************************/
status_e Audio_Stream_Play(const void *data);

/************************************************************************//**
 *  \brief Audio stream play pause
 *
 *  \return NO_ERROR for no problem
 *
 *  \see Audio_Stream_Play for (re-)starting playback
 *
 * This function will in fact fill the output buffers with zeroes, effectively
 * muting the output.
 *
 ***************************************************************************/
status_e Audio_Stream_Play_Pause(void);

/************************************************************************//**
 *  \brief Audio stream playing stop
 *
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_Stream_Play_Stop(void);

/************************************************************************//**
 *  \brief Is Audio_Stream_Play ready for the next buffer?
 *
 *  \return ERROR_AGAIN if not ready, NO_ERROR when ready
 *
 *  \see Audio_DMA_Play
 ***************************************************************************/
status_e Audio_Stream_Play_Status(void);

/************************************************************************//**
 *  \brief Audio stream record initialization
 *
 *  \param length byte length of each buffer
 *  \param buffer0 the first buffer to be played
 *  \param buffer1 the second buffer to be played
 *  \param done handler called with the data recorded. Called in interrupt context
 *
 *  \return NO_ERROR for no problem
 *
 *  \warning buffer0 and buffer1 are expected to exist until \see Audio_Stream_Record_Stop
 *
 *  The DMA will record alternatively into buffer0 and buffer1.
 ***************************************************************************/
status_e Audio_Stream_Record_Init(uint32_t length, void *buffer0, void *buffer1, void(*done)(const void *));

/************************************************************************//**
 *  \brief Audio stream record stop
 *  \return NO_ERROR for no problem
 ***************************************************************************/
status_e Audio_Stream_Record_Stop(void);

/**
 * Music notes
 */
enum note_e
{
    DO      = 262,
    DOd     = 277,
    RE      = 294,
    MIb     = 311,
    MI      = 330,
    FA      = 349,
    FAd     = 370,
    SOL     = 392,
    SOLd    = 415,
    LA      = 440,
    SIb     = 466,
    SI      = 494,
};

#ifdef __cplusplus
    }
#endif

/**
 * @}
 */
#endif /* HEIVS_AUDIO_H */