Bela
Real-time, ultra-low-latency audio and sensor processing system for BeagleBone Black
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Classes | Functions
Control and command line functions

Classes

struct  BelaInitSettings
 Structure containing initialisation parameters for the real-time audio control system. More...
 

Functions

BelaInitSettingsBela_InitSettings_alloc ()
 Allocate the data structure containing settings for Bela. More...
 
void Bela_InitSettings_free (BelaInitSettings *settings)
 De-allocate the data structure containing settings for Bela. More...
 
void Bela_defaultSettings (BelaInitSettings *settings)
 Initialise the data structure containing settings for Bela. More...
 
void Bela_userSettings (BelaInitSettings *settings)
 Initialise the data structure containing settings for Bela. More...
 
int Bela_getopt_long (int argc, char *const argv[], const char *customShortOptions, const struct option *customLongOptions, BelaInitSettings *settings)
 Get long options from command line argument list, including Bela standard options. More...
 
void Bela_usage ()
 Print usage information for Bela standard options. More...
 
void Bela_getVersion (int *major, int *minor, int *bugfix)
 Get the version of Bela you are running.
 
void Bela_setVerboseLevel (int level)
 Set level of verbose (debugging) printing. More...
 
BelaHw Bela_detectHw (BelaHwDetectMode mode)
 Detect what hardware we are running on. More...
 
int Bela_initAudio (BelaInitSettings *settings, void *userData)
 Initialise audio and sensor rendering environment. More...
 
int Bela_startAudio ()
 Begin processing audio and sensor data. More...
 
int Bela_runInSameThread ()
 Begin processing audio and sensor data in the same thread as the caller. More...
 
void Bela_stopAudio ()
 Stop processing audio and sensor data. More...
 
void Bela_cleanupAudio ()
 Clean up resources from audio and sensor processing. More...
 
void Bela_setUserData (void *newUserData)
 Set the userData variable, which is passed to setup(), render() and cleanup(). More...
 
void Bela_requestStop ()
 Tell the Bela program to stop. More...
 
int Bela_stopRequested ()
 Check whether the program should stop. More...
 

Detailed Description

These functions are used to initialise the Bela settings, process arguments from the command line, and start/stop the audio and sensor system.

Function Documentation

BelaInitSettings* Bela_InitSettings_alloc ( )

Allocate the data structure containing settings for Bela.

This function should be used to allocate the structure that holds initialisation data for Bela in order to preserve binary compatibility across versions of the library.

void Bela_InitSettings_free ( BelaInitSettings settings)

De-allocate the data structure containing settings for Bela.

This function should be used to de-allocate the structure that holds initialisation data for Bela.

Parameters
settingsPointer to structure to be de-allocated.
void Bela_defaultSettings ( BelaInitSettings settings)

Initialise the data structure containing settings for Bela.

This function should be called in main() before parsing any command-line arguments. It sets default values in the data structure which specifies the Bela settings, including frame sizes, numbers of channels, volume levels and other parameters.

Parameters
settingsStructure holding initialisation data for Bela.
void Bela_userSettings ( BelaInitSettings settings)

Initialise the data structure containing settings for Bela.

This function fwill be called by Bela_defaultSettings() after the settings have been initialied. It has weak linking so the user is free - but not forced to - define it. It can be used to override some of the default settings if the user code does not have access to the call to Bela_defaultSettings() (e.g.: because it is handled by the backend code).

Parameters
settingsStructure holding initialisation data for Bela.
Examples:
Extras/pru-pwm/render.cpp, and Extras/second-pru/render.cpp.
int Bela_getopt_long ( int  argc,
char *const  argv[],
const char *  customShortOptions,
const struct option *  customLongOptions,
BelaInitSettings settings 
)

Get long options from command line argument list, including Bela standard options.

This function should be used in main() to process command line options, in place of the standard library getopt_long(). Internally, it parses standard Bela command-line options, storing the results in the settings data structure. Any options which are not part of the Bela standard options will be returned, as they would normally be in getopt_long().

Parameters
argcNumber of command line options, as passed to main().
argvArray of command line options, as passed to main().
customShortOptionsList of short options to be parsed, analogous to getopt_long(). This list should not include any characters already parsed as part of the Bela standard options.
customLongOptionsList of long options to parsed, analogous to getopt_long(). This list should not include any long options already parsed as part of the Bela standard options.
settingsData structure holding initialisation settings for Bela. Any standard options parsed will automatically update this data structure.
Returns
Value of the next option parsed which is not a Bela standard option, or -1 when the argument list has been exhausted. Similar to the return value of getopt_long() except that Bela standard options are handled internally and not returned.
void Bela_usage ( )

Print usage information for Bela standard options.

This function should be called from your code wherever you wish to print usage information for the user. It will print usage information on Bela standard options, after which you can print usage information for your own custom options.

void Bela_setVerboseLevel ( int  level)

Set level of verbose (debugging) printing.

Parameters
levelVerbosity level of the internal Bela system. 0 by default; higher values will print more information. Presently all positive numbers produce the same level of printing.
BelaHw Bela_detectHw ( BelaHwDetectMode  mode)

Detect what hardware we are running on.

Parameters
modeHow to perform the detection. The behaviour is described in BelaHwDetectMode.
int Bela_initAudio ( BelaInitSettings settings,
void *  userData 
)

Initialise audio and sensor rendering environment.

This function prepares audio rendering in Bela. It should be called from main() sometime after command line option parsing has finished. It will initialise the rendering system, which in the process will result in a call to the user-defined setup() function.

Parameters
settingsData structure holding system settings, including numbers of channels, frame sizes, volume levels and other information.
userDataAn opaque pointer to a user-defined data structure which will be passed to setup(), render() and cleanup(). You can use this to pass custom information to the rendering functions, as an alternative to using global variables.
Returns
0 on success, or nonzero if an error occurred.
int Bela_startAudio ( )

Begin processing audio and sensor data.

This function will start the Bela audio/sensor system. After this function is called, the system will make periodic calls to render() until Bela_stopAudio() is called.

Returns
0 on success, or nonzero if an error occurred.
int Bela_runInSameThread ( )

Begin processing audio and sensor data in the same thread as the caller.

This function will start the Bela audio/sensor system. After this function is called, the system will make periodic calls to render() until Bela_stopAudio() is called.

Returns
0 on success, or nonzero if an error occurred.
void Bela_stopAudio ( )

Stop processing audio and sensor data.

This function will stop the Bela audio/sensor system. After this function returns, no further calls to render() will be issued.

void Bela_cleanupAudio ( )

Clean up resources from audio and sensor processing.

This function should only be called after Bela_stopAudio(). It will release any internal resources for audio and sensor processing. In the process, it will call the user-defined cleanup() function.

void Bela_setUserData ( void *  newUserData)

Set the userData variable, which is passed to setup(), render() and cleanup().

This function can be used to override userData after it has been set by Bela_initAudio().

Note
This function is experimental and may be removed in a future version.
void Bela_requestStop ( )

Tell the Bela program to stop.

This can be safely called anywhere in the code to tell the audio thread, and all threads monitoring Bela_stopRequested() that they should stop at the earliest occasion. The program will not stop immediately. If the render() function is currently running, it will keep running until it concludes its current execution, but will not be called again. The program's execution will stop when all threads have completed their execution. For this reason, all threads should check for Bela_stopRequested() to be notified when Bela_requestStop() has been called.

Examples:
Audio/record-audio/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, terminal-only/samples/render.cpp, and Trill/detect-all-devices/render.cpp.
int Bela_stopRequested ( )