src/media/vnext/fidl/fuchsia.audio/renderer.fidl

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

using fuchsia.media2;
using fuchsia.mediastreams;
using zx;

/// Represents an audio renderer.
protocol Renderer {
    /// Connects a stream sink for the renderer with the indicated properties. Multiple stream
    /// sinks may be used sequentially for a given renderer. This method responds when the
    /// connection is ready or the connect attempt fails.
    ConnectInputStream(
        zx.handle:EVENTPAIR buffer_collection_token,
        fuchsia.mediastreams.AudioFormat format,
        fuchsia.media2.StreamTimeline stream_timeline,
        request<fuchsia.media2.StreamSink> request)
        -> () error fuchsia.media2.ConnectionError;

    /// Indicates that the current input stream has been disconnected unexpectedly.
    -> OnInputStreamDisconnected(zx.status status);

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

    /// Indicates that the stream sink previously created is invalid,
    /// and the client should create another one if it wishes to
    /// continue sending packets.
    -> OnInputStreamSinkInvalid();

    /// Starts the renderer's presentation timeline.
    ///
    /// + request `reference_time` the reference time at which the presentation timeline should
    ///   start. A value of `fuchsia.media2.TIME_UNSPECIFIED` indicates it should start as soon as
    ///   possible.
    /// + request `presentation_time` the value of the renderer's presentation clock when
    ///   presentation timeline starts. A value of `fuchsia.media2.TIME_UNSPECIFIED` indicates the
    ///   presentation timeline should start at its current value.
    /// * response `reference_time` the reference time at which the presentation timeline actually
    ///   started.
    /// * response `presentation_time` the value of the renderer's presentation clock when the
    ///   presentation timeline actually started.
    ///
    /// If the renderer is currently playing, this method does nothing except return the same values
    /// returned by the previous `Play` call. If a play or pause transition is currently scheduled
    /// when this method is called, that scheduled transition is first cancelled.
    // TODO: flags? LOW_LATENCY, SUPPLY_DRIVEN
    Play(zx.time reference_time, zx.time presentation_time)
        -> (zx.time reference_time, zx.time presentation_time);

    /// Stops the renderer's presentation timeline.
    ///
    /// + request `presentation_time` the value of the renderer's presentation clock when
    ///   presentation timeline should stop. A value of `fuchsia.media2.TIME_UNSPECIFIED` indicates
    ///   the presentation timeline should stop as soon as possible.
    /// * response `reference_time` the reference time at which the presentation timeline actually
    ///   stopped.
    /// * response `presentation_time` the value of the renderer's presentation clock when the
    ///   presentation timeline actually stopped. This is the current presentation time until
    ///   a subsequent call to `Play`.
    ///
    /// If the renderer is currently paused, this method does nothing except return the same values
    /// returned by the previous `Pause` call or 0,0 if this renderer has never played. If a play
    /// or pause transition is currently scheduled when this method is called, that scheduled
    /// transition is first cancelled.
    Pause(zx.time presentation_time)
        -> (zx.time reference_time, zx.time presentation_time);

    /// 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.
    SetRate(float32 rate);

    /// Gets the current status of the renderer using the long get
    /// pattern. The renderer replies immediately to this method when
    /// it is first called. The renderer replies to subsequent calls
    /// when the status changes.
    WatchStatus() -> (RendererStatus status);

    /// Sets the reference clock to use for this renderer. All
    /// ‘reference time’ values for this renderer are interpreted
    /// with respect to this clock. If this method is never called,
    /// the reference clock is the system’s monotonic clock.
    SetReferenceClock(zx.handle:CLOCK reference_clock);

    // Binds the volume control for the renderer.
    //BindVolumeControl(request<VolumeControl> request);

    // Binds the gain control for the renderer.
    //BindGainControl(request<GainControl> request);
};

/// Represents the status of the renderer.
table RendererStatus {
    /// If present, indicates an error condition currently in effect.
    /// Absent if no error.
    1: RendererError error;

    /// If present, indicates the current relationship between the
    /// presentation timeline and reference clock. Absent initially.
    2: fuchsia.media2.PresentationTimeline presentation_timeline;

    /// Indicates the minimum lead time supported by this `Renderer`,
    /// that is, the minimum interval ahead of a packet’s effective
    /// presentation time that the packet must be submitted to prevent
    /// underflow.
    3: zx.duration min_lead_time;

    /// Indicates the maximum lead time supported by this `Renderer`,
    /// that is, the maximum interval ahead of a packet’s effective
    /// presentation time that the packet may be submitted to prevent
    /// overflow.
    4: zx.duration max_lead_time;
};

/// Represents an `Renderer` error condition.
// TODO: Define
enum RendererError {
    INTERNAL = 1;
};