Python API Reference

Functions

iris.sdk.init() → iris.sdk.LicenceInfo
iris.sdk.init(licence: str | None, key: str | None) → iris.sdk.LicenceInfo

Overloaded function.

  1. init() -> iris.sdk.LicenceInfo

    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

    return:

    An Info with the initialisation result

    rtype:

    Info

  2. init(licence: str | None, key: str | None) -> iris.sdk.LicenceInfo

    Initialise iris-sdk using a provided licence and key.

    param licence:

    A string containing the contents of a valid licence file

    type licence:

    str

    param key:

    A string containing the contents of a valid key

    type key:

    str

    return:

    An Info with the initialisation result

    rtype:

    Info

iris.sdk.create_audio_context(context_request: iris.sdk.AudioContextRequest | None) → iris.sdk.AudioContextConfig

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.

Parameters:

context_request (AudioContextRequest) – An AudioContextRequest describing the required setup

Returns:

An AudioContextConfig describing the created audio processing context

Return type:

AudioContextConfig

iris.sdk.release_audio_context(context_id: str | None) → None

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 context_id will return silence.

Parameters:

context_id (str) – The context_id to release

iris.sdk.process(context_id: str | None, input: numpy.ndarray[dtype=float32], output: numpy.ndarray[dtype=float32], frames: int) → None

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 file in one go. The frames value here should match the AudioContextConfig.buffer_length unless the AudioContextRequest.fixed_frame_count was set to false.

If the AudioContextConfig.frame_offset is non zero then the output data will be delayed by that offset. If the provided context_id is not available or has previously been released then the output will contain silence.

see buffer_length.

see fixed_frame_count

Parameters:
iris.sdk.process_offline(context_id: str | None, input: numpy.ndarray[dtype=float32], output: numpy.ndarray[dtype=float32], frames: int, callback: object | None = None) → None

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 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 should match the length of the input and output arrays.

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

see buffer_length.

see fixed_frame_count

Parameters:
iris.sdk.set_parameter(context_id: str | None, parameter_id: str | None, value: float | None) → None

Set a value for an existing parameter.

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

If the context_id or parameter_id cannot be found has no effect.

see ParameterDescription

Parameters:

  • context_id (str) – The context_id the parameter belongs to

  • parameter_id (str) – The ParameterDescription_id for the parameter

  • value (float32) – The value to set for the parameter

iris.sdk.get_parameter(context_id: str | None, parameter_id: str | None) → float

Get the current value for an existing parameter.

If the context_id or parameter_id cannot be found returns 0.0f.

see ParameterDescription

Parameters:

  • context_id (str) – The context_id the parameter belongs to

  • parameter_id (str) – The ParameterDescription_id for the parameter

Returns:

The current value of the parameter

Return type:

float32

iris.sdk.reset_parameters(context_id: str | None) → None

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

If the context_id or parameter_id cannot be found returns 0.0f.

see ParameterDescription

Parameters:

context_id (str) – The context_id to reset parameters for

iris.sdk.find_parameter_description(context_id: str | None, processor_id: str | None, parameter_name: str | None) → list[iris.sdk.ParameterDescription]

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.

see ParameterDescription

Parameters:

  • context_id (str) – The context_id to reset parameters for

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

  • parameter_name – The name of the parameter to search for

Returns:

List of matching ParameterDescription

iris.sdk.get_session_info() → str

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

Return type:

str

iris.sdk.cleanup() → None

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.

iris.sdk.open_source_licences() → list[iris.sdk.OpenSourceLicence]

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

Returns:

List of OpenSourceLicence used by iris-sdk

Return type:

OpenSourceLicence list

see OpenSourceLicence

sdk.ERROR_PROCESSOR_UNSUPPORTED = An unknown or unsupported processor was requested
sdk.ERROR_SAMPLE_RATE_MISMATCH = Processors with conflicting sample rates were requested

Classes

class iris.sdk.LicenceInfo
property available_processors

list of processors accessible through the licence, These can be requested in an AudioContextRequest

property expiry

the expiry date of the licence

property name

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

property status

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

property version

iris-sdk version number

class iris.sdk.AudioContextRequest(*args, **kwargs)

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 ref Iris::Constants::ANY.

processors contains a list of processor ids to configure within the audio context. Valid ids should be obtained by inspecting the value of available_processors after initialisation.

see create_audio_context()

see AudioContextConfig

property buffer_length

the desired buffer length, leave empty if no specific buffer length is preferred

property channel_count

the desired channel count, leave empty if no specific channel count is preferred

property fixed_frame_count

if true the context will be guaranteed to receive a consistent number of frames each buffer

property optimization

prioritise lower cpu usage or faster processing

property planar_channel_layout

specifies whether channels are laid out in planar form rather than interleaved

property processors

a list of strings containing required processor ids

property resampler_mode

prioritise higher quality resampling or faster processing

property sample_rate

the desired sample rate, leave empty if no specific sample rate is preferred

class iris.sdk.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 sample_rate, buffer_length and channel_count 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 context_id will still be usable but the audio context will just perform a simple passthrough with no processing applied.

property buffer_length

the buffer length the audio context expects to see, in frames. If fixed frame count is false, this serves as a maximum

property channel_count

the number of channels the audio context expects to see

property context_id

the unique id of the audio context

property description

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

property error

the error state of the audio context

property fixed_frame_count

whether or not the context is guaranteed to receive buffer_length frames per call to process

property frame_offset

the fractional offset between input and output audio, in frames

property optimal_buffering

whether or not the audio context is receiving optimally sized buffers

property optimization

prioritising lower cpu usage or faster processing

property parameters

list of ProcessorParameters available in this context

property planar_channel_layout

true if channels are laid out in planar form rather than interleaved

property resampler_mode

prioritise higher quality resampling or faster processing

property sample_rate

the sample rate the audio context expects to see

property will_mix

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

property will_resample

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

class iris.sdk.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 set_parameter()

see get_parameter()

property default_value

the default value for the parameter

property display_name

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

property id

the parameter id

property is_toggle

if true the parameter is a boolean toggle

property max_value

the maximum settable value of the parameter

property min_value

the minimum settable value of the parameter

property name

the name of the parameter

property skew_value

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

property step_value

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

property unit

the unit of measurement the value takes

class iris.sdk.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 set_parameter()

see get_parameter()

property id

the id for the processor

property name

the display name for the processor

property parameter_descriptions

the parameters for this processor

class iris.sdk.OpenSourceLicence

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

a link to the project licence details

property project_description

a description of the project

property project_licence

the project licence

a link to the project repository

property project_name

the name of the third-party project