This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
en:orx:tutorials:community:tdomhan:sound-recording [2010/12/09 10:13 (13 years ago)] – Minor alignment update iarwain | en:tutorials:audio:sound-recording [2022/03/27 13:42 (2 years ago)] (current) – Removed OpenAL reference iarwain | ||
---|---|---|---|
Line 2: | Line 2: | ||
===== Prerequisites ===== | ===== Prerequisites ===== | ||
- | Right now you need the **sound recording branch** | + | Right now you need the svn version |
- | Furthermore sound capturing is only implemented in the OpenAL sound plugin right now. We will now present some basic recipes for common tasks and then cover the advanced settings and the whole API later. | + | http:// |
+ | |||
+ | We will now present some basic recipes for common tasks and then cover the advanced settings and the whole API later. | ||
===== Capturing audio data to a file ===== | ===== Capturing audio data to a file ===== | ||
So let's say all you want to do is to capture some audio data from the default input device into a file. This is fairly easy and can be done like this: | So let's say all you want to do is to capture some audio data from the default input device into a file. This is fairly easy and can be done like this: | ||
<code c> | <code c> | ||
- | | + | // Let's start recording: |
- | record_info.u32ChannelNumber = 1; | + | |
- | | + | // _zName = " |
- | | + | // Its extension determines which file format |
- | | + | // _bWriteToFile = orxTRUE: we'll start writing to file immediately |
- | //now let's start recording: | + | // _u32SampleRate = 44100: 44100 samples will be recorded per second |
- | | + | |
</ | </ | ||
- | Now a file sound.wav will be created and recorded to. The format | + | A sound.wav |
+ | The supported file extensions/ | ||
+ | |||
+ | You can decide if you want to write the recorded data to the file with _bWriteToFile = orxTRUE/ | ||
+ | |||
+ | Passing 0 to _u32SampleRate and/or _u32ChannelNumber will use orx's default values for them. Defaults values are 44100Hz for the sampling rate and mono for the channel number. | ||
+ | |||
+ | Once you think you have captured enough data you can stop recording like this: | ||
<code c> | <code c> | ||
- | | + | |
</ | </ | ||
- | **warning: | ||
===== Processing audio data ===== | ===== Processing audio data ===== | ||
- | Let's say you want to do some fancy processing of the audio data, instead of recording it to a file. First we need to register a event handler, that will receive the raw audio data: | + | Let' |
+ | |||
+ | First we need an event handler, that will receive the raw audio samples: | ||
<code c> | <code c> | ||
static orxSTATUS orxFASTCALL SoundProcessingHandler(const orxEVENT *event) | static orxSTATUS orxFASTCALL SoundProcessingHandler(const orxEVENT *event) | ||
Line 32: | Line 42: | ||
switch(event-> | switch(event-> | ||
{ | { | ||
- | case orxSOUND_EVENT_RECORD_PACKET: | + | case orxSOUND_EVENT_RECORDING_PACKET: |
{ | { | ||
orxSOUND_EVENT_PAYLOAD* payload = (orxSOUND_EVENT_PAYLOAD*)event-> | orxSOUND_EVENT_PAYLOAD* payload = (orxSOUND_EVENT_PAYLOAD*)event-> | ||
- | some_fancy_library_process(payload ->stRecordPacket.au16SampleArray, payload-> | + | some_fancy_library_process(payload-> |
+ | |||
+ | payload-> | ||
} | } | ||
break; | break; | ||
- | case orxSOUND_EVENT_RECORD_START: | + | case orxSOUND_EVENT_RECORDING_START: |
some_fancy_library_initialize(); | some_fancy_library_initialize(); | ||
break; | break; | ||
- | case orxSOUND_EVENT_RECORD_STOP: | + | case orxSOUND_EVENT_RECORDING_STOP: |
some_fancy_library_finalize(); | some_fancy_library_finalize(); | ||
break; | break; | ||
Line 61: | Line 73: | ||
Now we can start to capture audio samples: | Now we can start to capture audio samples: | ||
<code c> | <code c> | ||
- | orxSOUNDSYSTEM_RECORD_INFO record_info; | ||
- | record_info.u32ChannelNumber = 1; //number of channels, either 1 or 2 | ||
- | record_info.u32SampleRate = 44100; | ||
- | record_info.bCustomPollingFrequency = orxFALSE; | ||
- | record_info.bFixedBlockSize = orxFALSE; | ||
//now let's start recording: | //now let's start recording: | ||
- | | + | |
</ | </ | ||
- | Afterwards first an event of the type orxSOUND_EVENT_RECORD_START | + | Afterwards, the first event our handler |
- | Once we are done we stop the capturing: | + | |
+ | Once again, when we are done we stop the capturing | ||
<code c> | <code c> | ||
- | | + | |
</ | </ | ||
- | Which will be followed by a orxSOUND_EVENT_RECORD_STOP | + | Which will be followed by a orxSOUND_EVENT_RECORDING_STOP |
===== Doing both: Capturing to a file and processing the audio data ===== | ===== Doing both: Capturing to a file and processing the audio data ===== | ||
- | So what if we want to do both, capturing the data to a file and process it at the same time? Well that's not a problem. | + | So what if we want to do both, capturing the data to a file and process it at the same time? Well that's not a problem. |
+ | We can specify for each sound packet if it needs to be recorded or not by changing payload-> | ||
- | ===== Advanced | + | We can also alter the samples directly in the payload array (payload-> |
- | So what are those advanced | + | If we want to use less samples, we need also to update their number (payload-> |
+ | |||
+ | If we need more space for our samples, we can't reuse the array pointed by the payload. Instead we can populate our own array and update the payload pointer and the sample number accordingly. | ||
+ | |||
+ | **NB: We can't use a stack allocated array for this as the array has to be valid till the next sound event we receive in our handler. | ||
+ | If we allocated dynamically this array, we'll be in charge of deleting when receiving a future sound event so as to not leak any memory.** | ||
+ | |||
+ | ===== Advanced | ||
+ | |||
+ | If we need more advanced | ||
+ | //NB: We can then process | ||
Line 87: | Line 106: | ||
Here is an overview of the API, until the doxygen documentation is updated: | Here is an overview of the API, until the doxygen documentation is updated: | ||
<code c> | <code c> | ||
- | /** Sound system record | + | /** Sound recording |
*/ | */ | ||
- | typedef struct | + | typedef struct |
{ | { | ||
- | orxU32 | + | orxU32 |
- | orxU32 | + | orxU32 |
- | orxBOOL | + | |
- | orxFLOAT | + | |
- | orxBOOL | + | |
- | orxU32 | + | |
- | } orxSOUNDSYSTEM_RECORD_INFO; | + | |
- | /** Starts | + | } orxSOUND_RECORDING_INFO; |
- | * @param[in] | + | |
- | * @param[in] | + | /** Sound recording |
- | * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE | + | |
*/ | */ | ||
- | orxSTATUS orxSoundSystem_StartRecording(const orxCHAR | + | typedef struct __orxSOUND_RECORDING_PACKET_t |
+ | { | ||
+ | orxBOOL | ||
+ | orxU32 | ||
+ | orxS16 | ||
+ | orxFLOAT | ||
- | /** Stops recording | + | } orxSOUND_RECORDING_PACKET; |
- | * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE | + | |
+ | /** Sound event payload | ||
*/ | */ | ||
- | orxSTATUS orxSoundSystem_StopRecording(); | + | typedef struct __orxSOUND_EVENT_PAYLOAD_t |
+ | { | ||
+ | const orxSTRING | ||
- | /** Is recording | + | union |
+ | { | ||
+ | orxSOUND | ||
+ | |||
+ | struct | ||
+ | { | ||
+ | orxSOUND_RECORDING_INFO | ||
+ | orxSOUND_RECORDING_PACKET stPacket; | ||
+ | } stRecording; | ||
+ | }; /**< Recording : 24 */ | ||
+ | |||
+ | } orxSOUND_EVENT_PAYLOAD; | ||
+ | |||
+ | /** Starts | ||
+ | * @param[in] | ||
+ | * @param[in] | ||
+ | * @param[in] | ||
+ | * @param[in] | ||
+ | * @return orxSTATUS_SUCCESS / orxSTATUS_FAILURE | ||
*/ | */ | ||
- | orxBOOL orxSoundSystem_RecordingAvailable(); | + | extern orxDLLAPI orxSTATUS orxFASTCALL |
- | /** Starts | + | /** Stops recording |
- | * @param[in] | + | * @return orxSTATUS_SUCCESS / orxSTATUS_FAILURE |
- | * @param[in] | + | |
- | * @param[in] | + | |
- | * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE | + | |
*/ | */ | ||
- | orxSTATUS | + | extern orxDLLAPI |
- | /** Stops recording | + | /** Is recording |
- | * @return | + | * @return |
*/ | */ | ||
- | orxSTATUS orxSoundSystem_StopRecordingToFile(); | + | extern orxDLLAPI orxBOOL orxFASTCALL |
</ | </ |