Skip to content

.NET client library (ViveSound.Sdk.Ctl)

Installation

Install the ViveSound.Sdk.Ctl package:

dotnet add package ViveSound.Sdk.Ctl

Index

class AsyncEngineClient

Namespace: ViveSound.Sdk.Ctl

Client for the ViveEngine Control API. It wraps a gRPC channel and an engine session, and exposes each engine RPC as an asynchronous method.

On top of gRPC, it adds:

  • session management: a session is opened on connect, renewed periodically by a background keepalive, and closed on disconnect;
  • an idiomatic API: async methods, DTO records, cancellation tokens, and per-request timeouts;
  • typed error handling via the EngineException hierarchy;
  • connection events: ConnectedAsync and ClosedAsync notify when the session opens and closes;
  • logging: diagnostics are emitted through an optional ILogger.

Connecting is optional: if an RPC is called on a client that is not connected yet, that first call connects automatically. Calling ConnectAsync explicitly is only needed to connect eagerly.

The client is thread-safe. Concurrent ConnectAsync and CloseAsync calls are serialized internally, while RPC calls normally proceed concurrently. CloseAsync aborts any pending calls, including an in-progress connect.

Each RPC surfaces failures in three ways: cancelling the per-call token throws OperationCanceledException; exceeding the per-request timeout throws TimeoutException; calling on a closed client, or losing the connection, throws EngineConnectionException. Errors reported by the engine surface as other EngineException subclasses.

AsyncEngineClient.AsyncEngineClient() 

AsyncEngineClient(
    EngineClientOptions? options = null,
    ILogger<AsyncEngineClient>? logger = null)

Creates a client that owns its gRPC channel. The channel is created for Address, or for the auto-discovered default engine when the address is null. Does not connect; the session is opened on ConnectAsync or on the first RPC.

Parameters:

AsyncEngineClient.AsyncEngineClient() 

AsyncEngineClient(
    GrpcChannel channel,
    EngineClientOptions? options = null,
    ILogger<AsyncEngineClient>? logger = null)

Creates a client that uses a caller-supplied channel. The channel is not owned, so it is not disposed by the client. Does not connect; the session is opened on ConnectAsync or on the first RPC.

Parameters:

AsyncEngineClient.CreateConnectedAsync() 

static Task<AsyncEngineClient> CreateConnectedAsync(
    EngineClientOptions? options = null,
    ILogger<AsyncEngineClient>? logger = null,
    CancellationToken ct = default)

Creates a client that owns its channel and connects it in one step.

Parameters:

AsyncEngineClient.Channel 

GrpcChannel Channel { get; }

gRPC channel used for communication. It is owned and disposed by the client only when the client created it itself.

AsyncEngineClient.Options 

EngineClientOptions Options { get; }

Effective options the client runs with. Reflects resolved values, such as the discovered engine address and the resolved user name.

AsyncEngineClient.IsConnected 

bool IsConnected { get; }

Whether the client currently has an open session. This is a snapshot that may change concurrently, for example if the connection is lost.

AsyncEngineClient.IsClosed 

bool IsClosed { get; }

Whether the client has been closed or disposed. Once set, this is terminal and the client can no longer be used.

AsyncEngineClient.ConnectedAsync 

event Func<object, EventArgs, Task>? ConnectedAsync

Raised once, when the client becomes connected. Handlers are invoked on a background task; any exception they throw is logged and suppressed.

AsyncEngineClient.ClosedAsync 

event Func<object, EventArgs, Task>? ClosedAsync

Raised once, when the client becomes closed, whether by CloseAsync, disposal, or a connection loss detected by the keepalive. Handlers are invoked on a background task; any exception they throw is logged and suppressed.

AsyncEngineClient.DisposeAsync() 

ValueTask DisposeAsync()

AsyncEngineClient.ConnectAsync() 

Task ConnectAsync(CancellationToken ct = default)

Connects the client: opens the engine session, establishing the gRPC connection if needed, and starts the background keepalive.

It is thread-safe and idempotent: once a connect succeeds, further calls return immediately. Calling it is optional, since RPC methods auto-connect on first use. A concurrent CloseAsync aborts an in-progress connect. Connecting is bounded by ConnectTimeout.

Parameters:

AsyncEngineClient.CloseAsync() 

Task CloseAsync()

Closes the client and releases its resources: cancels pending and future calls, which then fail with EngineConnectionException, stops the keepalive, closes the engine session, and closes the gRPC connection if the client owns it.

It is idempotent. Closing is bounded by DisconnectTimeout.

AsyncEngineClient.GetLicenseAsync() 

Task<LicenseState> GetLicenseAsync(CancellationToken ct = default)

Queries the current license state.

Returns the current LicenseState without changing it. The state reports the activation type and, when a license is active, either full or trial activation details.

Parameters:

Returns: The current license state.

AsyncEngineClient.ActivateTrialAsync() 

Task<LicenseState> ActivateTrialAsync(CancellationToken ct = default)

Activates a time-limited trial license and returns the resulting LicenseState. A trial requires no credentials and expires after a fixed period.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit a trial or if the service rejects the activation.

Parameters:

Returns: The resulting license state.

AsyncEngineClient.ActivateWithKeyAsync() 

Task<LicenseState> ActivateWithKeyAsync(
    string licenseKey,
    CancellationToken ct = default)

Activates a full license using the given license key and returns the resulting LicenseState. The activation is granted to this computer and counts against the license's available activations.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit key activation or if the service rejects the activation.

Parameters:

Returns: The resulting license state.

AsyncEngineClient.ActivateWithCredentialsAsync() 

Task<LicenseState> ActivateWithCredentialsAsync(
    string email,
    string password,
    CancellationToken ct = default)

Activates a full license using user account credentials (email and password) and returns the resulting LicenseState. The activation is granted to this computer and counts against the license's available activations.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit credentials activation or if the service rejects the activation.

Parameters:

Returns: The resulting license state.

AsyncEngineClient.DeactivateLicenseAsync() 

Task<LicenseState> DeactivateLicenseAsync(CancellationToken ct = default)

Releases the current activation and returns the updated LicenseState. This frees the activation so it can be used on another computer. Once deactivated, the engine stops audio processing until a license is activated again.

Parameters:

Returns: The updated license state.

AsyncEngineClient.ListPluginsAsync() 

Task<IReadOnlyList<Plugin>> ListPluginsAsync(CancellationToken ct = default)

Lists loaded plugins.

Returns one Plugin per plugin currently loaded in the engine. This lists loaded plugin binaries, not the instances created from them for use as effects.

Parameters:

Returns: The list of loaded plugins.

AsyncEngineClient.LoadPluginAsync() 

Task<Plugin> LoadPluginAsync(
    PluginType type,
    string location,
    CancellationToken ct = default)

