| // 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.media2; |
| |
| using zx; |
| |
| /// Describes any active consumer, including single-stream and multi-stream consumers. |
| /// All active consumers should compose this protocol. Single-stream active consumers |
| /// and streams exposed by multi-stream active consumers should also compose |
| /// `ActiveConsumerStream`. |
| protocol ActiveConsumer { |
| /// Starts the presentation timeline. |
| /// |
| /// + request `when` time when the presentation timeline should |
| /// start as a system time or reference time. If this parameter |
| /// is not supplied, the presentation timeline starts as soon as |
| /// possible. |
| /// + request `presentation_time` the presentation time at which |
| /// the presentation timeline should start. |
| /// - response `reference_time` the reference time when the |
| /// presentation timeline was actually started. |
| /// - response `presentation_time` the presentation time at which |
| /// the presentation timeline started. |
| /// * error reason the operation failed. |
| /// |
| /// When a call to this method succeeds, the response is sent when |
| /// the operation actually occurs (that is, when it was scheduled |
| /// to occur), indicating that the service is ready for a `Stop` |
| /// or `AmendPresentation` command. When a call to this method |
| /// fails, the response is sent when the failure is detected. |
| /// |
| /// If this method is called when presentation is already |
| /// underway, the call fails immediately with an `ALREADY_STARTED` |
| /// error. |
| /// |
| /// Otherwise, if this method is called, and `when` specifies a |
| /// time in the past, the presentation timeline is started as soon as possible. |
| /// |
| /// Otherwise, if this method is called when a `Start` operation |
| /// is already pending (requested but not completed), the pending |
| /// operation fails with a `CANCELED` error. |
| Start(struct { |
| when RealTime:optional; |
| presentation_time zx.duration; |
| }) -> (struct { |
| // TODO(dalesat): Add system time here. |
| reference_time zx.time; |
| presentation_time zx.duration; |
| }) error StartError; |
| |
| /// Stops the presentation timeline. |
| /// |
| /// + request `when` time when the presentation timeline should |
| /// stop as a system time, reference time or presentation time. |
| /// If this parameter is not supplied, the presentation timeline |
| /// stops as soon as possible. |
| /// - response `reference_time` the reference time when the |
| /// presentation timeline was actually stopped. |
| /// - response `presentation_time` the presentation time at which |
| /// the presentation timeline stopped. |
| /// * error reason the operation failed. |
| /// |
| /// When a call to this method succeeds, the response is sent when |
| /// the operation actually occurs (that is, when it was scheduled |
| /// to occur), indicating that the service is ready for a `Start` |
| /// command. When a call to this method fails, the response is |
| /// sent when the failure is detected. |
| /// |
| /// If this method is called when presentation is stopped, the |
| /// call fails immediately with an `ALREADY_STOPPED` error. |
| /// |
| /// Otherwise, if this method is called, and `when` specifies a |
| /// time in the past, the call fails immediately with a |
| /// `SCHEDULED_IN_PAST` error. |
| /// |
| /// Otherwise, if this method is called when a `Stop` operation |
| /// is already pending (requested but not completed), the pending |
| /// operation fails with a `CANCELED` error. |
| Stop(struct { |
| when RealOrPresentationTime:optional; |
| }) -> (struct { |
| // TODO(dalesat): Add system time here. |
| reference_time zx.time; |
| presentation_time zx.duration; |
| }) error StopError; |
| |
| /// Sets the presentation rate. |
| /// |
| /// + request `when` time when the presentation rate should be |
| /// changed as a system time, reference time or presentation |
| /// time. If this parameter is not supplied, the presentation |
| /// rate is changed as soon as possible. |
| /// + request `desired_rate` the desired presentation rate. Must |
| /// be greater than zero, otherwise the service closes the |
| /// channel. |
| /// - response `presentation_time` the presentation time at which |
| /// the rate changed. |
| /// - response `actual_rate` the actual presentation rate. This |
| /// can be different than `desired_rate` depending on the rate |
| /// capabilities of the object. |
| /// * error reason the operation failed. |
| /// |
| /// Rate changes can be requested at any time. Rate changes |
| /// requested when presentation is stopped remain pending until |
| /// presentation is started and the specified `when` value is |
| /// reached. If `when` is not supplied, the operation pends until |
| /// presentation starts, at which time, the new rate is used and |
| /// the operation completes. |
| /// |
| /// When a call to this method succeeds, the response is sent when |
| /// the operation actually occurs (that is, when it was scheduled |
| /// to occur), indicating that the service is ready for a new |
| /// rate change command. When a call to this method fails, |
| /// the response is sent when the failure is detected. |
| /// |
| /// If this method is called on an object that doesn’t support |
| /// rate changes at all, the call fails immediately with a |
| /// `NOT_SUPPORTED` error. |
| /// |
| /// Otherwise, if this method is called, and `when` specifies a |
| /// time in the past, the call fails immediately with a |
| /// `SCHEDULED_IN_PAST` error. |
| /// |
| /// Otherwise, if this method is called when a `SetRate` operation |
| /// is already pending (requested but not completed), the pending |
| /// operation fails with a `CANCELED` error. |
| SetRate(struct { |
| when RealOrPresentationTime:optional; |
| desired_rate float32; |
| }) -> (struct { |
| // TODO(dalesat): Add reference, system time here. |
| presentation_time zx.duration; |
| actual_rate float32; |
| }) error SetRateError; |
| |
| /// Amend the presentation timeline forward or backward. |
| /// |
| /// + request `when` time when the presentation timeline should |
| /// amended as a system time, reference time or presentation |
| /// time. If this parameter is not supplied, the presentation |
| /// timeline is amended as soon as possible. |
| /// + request `delta` the duration the presentation timeline |
| /// should be amended. This value is added to the presentation |
| /// time at the specified time. If this value is positive, the |
| /// timeline slips forward, possibly skipping some of the |
| /// presentation. If this value is negative, the timeline slips |
| /// backward, possibly stalling the presentation. |
| /// - response `reference_time` the reference time at which the |
| /// amendment occurred. |
| /// - response `presentation_time` the presentation time that |
| /// correlates to `reference_time` as a consequence of this |
| /// method. |
| /// * error reason the operation failed. |
| /// |
| /// When a call to this method succeeds, the response is sent when |
| /// the operation actually occurs (that is, when it was scheduled |
| /// to occur), indicating that the service is ready for a new |
| /// amend command. When a call to this method fails, the response |
| /// is sent when the failure is detected. |
| /// |
| /// If an amend operation is pending when presentation is stopped, |
| /// the pending operation fails with a `CANCELED` error. |
| /// |
| /// If this method is called when presentation is stopped, the |
| /// call fails immediately with an `NOT_STARTED` error. |
| /// |
| /// Otherwise, if this method is called, and `when` specifies a |
| /// time in the past, the call fails immediately with a |
| /// `SCHEDULED_IN_PAST` error. |
| /// |
| /// Otherwise, if this method is called when a `AmendPresentation` |
| /// operation is already pending (requested but not completed), |
| /// the pending operation fails with a `CANCELED` error. |
| AmendPresentation(struct { |
| when RealOrPresentationTime:optional; |
| delta zx.duration; |
| }) -> (struct { |
| reference_time zx.time; |
| presentation_time zx.duration; |
| }) error AmendPresentationError; |
| }; |
| |
| /// Describes any passive consumer, including single-stream and multi-stream consumers. |
| /// All passive consumers should compose this protocol. Single-stream passive consumers |
| /// and streams exposed by multi-stream passive consumers should also compose |
| /// `ActiveConsumerStream`. |
| protocol PassiveConsumer { |
| /// Indicates that writing to the files and consumption of packets |
| /// should start, configuration of the consumer having been |
| /// completed. |
| Start(); |
| |
| /// Indicates that the file should be completed and closed, all |
| /// expected packets having been consumed. |
| /// |
| /// - response duration the duration of the completed file. |
| Stop() -> (struct { |
| duration zx.duration; |
| }); |
| }; |
| |
| /// Describes any active consumer stream, including single-stream consumers and streams exposed by |
| /// multi-stream consumers. All single-stream active consumers and all streams exposed by |
| /// multi-stream active consumers should compose this protocol. |
| protocol ActiveConsumerStream { |
| /// Notifies the client that an end-of-stream signal has been |
| /// encountered in the consumed stream and that all prior packets |
| /// have been rendered or otherwise processed. |
| -> OnEndOfStream(); |
| |
| /// Notifies the client that the minimum lead time constraint has |
| /// been met. |
| -> OnPrimed(); |
| |
| /// Returns when packet arrival lead time falls outside the specified limits or when a new |
| /// `WatchPacketLeadTime` request arrives. Packet lead time is the interval between the arrival |
| /// of a packet at the consumer and the packet's arrival deadline. A lead time of zero indicates |
| /// that a packet arrived at the consumer just in time. Underflow (late packet arrival) is |
| /// indicated by a negative lead time value, if the value is known, or |
| /// `WatchLeadTimeResult.underflow` if it is not. For the purposes of filtering, |
| /// `WatchLeadTimeResult.underflow` is equivalent to a lead time value of -1. |
| /// |
| /// + request `min` the margin below which packet arrival lead |
| /// time must fall in order for the reply to be sent. For example, passing zero indicates |
| /// that the reply should be sent when packet arrives after the deadline (when the |
| /// connection has underflowed). |
| /// + request `max` the margin above which packet arrival lead |
| /// time must rise in order for the reply to be sent. |
| /// - response `packet_lead_time` the actual packet lead time measured when the |
| /// response was generated. This value will only be within |
| /// the specified limits if the response is generated due to |
| /// the arrival of a new `WatchPacketLeadTime` request. |
| /// * error `NO_LEAD_TIME_REPORTED` indicates a new `WatchPacketLeadTime` request arrived before |
| /// any lead time values were reported. |
| /// |
| /// Only one `WatchPacketLeadTime` operation may be pending at any |
| /// given time. If a `WatchPacketLeadTime` request is received |
| /// when another such request is pending, the consumer responds |
| /// to the older request with the latest packet lead time value or the error |
| /// `NO_LEAD_TIME_REPORTED`. |
| WatchPacketLeadTime(struct { |
| min zx.duration; |
| max zx.duration; |
| }) -> (struct { |
| result WatchLeadTimeResult; |
| }); |
| }; |
| |
| /// Describes any passive consumer stream, including single-stream consumers and streams exposed by |
| /// multi-stream consumers. All single-stream passive consumers and all streams exposed by |
| /// multi-stream passive consumers should compose this protocol. |
| protocol PassiveConsumerStream { |
| /// Notifies the client that an end-of-stream signal has been |
| /// encountered in the consumed stream and that all prior packets |
| /// have been rendered or otherwise processed. |
| -> OnEndOfStream(); |
| }; |