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.au16SampleArray, 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;
}
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

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean mattis dignissim eros in bibendum. Cras non libero urna. Nullam lorem nisi, vulputate nec iaculis ac, adipiscing sit amet velit. Aenean metus quam, tristique vitae eleifend at, hendrerit ut eros. Fusce metus felis, fermentum sed vestibulum nec, tempus id elit. Nullam feugiat varius magna, quis laoreet mi blandit vel. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nunc vel urna orci. Nullam libero diam, bibendum malesuada scelerisque quis, egestas at lectus. In metus libero, ultrices nec malesuada egestas, ultrices cursus lacus. Aliquam pellentesque pulvinar venenatis. Pellentesque malesuada pretium sodales. Etiam sed tortor a odio malesuada ornare.

Advanced settings explained

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean mattis dignissim eros in bibendum. Cras non libero urna. Nullam lorem nisi, vulputate nec iaculis ac, adipiscing sit amet velit. Aenean metus quam, tristique vitae eleifend at, hendrerit ut eros. Fusce metus felis, fermentum sed vestibulum nec, tempus id elit. Nullam feugiat varius magna, quis laoreet mi blandit vel. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nunc vel urna orci. Nullam libero diam, bibendum malesuada scelerisque quis, egestas at lectus. In metus libero, ultrices nec malesuada egestas, ultrices cursus lacus. Aliquam pellentesque pulvinar venenatis. Pellentesque malesuada pretium sodales. Etiam sed tortor a odio malesuada ornare.

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.1291719304.txt.gz · Last modified: 2017/05/30 00:50 (7 years ago) (external edit)