Loads the plugin binary at location, treating it as the given type, and returns the resulting Plugin with its assigned UID. The UID can then be used to create instances of the plugin as PluginEffect effects and to address the plugin in messaging calls.

Loading is persistent: the plugin is remembered and loaded again automatically after a restart. The call is idempotent; loading a plugin that is already loaded returns its existing UID without loading it twice. The UID is stable across unload and reload of the same plugin.

Parameters:

Returns: The loaded plugin.

AsyncEngineClient.UnloadPluginAsync() 

Task UnloadPluginAsync(string pluginUid, CancellationToken ct = default)

Unloads the plugin identified by pluginUid and removes it from the persistent set, so it is no longer loaded after a restart. All instances created from the plugin are destroyed and their effects are removed from the flows that contained them.

Parameters:

AsyncEngineClient.SendMessageAsync() 

Task SendMessageAsync(
    EffectSelector targetEffect,
    Any? messagePayload = null,
    CancellationToken ct = default)

Delivers messagePayload to the single plugin instance selected by targetEffect. The payload is an opaque protobuf message understood by the plugin. The message is delivered asynchronously; the call returns once the message is accepted, not once the plugin has processed it.

Parameters:

AsyncEngineClient.BroadcastMessageAsync() 

Task BroadcastMessageAsync(
    string targetPluginUid,
    Any? messagePayload = null,
    CancellationToken ct = default)

Delivers messagePayload to every instance created from the plugin identified by targetPluginUid. Aside from selecting all instances of a plugin rather than one instance, it behaves like SendMessageAsync.

Parameters:

  • targetPluginUid (string) — UID of the plugin whose instances receive the message.
  • messagePayload (Any?) — Opaque message payload.
  • ct (CancellationToken)

AsyncEngineClient.ReceiveMessagesAsync() 

Task<IAsyncEnumerable<PluginMessage>> ReceiveMessagesAsync(
    string sourcePluginUid,
    IEnumerable<EffectSelector> sourceEffects,
    CancellationToken ct = default)

Subscribes to messages produced by the plugin selected by sourcePluginUid, optionally narrowed to the instances listed in sourceEffects, and opens a stream of them. If sourceEffects is empty, messages from all instances of the plugin are received.

The returned sequence yields messages until the stream ends, the session ends, or ct is cancelled. Any error is thrown from the enumerator. Once the subscription is established, every matching message is guaranteed to be delivered, including messages from instances created afterwards.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. The subscription is established when the returned task is awaited: once the task completes, the subscription is active, and every matching message produced from that point on is guaranteed to be delivered. Enumerating the returned sequence yields the messages.

Cancelling ct, or disposing the enumerator (for example by breaking out of the iteration loop), automatically unsubscribes and ends the stream.

Parameters:

Returns: A task that completes once the subscription is active, yielding an async stream of plugin messages.

AsyncEngineClient.GetRunModeAsync() 

Task<RunMode> GetRunModeAsync(CancellationToken ct = default)

Retrieves the current run mode.

Returns a RunMode indicating whether input and output processing are currently enabled or disabled.

Parameters:

Returns: The current run mode.

AsyncEngineClient.SetRunModeAsync() 

Task<RunMode> SetRunModeAsync(RunMode mode, CancellationToken ct = default)

Enables or disables the engine for input, output, or both. Only the directions set on mode are updated; a null input or output processing retains its current value. Returns the resulting RunMode after the change is applied.

Parameters:

Returns: The resulting run mode.

AsyncEngineClient.QueryFlowAsync() 

Task<FlowConfig> QueryFlowAsync(
    FlowSelector selector,
    CancellationToken ct = default)

Retrieves the configuration of a flow.

Locates the flow by selector and returns its FlowConfig, with the current route and effect chain.

Parameters:

Returns: The flow configuration.

AsyncEngineClient.ConfigureFlowAsync() 

Task<FlowConfig> ConfigureFlowAsync(
    FlowSelector selector,
    FlowConfig config,
    CancellationToken ct = default)

Locates the flow by selector and replaces its configuration with config, setting its route and effect chain in one call. Returns the resulting FlowConfig.

If the route is omitted, the default route is used. An empty effect chain means default processing, that is, no processing.

Parameters:

Returns: The resulting flow configuration.

AsyncEngineClient.QueryEffectAsync() 

Task<EffectConfig> QueryEffectAsync(
    FlowSelector selector,
    uint effectKey,
    CancellationToken ct = default)

Retrieves a single effect from a flow.

Locates the effect by selector and effectKey, and returns its EffectConfig. Fails if no such effect exists.

Parameters:

Returns: The effect configuration.

AsyncEngineClient.InsertEffectAsync() 

Task<EffectConfig> InsertEffectAsync(
    FlowSelector selector,
    EffectConfig effectConfig,
    uint chainPosition,
    CancellationToken ct = default)

Locates the flow by selector and inserts effectConfig into its effect chain at the zero-based chainPosition, shifting later effects toward the end. Returns the resulting EffectConfig. Fails if chainPosition is past the end of the chain, or if the effect key is already in use within that chain.

Parameters:

Returns: The resulting effect configuration.

AsyncEngineClient.ConfigureEffectAsync() 

Task<EffectConfig> ConfigureEffectAsync(
    FlowSelector selector,
    EffectConfig effectConfig,
    CancellationToken ct = default)

Reconfigures a single effect in a flow.

Locates the effect by selector and the effect key of effectConfig, and replaces it, keeping its position. Returns the resulting EffectConfig. Fails if no such effect exists.

Parameters:

Returns: The resulting effect configuration.

AsyncEngineClient.DeleteEffectAsync() 

Task DeleteEffectAsync(
    FlowSelector selector,
    uint effectKey,
    CancellationToken ct = default)

Removes a single effect from a flow.

Locates the effect by selector and effectKey, and removes it, shifting later effects toward the start. Fails if no such effect exists.

Parameters:

AsyncEngineClient.ConfigureCaptionsAsync() 

Task<CaptionsConfig> ConfigureCaptionsAsync(
    CaptionsConfig config,
    CancellationToken ct = default)

Selects the captioning provider and configures its credentials.

Sets the provider in config and returns the resulting CaptionsConfig. The built-in provider needs no credentials. To use your own cloud account, select the Bring Your Own Cloud provider and supply the keys in the config.

Parameters:

Returns: The resulting captioning configuration.

AsyncEngineClient.ReceiveCaptionsAsync() 

Task<IAsyncEnumerable<CaptionMessage>> ReceiveCaptionsAsync(
    CancellationToken ct = default)

Subscribes to captions and opens a stream of them. The subscription covers every flow in the session that has captioning enabled.

The returned sequence yields captions until the stream ends, the session ends, or ct is cancelled. Any error is thrown from the enumerator. The DeviceUid of each caption identifies the audio stream it came from.

Captions include both partial and final messages, distinguished by IsPartial. While a phrase is being spoken, several partial messages refine the text, followed by one final message when the phrase is complete.

