Core module
Aspic Audiostack Core module offers basic features. Here is a list:
- Inputs
- HelloInput: basic synthetized input
- OpenALInput: standard cross-OS microphone
- Windows Core Audio Input: low-latency, windows-only microphone capture
- Outputs
- OpenALOutput: standard cross-OS mono/stereo output
- Windows Core Audio Output: low-latency, windows-only mono/stereo output
- Effects
Inputs
HelloInput
This is a simple input which automatically outputs the following generic sentence: “Aspic Audiostack says hello”.
I/O | Channel count | Sub channel count |
---|---|---|
out |
1 | 1 (MONO) |
Construction
No arguments
Usage :
context.createInput(ID,HelloInput);
Parameters
-
buffer_size (unsigned int) : the length of audio buffers.
This parameter is mapped by default to
application/buffer_size
.Usage with default vars and patterns:
context.setParameter("application/buffer_size",1024U)
OpenALInput
This input uses OpenAL API to access computer microphones. If you have multiple input devices, this OpenAL wrapper will choose the default one.
On windows, you can change default microphone in the control panel, section Sound, tab recording.
I/O | Channel count | Sub channel count |
---|---|---|
out |
1 | 1 (MONO) |
Construction
No arguments
Usage :
context.createInput(ID,OpenALInput);
Parameters
Runtime
No runtime parameters.
Instanciation
-
buffer_size (unsigned int) : the length of microphone audio buffers. Due to OpenAL drivers latency, values less than 2048 will create sound cracks. Recommanded value is 4096.
This parameter is mapped by default to
application/buffer_size
.Usage :
context.setParameter("application/buffer_size",4096U)
We strongly advise to set this parameter once before Audiostak play().
Windows Core Audio Input
This input uses Windows APIs to access computer microphones. If you have multiple input devices, this wrapper will choose the default one.
On windows, you can change default microphone in the control panel, section Sound, tab recording.
I/O | Channel count | Sub channel count |
---|---|---|
out |
1 | 1 (MONO) |
Construction
-
hardware_id (const char*) : the material identifier of the microphone you want to capture
This parameter is optional. If left empty, Audiostack will chose default microphone.
Usage :
context.createInput(ID,WindowsCoreAudioInput);
// or
context.createInput(ID,WindowsCoreAudioInput,"4d36e96c-e325-11ce-bfc1-08002be10318");
Parameters
Runtime
ø
Instanciation
-
buffer_size (unsigned int) : the length of microphone audio buffers.
This parameter is mapped by default to
application/buffer_size
.Usage :
context.setParameter("application/buffer_size",512U)
We strongly advise to set this parameter once before Audiostak play().
Outputs
OpenALOutput
Uses OpenAL API to output audio on speakers/headphone. Will use the default device if your computer have multiple outputs.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 or 2 (see construction) |
Construction
-
stereo (bool) : output will be stereo if value is set to TRUE or to mono if value is set to FALSE. When building a diagram, please ensure effects and outputs have compatible channel count : stereo effects may be plugged into stereo outputs.
Usage :
context.createOutput(ID,OpenALOutput,true); // creates a stereo output
context.createOutput(ID,OpenALOutput,false); // creates a mono output
Parameters
Runtime
-
master_gain (float) : master gain of this output (amplitude).
This parameter is mapped by default to
listener/%list_id/master_gain
.Usage :
context.setParameter("listener/2/master_gain",0.5f)
Instanciation
-
buffer_size (unsigned int) : the length of audio buffers.
This parameter is mapped by default to
application/buffer_size
.Usage :
context.setParameter("application/buffer_size",512U)
We strongly advise to set this parameter once before Audiostak play().
-
buffer_count (unsigned int) : the number of audio buffers in queue. Default value is 2, it means that audio is double-buffered.
This parameter is mapped by default to
application/buffer_count
.Usage :
context.setParameter("application/buffer_count",3U)
Callbacks
- triggered : to be documented
Android behavior
To be documented
Windows Core Audio Output
Uses Windows APIs to output audio on speakers/headphone. Will use the default device if your computer have multiple outputs.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 or 2 (see construction) |
Construction
-
stereo (bool) : output will be stereo if value is set to TRUE or to mono if value is set to FALSE. When building a diagram, please ensure effects and outputs have compatible channel count : stereo effects may be plugged into stereo outputs.
-
hardware_id (const char*) : the material identifier of the microphone you want to capture
This parameter is optional. If left empty, Audiostack will chose default microphone.
Usage :
context.createOutput(ID,WindowsCoreAudioOutput,false); // creates a mono output
context.createOutput(ID,WindowsCoreAudioOutput,true); // creates a stereo output
context.createOutput(ID,WindowsCoreAudioOutput,true,"4d36e96c-e325-11ce-bfc1-08002be10318");
Parameters
Runtime
-
master_gain (float) : master gain of this output (amplitude).
This parameter is mapped by default to
listener/%list_id/master_gain
.Usage :
context.setParameter("listener/2/master_gain",0.5f)
Instanciation
-
buffer_size (unsigned int) : the length of audio buffers.
This parameter is mapped by default to
application/buffer_size
.Usage :
context.setParameter("application/buffer_size",512U)
We strongly advise to set this parameter once before Audiostak play().
Effects
SimpleGain
May be used to apply a gain to specific audio channels.
Will be renamed “Gain”
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 (MONO) | |
out |
N | 1 (MONO) |
Will allow custom subchannel count in input/output, in order to become
Construction
No construction parameters.
Usage:
context.createEffect(EFFECT_ID, BUS_ID, SimpleGain);
Parameters
Runtime
-
src_gain (float, multivalued) : controls the gain applied to audio channels. Default value is
1.0f
for each channel. The higher the value, the loudest the sound will be. A value equal to0.0f
mutes the signal.This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/gain
Usage thanks to default vars and patterns:
context.setParameter("source/7/gain", 0.42f); // set gain of input with objectId 7
-
mute (bool, multivalued) : if set to TRUE, mutes one audio channel. Default value is FALSE.
This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/mute
Usage thanks to default vars and patterns:
context.setParameter("source/7/mute", true);
Instanciation
No instanciation parameters.
MultiChannelSimpleGain
This effect splits mono input channels into more sub channels. It is usefull to transform a mono signal in a stereo (or multichannel) output, for instance on a 2D bus before outputing to your stereo outputs.
Currenlty, also applies gain modification to channels. The gain applied to one signal is applied equally to each one of its sub channels.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 (MONO) | |
out |
N | M (specified at construction) |
Construction
-
nbSubChannel (unsigned int) : set sub channel count of the output.
Usage :
context.createEffect(EFFECT_ID, BUS_ID, MultiChannelSimpleGain, 2U) // creates a stereo gain context.createEffect(EFFECT_ID, BUS_ID, MultiChannelSimpleGain, 8U) // creates a 7.1 master gain.
Will be renamed “Splitter”
Parameters
Runtime
Will lost gain and mute parameters (refer to SimpleGain )
-
src_gain (float, multivalued) : controls the gain applied to audio channels. Default value is
1.0f
for each channel. The higher the value, the loudest the sound will be. A value equal to0.0f
mutes the signal.This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/gain
Usage thanks to default vars and patterns:
context.setParameter("source/7/gain", 0.42f); // set gain of input with objectId 7
-
mute (bool, multivalued) : if set to TRUE, mutes one audio channel. Default value is FALSE.
This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/mute
Usage thanks to default vars and patterns:
context.setParameter("source/7/mute", true);
Instanciation
No instanciation parameters.
MultiChannelMixer
Mix down many channels into one channel. Mixers are usefull because they enable following effects to process fewer audio data. However, effects after a mixer cannot apply source-specific effects (like spatialization or attenuation), since sources are mixed.
It reduces the number of channels, but do not change the number of subchannels: mixing 2 stereo channels will produce 1 stereo channel.
Will be renamed “Mixer”
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | M | |
out |
1 | M |
Construction
-
nbSubChannel (unsigned int) : set sub channel count of input and output channels.
Usage :
context.createEffect(EFFECT_ID, BUS_ID, MultiChannelMixer, 2U) // creates a stereo mixer context.createEffect(EFFECT_ID, BUS_ID, MultiChannelMixer, 8U) // creates a 7.1 mixer
Parameters
Runtime
-
volume (float, multivalued) : controls amount of each input channel that goes to the output. Default value is
1.0f
and values must be between0.0f
and1.0f
This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/volume
Usage thanks to default vars and patterns:
context.setParameter("source/7/volume", 0.42f);
Instanciation
No instanciation parameters.
Delay
Applies delay on signal.
WORK IN PROGRESS
R128Metering
Computes metering of your audio signals, using R128. Audio signal stays untouched.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | M | |
out |
N | M |
Construction
-
nbSubChannel (unsigned int) : set sub channel count of input and output channels.
Usage :
context.createEffect(EFFECT_ID, BUS_ID, R128Metering, 2U) // creates a mono metering context.createEffect(EFFECT_ID, BUS_ID, R128Metering, 9U) // creates a 2nd order ambisonics metering
Parameters
No runtime parameters.
No instanciation parameters.
Callbacks
- peak: this callback is called each time a peak value has been computed. It is called once per channel and subchannel. Therefore, having a 2 channels containing 1st order ambisonics will give you 8 calls.
TODO DEFAULT MAPPING
TODO USAGE
MixFocus
Applies gain depending on whether a listener is looking towards a source.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 (MONO) | |
out |
N | 1 (MONO) |
Construction
No construction parameters.
Usage : ```cpp context.createEffect(EFFECT_ID, BUS_ID, MixFocus); ```
Parameters
Runtime
TODO src_position
TODO list_position
TODO list_rotation
TODO gain
TODO angle
Instanciation
No instanciation parameters.
AttenuationEffect
Effect documentation under revision to match actual interface
This effects uses distance between sources and listeners to apply custom audio volume. It may be used to reproduce sound rollof over distance in real life.
Currently available attenuation profiles are linear and inverse.
Linear attenuation requires you to set a min and max distance. When distance between source and listener is below min, volume is set to 1.0f; when distance goes over max, volume is set to 0.0f.
Inverse attenuation requires a min distance and a decay coefficient. Audio volume is set to 1.0f
below min distance, and then follow a inverse law (1/distance). The decay coefficient enable a fine tuning of the strength of attenuation.
I/O | Channel count | Sub channel count |
---|---|---|
in |
N | M |
out |
N | M |
Construction
-
attenuationType (unsigned int) : choose between attenuation laws, use 0 for linear, use 1 for inverse.
-
nbSubChannel (unsigned int) : set subchannel count of input and output channels.
Usage :
context.createEffect(EFFECT_ID, BUS_ID, AttenuationEffect, 0, 1) // creates linear attenuation effect for mono signals
context.createEffect(EFFECT_ID, BUS_ID, AttenuationEffect, 1, 2) // creates inverse attenuation effect for stereo signals
Parameters
-
src_position (vec3, multivalued) : position of audio source
This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/position
-
listener_position (vec3, multivalued) : position of audio listener
This parameter will contain N values, with N equal to the number of buses output.
Parameter is mapped by default to
listener/%list_id/position
-
min_distance (float) : available for linear and inverse attenuation. Default is
0.0f
. -
max_distance (float) : available for linear attenuation only. Default is
25.0f
. -
sound_decay_coef (float) : available for inverse attenuation only. Default is
1e-6
. Try to tune this value to makes attenuation more or less efficient.
Deprecated effects
Mixer
Will be deprecated, see MultiChannelMixer
Mix down many mono channels into one mono channel. Mixers are usefull because they enable following effects to process fewer audio data. However, effects after a mixer cannot apply source-specific effects (like spatialization or attenuation).
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 1 (MONO) | |
out |
1 | 1 (MONO) |
Construction
No arguments
Usage :
context.createEffect(EFFECT_ID, BUS_ID, Mixer);
Parameters
Runtime
-
volume (float, multivalued) : controls amount of each input channel that goes to the output. Default value is
1.0f
and values must be between0.0f
and1.0f
This parameter will contain N values, with N equal to the number of channels reaching effect’s input.
Parameter is mapped by default to
source/%src_id/volume
Usage thanks to default vars and patterns:
context.setParameter("source/7/volume", 0.42f);
Instanciation
ø
StereoMixer
Under deprecation, see MultiChannelMixer
Behaves like Mixer but with stereo inputs and output.
I/O | Channel count | Sub channel count | |
---|---|---|---|
in |
N | 2 (STEREO) | |
out |
1 | 2 (STEREO) |
Construction
No arguments
Usage :
context.createEffect(EFFECT_ID, BUS_ID, StereoMixer);
Parameters
Same as Mixer.
Code samples
For more code samples, see Core samples
C++ API Samples
OpenAL simple application
This sample connects microphone to computer output using OpenAL drivers.
Please note this sample doesn’t handle errors, please go direclty to the next sample for error handling.
[...]
enum:int{micId, outputId };
AudiostackContext context;
context.setLicenseKeyFromFile("LICENSE_FILE.aslc");
context.createInput(micId,OpenALInput);
context.createOutput(outputId,OpenALOutput,false);
// Output is mono, in order to accept mono microphone.
context.connect(micId,outputId);
// No need of bus in this sample.
context.play();
char c;
std::cout<<"Mic capture in progress. Press q to quit."<<std::endl;
do{
std::cin>>c;
} while(c!='q');
context.stop();
[...]
Error handling
The previous sample doesn’t catch any error, here is the sample application with error handling.
void err(const AudiostackContext& _context){
if(_context.getError())
throw std::runtime_error(_context.getLastErrorMessage());
}
[...]
try{
enum:int{micId, outputId };
AudiostackContext context;
context.setLicenseKeyFromFile("LICENSE_FILE.aslc");
err(context);
context.createInput(micId,OpenALInput);
context.createOutput(outputId,OpenALOutput,false);
err(context);
context.connect(micId,outputId);
err(context);
context.play();
err(context);
char c;
std::cout<<"Mic capture in progress. Press q to quit."<<std::endl;
do{ std::cin>>c;} while(c!='q');
context.stop();
err(context);
}catch(std::exception& e){
std::cout<<e.what()<<std::endl;
}catch(...){
std::cout<<"Unhandled error"<<std::endl;
}
[...]
For more code samples, see Core samples