C++ API Reference

Functions

LicenceInfo Iris::init()

Initialise iris-sdk using a licence and key from a fixed location.

By default, iris-sdk will search for the files iris.lic and iris.key in the following locations:

  • ~/iris/licence/ on macos or linux

  • C:\Users\username\iris\licence\ on Windows

To change the root directory, set the environment variable IRIS_DATA to a desired location

Returns:

iris-sdk initialisation info

LicenceInfo Iris::init(const std::string &licenceString, const std::string &keyString)

Initialise iris-sdk using a provided licence and key.

Parameters:

  • licenceString – The licence to use

  • keyString – The key to use

Returns:

iris-sdk initialisation info

AudioContextConfig Iris::createAudioContext(AudioContextRequest &contextRequest)

Creates an audio processing context.

An audio processing context is used to process one continuous stream of audio. After an audio stream is stopped a new context should be created to process further audio data and the current context should be released. An AudioContextRequest describes the audio the client proposes to deliver to the context. An AudioContextConfig describes the audio the client should to deliver to the context.

See also

AudioContextRequest

See also

AudioContextConfig

Parameters:

contextRequest – An AudioContextRequest describing the required setup

Returns:

An AudioContextConfig describing the created audio processing context

void Iris::releaseAudioContext(const std::string &contextId)

Releases a previously created audio processing context that is no longer required.

After an audio processing context has been released any call to process with the released AudioContextConfig::contextId will return silence.

Parameters:

contextId – The AudioContextConfig::contextId to release

void Iris::process(const std::string &contextId, const float *input, float *output, uint32_t frames)

Processes sequential chunks of a contiguous audio stream through an existing audio processing context.

Audio samples will be read from input, processed and placed into output. This function should be called continuously with short buffers of audio, it is not intended to be used to process an entire large buffer in one go.

The frames value here should match the AudioContextConfig::bufferLength unless AudioContextRequest::fixedFrameCount was set to false.

If the AudioContextConfig::frameOffset is non zero then the output data will be delayed by that offset.

If the provided contextId is not available or has previously been released then the output will contain silence.

See also

AudioContextConfig.bufferLength

See also

AudioContextConfig.fixedFrameCount

Parameters:

  • contextId – The AudioContextConfig::contextId to use for processing

  • input – 32-bit float array of length frames * channels

  • output – 32-bit float array of length frames * channels

  • frames – The number of frames in the input array. A frame consists of 1 32-bit float per channel.

void Iris::processOffline(const std::string &contextId, const float *input, float *output, uint32_t frames, ProgressCallback callback = nullptr)

Processes an entire large audio buffer through an existing audio processing context.

Audio samples will be read from input, processed and placed into output. This function should be called once with a single large buffer to fully process, e.g. the contents of a file. It should not be used to process sequential chunks of an audio stream.

The entire buffer will be processed, accounting for and removing any incurred frame offset caused by resampling and processing.

The frames value here should match the length of the input and output arrays.

If the provided contextId is not available or has previously been released then the output will contain silence.

See also

AudioContextConfig.bufferLength

See also

AudioContextConfig.fixedFrameCount

Parameters:

  • contextId – The AudioContextConfig::contextId to use for processing

  • input – 32-bit float array of length frames * channels

  • output – 32-bit float array of length frames * channels

  • frames – The number of frames in the input array. A frame consists of 1 32-bit float per channel.

  • callback – An optional callback to report processing percentage completion

void Iris::setParameter(const std::string &contextId, const std::string &parameterId, const float value)

Set a value for an existing parameter.

If the value is not within the range ParameterDescription::minValue to ParameterDescription::maxValue it will be clamped.

If the contextId or parameterId cannot be found has no effect.

See also

ParameterDescription

Parameters:
float Iris::getParameter(const std::string &contextId, const std::string &parameterId)

Get the current value for an existing parameter.

If the contextId or parameterId cannot be found returns 0.0f

Parameters:
Returns:

The current value of the parameter

void Iris::resetParameters(const std::string &contextId)

Resets all parameters in a previously created audio processing context to default values.

Parameters:

contextId – The AudioContextConfig::contextId to reset parameters for

std::vector<ParameterDescription> Iris::findParameterDescription(const std::string &contextId, const std::string &processor, const std::string &parameterName)

Find matching parameter descriptions within an audio processing context.

If the returned vector is empty no parameters were found. If multiple processors of the same type are in the audio processing chain the returned vector will contain the matching parameters in the processing chain order.

eg if the processor chain is gain,clarity,gain then searching for gain_db would return 2 values. The first being the gain param for the first gain processor in the chain, the second being the gain param for the second gain processor in the chain.

Parameters:

  • contextId – The AudioContextConfig::contextId to search for the parameter in

  • processor – The processor name to search for the parameter in

  • parameterName – The name of the parameter to search for

Returns:

vector of matching ParameterDescription.

void Iris::cleanup()

Cleanup memory allocated by iris-sdk.

After cleanup is called init should be called again before attempting to use any other functions. Any previously created audio processing contexts that have not been released will be automatically released.

