src/media/vnext/fidl/fuchsia.media2/stream_sink.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 fuchsia.mediastreams;
using zx;

/// The maximum number of `PayloadRange`s allowed per `Packet`.
const int64 MAX_PAYLOAD_RANGES = 16;

/// The maximum number of `EncryptionSubsampleEntry`s allowed.
const int64 MAX_SUBSAMPLE_ENTRIES = 16;

struct Void {
};

/// A packet consumer for cross-process elementary stream transport.
protocol StreamSink {
    /// Puts a packet to the sink. Closure of the release fence
    /// by the consumer indicates that the consumer is done with
    /// the packet and that the buffer regions associated with the
    /// packet may be reused by the producer.
    PutPacket(Packet packet, zx.handle:EVENTPAIR release_fence);

    /// Indicates that the end of the stream has been reached.
    /// Consumers such as audio and video renderers signal their
    /// clients when the last packet before end-of-stream has been
    /// rendered, so the client knows when to, for example, change
    /// the UI state of a player to let the user know the content is
    /// done playing. Packets may arrive after `End` is received, e.g.
    /// when a seek occurs.
    End();

    /// Indicates that all packets that are currently pending (sent
    /// with `PutPacket` but not yet released) should be released as
    /// well as any pending `End` indications, and that this process
    /// should continue downstream. For example, a decoder that
    /// receives a call to this method on the `StreamSink` it
    /// implements (the docoder’s input), the decoder should release
    /// all unreleased packets and `End` indications previously
    /// received on the input and call `Clear` on its output
    /// `StreamSink`.
    Clear();
};

/// Describes a packet delivered via `StreamSink`.
struct Packet {
    /// Locations of the payload for this packet. The effective
    /// payload comprises all the payload ranges concatenated in
    /// the order they appear in `payload`.
    vector<PayloadRange>:MAX_PAYLOAD_RANGES payload;

    /// Timestamp indicating when this packet should be presented as a
    /// stream timeline value. Mapping this value to presentation time
    /// requires knowledge of the stream timeline parameters.
    Timestamp timestamp;

    /// Capture time for this packet as a system monotonic time value.
    /// This field is generally zero, but may be set by capturers
    /// to indicate when this packet was captured.
    zx.time capture_timestamp = 0;

    /// Properties describing packets in a compressed stream. This
    /// value may be provided for a packet in a compressed stream,
    /// and may not be provided for any packet in an uncompressed
    /// stream. If a packet in a compressed stream omits this value,
    /// default compression properties are assumed.
    PacketCompressionProperties? compression_properties;

    /// Properties describing packets in an encrypted stream. This
    /// value must be provided for every packet in an encrypted
    /// stream, and may not be provided for any packet in an
    /// unencrypted stream.
    PacketEncryptionProperties? encryption_properties;
};

/// Describes a packet payload.
struct PayloadRange {
    /// The id of the buffer in which the payload resides.
    uint32 buffer_id;

    /// The offset of the payload in the specified buffer.
    uint64 offset;

    /// The size in bytes of the payload.
    uint64 size;
};

/// Indicates the time of the packet in the stream timeline.
union Timestamp {
    /// Specific timestamp in the stream timeline.
    1: int64 specified;

    /// Indicates the packet should be presented immediately
    /// after the previous packet, if there is a previous
    /// packet. If there is no previous packet, this option
    /// is equivalent to a `specified` value of 0.
    2: Void unspecified_continuous;

    /// Indicates the packet should be presented as soon as
    /// possible after the previous packet, if there is one,
    /// as soon as possible if not.
    3: Void unspecified_best_effort;

    // TODO: There’s an argument to be made for another option
    // here, which means “present ASAP, discarding all previous
    // packets.” That would be used for video trick modes like
    // timeline scrubbing.
};

/// Properties accompanying a packet in a compressed stream.
flexible union PacketCompressionProperties {
    /// Properties accompanying a packet in a compressed audio
    /// stream. Providing audio properties for a non-audio stream
    /// is an error.
    1: AudioPacketCompressionProperties audio;

    /// Properties accompanying a packet in a compressed video
    /// stream. Providing video properties for a non-video stream
    /// is an error.
    2: VideoPacketCompressionProperties video;
};

/// Properties accompanying a packet in a compressed audio stream.
table AudioPacketCompressionProperties {
    /// Indicates how many frames should be dropped from the front of
    /// the packet produced by a decoder from this packet. When this
    /// value is absent, a value of 0 is implied.
    1: uint32 front_frames_to_drop;

    /// Indicates how many frames should be dropped from the back of
    /// the packet produced by a decoder from this packet. When this
    /// value is absent, a value of 0 is implied.
    2: uint32 back_frames_to_drop;
};

/// Properties accompanying a packet in a compressed video stream.
table VideoPacketCompressionProperties {
    /// Flags describing the packet. If this value is omitted, a value
    /// with no flags set is implied.
    1: VideoPacketCompressionFlags flags;
};

/// Flags describing a packet in a compressed video stream.
flexible bits VideoPacketCompressionFlags {
    /// Indicates that this access unit can be interpreted without
    /// information from any other packet.
    KEY_FRAME = 0x01;

    /// Indicates that no other access unit requires information
    /// from this access unit in order to be interpreted.
    DROPPABLE = 0x02;
};

/// Properties accompanying a packet in an encrypted stream.
struct PacketEncryptionProperties {
    /// Indicates whether the packet is encrypted.
    bool is_encrypted;

    /// If specified, overrides the previous key id.
    fuchsia.mediastreams.EncryptionKeyId? key_id;

    /// If specified, overrides the previous initialization vector.
    fuchsia.mediastreams.EncryptionInitVector? init_vector;

    /// If specified, overrides the previous encryption pattern.
    fuchsia.mediastreams.EncryptionPattern? pattern;

    /// Subsamples to decrypt. An empty list indicates whole sample
    /// decryption.
    vector<fuchsia.mediastreams.EncryptionSubsampleEntry>:MAX_SUBSAMPLE_ENTRIES subsamples;
};