The Timecode is the position of the caption within the audio stream, measured from the moment captioning started on that flow.

Some fields depend on the provider. In particular, speaker identification (Speaker) is only populated by providers that support it, and is otherwise left empty.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. The subscription is established when the returned task is awaited: once the task completes, the subscription is active, and every caption produced from that point on is guaranteed to be delivered. Enumerating the returned sequence yields the captions.

Cancelling ct, or disposing the enumerator (for example by breaking out of the iteration loop), automatically unsubscribes and ends the stream.

Parameters:

Returns: A task that completes once the subscription is active, yielding an async stream of captions.

AsyncEngineClient.ListDevicesAsync() 

Task<IReadOnlyList<DeviceInfo>> ListDevicesAsync(CancellationToken ct = default)

Lists the available audio devices.

Returns the current input and output devices, each described by a DeviceInfo. Exactly one input device and one output device are marked with Default, indicating the current system default for that direction.

Parameters:

Returns: The list of available devices.

AsyncEngineClient.ReceiveEventsAsync() 

Task<IAsyncEnumerable<EventMessage>> ReceiveEventsAsync(
    CancellationToken ct = default)

Subscribes to engine events and opens a stream of them.

The returned sequence yields events until the stream ends, the session ends, or ct is cancelled. Any error is thrown from the enumerator. Each EventMessage reports a single change through its Code; the application then reads the new state through the relevant call.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. The subscription is established when the returned task is awaited: once the task completes, the subscription is active, and every event produced from that point on is guaranteed to be delivered. Enumerating the returned sequence yields the events.

Cancelling ct, or disposing the enumerator (for example by breaking out of the iteration loop), automatically unsubscribes and ends the stream.

Parameters:

Returns: A task that completes once the subscription is active, yielding an async stream of engine events.

class EngineClientOptions

Namespace: ViveSound.Sdk.Ctl

Configures an AsyncEngineClient. Every field is optional and falls back to the default documented on it.

EngineClientOptions.Address 

Uri? Address { get; set; }

gRPC address of the engine, e.g. http://127.0.0.1:52731. When null (the default), the engine is auto-detected via GetDefaultEngine.

EngineClientOptions.ConnectTimeout 

TimeSpan ConnectTimeout { get; set; }

Bounds establishing the connection and opening the session. Defaults to InfiniteTimeSpan; any value less than or equal to zero waits indefinitely.

EngineClientOptions.DisconnectTimeout 

TimeSpan DisconnectTimeout { get; set; }

Bounds disconnecting the client and closing its session. Defaults to ten seconds; any value less than or equal to zero waits indefinitely.

EngineClientOptions.Mode 

EngineClientOptions.ConnectMode Mode { get; set; }

Behavior when UserName is not the active OS user. Defaults to WaitUser.

EngineClientOptions.RequestTimeout 

TimeSpan RequestTimeout { get; set; }

Bounds a single request to the engine. Defaults to one minute; any value less than or equal to zero waits indefinitely.

EngineClientOptions.UserName 

string? UserName { get; set; }

OS user the session is opened for. When null or empty (the default), the current process user is used.

enum ConnectMode

Namespace: ViveSound.Sdk.Ctl

Selects how connecting behaves when UserName is not the currently active OS user.

ConnectMode.WaitUser 

WaitUser

Block connecting until the requested user becomes the active user. This is the default.

ConnectMode.FailFast 

FailFast

Fail connecting immediately when the requested user is not the active user.

enum EngineCompatibilityError

Namespace: ViveSound.Sdk.Ctl

Identifies a specific EngineCompatibilityException condition.

EngineCompatibilityError.Unknown 

Unknown

Unspecified compatibility error.

EngineCompatibilityError.VersionMismatch 

VersionMismatch

The engine version is incompatible with the client. Can happen when using an older engine with a newer client.

EngineCompatibilityError.UnexpectedResponse 

UnexpectedResponse

The engine returned a successful response that is semantically invalid or incomplete, implying a client/engine protocol or version mismatch. For example, an empty session token or a missing renewal interval.

class EngineCompatibilityException

Namespace: ViveSound.Sdk.Ctl

Indicates that the client and engine versions are not compatible with each other. See Error for the specific condition.

EngineCompatibilityException.Error 

EngineCompatibilityError Error { get; }

Specific compatibility condition that occurred.

EngineCompatibilityException.EngineCompatibilityException() 

EngineCompatibilityException(
    EngineCompatibilityError error,
    Exception? innerException = null)

Creates the exception for the given error.

Parameters:

EngineCompatibilityException.EngineCompatibilityException() 

EngineCompatibilityException(
    EngineCompatibilityError error,
    string message,
    Exception? innerException = null)

Creates the exception for the given error with an explicit message.

Parameters:

enum EngineConnectionError

Namespace: ViveSound.Sdk.Ctl

Identifies a specific EngineConnectionException condition.

EngineConnectionError.Unknown 

Unknown

Unspecified connection error.

EngineConnectionError.NotDiscovered 

NotDiscovered

No engine was found to connect to. Can happen when the engine is not properly installed.

EngineConnectionError.Unavailable 

Unavailable

The connection to the engine could not be established, an established connection was lost, or the session expired on the engine and is no longer usable. Can happen if the active user switches and the engine drops existing sessions, or if the engine is not running or restarts.

class EngineConnectionException

Namespace: ViveSound.Sdk.Ctl

Indicates that the engine cannot be reached: no engine was discovered, the connection could not be established, or an established connection or session was lost. See Error for the specific condition.

EngineConnectionException.Error 

EngineConnectionError Error { get; }

Specific connection condition that occurred.

EngineConnectionException.EngineConnectionException() 

EngineConnectionException(
    EngineConnectionError error,
    Exception? innerException = null)

Creates the exception for the given error.

Parameters:

EngineConnectionException.EngineConnectionException() 

EngineConnectionException(
    EngineConnectionError error,
    string message,
    Exception? innerException = null)

Creates the exception for the given error with an explicit message.

Parameters:

class EngineDiscovery

Namespace: ViveSound.Sdk.Ctl

Discovers ViveEngine instances from local metadata files.

EngineDiscovery.DiscoverEngines() 

static IReadOnlyList<EngineMetadata> DiscoverEngines()

Finds all engine metadata files on the system and returns info about each running engine. Returns an empty list if no engines are found.

EngineDiscovery.TryGetDefaultEngine() 

static bool TryGetDefaultEngine(EngineMetadata& meta)

Parameters:

EngineDiscovery.GetDefaultEngine() 

static EngineMetadata GetDefaultEngine()

Returns metadata for the default shared engine. Throws EngineConnectionException with NotDiscovered if no engine is found.

class EngineException

Namespace: ViveSound.Sdk.Ctl

