User Tools

Site Tools


en:tutorials:audio:sound-recording

This is an old revision of the document!


Sound Recording

Prerequisites

Right now you need the sound recording branch of orx in order to actually be able to record sound. However this is subject too change in the next couple of weeks. You can find the branch in the project's SVN repository: http://orx.svn.sourceforge.net/viewvc/orx/branches/SoundRecording/ 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.

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:

  orxSOUNDSYSTEM_RECORD_INFO record_info;
  record_info.u32ChannelNumber = 1;                  //number of channels, either 1 or 2
  record_info.u32SampleRate = 44100;                 //leave the sample rate like this unless you know what you're doing
  record_info.bCustomPollingFrequency = orxFALSE;    //this feature will be covered later
  record_info.bFixedBlockSize = orxFALSE;            //this feature will be covered later
  //now let's start recording:
  orxSoundSystem_StartRecordingToFile("sound.wav","sound", &record_info);
Now a file sound.wav will be created and recorded to. The format is always WAV. Once you think you have captured enough data you can stop recording like this:
  orxSoundSystem_StopRecording();
warning: orxSoundSystem_StopRecordingToFile will stop capturing to that file, but will not stop the actual sound capturing!

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:

static orxSTATUS orxFASTCALL SoundProcessingHandler(const orxEVENT *event) 
{
  switch(event->eType)
  {
    case orxEVENT_TYPE_SOUND:
      switch(event->eID)
      {
        case orxSOUND_EVENT_RECORD_PACKET:
          {
            orxSOUND_EVENT_PAYLOAD* payload = (orxSOUND_EVENT_PAYLOAD*)event->pstPayload;
            some_fancy_library_process(payload ->stRecordPacket.au16SampleArray, payload->stRecordPacket.u32SampleNumber, payload->stRecordPacket.dTimestamp);
          }
          break;
        case orxSOUND_EVENT_RECORD_START:
          some_fancy_library_initialize();
          break;
        case orxSOUND_EVENT_RECORD_STOP:
          some_fancy_library_finalize();
          break;
        default:
          // do nothing
          break;
      }
    default:
      // do nothing
      break;
  }
  return orxSTATUS_SUCCESS;
}
We have to register this handler to the game engine:
  orxEvent_AddHandler(orxEVENT_TYPE_SOUND, SoundProcessingHandler);
Now we can start to capture audio samples:
  orxSOUNDSYSTEM_RECORD_INFO record_info;
  record_info.u32ChannelNumber = 1;                  //number of channels, either 1 or 2
  record_info.u32SampleRate = 44100;                 //leave the sample rate like this unless you know what you're doing
  record_info.bCustomPollingFrequency = orxFALSE;    //this feature will be covered later
  record_info.bFixedBlockSize = orxFALSE;            //this feature will be covered later
  //now let's start recording:
  orxSoundSystem_StartRecording("sound", &record_info);
Afterwards first an event of the type orxSOUND_EVENT_RECORD_START will be created. After that each time new audio data is available an event of the type orxSOUND_EVENT_RECORD_PACKET will be created. You can access the raw audio data through the payload of the event. Beside the audio data it also contains the number of samples that were captured and the time at which the current samples were recorded(in seconds since starting the application). More precisely it's the timestamp of the first sample in the current package. Each audio sample is represented by a 16bit integer value. Once we are done we stop the capturing:
  orxSoundSystem_StopRecording();
Which will be followed by a orxSOUND_EVENT_RECORD_STOP event.

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. After calling orxSoundSystem_StartRecordingToFile the same events(containing the raw audio data), as described in the previous section, will be created. If you don't want to start both at the same time, meaning like you want to process the audio data the whole time but you want to record to a file only temporarily, you can just call orxSoundSystem_StartRecording at first and once you want to record to a file call orxSoundSystem_StartRecordingToFile. Once you are done capturing to a file just call orxSoundSystem_StopRecordingToFile. This will not stop the actual capturing, but just the recording to the file. Calling orxSoundSystem_StartRecording will both capturing and recording to a file!

Advanced settings explained

So what are those advanced settings about? There are basically two advanced settings: the polling frequency and the fixed block size. The polling frequency will determine how often the audio hardware is polled for new audio data. This means the higher the frequency is the less is the latency of the capturing. However if it is too high you will waste CPU time, because the likelihood that no data is available yet increases. So use this setting only if you really need it. By default everytime there is new audio data, no matter how many samples, an orxSOUND_EVENT_RECORD_PACKET event will be raised. This does not necessarily mean that, e.g. there will be an event for something like just 1 sample, because of hardware/driver limitations. If you don't want this behavior or if you always want the same number of samples you may specify a fixed block size.

API

Here is an overview of the API, until the doxygen documentation is uploaded:

/** Sound system record info
 */
typedef struct __orxSOUNDSYSTEM_RECORD_INFO_t
{
  orxU32                      u32SampleRate;           /**< The sample rate, e.g. 44100 Hertz */
  orxU32                      u32ChannelNumber;        /**< Number of channels. either mono(1) or stereo (2) */
  orxBOOL                     bCustomPollingFrequency; /**< Do you need a specific polling freq? (Usually you don't!) */
  orxFLOAT                    dPollingFrequency;       /**< The frequency at which the audio capturing device is polled. HighFreq = low latency. Be careful when also using a fixed block size. */
  orxBOOL                     bFixedBlockSize;         /**< Shall the audio data be fetched from the device in blocks of a fixed size? Only use it when you really need it! */
  orxU32                      u32BlockSize;            /**< Fixed number of samples that will be fetched at each poll. */
} orxSOUNDSYSTEM_RECORD_INFO;
 
/** Starts recording
 * @param[in]   _zName                                Name for the recorded sound
 * @param[in]   _pstInfo                              Recording information
 * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE
 */
orxSTATUS orxSoundSystem_StartRecording(const orxCHAR *_zName, const orxSOUNDSYSTEM_RECORD_INFO *_pstInfo);
 
/** Stops recording
 * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE
 */
orxSTATUS orxSoundSystem_StopRecording();
 
/** Is recording possbile on the current system?
 */
orxBOOL orxSoundSystem_RecordingAvailable();
 
/** Starts recording to a file. orxSoundSystem_StartRecording might have been called before, but it's not mandatory.
 * @param[in]   _zFileName                            Name of the resulting audio file.
 * @param[in]   _zName                                Name for the recorded sound
 * @param[in]   _pstInfo                              Recording information
 * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE
 */
orxSTATUS orxSoundSystem_StartRecordingToFile(const orxCHAR *_zFileName, const orxCHAR *_zName, const orxSOUNDSYSTEM_RECORD_INFO *_pstInfo);
 
/** Stops recording to a file. Does not stop the actual capturing! If you want to stop all capturing use orxSoundSystem_StopRecording instead.
 * @return orxSTATUS_SUCCESS / orxSTATSUS_FAILURE
 */
orxSTATUS orxSoundSystem_StopRecordingToFile();

en/tutorials/audio/sound-recording.1291720928.txt.gz · Last modified: 2017/05/30 00:50 (7 years ago) (external edit)