blob: dc7b111266bc5dc175c99835fe95eb54c5ae2748 [file] [log] [blame]
// 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.
using zx;
/// Interface for creating audio consumers bound to a session
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 here, because dependencies.
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
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.
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.
/// 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.
request<> 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.
/// 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.
/// 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;