Base class for every error reported by the client. Each concrete subclass represents one category of failure and carries an Error property that identifies the specific condition within that category.

Callers can branch at two levels:

  • on the exception type, to detect a category of failures, e.g. EngineConnectionException;
  • on the Error property, to detect a specific condition, e.g. Unavailable.

Locally terminated operations are not reported through this hierarchy: a client-side timeout surfaces as TimeoutException and a canceled operation as OperationCanceledException.

EngineException.RpcStatus 

StatusCode? RpcStatus { get; }

gRPC status code that produced this exception, or null for client-side conditions that did not originate from a gRPC status.

class EngineMetadata

Namespace: ViveSound.Sdk.Ctl

Describes a running ViveEngine instance, as reported by its local metadata file.

EngineMetadata.Edition 

string Edition { get; set; }

Human-readable edition title, e.g. "ViveEngine (Shared)".

EngineMetadata.Identifier 

string Identifier { get; set; }

Edition identifier derived from the metadata filename.

EngineMetadata.RpcAddress 

string RpcAddress { get; set; }

gRPC address of the engine, e.g. "127.0.0.1:52731".

EngineMetadata.Version 

string Version { get; set; }

Engine version, e.g. "1.1.92".

enum EngineRequestError

Namespace: ViveSound.Sdk.Ctl

Identifies a specific EngineRequestException condition.

EngineRequestError.Unknown 

Unknown

Unspecified request error.

EngineRequestError.InvalidRequest 

InvalidRequest

The request is ill-formed and was rejected by the engine. For example, a required field is empty, or mutually exclusive fields are set.

EngineRequestError.ResourceNotFound 

ResourceNotFound

The requested identifier was not found. For example, reading an unknown device ID.

EngineRequestError.ResourceAlreadyExists 

ResourceAlreadyExists

The requested identifier already exists. For example, creating a duplicate effect ID.

EngineRequestError.ResourceExhausted 

ResourceExhausted

The engine rejected the operation because a limit was reached. For example, the number of license activations or the maximum number of sessions.

EngineRequestError.PermissionDenied 

PermissionDenied

The engine rejected the operation because the client is not permitted to perform it. For example, enabling processing without an active license, or when processing is locked by another edition of the engine.

class EngineRequestException

Namespace: ViveSound.Sdk.Ctl

Indicates that the request reached the engine and was rejected by it, for example because it was ill-formed or not permitted. See Error for the specific condition.

EngineRequestException.Error 

EngineRequestError Error { get; }

Specific request condition that occurred.

EngineRequestException.EngineRequestException() 

EngineRequestException(
    EngineRequestError error,
    Exception? innerException = null)

Creates the exception for the given error.

Parameters:

EngineRequestException.EngineRequestException() 

EngineRequestException(
    EngineRequestError error,
    string message,
    Exception? innerException = null)

Creates the exception for the given error with an explicit message.

Parameters:

enum EngineRuntimeError

Namespace: ViveSound.Sdk.Ctl

Identifies a specific EngineRuntimeException condition.

EngineRuntimeError.Unknown 

Unknown

Unspecified runtime error.

EngineRuntimeError.EngineFault 

EngineFault

Temporary engine failure. The client is recommended to re-create the session and retry. Also used as a fallback for unmapped engine statuses.

class EngineRuntimeException

Namespace: ViveSound.Sdk.Ctl

Indicates that the engine failed while handling the request, as opposed to rejecting it. The client is typically recommended to retry. See Error for the specific condition.

EngineRuntimeException.Error 

EngineRuntimeError Error { get; }

Specific runtime condition that occurred.

EngineRuntimeException.EngineRuntimeException() 

EngineRuntimeException(
    EngineRuntimeError error,
    Exception? innerException = null)

Creates the exception for the given error.

Parameters:

EngineRuntimeException.EngineRuntimeException() 

EngineRuntimeException(
    EngineRuntimeError error,
    string message,
    Exception? innerException = null)

Creates the exception for the given error with an explicit message.

Parameters:

class EngineServiceCollectionExtensions

Namespace: ViveSound.Sdk.Ctl

Extension methods for registering an IAsyncEngineClient in a dependency injection container.

EngineServiceCollectionExtensions.AddViveEngineAsyncClient() 

static IServiceCollection AddViveEngineAsyncClient(
    IServiceCollection services,
    Action<EngineClientOptions>? configure = null)

Registers an IAsyncEngineClient as a singleton. The optional configure callback customizes the EngineClientOptions used to create it.

Parameters:

EngineServiceCollectionExtensions.AddViveEngineAsyncClient() 

static IServiceCollection AddViveEngineAsyncClient(
    IServiceCollection services,
    GrpcChannel channel,
    Action<EngineClientOptions>? configure = null)

Registers an IAsyncEngineClient as a singleton that uses the supplied channel. The optional configure callback customizes the EngineClientOptions used to create it.

Parameters:

interface IAsyncEngineClient

Namespace: ViveSound.Sdk.Ctl

Interface implemented by AsyncEngineClient. It exists to allow convenient mocking of the client in tests.

See AsyncEngineClient for documentation of the client and its members.

IAsyncEngineClient.Channel 

GrpcChannel Channel { get; }

See Channel.

IAsyncEngineClient.Options 

EngineClientOptions Options { get; }

See Options.

IAsyncEngineClient.IsConnected 

bool IsConnected { get; }

See IsConnected.

IAsyncEngineClient.IsClosed 

bool IsClosed { get; }

See IsClosed.

IAsyncEngineClient.ConnectedAsync 

event Func<object, EventArgs, Task>? ConnectedAsync

See ConnectedAsync.

IAsyncEngineClient.ClosedAsync 

event Func<object, EventArgs, Task>? ClosedAsync

See ClosedAsync.

IAsyncEngineClient.ConnectAsync() 

Task ConnectAsync(CancellationToken ct = default)

See ConnectAsync.

Parameters:

IAsyncEngineClient.CloseAsync() 

Task CloseAsync()

See CloseAsync.

IAsyncEngineClient.GetLicenseAsync() 

Task<LicenseState> GetLicenseAsync(CancellationToken ct = default)

See GetLicenseAsync.

Parameters:

IAsyncEngineClient.ActivateTrialAsync() 

Task<LicenseState> ActivateTrialAsync(CancellationToken ct = default)

See ActivateTrialAsync.

Parameters:

IAsyncEngineClient.ActivateWithKeyAsync() 

Task<LicenseState> ActivateWithKeyAsync(
    string licenseKey,
    CancellationToken ct = default)

See ActivateWithKeyAsync.

Parameters:

IAsyncEngineClient.ActivateWithCredentialsAsync() 

Task<LicenseState> ActivateWithCredentialsAsync(
    string email,
    string password,
    CancellationToken ct = default)

See ActivateWithCredentialsAsync.

Parameters:

IAsyncEngineClient.DeactivateLicenseAsync() 

