C# API Reference

Functions

LicenceInfo Iris.Sdk.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 the desired location.

Returns:: iris-sdk initialisation info

LicenceInfo Iris.Sdk.Init(string licenceString, 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.Sdk.CreateAudioContext(AudioContextRequest request)

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 deliver to the context.

Parameters:: request – An AudioContextRequest describing the required setup
Returns:: An AudioContextConfig describing the created audio processing context

void Iris.Sdk.ReleaseAudioContext(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 contextId will return silence.

Parameters:: contextId – The context ID to release

void Iris.Sdk.Process(string contextId, float[] input, float[] output, uint 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 should match the BufferLength of the AudioContextConfig unless FixedFrameCount was set to false in the request, in which case BufferLength serves as a maximum.

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

Parameters:

contextId – The context ID 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 one 32-bit float per channel.

void Iris.Sdk.ProcessOffline(string contextId, float[] input, float[] output, uint frames, Action<ProgressEvent> onProgress = null)

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.

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

Parameters:

contextId – The context ID 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 one 32-bit float per channel.
onProgress – An optional callback to report processing percentage completion

void Iris.Sdk.SetParameter(string contextId, string parameterId, float value)

Set a value for an existing parameter.

If the value is not within the range MinValue to MaxValue it will be clamped. If the contextId or parameterId cannot be found this has no effect.

Parameters:

contextId – The context ID the parameter belongs to
parameterId – The parameter ID to set
value – The value to set for the parameter

float Iris.Sdk.GetParameter(string contextId, string parameterId)

Get the current value for an existing parameter. If the contextId or parameterId cannot be found returns 0.0.

Parameters:

contextId – The context ID the parameter belongs to
parameterId – The parameter ID to query

Returns:

The current value of the parameter

void Iris.Sdk.ResetParameters(string contextId)

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

Parameters:: contextId – The context ID to reset parameters for

IReadOnlyList<ParameterDescription> Iris.Sdk.FindParameterDescription(string contextId, string processor, string parameterName)

Find matching parameter descriptions within an audio processing context. If the returned list is empty no parameters were found. If multiple processors of the same type are in the audio processing chain the returned list will contain the matching parameters in processing chain order.

Parameters:

contextId – The context ID 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:

List of matching ParameterDescription

uint Iris.Sdk.SetAudioAnalyticsCallback(Action<AudioAnalytics> handler)

Attach a callback to receive audio analytics. The callback may receive analytics from multiple audio processing contexts. Pass null to remove a previously attached callback.

Parameters:: handler – The callback to invoke when analytics data is available, or null to detach
Returns:: An error code indicating whether attaching the callback was successful. Returns non-zero if your licence does not permit audio analytics.

string Iris.Sdk.GetSessionInfo()

Retrieves information about the ongoing session (since initialisation), including usage time, to be used in conjunction with the licensing service.

Returns:: An encrypted payload containing information about the ongoing session, to be decrypted by the licensing service

void Iris.Sdk.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.

IReadOnlyList<OpenSourceLicence> Iris.Sdk.OpenSourceLicences()

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

Returns:: List of OpenSourceLicence objects

Classes

class Iris.LicenceInfo

Initialisation information returned by Init().

LicenceStatus Status: The status of the licence (e.g. Valid).

string Version: The SDK version number.

string Name: The name of the licence (e.g. your company name).

string Expiry: The expiry date of the licence.

IReadOnlyList<string> AvailableProcessors: Processors accessible through the licence.

class Iris.AudioContextRequest

A 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. If the client can adapt to the optimum values, leave these at their defaults (-1 / ANY).

List<string> Processors: A list of processor IDs to configure within the audio context. Valid IDs are obtained from LicenceInfo.AvailableProcessors after initialisation.

int SampleRate: The desired sample rate. Set to -1 (ANY) if no specific sample rate is preferred.

int BufferLength: The desired buffer length. Set to -1 (ANY) if no specific buffer length is preferred.

int ChannelCount: The desired channel count. Set to -1 (ANY) if no specific channel count is preferred.

bool FixedFrameCount: Specifies whether the context will be guaranteed to receive BufferLength frames on each call to Process(). Default: true.

bool AudioAnalytics: Enables audio analytics, which can then be retrieved by setting a callback via SetAudioAnalyticsCallback(). Default: false.

bool PlanarChannelLayout: Specifies whether channels are laid out in planar form rather than interleaved. Default: false.

OptimizationType Optimization: Prioritise lower CPU usage or faster processing. Default: OptimizationType.Cpu.

ResamplerMode ResamplerMode: Prioritise higher quality resampling or faster processing. Default: ResamplerMode.HighQuality.

class Iris.AudioContextConfig

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

string ContextId: The unique ID of the audio context.

string Description: A description of the processing chain as a string of processor IDs.

uint SampleRate: The sample rate the audio context expects to see.

uint BufferLength: The buffer length the audio context expects to see, in frames. If FixedFrameCount is false, this serves as a maximum.

uint ChannelCount: The number of channels the audio context expects to see.

IReadOnlyList<ProcessorParameters> Parameters: Description of the parameters available in this context.

double FrameOffset: The fractional offset between input and output audio, in frames.

bool PlanarChannelLayout: True if channels are laid out in planar form rather than interleaved.

bool OptimalBuffering: Whether the audio context is receiving optimally sized buffers.

bool WillResample: Whether the audio context is performing resampling to match the requested sample rate.

bool WillMix: Whether the audio context is being up/down-mixed to match the requested channel count.

bool FixedFrameCount: 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.

uint Error: The error state of the audio context. A value of 0 indicates no error.

bool AudioAnalytics: True if audio analytics is enabled.

class Iris.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.

string Id: The parameter ID, used with SetParameter() and GetParameter().

string Name: The name of the parameter.

string DisplayName: A more human-readable name suitable for logging or displaying in a UI.

string Unit: The unit of measurement the value takes.

float DefaultValue: A default value for the parameter.

float MinValue: The minimum settable value of the parameter.

float MaxValue: The maximum settable value of the parameter.

float StepValue: The recommended granularity of the parameter for a slider or knob in a UI.

float SkewValue: The recommended mid-point of a slider or knob in a UI.

bool IsToggle: Whether the parameter is a boolean toggle.

class Iris.ProcessorParameters

A group 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 more associated parameters.

string Name: The display name for the processor.

string Id: The ID of the processor.

IReadOnlyList<ParameterDescription> Parameters: The parameters for this processor.

class Iris.OpenSourceLicence

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

string ProjectName: The name of the third-party project.

string ProjectDescription: A description of the project.

string ProjectLicence: The project licence.

string ProjectLink: A link to the project repository.

string LicenceLink: A link to the project licence details.

Enums

class Iris.LicenceStatus

Different statuses that can be returned from a licence.

Unknown

Corrupt: The licence file could not be decrypted.

Expired: The licence has expired and must be renewed.

NotFound: No licence file was found.

KeyNotFound: No key file was found.

InvalidAlgorithm: The licence file contains an unsupported algorithm.

Tampered: The signature in the licence file does not match.

InvalidKey: The key provided does not match the licence provided.

InvalidFormat: The licence file is in an invalid format.

Valid: The licence file is valid.

class Iris.OptimizationType

Attempt to optimise processing for different scenarios.

Cpu: Try to reduce CPU usage at the expense of speed.

Speed: Try to reduce the processing time at the expense of higher CPU usage.

class Iris.ResamplerMode

Set the resampling mode to use. Higher quality resampling incurs a higher frame offset and is slower.

HighQuality: High quality resampling.

Speed: Faster resampling at the expense of audio quality.