src/media/vnext/fidl/fuchsia.media2/timelines.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.media2;

using zx;

/// Expresses presentation time as a linear function of reference
/// time. The reference timeline is typically the system monotonic
/// clock, but may be another clock.
struct PresentationTimeline {
    /// Initial presentation time of this piece of the piecewise-
    /// linear presentation timeline.
    zx.time initial_presentation_time = 0;

    /// Initial reference time of this piece of the piecewise-
    /// linear presentation timeline.
    zx.time initial_reference_time = 0;

    /// Presentation rate, typically 1.0. Non-positive values are
    /// not permitted. This field gives the rate at which the
    /// presentation progresses if `progressing` is true. If
    /// `progressing` is false, the effective rate is zero.
    float32 rate = 1.0;

    /// Indicates whether presentation is progressing. If this
    /// value is true, presentation is progressing at the rate
    /// given by the `rate` field. If this value is false, the
    /// effective presentation rate is zero.
    bool progressing = false;
};

/// Expresses the relationship between the timeline represented by
/// the timestamps in a stream and the presentation timeline.
///
/// The `stream_interval` and `presentation_interval` establish the
/// units of the `Timestamp` values in packets in a stream. For
/// example, if the timestamps are in nanosecond units, the two
/// intervals are equal. If the timestamps are frame indices in a
/// 44.1k frames/second audio stream, `stream_interval` would be
/// 44,100, and `presentation_interval` would be 1,000,000,000.
/// The intervals constitute a ratio, so the values 441 and
/// 10,000,000 would do just as well for the second example.
///
/// `initial_stream_time` and `initial_presentation_time` specify the
/// start of the desired segment of the stream. In most cases, the
/// initial stream time is just the first timestamp in the stream,
/// often zero.
///
/// There are cases in which a stream will start before the initial
/// stream time given in a `StreamTimeline`. When seeking into a
/// compressed video stream, the decoder needs to start processing
/// the stream at an I-framee. Based on the initial stream time given
/// to the decoder, it knows what output frames to discard.
struct StreamTimeline {
    /// Stream time of the start of the desired segment of the stream.
    int64 initial_stream_time = 0;

    /// Presentation time of the start of the desired segment of the
    /// stream.
    zx.time initial_presentation_time = 0;

    /// Duration in the stream timeline corresponding to
    /// `presentation_interval`.
    uint64 stream_interval = 1000000000;

    /// Duration in the presentation timeline corresponding to
    /// `stream_interval`.
    zx.duration presentation_interval = 1000000000;
};

/// Placeholder value for unspecified times.
const zx.time TIME_UNSPECIFIED = 0x7fffffffffffffff;