IMediaDevice

interface NatML.Devices.IMediaDevice<TSampleBuffer> : System.IEquatable<IMediaDevice>

This is the fundamental interface that all media devices--camera or microphone--inherit from.

This interface has a non-generic counterpart which does not define the StartRunning method.

Identifying the Device

Media devices can be identified in several ways:

Unique Identifier

/// <summary>
/// Device unique ID.
/// </summary>
string uniqueID { get; }

Most IMediaDevice instances will abstract a hardware media device, and as such these hardware devices can be uniquely identified by their ID.

Multiple IMediaDevice instances can refer to the same hardware device. As such, you must not use multiple IMediaDevice instances for the same hardware device.

Device Name

/// <summary>
/// Display friendly device name.
/// </summary>
string name { get; }

Media devices provide a localized, display-friendly name to present to the user. This can be useful for building device selection UI's.

Device Location

/// <summary>
/// Device location.
/// </summary>
DeviceLocation location { get; }

Media devices can report their location relative to their host device:

/// <summary>
/// Device location.
/// </summary>
enum DeviceLocation : int {
    /// <summary>
    /// Device location is unknown.
    /// </summary>
    Unknown = 0,
    /// <summary>
    /// Device is internal.
    /// </summary>
    Internal = 1 << 0,
    /// <summary>
    /// Device is external.
    /// </summary>
    External = 1 << 1
}

Default Device

/// <summary>
/// Device is the default device for its media type.
/// </summary>
bool defaultForMediaType { get; }

Media devices can report whether they are the default device for their type. This can be useful for preserving a user's existing audio configuration when streaming.

For a given media device type, a default device is not guaranteed to exist. As a result, do not expect to always discover a default device.

Checking the Device State

/// <summary>
/// Is the device running?
/// </summary>
bool running { get; }

This property reports whether the media device is running.

Streaming Sample Buffers

/// <summary>
/// Start running.
/// </summary>
/// <param name="handler">Delegate to receive sample buffers.</param>
void StartRunning (Action<TSampleBuffer> handler);

Media devices work by streaming sample buffers to a provided delegate function. The type of the sample buffer TSampleBuffer is generic, and specified by implementations of the IMediaDevice interface.

This method is only defined on the generic IMediaDevice<T> interface. The non-generic IMediaDevice interface does not define this method.

Stopping the Stream

/// <summary>
/// Stop running.
/// </summary>
void StopRunning ();

When you are done streaming, you must stop the device.

NatDevice does not automatically stop and restart media devices when the app is suspended and resumed, so you must manage this yourself.

Handling Device Disconnection

/// <summary>
/// Event raised when the device is disconnected.
/// </summary>
event Action onDisconnected { add; remove; }

Media devices expose an event which is raised when the device is disconnected or becomes otherwise unavailable. NatDevice automatically handles any shut down operations required, so that no action is needed from the client when the event is raised.

This event is not guaranteed to be raised on the Unity main thread.