public/lib/media/fidl/media_transport.fidl

// Copyright 2016 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.

module media;

import "lib/media/fidl/media_result.fidl";
import "lib/media/fidl/media_types.fidl";

// Describes a fragment of media content, including metadata and a locator for
// the payload.
struct MediaPacket {
  // A special value which may be written into the PTS field in certain
  // circumstances.  For example, depending on the specific scenario,
  // kNoTimestamp may be used if...
  //
  // 1) The timestamp of a packet is simply not known.
  // 2) A client wishes for the timestamp of a packet to be interpolated based
  //    on nominal frame rate and previous packet timestamps.
  // 3) A client wishes to schedule a packet or timeline transformation to take
  //    place as soon as possible.
  const int64 kNoTimestamp = 0x7fffffffffffffff;

  // Flags used to indicate properties of this payload.
  //
  //  ** EOS
  //     This payload represents the end of a stream.  For example, EOS
  //     may be set on a packet which represents the final payload in a stream
  //     of compressed video, causing a video codec to flush out any remaining
  //     frames it may be holding onto because of frame-reordering dependencies.
  //
  //  ** Keyframe
  //     This packet represents a point in a compressed sequence which depends
  //     on no other packets in the sequence.  In other words, this is a random
  //     access point at which the decoder may start decoding.  For example, an
  //     I-Frame in an MPEG2 video sequence is a "keyframe".  All audio payloads
  //     in an MP1L3 sequences are independently decodable, and therefor
  //     "keyframes".
  //
  //  ** Dropable
  //     This packet represents data in a compressed sequence which no other
  //     packets depend on.  For example, a B-Frame in an MPEG2 video sequence
  //     produces no reference frames.
  //
  //  ** Discontinuous
  //     This packet represents data which is discontinuous from a timing
  //     perspective from the previous delivered packet in the sequence.  For
  //     example packets containing audio frames with audio frame numbers
  //     [0, 999], [1000, 1999] and [2500, 2999] are delivered, the first two
  //     packets are continuous with each other, but the 3rd packet is
  //     discontinuous relative to the 2nd.
  const uint32 kFlagEos = 0x01;
  const uint32 kFlagKeyframe = 0x02;
  const uint32 kFlagDroppable = 0x04;
  const uint32 kFlagDiscontinuous = 0x08;

  // Presentation timestamp. Time at which the media should be presented,
  // according to the media timeline.
  int64 pts = kNoTimestamp;

  // Indicates the number of PTS ticks that correspond to pts_rate_seconds
  // seconds. In other words, the time represented by a single PTS tick in
  // seconds is pts_rate_ticks / pts_rate_seconds. For example, if PTS is
  // given in nanoseconds, pts_rate_ticks would be 1,000,000,000, and
  // pts_rate_seconds would be 1.
  uint32 pts_rate_ticks;

  // Indicates the number of seconds that correspond to pts_rate_ticks
  // PTS ticks. See pts_rate_ticks for more info.
  uint32 pts_rate_seconds;

  // A collection of flags (see constants above) describing properties of this
  // packet.
  uint32 flags = 0;

  // Identifier of the shared buffer that contains the payload for this packet.
  // This identifier must be established by a call to MediaPacketConsumer's
  // AddPayloadBuffer method before it can be used.
  uint32 payload_buffer_id;

  // Offset of the packet payload in the indicated shared buffer.
  uint64 payload_offset;

  // Size in bytes of the packet payload.
  uint64 payload_size;

  // Revised media type describing this and subsequent packets.
  MediaType? revised_media_type;
};

// Describes consumer demand for MediaPackets. Demand is initially assumed to
// be the default values given below. Changes in demand can be signalled
// in-band with SupplyPacket responses or by responding to PullDemandUpdate.
struct MediaPacketDemand {
  // The minimum number of packets that should be outstanding at any moment.
  // The producer should try to keep at least this many SupplyPacket operations
  // pending.
  uint32 min_packets_outstanding = 0;

  // The minimum packet PTS value. If the last packet supplied has a PTS less
  // than this value, another packet should be supplied. A value of kNoTimestamp
  // means this value is not applicable.
  int64 min_pts = MediaPacket.kNoTimestamp;
};

// Models a stream producer. A MediaPacketProducer allows a client to connect
// the producer to a MediaPacketConsumer so packets flow from the producer to
// the consumer.
//
// The client calls Connect to connect producer and consumer. The producer then
// calls PushPacket on the consumer to deliver packets.
interface MediaPacketProducer {
  // Connects this MediaPacketProducer to a MediaPacketConsumer.
  Connect@0(MediaPacketConsumer consumer) => ();

  // Disconnects this MediaPacketProducer from a previously-connected
  // MediaPacketConsumer.
  Disconnect@1();
};

// Models a stream consumer. A MediaPacketConsumer allows a client to send
// packets directly to the consumer or to connect the consumer to a
// MediaPacketProducer so packets flow from the producer to the consumer.
//
// In the former scenario, the client calls PushPacket to deliver a packet. The
// callback notifies the client that the consumer is done with the packet
// buffer region.
//
// In the latter scenario, the client calls Connect on the producer to connect
// producer and consumer. The producer then calls PushPacket on the consumer to
// deliver packets.
interface MediaPacketConsumer {
  const uint64 kMaxBufferLen = 0x3FFFFFFFFFFFFFFF;

  // Gets the demand. The consumer is free to respond to this method when it
  // sees fit to do so. Demand can be communicated in the response to
  // SupplyPacket, so this method is only used when the demand update can't wait
  // until the next SupplyPacket response is sent.
  PullDemandUpdate@0() => (MediaPacketDemand? demand);

  // Adds a payload buffer that may subsequently be referenced by a MediaPacket.
  AddPayloadBuffer@1(uint32 payload_buffer_id,
                     handle<vmo> payload_buffer);

  // Indicates that the identified payload buffer will no longer be used.
  RemovePayloadBuffer@2(uint32 payload_buffer_id);

  // Supplies a packet to the consumer. The callback signals that the consumer
  // is done with the packet and its payload. Demand is only provided in the
  // response if it has changed.
  SupplyPacket@3(MediaPacket packet) => (MediaPacketDemand? demand);

  // Supplies a packet to the consumer without a completion callback. This
  // version is useful for clients that use a synchronous proxy. Without the
  // callback, the consumer can't signal that it's done with the payload, so
  // the client needs some other method to determine this. Typically, this
  // method is used for audio renderers, in which case the consumer is reliably
  // done with the payload when the last frame of the packet has been presented.
  // The presentation timeline transform can be used to determine this time.
  SupplyPacketNoReply@4(MediaPacket packet);

  // Flushes the stream. The callback signals that the flush operation is
  // complete. |hold_frame| indicates whether a video renderer (if any) should
  // continue to display the last displayed frame.
  Flush@5(bool hold_frame) => ();
};