// 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;

@discoverable
open protocol Player {
    /// Read audio data from a socket in WAV format and play it to a destination.
    ///
    /// Returns when all bytes have been read from the socket.
    flexible Play(resource table {
        /// Socket for the client to send audio data in WAV format.
        ///
        /// The client should transmit an entire file, then close the socket.
        ///
        /// Required.
        1: wav_source zx.Handle:<SOCKET, zx.Rights.READ | zx.Rights.WAIT | zx.Rights.DUPLICATE>;

        /// The destination to which to play the audio.
        ///
        /// Required.
        2: destination @generated_name("PlayDestination") flexible union {
            /// Create an `AudioRenderer` using the audio_core API and play audio through it.
            1: renderer @generated_name("RendererConfig") flexible union {
                /// Renderer for standard frequencies.
                1: standard_renderer @generated_name("StandardRendererConfig") table {
                    /// The usage of the audio stream.
                    ///
                    /// Required.
                    1: usage fuchsia.media.AudioRenderUsage;

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

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

                /// Renderer for ultrasonic frequencies.
                2: ultrasound_renderer @generated_name("UltrasoundRendererConfig") table {
                    /// How many packets to use when sending data to the `AudioRenderer`.
                    ///
                    /// Optional. If not specified, defaults to four packets.
                    1: packet_count uint32;
                };
            };

            /// A device ring buffer.
            2: device_ring_buffer DeviceRingBuffer;
        };

        /// 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;
};