These bindings are compatible with top of tree LabSound. They will also work with upcoming release 1.3.0.
copyright (c) 2022- Nick Porcino MIT License
To build the demo, install LabSound. Installing LabSound will also install libnyquist. Use cmake to configure this project, with a CMAKE_SYSTEM_PREFIX set to the install prefix used for LabSound.
To use the bindings in your own project, include labsound-c.cpp into your project directly, and also link to libnyquist and LabSound.
Strings are supplied to labsound-c via string slices. These are compatible with all languages you are likely to bind LabSound to, as there is no requirement that the string be zero terminated.
Although labsound-c.cpp is implemented in C++, the interface in labsound-c.h exposes symbols for C.
typedef struct {
const char* start;
const char* end;
} ls_StringSlice;
There's an array of string slices ~
typedef struct {
ls_StringSlice* names;
int count;
} ls_NameArray;
For C users, there is a convenience function ~
#define ls_cstr(s) ls_StringSlice { (s), strlen(s) }
Time is passed in a simple struct ~
typedef struct {
float t;
} ls_Seconds;
There are a variety of opaque lsc objects that the labsound-c interfaces will consume.
struct ls_Pin, ls_Node, ls_Connection, ls_BusData;
There are a few enumerations ~
typedef enum {
ls_PinInvalid = 0,
ls_PinInput, ls_PinOutput, ls_PinParam, ls_PinSetting
} ls_PinKind;
typedef enum {
ls_Invalid = 0,
ls_String, ls_Path, ls_Bool, ls_Int, ls_Float, ls_Bus, ls_Enum
} ls_PinDataType;
There are some housekeeping routines. You'll need to create and release the LabSoundAPI_1_0 interface object, and once per frame call ls_idle
to give the engine a chance to do various tasks.
typedef struct {
void* (*malloc)(size_t);
void (*free)(void*);
} ls_Alloc;
const ls_Alloc ls_default_alloc = { malloc, free };
struct LabSoundAPI_1_0* ls_create_api_1_0(ls_Alloc);
void ls_release_api_1_0(struct LabSoundAPI_1_0*);
void ls_idle(struct LabSoundAPI_1_0*);
The interface differs from the C++ interface. The C++ interface is an object oriented API meant to mimic the WebAudio specification's interfaces as closely as possible. The C interfaces however, are opaque, and not object oriented.
Inputs and outputs from a node are accessed from pins, as are the node's properties.
Instead, they are built around generic interfaces that rely on LabSounds additional C++ interfaces for querying capabilities and attributes.
Please refer to the demo for usage examples.
// scheduling nodes
ls_Seconds (*node_get_timing)(struct LabSoundAPI_1_0*, ls_Node);
ls_Seconds (*node_get_self_timing)(struct LabSoundAPI_1_0*, ls_Node);
void (*node_start)(struct LabSoundAPI_1_0*, ls_Node, ls_Seconds);
void (*node_schedule)(struct LabSoundAPI_1_0*, ls_Node, ls_Seconds, int32_t);
void (*node_stop)(struct LabSoundAPI_1_0*, ls_Node, ls_Seconds);
// managing nodes
const ls_NameArray* (*node_names)(struct LabSoundAPI_1_0*);
ls_Node (*node_create)(struct LabSoundAPI_1_0*, ls_StringSlice name, ls_StringSlice type);
void (*node_delete)(struct LabSoundAPI_1_0*, ls_Node);
void (*create_node_output)(struct LabSoundAPI_1_0*, ls_Node, ls_StringSlice name, int channels);
void (*node_set_on_ended)(struct LabSoundAPI_1_0*, ls_Node, void(*)());
// getting pins from nodes
ls_Pin (*node_named_input)(struct LabSoundAPI_1_0*, ls_Node, ls_StringSlice);
ls_Pin (*node_indexed_input)(struct LabSoundAPI_1_0*, ls_Node, int);
ls_Pin (*node_named_output)(struct LabSoundAPI_1_0*, ls_Node, ls_StringSlice);
ls_Pin (*node_indexed_output)(struct LabSoundAPI_1_0*, ls_Node, int);
ls_Pin (*node_parameter)(struct LabSoundAPI_1_0*, ls_Node, ls_StringSlice);
ls_Pin (*node_setting)(struct LabSoundAPI_1_0*, ls_Node, ls_StringSlice);
// information about pins
ls_PinKind (*pin_kind)(struct LabSoundAPI_1_0*, ls_Pin);
ls_PinDataType (*pin_data_type)(struct LabSoundAPI_1_0*, ls_Pin);
// setting and getting pin values
// note - these interfaces are going to be prefixed with pin_
void (*set_float)(struct LabSoundAPI_1_0*, ls_Pin, float);
void (*set_enum)(struct LabSoundAPI_1_0*, ls_Pin, uint32_t);
void (*set_int)(struct LabSoundAPI_1_0*, ls_Pin, uint32_t);
void (*set_bool)(struct LabSoundAPI_1_0*, ls_Pin, bool);
void (*set_bus)(struct LabSoundAPI_1_0*, ls_Pin, ls_BusData);
void (*set_bus_from_file)(struct LabSoundAPI_1_0*, ls_Pin, ls_StringSlice path);
void (*set_named_enum)(struct LabSoundAPI_1_0*, ls_Pin, ls_StringSlice enum_name);
// managing busses
ls_BusData (*bus_create_from_file)(struct LabSoundAPI_1_0*, const char* path, bool mix_to_mono);
// graph management
// note - device_node is going to be renamed destination_node
ls_Node(*device_node)(struct LabSoundAPI_1_0*);
ls_Connection (*connect_output_to_input)(struct LabSoundAPI_1_0*, ls_Pin input, ls_Pin output);
// after disconnection, ls_Connection will no longer be valid
void (*disconnect)(struct LabSoundAPI_1_0*, ls_Connection);