const std::vector<OpenSourceLicence> &Iris::openSourceLicences()

Licence information for 3rd-party software used by iris-sdk.

Classes

struct LicenceInfo

Initialisation information.

Public Members

std::string version

sdk version number

std::string name

name of the licence (e.g. your-company-name)

std::string expiry

the expiry date of the licence

std::vector<std::string> availableProcessors = {}

processors accessible through the licence

LicenceStatus status = licenceUnknown

the status of the licence (e.g. valid)

struct AudioContextRequest

Request for an audio processing context to be created.

If the sample rate, channel count or buffer length are fixed by the client they can be set here. This will cause iris-sdk to adapt the input and output streams as required.

If the client can adapt to the optimum sample rate and buffer length, leave these values as Iris::Constants::ANY.

The processors field contains a list of processor ids to configure within the audio context. Valid ids should be obtained by inspecting the value of LicenceInfo::availableProcessors after initialisation.

See also

createAudioContext

See also

AudioContextConfig

Public Members

std::vector<std::string> processors

a vector of strings containing desired processor ids

int sampleRate = Constants::ANY

the desired sample rate, leave as ANY if no specific sample rate is preferred

int bufferLength = Constants::ANY

the desired buffer length, leave as ANY if no specific buffer length is preferred

int channelCount = Constants::ANY

the desired channel count, leave as ANY if no specific channel count is preferred

bool fixedFrameCount = true

specifies whether the context will be guaranteed to receive bufferLength frames each buffer

bool eventDetection = false

enables audio events, which can then be retrieved by setting an Iris::AudioEventCallback

bool audioAnalytics = false

enables audio analytics, which can then be retrieved by setting an Iris::AudioAnalyticsCallback

OptimizationType optimization = OptimizationType::cpu

prioritise lower cpu usage or faster processing

ResamplerMode resamplerMode = ResamplerMode::hq

prioritise higher quality resampling or faster processing

struct AudioContextConfig

An audio processing context configuration.

Describes the actual properties of an audio processing context that was created from an AudioContextRequest. Values may differ from those originally requested depending on the combination of processors originally requested.

The sampleRate, bufferLength and channelCount represent the properties of the audio buffers that are expected when calling process.

As a minimum the error value should be checked. In most error cases the context with this contextId will still be usable but the audio context will just perform a simple passthrough with no processing applied.

See also

createAudioContext

See also

AudioContextRequest

See also

process

Public Members

std::string contextId = ""

the unique id of the audio context as a string

std::string description = ""

a description of the processing chain as a string of processor ids

uint32_t sampleRate = Constants::DEFAULT_SAMPLE_RATE

the sample rate the audio context expects to see

uint32_t bufferLength = Constants::DEFAULT_BUFFER_LENGTH

the buffer length the audio context expects to see, in frames.

If fixed frame count is false, this serves as a maximum

uint32_t channelCount = Constants::DEFAULT_CHANNEL_COUNT

the number of channels the audio context expects to see

std::vector<ProcessorParameters> parameters

description of the parameters available in this context

double frameOffset = 0

the fractional offset between input and output audio, in frames

bool optimalBuffering = true

whether the audio context is receiving optimally sized buffers

bool willResample = false

whether the audio context is performing resampling to match requested sample rate

bool willMix = false

whether the audio context is being up/down-mixed to match requested channel count

bool fixedFrameCount = true

whether the context is guaranteed to receive bufferLength frames per call to process

OptimizationType optimization

prioritising lower cpu usage or faster processing

ResamplerMode resamplerMode

prioritise higher quality resampling or faster processing

int error = 0

the error state of the audio context

bool eventDetection = false

true if event detection is enabled

struct ParameterDescription

Describes a parameter that can be set on an audio processing context.

The id is used when setting or getting the parameter value within a context

See also

setParameter

See also

getParameter

Public Members

std::string id = ""

the parameter id.

std::string name = ""

the name of the parameter

std::string displayName = ""

a more human readable name suitable for logging or displaying in a UI

float defaultValue = 0.0f

a default value for the parameter

std::string unit = ""

the unit of measurement the value takes

float minValue = 0.0f

the minimum settable value of the parameter

float maxValue = 1.0f

the maximum settable value of the parameter

float stepValue = 1.0f

the recommended granularity of the parameter for a slider/knob in a UI

float skewValue = 0.0f

the recommended mid-point of a slider/knob in a UI

bool isToggle = true

whether or not the parameter is a boolean toggle

struct ProcessorParameters

A list of ParameterDescription in the order they would be applied within a context.

Each processor in a chain within an audio processing context may have zero or mode associated parameters.

See also

setParameter

See also

getParameter

Public Members

std::string name = ""

the display name for the processor

std::string id = ""

the id of the processor

std::vector<ParameterDescription> parameterDescriptions

the parameters for this processor

struct OpenSourceLicence

Details of third-party Open Source software used within iris-sdk.

Public Members

std::string projectName

the name of the third-party project

std::string projectDescription

a description of the project

std::string projectLicence

the project licence

std::string projectLink

a link to the project repository

std::string licenceLink

a link to the project licence details