Plugin API (custom algorithms)

Plugin API extension allows you to implement your own algorithms in Audiostack. Whether you want to use your own binaural decoder, or add new effects that are not available in Audiostack, this extension is what you need.

If you are looking for plugin API extension doc, go here.

  1. Create your own HOA to Binaural plugin

HOA to binaural

In this sample, we will create a user effect that takes third order ambisonics and outputs binaural.

For clarity, the effect implementation will only be a blueprint. You have learned above that we will process in two steps:

  • first, create a plugin: a small dynamic library containing your effect(s)
  • then, create an Audiostack app that will load this plugin and access its effect(s)

Create a plugin

  • inherit from aspic::audiostack::AudiostackEffect
  • specify in and out channel counts using getSubchannelLayout
  • declare parameters (listener rotation)
  • implement your decoding algorithm in processAudio
  • create a plugin that contains your effect
#include "AspicAudiostackPluginAPI.h"

using namespace aspic::audiostack;

// This is a blueprint, the audio processing method mutes output
class HOA3ToBinauralEffect : public AudiostackEffect{
public:
	HOA3ToBinauralEffect()
	{

	}

	// Implement your hoa3 to binaural decoding in this method
	virtual void processAudio(const float** _in, float** _out, int _bufferLength, float _sampleRate){
		// Debug received param
		std::cout<<"rot : "<<headRot.x<<", "<<headRot.y<<", "<<headRot.z<<std::endl;
		
		// Mute output
		for(int i =0; i<_bufferLength;++i){
			_out[0][i] = 0.0f;
			_out[1][i] = 0.0f;
		}
	}

	// Ask for 16 inputs (Hoa3) and 2 outputs (binaural)
	virtual void getSubchannelLayout(int &_inCount, int &_outCount) const{
		_inCount = 16;
		_outCount = 2;
	}
protected:
	// You want -at least- listener rotation. You could also ask for more parameters, dependeing on your algorithms
	virtual void declareParameters(){
		registerListenerParam("rotation",headRot);
	}
private:
	Vector3 headRot;
};

// Create a plugin that contains HOA3ToBinauralEffect. You could add more effects in this plugin.
class AmbisonicsSkeletonPlugin : public AudiostackPlugin{
public:
	AmbisonicsSkeletonPlugin(){
		registerEffect<HOA3ToBinauralEffect>(0);
	}
};

AUDIOSTACK_PLUGIN(AmbisonicsSkeletonPlugin)

Create your Audiostack app

[...]

enum{file, bus, ambToBinaural, coreOut};

AudiostackContext context;
context.setLicenseKeyFromFile("LICENSE.aslc");

// Read a HOA3 file (16 sub-channels)
context.createInput(file,SyncAudioFileReader,0,0,16);
context.setParameter("sync_source/0/file", "path/to/hoa3_file.wav");
context.setParameter("sync_source/0/loop", true);
context.setParameter("sync_source/0/start_on_awake", true);
context.setParameter("sync_source/0/nb_channel",16);

context.createBus(bus);

// Load plugin interface features
PluginInterface::Load(context.impl);

// Load your plugin and create an effect it contains
AudiostackPlugin plugin(context,"AmbisonicsSkeletonPlugin.dll");
context.createEffect(ambToBinaural,bus, UserEffect, plugin.impl,0);

context.createOutput(coreOut,WindowsCoreAudioOutput,true);

context.connect(file, bus);
context.connect(bus, coreOut);

context.play();

float listRot[3];
listRot[0] = 0.0f;
listRot[1] = 0.0f;
listRot[2] = 0.0f;

char c;
do {
	std::cout<<"Press q or d to rotate listener."<<std::endl;
	std::cout<<"Press x to exit."<<std::endl;
	std::cin >> c;
	switch(c){
	case 'q':
		listRot[1] -= 5.0f;
		break;
	case 'd':
		listRot[1] += 5.0f;
		break;
	}
	context.setParameter("listener/3/rotation",listRot);

}while(c != 'x');

context.stop();

[...]

Build

  • Create a dynamic library with your plugin
  • Install this new library in Audiostack execution folder