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

library fuchsia.audio.mixer;

using fuchsia.audio;
using fuchsia.audio.effects;
using fuchsia.media2;
using fuchsia.mediastreams;
using zx;

/// A Producer node can pull from a StreamSink or a RingBuffer.
type ProducerDataSource = flexible resource union {
    1: stream_sink StreamSinkProducer;
    2: ring_buffer fuchsia.audio.RingBuffer;
};

/// A Consumer node can write to a StreamSink or a RingBuffer.
type ConsumerDataSource = flexible resource union {
    1: stream_sink StreamSinkConsumer;
    2: ring_buffer fuchsia.audio.RingBuffer;
};

/// A producer driven by a [`fuchsia.media2/StreamSink`].
type StreamSinkProducer = resource table {
    /// Channel to receive packets.
    ///
    /// Required.
    1: stream_sink server_end:fuchsia.media2.StreamSink;

    /// Encoding of this audio stream.
    ///
    /// Required.
    2: format fuchsia.mediastreams.AudioFormat;

    /// Clock for this node's output stream. The clock must be
    /// ZX_CLOCK_OPT_MONOTONIC and ZX_CLOCK_OPT_CONTINUOUS with ZX_RIGHT_READ.
    /// See "Clocks" under the description for [`Graph`].
    ///
    /// Required.
    3: reference_clock zx.handle:CLOCK;
};

/// A consumer driven by a [`fuchsia.media2/StreamSink`].
type StreamSinkConsumer = resource table {
    /// Channel to send packets.
    ///
    /// Required.
    1: stream_sink client_end:fuchsia.media2.StreamSink;

    /// Encoding of this audio stream.
    ///
    /// Required.
    2: format fuchsia.mediastreams.AudioFormat;

    /// Clock for this node's input stream. The clock must be
    /// ZX_CLOCK_OPT_MONOTONIC and ZX_CLOCK_OPT_CONTINUOUS with ZX_RIGHT_READ.
    /// See "Clocks" under the description for [`Graph`].
    ///
    /// Required.
    3: reference_clock zx.handle:CLOCK;
};

/// Return value for CreateCustom.
type CustomNodeProperties = resource table {
    /// IDs for each input node. See comments at [`Graph.CreateCustom`].
    ///
    /// Required.
    1: input_ids vector<NodeId>:fuchsia.audio.effects.MAX_INPUT_STREAMS;

    /// IDs for each output node. See comments at [`Graph.CreateCustom`].
    ///
    /// Required.
    2: output_ids vector<NodeId>:fuchsia.audio.effects.MAX_OUTPUT_STREAMS;
};

/// Options for consumer nodes, including hidden consumer nodes within Splitter
/// and Custom nodes.
type ConsumerOptions = resource table {
    /// The Consumer's mix job should execute on this thread.
    ///
    /// Required.
    1: thread ThreadId;

    /// Each mix job should consume one `period` worth of audio data each `period`.
    ///
    /// Required.
    2: period zx.duration;
};

/// Every node is part of an output pipeline or an input pipeline.
///
/// Output pipelines, also known as "render" pipelines, produce audio that is
/// written to an output device, usually some kind of speaker. Output pipelines
/// operate on audio that should be rendered to an output device at some time
/// in the future.
///
/// Input pipelines, also known as "capture" pipelines, consume audio that is
/// read from an input device, usually some kind of microphone. Input pipelines
/// operate on audio that was captured from an input device at some time in the
/// past.
///
/// Input pipelines can read from output pipelines. This is commonly known as a
/// "loopback" capture.
///
/// Input pipelines cannot write to output pipelines. This is not allowed
/// because it creates a timestamp paradox: When an input pipeline reads a
/// frame, it assigns the frame timestamp `T`, which represents the time at
/// which the frame was captured from an input device. Timestamp `T` occurred in
/// the past. When we forward that frame to an output pipeline, the frame will
/// underflow because time `T` is in the past. It can sometimes be useful to
/// connect pipelines in this way, but this must be done by the client, who is
/// responsible for re-timstamping captured frames in an appropriate way before
/// forwarding those frames to an output pipeline.
type PipelineDirection = strict enum {
    OUTPUT = 1;
    INPUT = 2;
};