Audio file

Audio file module enables applications to read and write audio files. Supported formats are .wav, .ogg. More extension will be supported soon. Please contact us for more details.

  1. Inputs
    • AudioFileReader
    • SyncAudioFileReader
  2. Outputs
    • AudioFileWriter
    • SyncAudioFileWriter

Inputs

AudioFileReader

This input read a file on your drive and outputs its audio content. It provides commands to pause or resume reading.

WAV Files: must be monophonic and encoded at 48kHz/16bits.

OGG files: must be encoded at 48kHz. If not, consider changing “application/sample_rate”.

I/O Channel count Sub channel count
out 1 1 (MONO)

Construction

No arguments

Usage :

context.createInput(ID,AudioFileReader);

Parameters

Instanciation

  • filename (const char *) : path (with filename and extension) to the audio file to read. May be an absolute path or a relative path (relative to the executable location).

    This parameter is mapped by default to source/%src_id/file.

    Usage :

context.setParameter("source/7/filename","./hello.wav");	// using relative path
context.setParameter("source/7/filename","C:/path/to/hello.wav");	// using absolute path

  • buffer_size (unsigned int) : the length of audio buffers read by this input.

    This parameter is mapped by default to application/buffer_size.

    Usage :

context.setParameter("application/buffer_size",1024U);

  • start_on_awake (bool) : if set to TRUE, file is played when application starts, which is usefull for background sounds. Default value is FALSE (usefull for event sounds).

    This parameter is mapped by default to source/%src_id/start_on_awake.

    Usage :

context.setParameter("source/5/start_on_awake",true);
Runtime

  • loop (bool) : if set to TRUE, audiofile will be played in loops, which may prove usefull for background sounds. Default is FALSE.

    This parameter is mapped by default to source/%src_id/loop.

    Usage with default vars and patterns:

    context.setParameter("source/8/loop",true);

Commands

  • play : resume file reading.

    This parameter is mapped by default to source/%src_id/play.

    Usage :

context.sendCommand("source/10/play");

  • pause : pause file reading. Reader head remains at its current position.

    This parameter is mapped by default to source/%src_id/pause.

    Usage :

context.sendCommand("source/11/pause");

  • stop : stop file reading and place reader head to the beginning of the file.

    This parameter is mapped by default to source/%src_id/stop.

    Usage :

    context.sendCommand("source/5/stop");

  • seek (int) : move the header head N samples afer begin. Seek doesn’t start or stop file reading.

    This parameter is mapped by default to source/%src_id/seek.

    TODO requires revision

    Usage :

    context.sendCommand("source/3/seek",4800);

Callbacks

  • at_end : this callback is called when file reading reaches the end of the file. You can use it to notify your application and trigger an event.

    This parameter is mapped by default to source/%src_id/at_end.

    Usage :

    context.setCallback("source/ID/at_end",&atEndCallback); // atEndCallback is an argument-less function returning void.

TODO add AudioFileWriter

TODO add SyncAudioFileReader/Writer


Classes

AudioClipLibrary

AudioClipLibrary helps you manage audio files and get useful information such as length, samplerate, etc.

Construction

AudioClipLibrary();

Creates an empty audio clip library.

Methods

void registerClip(const char* _id, const char* _filename)

Register the audio file located at _filename under the identifier _id. Will set an error on the context if the audio file could not be opened.

Usage: ```cpp  AudioClipLibrary myLibrary; myLibrary.registerClip("hello","/path/to/hello.wav") ```

float getSampleRate(const char* _id)

Returns the samplerate of the clip with identifier _id

int getLengthInSample(const char* _id)

Returns the length, in samples, of the clip with identifier _id

float getLengthInSeconds(const char* _id)

Returns the length, in seconds, of the clip with identifier _id

int getChannelCount(const char* _id)

Returns the number of channels of the clip with identifier _id

bool hasClip(const char* _id)

Returns true is the library contains a clip with id _id


Usage:

AudioClipLibrary myLibrary;
myLibrary.registerClip("hello","/path/to/hello.wav");

if(myLibrary.hasClip("hello")){
	std::cout << "Clip duration is " << myLibrary.getLengthInSeconds("hello") << " seconds." << std::endl;
}else{
	// It could be a good idea to check error on Context
}

Code samples

For more code samples, see Audio File samples

C++ API Samples

AudioFile simple application

This sample connects an audio file reader to computer output using OpenAL drivers.

Please note this sample doesn’t handle errors for code clarity.

[...]


enum:int{fileId = 0,outputId};

AudiostackContext context;
context.setLicenseKeyFromFile("LICENSE.aslc");
CoreAudioFileExtension::Load(context->impl);	// Load extension, allows to use inputs/outputs and helpers contained in the extension

context.createInput(fileId,AudioFileReader,"FILE.wav");
// file is a mono, 48kHz/16bits wav file located on disk
// OR context.createInput(0,AudioFileReader,"KEY") if in server
context.createOutput(outputId,OpenALOutput,false);
// Output is mono, in order to accept mono file.

context.setParameter("source/0/loop",true);             // file will play in loop
context.setParameter("source/0/start_on_awake",true);   // start file reading automatically

context.connect(fileId,outputId);

context.play();

char c;
do{
	std::cout<<"Press r to play, p to pause and s to stop. Press q to quit."<<std::endl;
	std::cin>>c;

	switch(c){
	case 'r':
		context.sendCommand("source/0/play");
		break;

	case 'p':
		context.sendCommand("source/0/pause");
		break;

	case 's':
		context.sendCommand("source/0/stop");
		break;
	}
}while(c!='q');

context.stop();

[...]

AudioFile callbacks

This sample provides hints to use callbacks on file reader.

In this use case, the application stops once the file reading reaches end of file.

static bool mustStop = false;

void atEndCallback(){
	std::cout<<"Callback received"<<std::endl;
	mustStop = true;
}

[...]

enum:int{fileId=0,outputId=1};

AudiostackContext context;
context.setLicenseKeyFromFile("LICENSE_FILE.aslc");
CoreAudioFileExtension::Load(context->impl);	// Load extension, allows to use inputs/outputs and helpers contained in the extension

context.createInput(fileId,AudioFileReader,"FILE.wav");
context.createOutput(outputId,OpenALOutput,false);

context.setParameter("source/0/loop",false);			// File will not loop (otherwise, end callback cannot be called)
context.setParameter("source/0/start_on_awake",true);

context.setCallback("source/0/at_end",&atEndCallback);
// at_end callback from our will call atEndCallback method

context.connect(fileId,outputId);
context.play();
	
do{
	
}while(!mustStop);

context.stop();

[...]

For more code samples, see Audio File samples