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

[Discoverable]
protocol AudioConsumer {
    /// Creates a stream sink for the consumer with the indicated properties. `session_id` is the
    /// identifier of the media session for which audio is to be rendered.
    ///
    /// 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.
    // TODO(dalesat): Need something about timestamp interpretation.
    // TODO(dalesat): Can't use fuchsia.media.sessions2.SessionId here, because dependencies.
    // TODO(dalesat): Do we want the service to drop an old StreamSink when a new one is created?
    CreateStreamSink(
        uint64 session_id,
        vector<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`. Rendering starts as soon as possible after this
    /// method is called. The actual start time will be reflected in the updated status.
    Start(AudioConsumerStartFlags flags);

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

    /// 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. Initial status has null `error` and
/// `presentation_timeline` values.
struct AudioConsumerStatus {
    /// If not null, indicates an error condition currently in effect.
    AudioConsumerError? error;

    /// If not null, indicates the current relationship between the presentation timeline
    /// and local monotonic clock, both in nanosecond units.
    ///
    /// '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.
    TimelineFunction? presentation_timeline;
};

struct Void {
};

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