Task<LicenseState> DeactivateLicenseAsync(CancellationToken ct = default)

See DeactivateLicenseAsync.

Parameters:

IAsyncEngineClient.ListPluginsAsync() 

Task<IReadOnlyList<Plugin>> ListPluginsAsync(CancellationToken ct = default)

See ListPluginsAsync.

Parameters:

IAsyncEngineClient.LoadPluginAsync() 

Task<Plugin> LoadPluginAsync(
    PluginType type,
    string location,
    CancellationToken ct = default)

See LoadPluginAsync.

Parameters:

IAsyncEngineClient.UnloadPluginAsync() 

Task UnloadPluginAsync(string pluginUid, CancellationToken ct = default)

See UnloadPluginAsync.

Parameters:

IAsyncEngineClient.SendMessageAsync() 

Task SendMessageAsync(
    EffectSelector targetEffect,
    Any? messagePayload = null,
    CancellationToken ct = default)

See SendMessageAsync.

Parameters:

IAsyncEngineClient.BroadcastMessageAsync() 

Task BroadcastMessageAsync(
    string targetPluginUid,
    Any? messagePayload = null,
    CancellationToken ct = default)

See BroadcastMessageAsync.

Parameters:

IAsyncEngineClient.ReceiveMessagesAsync() 

Task<IAsyncEnumerable<PluginMessage>> ReceiveMessagesAsync(
    string sourcePluginUid,
    IEnumerable<EffectSelector> sourceEffects,
    CancellationToken ct = default)

See ReceiveMessagesAsync.

Parameters:

IAsyncEngineClient.GetRunModeAsync() 

Task<RunMode> GetRunModeAsync(CancellationToken ct = default)

See GetRunModeAsync.

Parameters:

IAsyncEngineClient.SetRunModeAsync() 

Task<RunMode> SetRunModeAsync(RunMode mode, CancellationToken ct = default)

See SetRunModeAsync.

Parameters:

IAsyncEngineClient.QueryFlowAsync() 

Task<FlowConfig> QueryFlowAsync(
    FlowSelector selector,
    CancellationToken ct = default)

See QueryFlowAsync.

Parameters:

IAsyncEngineClient.ConfigureFlowAsync() 

Task<FlowConfig> ConfigureFlowAsync(
    FlowSelector selector,
    FlowConfig config,
    CancellationToken ct = default)

See ConfigureFlowAsync.

Parameters:

IAsyncEngineClient.QueryEffectAsync() 

Task<EffectConfig> QueryEffectAsync(
    FlowSelector selector,
    uint effectKey,
    CancellationToken ct = default)

See QueryEffectAsync.

Parameters:

IAsyncEngineClient.InsertEffectAsync() 

Task<EffectConfig> InsertEffectAsync(
    FlowSelector selector,
    EffectConfig effectConfig,
    uint chainPosition,
    CancellationToken ct = default)

See InsertEffectAsync.

Parameters:

IAsyncEngineClient.ConfigureEffectAsync() 

Task<EffectConfig> ConfigureEffectAsync(
    FlowSelector selector,
    EffectConfig effectConfig,
    CancellationToken ct = default)

See ConfigureEffectAsync.

Parameters:

IAsyncEngineClient.DeleteEffectAsync() 

Task DeleteEffectAsync(
    FlowSelector selector,
    uint effectKey,
    CancellationToken ct = default)

See DeleteEffectAsync.

Parameters:

IAsyncEngineClient.ConfigureCaptionsAsync() 

Task<CaptionsConfig> ConfigureCaptionsAsync(
    CaptionsConfig config,
    CancellationToken ct = default)

See ConfigureCaptionsAsync.

Parameters:

IAsyncEngineClient.ReceiveCaptionsAsync() 

Task<IAsyncEnumerable<CaptionMessage>> ReceiveCaptionsAsync(
    CancellationToken ct = default)

See ReceiveCaptionsAsync.

Parameters:

IAsyncEngineClient.ListDevicesAsync() 

Task<IReadOnlyList<DeviceInfo>> ListDevicesAsync(CancellationToken ct = default)

See ListDevicesAsync.

Parameters:

IAsyncEngineClient.ReceiveEventsAsync() 

Task<IAsyncEnumerable<EventMessage>> ReceiveEventsAsync(
    CancellationToken ct = default)

See ReceiveEventsAsync.

Parameters:

enum ActivationType

Namespace: ViveSound.Sdk.Ctl.Dto

The activation type, used both to request an activation method and to report the current one in LicenseState.

Which types an engine accepts depends on its edition. During activation the engine contacts the licensing service, which grants or denies the request; a granted activation stays in effect across restarts until it expires or is deactivated. Editions that require no license report None and run without activation.

ActivationType.None 

None

No license is active. In LicenseState this means the engine runs without activation or has not been activated yet.

ActivationType.Trial 

Trial

A time-limited trial bound to this computer. Requires no credentials and expires after a fixed period.

ActivationType.Key 

Key

A full activation using a license key. The activation is granted to this computer and counts against the license's available activations.

ActivationType.Creds 

Creds

A full activation using user account credentials. The activation is granted to this computer and counts against the license's available activations.

class CaptionMessage

Namespace: ViveSound.Sdk.Ctl.Dto

A single caption produced by captioning.

Streamed by ReceiveCaptionsAsync.

CaptionMessage.DeviceUid 

string DeviceUid { get; set; }

Device whose audio stream this caption was transcribed from.

CaptionMessage.IsPartial 

bool IsPartial { get; set; }

Whether this is a partial caption. While a phrase is being spoken, it is delivered as a series of partial captions, each of which may hold an incomplete phrase, be inaccurate, and change as the speaker continues. The phrase ends with a single final caption (with IsPartial set to false) that holds its settled text.

CaptionMessage.Speaker 

string Speaker { get; set; }

Label of the detected speaker, when speaker identification is available. Only populated by providers that support it, and otherwise left empty.

CaptionMessage.Text 

string Text { get; set; }

Transcribed text of the caption.

CaptionMessage.Timecode 

TimeSpan Timecode { get; set; }

Position of the caption within the audio stream, measured from the moment captioning started.

class CaptioningEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A speech captioning effect.

Adding this effect to a flow's effect chain enables live transcription of speech in that flow.

CaptioningEffect.LanguageCode 

string LanguageCode { get; set; }

BCP-47 language code of the spoken language to transcribe, for example "en-US". If empty, the provider's default language is used.

class CaptionsAuth

Namespace: ViveSound.Sdk.Ctl.Dto

Holds credentials for the Bring Your Own Cloud captioning provider.

Supplies the keys of the user's own AWS account, used to access AWS Transcribe.

CaptionsAuth.AwsAccessKey 

string AwsAccessKey { get; set; }

AWS access key ID. Required and must be non-empty.

CaptionsAuth.AwsSecretKey 

