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

/// Cancels a `Recorder.Record` request.
open protocol RecordCanceler {
    /// Stop recording and writing data on the output socket.
    strict Cancel() -> () error zx.Status;
};

@discoverable
open protocol Recorder {
    /// Record audio data and write it to a socket in WAV format.
    flexible Record(resource table {
        /// The source from which to record the audio.
        ///
        /// Required.
        1: source @generated_name("RecordSource") flexible union {
            /// An audio_core `AudioCapturer` protocol connection.
            1: capturer @generated_name("CapturerConfig") flexible union {
                /// `AudioCapturer` for standard frequencies.
                1: standard_capturer @generated_name("StandardCapturerConfig") table {
                    /// The usage of the audio stream.
                    ///
                    /// Required.
                    1: usage fuchsia.media.AudioCaptureUsage;

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

                /// `AudioCapturer` for ultrasonic frequencies.
                2: ultrasound_capturer struct {};
            };

            /// An audio_core `AudioCapturer` protocol connection with loopback enabled.
            2: loopback struct {};

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

        /// The stream format in which to record the audio.
        ///
        /// Required.
        2: stream_type fuchsia.media.AudioStreamType;

        /// Duration in nanoseconds to record audio data.
        ///
        /// If not specified, `Recorder` will record and write data to the
        /// socket until it receives a stop signal on `canceler`.
        ///
        /// If present, the record request is still cancelable via `canceler`.
        ///
        /// Optional.
        3: duration zx.Duration;

        /// Handle to signal when to stop sending data back to the client.
        ///
        /// Required.
        4: canceler server_end:RecordCanceler;

        /// Record gain settings.
        ///
        /// Only used for the `capturer` and `loopback` sources.
        ///
        /// Optional.
        5: gain_settings GainSettings;

        /// Buffer size.
        ///
        /// Optional. If not specified, defaults to a size that is enough to
        /// hold one second of audio data.
        6: buffer_size uint64;

        /// Sink for audio data.
        ///
        /// The captured data here will be written here as a complete WAV file.
        ///
        /// Required.
        7: wav_data zx.Handle:SOCKET;
    }) -> (resource table {
        /// Total number of bytes read from the source.
        1: bytes_processed uint64;

        /// If applicable, number of packets read from an `AudioCapturer`.
        2: packets_processed uint64;

        /// If applicable, number of times the capturer woke up too late to
        /// read valid data from the device.
        ///
        /// If this is non-zero, some data was lost and replaced with silence.
        3: late_wakeups uint64;
    }) error Error;
};