sdk/fidl/fuchsia.audio.controller/play.fidl

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

library fuchsia.audio.controller;

using fuchsia.media;
using zx;

/// Where to output audio data supplied by an ffx client.
type PlayLocation = flexible union {
    /// Create an `AudioRenderer` using the audio_core API and play audio through it.
    1: renderer RendererConfig;

    /// Write audio data directly to a device ring buffer.
    2: device_ring_buffer DeviceSelector;
};

/// Selection of the frequency range than an `AudioRenderer` can write.
type RendererConfig = flexible union {
    /// Renderer for standard frequencies.
    1: standard_renderer StandardRendererConfig;

    /// Renderer for ultrasonic frequencies.
    2: ultrasound_renderer UltrasoundRendererConfig;
};

/// Configuration parameters for creating an `AudioRenderer` for the standard frequency range.
type StandardRendererConfig = table {
    /// The usage of the audio stream.
    ///
    /// Required.
    1: usage fuchsia.media.AudioRenderUsage;

    /// The reference clock type used by the stream. If unspecified, use the default
    /// reference clock provided by the renderer.
    ///
    /// Optional.
    2: clock ClockType;

    /// How many packets to use when sending data to an `AudioRenderer`.
    /// Optional. If not specified, AudioDaemon will use four packets.
    3: packet_count uint32;
};

/// Configuration parameters for creating an `AudioRenderer` for the standard frequency range.
type UltrasoundRendererConfig = table {
    /// How many packets to use when sending data to an `AudioRenderer`.
    /// Optional. If not specified, AudioDaemon will use four packets.
    1: packet_count uint32;
};

@discoverable
open protocol Player {
    /// Plays audio data from socket on either an `AudioRenderer` or on device ring buffer.
    /// Returns sockets for transmitting info back to stdout and stderr on host.
    flexible Play(resource table {
        /// Socket for audio data. Should transmit entire file in WAV format.
        ///
        /// Required.
        1: socket zx.Handle:SOCKET;

        /// Play on device ring buffer or AudioRenderer.
        ///
        /// Required.
        2: location PlayLocation;

        /// Play settings.
        ///
        /// Required.
        3: gain_settings GainSettings;
    }) -> (resource table {
        /// Information from daemon component for ffx plugin to display.
        ///
        /// Required.
        1: stdout zx.Handle:SOCKET;

        /// Errors from daemon component for ffx plugin to display.
        ///
        /// Required.
        2: stderr zx.Handle:SOCKET;
    }) error zx.Status;
};