string AwsSecretKey { get; set; }

AWS secret access key. Required and must be non-empty.

class CaptionsConfig

Namespace: ViveSound.Sdk.Ctl.Dto

The captioning provider configuration.

Return value of ConfigureCaptionsAsync, also carried by its input argument. In a return value ByocAuth is never set, because the credentials are write-only.

CaptionsConfig.ByocAuth 

CaptionsAuth? ByocAuth { get; set; }

Cloud credentials for the Bring Your Own Cloud provider. Required when Provider is Byoc, and must be omitted otherwise. See CaptionsAuth.

CaptionsConfig.Provider 

CaptionsProvider Provider { get; set; }

Captioning provider to use. See CaptionsProvider.

enum CaptionsProvider

Namespace: ViveSound.Sdk.Ctl.Dto

The captioning provider.

CaptionsProvider.Billed 

Billed

The built-in provider billed by ViveSound. Requires no credentials, but is only available when the license allows it.

CaptionsProvider.Byoc 

Byoc

The Bring Your Own Cloud provider that uses the user's own cloud account. Requires credentials to be supplied in ByocAuth.

enum DeviceDriver

Namespace: ViveSound.Sdk.Ctl.Dto

The operating-system audio backend a device belongs to.

DeviceDriver.Unspecified 

Unspecified

The backend is unknown or unspecified.

DeviceDriver.CoreAudio 

CoreAudio

Core Audio, used on macOS.

DeviceDriver.WASAPI 

WASAPI

WASAPI, used on Windows.

enum DeviceFeatures

Namespace: ViveSound.Sdk.Ctl.Dto

Individual flags of Features.

The connection and type flags (for example Bluetooth or USB) are best-effort hints reported by the operating system.

DeviceFeatures.None 

None

No flags set.

DeviceFeatures.Input 

Input

An input (capture) device. Set for every device in the input list.

DeviceFeatures.Output 

Output

An output (playback) device. Set for every device in the output list.

DeviceFeatures.Default 

Default

The current system default device for its direction. Set on exactly one input and one output device.

DeviceFeatures.Virtual 

Virtual

A virtual device not backed by physical hardware.

DeviceFeatures.Builtin 

Builtin

A microphone or speaker integrated into the computer itself, rather than an external or removable device.

DeviceFeatures.Headset 

Headset

Headphones or a headset. Headphones provide playback only, while a headset combines headphones with a microphone. May be connected in any way, such as a wired jack, USB, or Bluetooth.

DeviceFeatures.Bluetooth 

Bluetooth

A device connected via Bluetooth.

DeviceFeatures.Airplay 

Airplay

A device connected via AirPlay.

DeviceFeatures.USB 

USB

A device connected via USB. This may be a USB audio device such as a USB headset, or a USB sound card, in which case the attached hardware (headset, speakers, and so on) is usually unknown.

DeviceFeatures.Thunderbolt 

Thunderbolt

A device connected via Thunderbolt.

DeviceFeatures.HDMI 

HDMI

A device connected via HDMI.

DeviceFeatures.DisplayPort 

DisplayPort

A device connected via DisplayPort.

class DeviceInfo

Namespace: ViveSound.Sdk.Ctl.Dto

A single audio device.

DeviceInfo.DisplayName 

string DisplayName { get; set; }

Human-readable, one-line device title suitable for display. On macOS it is derived from the Core Audio data source or device name; on Windows it is the WASAPI endpoint friendly name. Not guaranteed to be unique.

DeviceInfo.Driver 

DeviceDriver Driver { get; set; }

Operating-system audio backend that provides the device: Core Audio on macOS, WASAPI on Windows.

DeviceInfo.Features 

DeviceFeatures Features { get; set; }

Device properties, as a combination of DeviceFeatures flags.

DeviceInfo.IsAirplay 

bool IsAirplay { get; }

Whether the device has the Airplay flag.

DeviceInfo.IsBluetooth 

bool IsBluetooth { get; }

Whether the device has the Bluetooth flag.

DeviceInfo.IsBuiltin 

bool IsBuiltin { get; }

Whether the device has the Builtin flag.

DeviceInfo.IsDefault 

bool IsDefault { get; }

Whether the device has the Default flag.

DeviceInfo.IsDisplayPort 

bool IsDisplayPort { get; }

Whether the device has the DisplayPort flag.

DeviceInfo.IsHdmi 

bool IsHdmi { get; }

Whether the device has the HDMI flag.

DeviceInfo.IsHeadset 

bool IsHeadset { get; }

Whether the device has the Headset flag.

DeviceInfo.IsInput 

bool IsInput { get; }

Whether the device has the Input flag.

DeviceInfo.IsOutput 

bool IsOutput { get; }

Whether the device has the Output flag.

DeviceInfo.IsThunderbolt 

bool IsThunderbolt { get; }

Whether the device has the Thunderbolt flag.

DeviceInfo.IsUsb 

bool IsUsb { get; }

Whether the device has the USB flag.

DeviceInfo.IsVirtual 

bool IsVirtual { get; }

Whether the device has the Virtual flag.

DeviceInfo.SystemName 

string SystemName { get; set; }

Platform-specific device identifier assigned by the operating system. On macOS this is the Core Audio device UID; on Windows it is the WASAPI endpoint ID. Its format is driver-dependent and may contain special characters. This is a low-level identifier, not a name meant for display; use Uid to identify a device and DisplayName to present it to the user.

DeviceInfo.Uid 

string Uid { get; set; }

Stable, engine-specific device identifier. This is not an operating-system device name. It has a platform-independent format and is derived by the engine so that the same physical device always keeps the same UID, even after it is disconnected and connected again. Use it in Route to route a flow to this device.

class EffectConfig

Namespace: ViveSound.Sdk.Ctl.Dto

The configuration of a single effect within an effect chain.

An effect is either one of the built-in effects provided by the engine or a plugin effect. Exactly one of the effect fields selects the kind of effect and carries its parameters.

EffectConfig.Captioning 

CaptioningEffect? Captioning { get; set; }

Speech captioning. See CaptioningEffect.

EffectConfig.Disabled 

bool Disabled { get; set; }

When true, the effect is kept in the chain but bypassed, passing audio through unchanged. Defaults to false (active).

EffectConfig.EffectKey 

uint EffectKey { get; set; }

Caller-assigned key that identifies the effect within its chain. Must be unique within the chain. Used to address the effect in QueryEffectAsync, ConfigureEffectAsync, and DeleteEffectAsync.

EffectConfig.Equalizer 

EqualizerEffect? Equalizer { get; set; }

Multi-band equalizer. See EqualizerEffect.

EffectConfig.Gain 

GainEffect? Gain { get; set; }

Per-channel gain. See GainEffect.

EffectConfig.NoiseReduction 

NoiseReductionEffect? NoiseReduction { get; set; }

