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 PlayDestination = 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.
    /// Return when all bytes have been read from the socket.
    flexible Play(resource table {
        /// Socket for the client to send audio data. Should transmit entire file in WAV format.
        ///
        /// Required.
        1: wav_source zx.Handle:<SOCKET, zx.Rights.READ | zx.Rights.WAIT | zx.Rights.DUPLICATE>;

        /// Play on device ring buffer or AudioRenderer.
        ///
        /// Required.
        2: destination PlayDestination;

        /// Play settings.
        ///
        /// Optional. If not specified, use unity gain unmuted, and no other gain
        /// processing enabled.
        3: gain_settings GainSettings;
    }) -> (resource table {
        /// Total number of bytes sent to destination.
        1: bytes_processed uint64;
    }) error Error;
};