// Copyright 2019 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.media;

using zx;
using fuchsia.media.audio;

/// Interface for creating audio consumers bound to a session
[Discoverable]
protocol SessionAudioConsumerFactory {
    /// Creates an `AudioConsumer` which is an interface for playing audio bound
    /// to a particular session. `session_id` is the identifier of the media session
    /// for which audio is to be rendered.
    // TODO(dalesat): Can't use fuchsia.media.sessions2.SessionId here, because dependencies.
    CreateAudioConsumer(
        uint64 session_id,
        request<AudioConsumer> audio_consumer_request);
};

/// Interface for playing and controlling audio
protocol AudioConsumer {
    /// Creates a `StreamSink` for the consumer with the indicated properties.
    ///
    /// Multiple stream sinks may be acquired using this method, but they are intended to be used
    /// sequentially rather than concurrently. The first stream sink that's created using this
    /// method is used as the sole source of packets incoming to the logical consumer until that
    /// stream sink is closed or the `EndOfStream` method is called on that sink. At that point,
    /// the second stream sink is used, and so on.
    ///
    /// If an unsupported compression type is supplied, the
    /// `stream_sink_request` request will be closed with an epitaph value of
    /// `ZX_ERR_INVALID_ARGS`
    CreateStreamSink(
        vector<zx.handle:VMO>:16 buffers,
        AudioStreamType stream_type,
        Compression? compression,
        request<StreamSink> stream_sink_request);

    /// Indicates that the last packet prior to the end of the stream has been rendered.
    -> OnEndOfStream();

    /// Starts rendering as indicated by `flags`.
    ///
    /// `media_time` indicates the packet timestamp that corresponds to `reference_time`.
    /// Typically, this is the timestamp of the first packet that will be
    /// rendered. If packets will be supplied with no timestamps, this value
    /// should be `NO_TIMESTAMP`.  Passing a `media_time` value of
    /// `NO_TIMESTAMP` chooses the default media time, established as follows:
    ///     1. When starting for the first time, the default media time is the
    ///        timestamp on the first packet sent to the stream sink.
    ///     2. When resuming after stop, the default media time is the media
    ///        time at which the stream stopped.
    ///
    /// `reference_time` is the monotonic system time at which rendering should
    /// be started. For supply-driven sources, this must be the time at which
    /// the first packet was (or will be) sent plus a lead time, which must be
    /// in the range indicated in the `AudioConsumerStatus`. For demand-driven
    /// sources, the client must ensure that the lead time requirement is met at
    /// the start time.  Passing the default value of 0 for `reference_time`
    /// causes the consumer to choose a start time based on the availability of
    /// packets, the lead time requirements, and whether `LOW_LATENCY` has been
    /// specified.
    ///
    /// The actual start time will be reflected in the updated status.
    Start(
        AudioConsumerStartFlags flags,
        zx.time reference_time,
        int64 media_time);

    /// Stops rendering as soon as possible after this method is called. The actual stop time will
    /// be reflected in the updated status.
    Stop();

    /// Requests to change the playback rate of the renderer. 1.0 means normal
    /// playback. Negative rates are not supported. The new rate will be
    /// reflected in the updated status. The default rate of any newly created `StreamSink` is 1.0.
    SetRate(float32 rate);

    /// Binds to this `AudioConsumer` volume control for control and notifications.
    BindVolumeControl(
        request<fuchsia.media.audio.VolumeControl> volume_control_request);

    /// Gets the current status of the consumer using the long get pattern. The consumer responds
    /// to this method when the status changes - initially with respect to the initial status value
    /// and thereafter with respect to the previously-reported status value.
    WatchStatus() -> (AudioConsumerStatus status);
};

/// Flags passed to `AudioConsumer.Start`.
bits AudioConsumerStartFlags {
    /// Indicates that latency should be kept as low as possible.
    LOW_LATENCY = 0x01;

    /// Indicates that the timing of packet delivery is determined by an external process rather
    /// than being demand-based. When this flag is set, the service should expect underflow or
    /// overflow due to a mismatch between packet arrival rate and presentation rate. When this
    /// flag is not set, packets arrive on demand.
    SUPPLY_DRIVEN = 0x02;
};

/// Represents the status of the consumer. In the initial status, `error` and
/// `presentation_timeline` are absent. The lead time fields are always present.
table AudioConsumerStatus {
    /// If present, indicates an error condition currently in effect. Absent if no error.
    1: AudioConsumerError error;

    /// If present, indicates the current relationship between the presentation timeline
    /// and local monotonic clock, both in nanosecond units. If not present,
    /// indicates there is no relationship. Absent initially.
    ///
    /// 'Presentation timeline' refers to the `pts` (presentation timestamp) values on the packets.
    /// This timeline function can be used to determine the local monotonic clock time that a
    /// packet will be presented based on that packet's `pts` value.
    2: TimelineFunction presentation_timeline;

    /// Indicates the minimum lead time in nanoseconds supported by this
    /// `AudioConsumer`.  Or in other words, how small of a gap between the
    /// `media_time` provided to `AudioConsumer.Start` and the pts on the first
    /// packet can be. Values outside this range will be clipped.
    3: uint64 min_lead_time;

    /// Indicates the maximum lead time in nanoseconds supported by this
    /// `AudioConsumer`.  Or in other words, how large of a gap between the
    /// `media_time` provided to `AudioConsumer.Start` and the pts on the first
    /// packet can be. Values outside this range will be clipped.
    4: uint64 max_lead_time;
};

struct Void {
};

/// Represents a `AudioConsumer` error condition.
union AudioConsumerError {
    1: Void place_holder;
};