Noise reduction. See NoiseReductionEffect.

EffectConfig.Plugin 

PluginEffect? Plugin { get; set; }

Plugin effect. See PluginEffect.

EffectConfig.RangeCompression 

RangeCompressionEffect? RangeCompression { get; set; }

Dynamic range compression. See RangeCompressionEffect.

class EffectSelector

Namespace: ViveSound.Sdk.Ctl.Dto

Addresses a single effect within a flow.

Combines a FlowSelector with the EffectKey of one effect in that flow's effect chain.

EffectSelector.Direction 

FlowDirection Direction { get; set; }

Whether the effect belongs to the input or output flow. See FlowDirection.

EffectSelector.EffectKey 

uint EffectKey { get; set; }

Key of the effect within the flow's effect chain.

EffectSelector.Scope 

FlowScope Scope { get; set; }

Which flow the effect belongs to. See FlowScope.

class EqualizerEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A multi-band equalizer effect.

Shapes the spectrum by applying an independent gain to each of a series of contiguous frequency bands. BandFrequencies and BandGains are parallel arrays and must have the same length: entry i defines band i.

The bands are ordered from low to high frequency. BandFrequencies gives the upper edge of each band in ascending order; a band covers from the previous band's edge (or DC for the first band) up to its own edge. The final band extends up to the Nyquist frequency, so its edge only needs to be at or above the highest reproduced frequency.

EqualizerEffect.BandFrequencies 

ImmutableArray<double> BandFrequencies { get; set; }

Upper edge frequency of each band, in Hz, in strictly ascending order. If empty, a default of eight octave-spaced bands is used (from about 177 Hz up to about 22627 Hz).

EqualizerEffect.BandGains 

ImmutableArray<double> BandGains { get; set; }

Gain applied within each band, in dB. Parallel to BandFrequencies. A positive value boosts the band, a negative value cuts it, and 0 leaves it flat. If empty, all bands default to 0 dB (flat response).

enum EventCode

Namespace: ViveSound.Sdk.Ctl.Dto

The kind of change reported by an EventMessage.

EventCode.RunModeChanged 

RunModeChanged

The run mode changed; read the new value with GetRunModeAsync. This can happen after user interaction, for example a call to SetRunModeAsync, or on its own, for example when a license expires and the engine disables itself.

EventCode.LicenseStateChanged 

LicenseStateChanged

The license state changed; read the new state with GetLicenseAsync. This can happen after user interaction, for example a call to ActivateTrialAsync, ActivateWithKeyAsync, ActivateWithCredentialsAsync, or DeactivateLicenseAsync, or on its own, for example when a license expires or the engine re-verifies it in the background.

EventCode.PluginListChanged 

PluginListChanged

The set of loaded plugins changed; read the new list with ListPluginsAsync. This can happen after user interaction, for example a call to LoadPluginAsync or UnloadPluginAsync, or on its own, for example when a plugin fails or its process exits.

EventCode.DeviceListChanged 

DeviceListChanged

The set of available devices changed; read the new list with ListDevicesAsync. This can happen after user interaction, for example connecting or disconnecting a device, or on its own, for example when the system default input or output device changes.

class EventMessage

Namespace: ViveSound.Sdk.Ctl.Dto

A single event reporting a change in the engine's state.

Streamed by ReceiveEventsAsync. An event carries no payload beyond its Code and Time; it only signals that something changed. Subscribing reports later changes but not the current state.

EventMessage.Code 

EventCode Code { get; set; }

What changed. See EventCode.

EventMessage.Time 

DateTime Time { get; set; }

Point in time at which the engine emitted the event.

class FlowConfig

Namespace: ViveSound.Sdk.Ctl.Dto

The configuration of a single flow.

Return value of QueryFlowAsync and ConfigureFlowAsync, and the configuration passed to ConfigureFlowAsync.

FlowConfig.EffectChain 

ImmutableArray<EffectConfig> EffectChain { get; set; }

Ordered list of effects applied to the audio, from first to last. An empty chain means default processing, that is, no processing. See EffectConfig.

FlowConfig.Route 

Route? Route { get; set; }

Route that selects the device used by the flow. If omitted, the default route is used. Only meaningful for application flows; ignored for device flows. See Route.

enum FlowDirection

Namespace: ViveSound.Sdk.Ctl.Dto

The direction of a flow: capture or playback.

FlowDirection.Input 

Input

The input (capture) flow, for audio captured from an input device.

FlowDirection.Output 

Output

The output (playback) flow, for audio played to an output device.

enum FlowScope

Namespace: ViveSound.Sdk.Ctl.Dto

The scope of a flow: which entity it applies to.

FlowScope.Default 

Default

The default flow, applied to applications that have no flow of their own.

class FlowSelector

Namespace: ViveSound.Sdk.Ctl.Dto

Addresses a single flow by scope and direction.

FlowSelector.Direction 

FlowDirection Direction { get; set; }

Whether the input or the output flow is selected. See FlowDirection.

FlowSelector.Scope 

FlowScope Scope { get; set; }

Which flow the selector refers to. See FlowScope.

class FullActivation

Namespace: ViveSound.Sdk.Ctl.Dto

Details of a full (key or credentials) license, reported in LicenseState.

FullActivation.ActivationDate 

DateTimeOffset? ActivationDate { get; set; }

Point in time when this computer was activated.

FullActivation.AvailableActivations 

int AvailableActivations { get; set; }

Total number of activations the license permits.

FullActivation.ExpirationDate 

DateTimeOffset? ExpirationDate { get; set; }

Point in time after which the license expires.

FullActivation.IssueDate 

DateTimeOffset? IssueDate { get; set; }

Point in time when the license was issued.

FullActivation.UsedActivations 

int UsedActivations { get; set; }

Number of activations currently in use across all computers.

class GainEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A per-channel gain effect.

Applies a constant gain to each channel independently, in decibels. A positive value amplifies, a negative value attenuates, and 0 leaves the channel unchanged.

GainEffect.ChannelGains 

ImmutableArray<double> ChannelGains { get; set; }

Gain per channel, in dB. The n-th entry applies to the n-th channel. If fewer entries are given than there are channels, the last entry applies to all remaining channels. If empty, a gain of 0 dB (unity) is applied to every channel. Typical range is roughly -60 to +30 dB.

class LicenseState

Namespace: ViveSound.Sdk.Ctl.Dto

Return value of GetLicenseAsync, ActivateTrialAsync, ActivateWithKeyAsync, ActivateWithCredentialsAsync, and DeactivateLicenseAsync.

The details are present only when a license is active, and the populated field matches Type: a trial activation reports TrialActivation, a full (key or credentials) activation reports FullActivation. When Type is None no license is active and both details are null.

LicenseState.FullActivation 

FullActivation? FullActivation { get; set; }

Details of a full license, set when Type is Key or Creds.

LicenseState.TrialActivation 

