C# API Reference ================ .. rubric:: Functions .. function:: 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 .. function:: LicenceInfo Iris.Sdk.Init(string licenceString, string keyString) Initialise iris-sdk using a provided licence and key. :param licenceString: The licence to use :param keyString: The key to use :returns: iris-sdk initialisation info .. function:: 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 :class:`AudioContextRequest` describes the audio the client proposes to deliver to the context. An :class:`AudioContextConfig` describes the audio the client should deliver to the context. :param request: An :class:`AudioContextRequest` describing the required setup :returns: An :class:`AudioContextConfig` describing the created audio processing context .. function:: 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 :func:`Process` with the released ``contextId`` will return silence. :param contextId: The context ID to release .. function:: 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 :class:`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. :param contextId: The context ID to use for processing :param input: 32-bit float array of length ``frames`` * channels :param output: 32-bit float array of length ``frames`` * channels :param frames: The number of frames in the input array. A frame consists of one 32-bit float per channel. .. function:: void Iris.Sdk.ProcessOffline(string contextId, float[] input, float[] output, uint frames, Action 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. :param contextId: The context ID to use for processing :param input: 32-bit float array of length ``frames`` * channels :param output: 32-bit float array of length ``frames`` * channels :param frames: The number of frames in the input array. A frame consists of one 32-bit float per channel. :param onProgress: An optional callback to report processing percentage completion .. function:: 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. :param contextId: The context ID the parameter belongs to :param parameterId: The parameter ID to set :param value: The value to set for the parameter .. function:: 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``. :param contextId: The context ID the parameter belongs to :param parameterId: The parameter ID to query :returns: The current value of the parameter .. function:: void Iris.Sdk.ResetParameters(string contextId) Resets all parameters in a previously created audio processing context to default values. :param contextId: The context ID to reset parameters for .. function:: IReadOnlyList 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. :param contextId: The context ID to search for the parameter in :param processor: The processor name to search for the parameter in :param parameterName: The name of the parameter to search for :returns: List of matching :class:`ParameterDescription` .. function:: uint Iris.Sdk.SetAudioAnalyticsCallback(Action 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. :param 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. .. function:: 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 .. function:: void Iris.Sdk.Cleanup() Cleanup memory allocated by iris-sdk. After cleanup is called :func:`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. .. function:: IReadOnlyList Iris.Sdk.OpenSourceLicences() Licence information for 3rd-party software used by iris-sdk. :returns: List of :class:`OpenSourceLicence` objects .. rubric:: Classes .. class:: Iris.LicenceInfo Initialisation information returned by :func:`Init`. .. attribute:: LicenceStatus Status The status of the licence (e.g. ``Valid``). .. attribute:: string Version The SDK version number. .. attribute:: string Name The name of the licence (e.g. your company name). .. attribute:: string Expiry The expiry date of the licence. .. attribute:: IReadOnlyList 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``). .. attribute:: List Processors A list of processor IDs to configure within the audio context. Valid IDs are obtained from ``LicenceInfo.AvailableProcessors`` after initialisation. .. attribute:: int SampleRate The desired sample rate. Set to ``-1`` (``ANY``) if no specific sample rate is preferred. .. attribute:: int BufferLength The desired buffer length. Set to ``-1`` (``ANY``) if no specific buffer length is preferred. .. attribute:: int ChannelCount The desired channel count. Set to ``-1`` (``ANY``) if no specific channel count is preferred. .. attribute:: bool FixedFrameCount Specifies whether the context will be guaranteed to receive ``BufferLength`` frames on each call to :func:`Process`. Default: ``true``. .. attribute:: bool AudioAnalytics Enables audio analytics, which can then be retrieved by setting a callback via :func:`SetAudioAnalyticsCallback`. Default: ``false``. .. attribute:: bool PlanarChannelLayout Specifies whether channels are laid out in planar form rather than interleaved. Default: ``false``. .. attribute:: OptimizationType Optimization Prioritise lower CPU usage or faster processing. Default: ``OptimizationType.Cpu``. .. attribute:: 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 :class:`AudioContextRequest`. Values may differ from those originally requested depending on the combination of processors requested. .. attribute:: string ContextId The unique ID of the audio context. .. attribute:: string Description A description of the processing chain as a string of processor IDs. .. attribute:: uint SampleRate The sample rate the audio context expects to see. .. attribute:: uint BufferLength The buffer length the audio context expects to see, in frames. If ``FixedFrameCount`` is ``false``, this serves as a maximum. .. attribute:: uint ChannelCount The number of channels the audio context expects to see. .. attribute:: IReadOnlyList Parameters Description of the parameters available in this context. .. attribute:: double FrameOffset The fractional offset between input and output audio, in frames. .. attribute:: bool PlanarChannelLayout True if channels are laid out in planar form rather than interleaved. .. attribute:: bool OptimalBuffering Whether the audio context is receiving optimally sized buffers. .. attribute:: bool WillResample Whether the audio context is performing resampling to match the requested sample rate. .. attribute:: bool WillMix Whether the audio context is being up/down-mixed to match the requested channel count. .. attribute:: bool FixedFrameCount Whether the context is guaranteed to receive ``BufferLength`` frames per call to :func:`Process`. .. attribute:: OptimizationType Optimization Prioritising lower CPU usage or faster processing. .. attribute:: ResamplerMode ResamplerMode Prioritise higher quality resampling or faster processing. .. attribute:: uint Error The error state of the audio context. A value of ``0`` indicates no error. .. attribute:: 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. .. attribute:: string Id The parameter ID, used with :func:`SetParameter` and :func:`GetParameter`. .. attribute:: string Name The name of the parameter. .. attribute:: string DisplayName A more human-readable name suitable for logging or displaying in a UI. .. attribute:: string Unit The unit of measurement the value takes. .. attribute:: float DefaultValue A default value for the parameter. .. attribute:: float MinValue The minimum settable value of the parameter. .. attribute:: float MaxValue The maximum settable value of the parameter. .. attribute:: float StepValue The recommended granularity of the parameter for a slider or knob in a UI. .. attribute:: float SkewValue The recommended mid-point of a slider or knob in a UI. .. attribute:: bool IsToggle Whether the parameter is a boolean toggle. .. class:: Iris.ProcessorParameters A group of :class:`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. .. attribute:: string Name The display name for the processor. .. attribute:: string Id The ID of the processor. .. attribute:: IReadOnlyList Parameters The parameters for this processor. .. class:: Iris.OpenSourceLicence Details of third-party Open Source software used within iris-sdk. .. attribute:: string ProjectName The name of the third-party project. .. attribute:: string ProjectDescription A description of the project. .. attribute:: string ProjectLicence The project licence. .. attribute:: string ProjectLink A link to the project repository. .. attribute:: string LicenceLink A link to the project licence details. .. rubric:: Enums .. class:: Iris.LicenceStatus Different statuses that can be returned from a licence. .. attribute:: Unknown .. attribute:: Corrupt The licence file could not be decrypted. .. attribute:: Expired The licence has expired and must be renewed. .. attribute:: NotFound No licence file was found. .. attribute:: KeyNotFound No key file was found. .. attribute:: InvalidAlgorithm The licence file contains an unsupported algorithm. .. attribute:: Tampered The signature in the licence file does not match. .. attribute:: InvalidKey The key provided does not match the licence provided. .. attribute:: InvalidFormat The licence file is in an invalid format. .. attribute:: Valid The licence file is valid. .. class:: Iris.OptimizationType Attempt to optimise processing for different scenarios. .. attribute:: Cpu Try to reduce CPU usage at the expense of speed. .. attribute:: 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. .. attribute:: HighQuality High quality resampling. .. attribute:: Speed Faster resampling at the expense of audio quality.