| // 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(resource struct { |
| session_id uint64; |
| audio_consumer_request server_end:AudioConsumer; |
| }); |
| }; |
| |
| /// Interface for creating audio consumers for local rendering. |
| @discoverable |
| protocol UsageAudioConsumerFactory { |
| /// Creates an `AudioConsumer`, which is an interface for playing audio, given a usage value. |
| /// Audio submitted to such a consumer is always rendered locally. |
| CreateAudioConsumer(resource struct { |
| usage AudioRenderUsage; |
| audio_consumer_request server_end:AudioConsumer; |
| }); |
| }; |
| |
| /// 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(resource struct { |
| buffers vector<zx.handle:VMO>:16; |
| stream_type AudioStreamType; |
| compression box<Compression>; |
| stream_sink_request server_end:StreamSink; |
| }); |
| |
| /// 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(struct { |
| flags AudioConsumerStartFlags; |
| reference_time zx.time; |
| media_time int64; |
| }); |
| |
| /// 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(struct { |
| rate float32; |
| }); |
| |
| /// Binds to this `AudioConsumer` volume control for control and notifications. |
| BindVolumeControl(resource struct { |
| volume_control_request server_end:fuchsia.media.audio.VolumeControl; |
| }); |
| |
| /// 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() -> (struct { |
| status AudioConsumerStatus; |
| }); |
| }; |
| |
| /// Flags passed to `AudioConsumer.Start`. |
| type AudioConsumerStartFlags = strict bits { |
| /// 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. |
| type AudioConsumerStatus = table { |
| /// If present, indicates an error condition currently in effect. Absent if no error. |
| 1: error AudioConsumerError; |
| |
| /// 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: presentation_timeline TimelineFunction; |
| |
| /// 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: min_lead_time uint64; |
| |
| /// 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: max_lead_time uint64; |
| }; |
| |
| type Void = struct {}; |
| |
| /// Represents a `AudioConsumer` error condition. |
| type AudioConsumerError = strict union { |
| 1: place_holder Void; |
| }; |