TrialActivation? TrialActivation { get; set; }

Details of a trial license, set when Type is Trial.

LicenseState.Type 

ActivationType Type { get; set; }

Current activation type, or None when no license is active. See ActivationType.

class NoiseReductionEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A noise reduction effect.

Attenuates steady background noise while preserving the desired signal. The Mode selects the algorithm. See NoiseReductionMode.

NoiseReductionEffect.Mode 

NoiseReductionMode Mode { get; set; }

Noise reduction algorithm to use. See NoiseReductionMode.

enum NoiseReductionMode

Namespace: ViveSound.Sdk.Ctl.Dto

The noise reduction algorithm.

NoiseReductionMode.DSP 

DSP

Classic spectral noise reduction. This is the default.

NoiseReductionMode.RNN 

RNN

Neural-network noise reduction. More aggressive than DSP and generally more effective on speech.

class Plugin

Namespace: ViveSound.Sdk.Ctl.Dto

A plugin loaded in the engine.

Returned by LoadPluginAsync and listed by ListPluginsAsync. This describes a loaded plugin binary, not an instance of it; instances are PluginEffect effects placed into flows.

Plugin.InstanceCount 

uint InstanceCount { get; set; }

Number of instances currently created from this plugin across all flows.

Plugin.Location 

string Location { get; set; }

Filesystem path the plugin was loaded from, as passed to LoadPluginAsync.

Plugin.Type 

PluginType Type { get; set; }

Kind of plugin binary. See PluginType.

Plugin.Uid 

string Uid { get; set; }

Identifier of the plugin. Derived from the plugin and stable across unload and reload, so the same plugin keeps the same UID. Used to create instances and to address the plugin in messaging calls.

class PluginEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A plugin effect.

Runs an instance of a loaded plugin as an effect in the chain.

PluginEffect.CustomConfig 

Any? CustomConfig { get; set; }

Optional plugin-specific configuration passed to the plugin instance constructor. An opaque protobuf message whose schema is defined by the plugin developer and shared with the application.

PluginEffect.PluginUid 

string PluginUid { get; set; }

UID of the plugin to instantiate, as returned by LoadPluginAsync. The plugin must be currently loaded.

class PluginMessage

Namespace: ViveSound.Sdk.Ctl.Dto

A message produced by a plugin instance.

Streamed by ReceiveMessagesAsync.

PluginMessage.MessagePayload 

Any? MessagePayload { get; set; }

Message payload. An opaque protobuf message whose schema is defined by the plugin developer and shared with the application.

PluginMessage.SourceEffect 

EffectSelector? SourceEffect { get; set; }

Instance that produced the message, addressed by its effect within a flow. See EffectSelector.

PluginMessage.SourcePluginUid 

string SourcePluginUid { get; set; }

Plugin that produced the message, as returned by LoadPluginAsync.

enum PluginType

Namespace: ViveSound.Sdk.Ctl.Dto

The kind of a plugin binary, selecting how the engine loads and runs it.

PluginType.Unspecified 

Unspecified

Unset. Not a valid value in a LoadPluginAsync request.

PluginType.Native 

Native

A native plugin, a shared library loaded directly into the engine's address space for the lowest overhead. The binary is a shared library with a platform-specific extension: .dll on Windows, .so on Linux and macOS.

PluginType.Golang 

Golang

A managed plugin written in Go using the vsplug package. The plugin is compiled into a regular executable that the engine runs as a separate process and communicates with over IPC. The binary is an executable with a platform-specific extension: .exe on Windows, no extension on Linux and macOS.

class ProcessingMode

Namespace: ViveSound.Sdk.Ctl.Dto

The state of the engine for a single audio direction (input or output).

ProcessingMode.Enabled 

bool Enabled { get; set; }

Whether the engine is active on this direction. When false, the engine detaches from the corresponding audio path and audio flows through the OS unmodified.

class RangeCompressionEffect

Namespace: ViveSound.Sdk.Ctl.Dto

A dynamic range compression effect.

A multi-band automatic gain control that raises the level of quiet signals and holds louder signals near a set of per-band target levels, reducing the overall dynamic range and evening out perceived loudness.

RangeCompressionEffect.BoostLevel 

double BoostLevel { get; set; }

Maximum gain applied to quiet signals, in dB. Bounds how much the effect may boost signals below the target level. Range 0 to 40 dB; recommended default 30 dB.

RangeCompressionEffect.CompressionRatio 

double CompressionRatio { get; set; }

Compression ratio applied to signals that exceed the target level, expressed as the input-to-output ratio (for example 10 means 10:1). A higher ratio makes the level more even; a lower ratio sounds more natural. Range 1 (no compression) to 20; recommended default 10.

RangeCompressionEffect.Levels 

RangeCompressionLevels? Levels { get; set; }

Per-band target loudness. If omitted, the default per-band targets are used. See RangeCompressionLevels.

class RangeCompressionLevels

Namespace: ViveSound.Sdk.Ctl.Dto

The per-band target loudness for RangeCompressionEffect.

Each field sets the loudness the compressor aims for in one frequency band, in dBFS (decibels relative to full scale, so 0 is the loudest possible and negative values are quieter). Range for each field is -40 to 0 dBFS.

RangeCompressionLevels.BassTargetLevel 

double BassTargetLevel { get; set; }

Target loudness for the low band, in dBFS. Recommended default -20 dBFS.

RangeCompressionLevels.MidsTargetLevel 

double MidsTargetLevel { get; set; }

Target loudness for the mid band, in dBFS. Recommended default -8 dBFS.

RangeCompressionLevels.TrebleTargetLevel 

double TrebleTargetLevel { get; set; }

Target loudness for the high band, in dBFS. Recommended default -12 dBFS.

class Route

Namespace: ViveSound.Sdk.Ctl.Dto

The route of a flow: the device its audio is bound to.

Route.DeviceUid 

string DeviceUid { get; set; }

UID of the device the flow is routed to, as reported by ListDevicesAsync. See DeviceInfo.

class RunMode

Namespace: ViveSound.Sdk.Ctl.Dto

Return value of GetRunModeAsync and SetRunModeAsync.

Reports whether the engine is currently active on the input and output audio paths.

RunMode.InputProcessing 

ProcessingMode? InputProcessing { get; set; }

Current state of input processing. When passed to SetRunModeAsync, a null value leaves input processing unchanged. See ProcessingMode.

RunMode.OutputProcessing 

ProcessingMode? OutputProcessing { get; set; }

Current state of output processing. When passed to SetRunModeAsync, a null value leaves output processing unchanged. See ProcessingMode.

class TrialActivation

Namespace: ViveSound.Sdk.Ctl.Dto

Details of a trial license, reported in LicenseState.

TrialActivation.ExpirationDate 

DateTimeOffset? ExpirationDate { get; set; }

Point in time after which the trial expires.