sdk/fidl/fuchsia.audio.controller/audio_proxy.fidl

// Copyright 2022 The Fuchsia Authors.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

/// This library contains protocols used by the `ffx audio` tool only.
@available(added=HEAD)
library fuchsia.audio.controller;

using fuchsia.hardware.audio;
using fuchsia.io;
using zx;

/// Maximum number of audio devices in the system at any time.
const MAX_COUNT_DEVICES uint32 = 256;

/// Information about a device.
type DeviceInfo = flexible union {
    /// Device supports the fuchsia.hardware.audio/StreamConfig protocol.
    1: stream_config StreamConfigDeviceInfo;
};

/// Information about a device that supports the fuchsia.hardware.audio/StreamConfig protocol.
type StreamConfigDeviceInfo = table {
    /// Top level static properties of the stream.
    ///
    /// Required.
    1: stream_properties fuchsia.hardware.audio.StreamProperties;

    /// Supported formats.
    ///
    /// Required.
    2: supported_formats
            vector<fuchsia.hardware.audio.SupportedFormats>:fuchsia.hardware.audio.MAX_COUNT_FORMATS;

    /// Gain state.
    ///
    /// Required.
    3: gain_state fuchsia.hardware.audio.GainState;

    /// Plug state.
    ///
    /// Required.
    4: plug_state fuchsia.hardware.audio.PlugState;
};

/// Identifies which device to retrieve information about.
type DeviceSelector = table {
    /// Whether device is input or output.
    ///
    /// Required. Future device types may not require this field.
    1: is_input bool;

    /// ID of device.
    ///
    /// Required.
    2: id fuchsia.io.Path;

    /// Device type. If not specified, defaults to StreamConfig.
    3: device_type fuchsia.hardware.audio.DeviceType;
};


/// Enumerate, query, and control audio devices from clients.
@discoverable
open protocol DeviceControl {

    /// Lists all available audio devices on target.
    flexible ListDevices() -> (resource table {
        /// List of available devices, sorted by name.
        ///
        /// Required.
        1: devices vector<DeviceSelector>:MAX_COUNT_DEVICES;
    }) error zx.Status;

    /// Returns details about a specific audio device.
    flexible GetDeviceInfo(resource table {
        /// Id of device to retrieve information about, and
        /// whether it is an input or output device.
        ///
        /// Required.
        1: device DeviceSelector;
    }) -> (resource table {
        /// Information about the device.
        ///
        /// Required.
        1: device_info DeviceInfo;
    }) error zx.Status;

    /// Sets the gain of the stream in decibels.
    flexible DeviceSetGainState(resource table {
        /// Id of the device to set the gain state.
        ///
        /// Required.
        1: device DeviceSelector;

        /// Desired gain state.
        ///
        /// Required.
        2: gain_state fuchsia.hardware.audio.GainState;
    }) -> () error zx.Status;
};