Convenience functions to apply OnsetsDS to a chunk of audio data, or to an audio file.

Data Structures
struct	OnsetsDSAudioBuf
struct	OnsetsDSEvalData
Typedefs
typedef void(*)	ODSFileCallback (OnsetsDS *, double)
typedef void(*)	ODSDataCallback (OnsetsDSAudioBuf *, size_t)
Functions
void	onsetsds_init_audiodata (OnsetsDSAudioBuf *odsbuf, OnsetsDS *ods, size_t hopsize)
void	onsetsds_destroy_audiodata (OnsetsDSAudioBuf *odsbuf)
void	onsetsds_process_audiodata (OnsetsDSAudioBuf *odsbuf, float *data, size_t datalen, ODSDataCallback callback)
int	onsetsds_process_audiofile (OnsetsDSAudioBuf *odsbuf, const char *infilename, ODSFileCallback callback)
int	onsetsds_evaluate_audiofile (OnsetsDSAudioBuf *odsbuf, const char *infilename, const char *gtfilename, OnsetsDSEvalData *results)

---

Detailed Description

These functions are NOT required in order to use the core OnsetsDS functionality, but provide wrappers to make it easy to apply OnsetsDS to time-domain data (audio chunks, or audio files) without having to write the FFT processing yourself.

---

Typedef Documentation

typedef void(*) ODSFileCallback(OnsetsDS *, double)

When using onsetsds_process_audiofile(), this specifies that your callback function should take an OnsetsDS and a double as arguments, and return void. The double will be a time offset, from the beginning of the recording, at which the detected onset occurred.

typedef void(*) ODSDataCallback(OnsetsDSAudioBuf *, size_t)

When using onsetsds_process_audiodata(), this specifies that your callback function should take an OnsetsDSAudioBuf and a size_t as arguments, and return void. The size_t will be a sample offset at which the detected onset occurred, within the audio frame that was just passed in. (More than one onset per audio frame is possible, depending on how much data you're passing in at a time.)

---

Function Documentation

void onsetsds_init_audiodata	(	OnsetsDSAudioBuf *	odsbuf,
		OnsetsDS *	ods,
		size_t	hopsize
	)

Set up the data structures for use by onsetsds_process_audiodata().

Parameters:

	odsbuf	Will be set up nicely by this function.
	ods	Must have been initialised properly before calling this function.
	hopsize	Hop size in samples (256 is recommended)

void onsetsds_destroy_audiodata

(

OnsetsDSAudioBuf *

odsbuf

)

Correctly deallocate and destroy the OnsetsDSAudioBuf. Use this after onsetsds_process_audiofile(), or after you've finished running a series of onsetsds_process_audiodata() calls.

Parameters:

odsbuf

void onsetsds_process_audiodata	(	OnsetsDSAudioBuf *	odsbuf,
		float *	data,
		size_t	datalen,
		ODSDataCallback	callback
	)

Process a new chunk of audio data.

Parameters:

	odsbuf	Must have been initialised properly before calling this function, using onsetsds_init_audiodata()
	data	The *new* chunk of mono, time-domain audio data. Internal buffers will handle frame overlap etc. The size of the input data does *not* need to have a relation to the frame size or hop size.
	datalen	Size of the data buffer.
	callback	Name of your callback function, which will be called whenever an onset is detected. It will be passed the OnsetsDSAudioBuf object and (more importantly) the sample offset at which the onset was detected (i.e. a value between 0 and datalen).

int onsetsds_process_audiofile	(	OnsetsDSAudioBuf *	odsbuf,
		const char *	infilename,
		ODSFileCallback	callback
	)

Process an entire file of audio data. Returns 0 if successful (may fail if it can't find/open the audio file, for example).

Parameters:

	odsbuf	Must have been initialised properly before calling this function, using onsetsds_init_audiodata()
	infilename	The file to be loaded.
	callback	Name of your callback function, which will be called whenever an onset is detected. It will be passed the OnsetsDS object and (more importantly) the time offset in seconds at which the onset was detected (a double-precision-floating-point value between 0 and the duration of the audio file).

int onsetsds_evaluate_audiofile	(	OnsetsDSAudioBuf *	odsbuf,
		const char *	infilename,
		const char *	gtfilename,
		OnsetsDSEvalData *	results
	)

Process an entire file of audio data and compare the onset detector's output against a single "ground truth" annotation of where the onsets really are.

Parameters:

	odsbuf	Must have been initialised properly before calling this function, using onsetsds_init_audiodata()
	infilename	The file to be loaded.
	gtfilename	The file containing a text list of ground-truth annotations, one number per line, each being an onset's position in seconds from the beginning of the file. The numbers must be in ascending order. This format can be easily exported from programs such as Sonic Visualiser.
	results	Pointer to the OnsetsDSEvalData where the results should be written.