sdk/fidl/fuchsia.audiovideo/producer.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.audiovideo;

using fuchsia.media2;
using fuchsia.mediastreams;
using zx;

/// Creates a producer that reads from a file.
@discoverable
protocol ProducerCreator {
    /// Creates a producer that reads from a file.
    ///
    /// + request `file_channel` the channel representing the file to read.
    /// + request `producer_server_end` the server end of the `Producer` channel.
    ///
    /// If this method fails, `producer_server_end` is closed with an epitaph that indicates the
    /// nature of the failure.
    Create(resource struct {
        file_channel zx.handle:CHANNEL;
        producer_server_end server_end:Producer;
    });
};

alias StreamId = uint32;

const MAX_STREAM_CHANGES uint32 = 16;

/// Represents an audio/video producer.
protocol Producer {
    compose fuchsia.media2.PassiveProducer;

    /// Gets producer status using the long get pattern. The first call to this method returns
    /// when meaningful status is available. Subsequent calls to this method will return when the
    /// status has changed.
    WatchStatus() -> (struct {
        status ProducerStatus;
    });

    /// Gets stream changes using the long get pattern. The first call to this method returns as
    /// soon as the producer determines the initial set of streams. Subsequent calls to this method
    /// will return when there are new changes.
    WatchStreamChanges() -> (struct {
        changes vector<ProducerStreamChange>:MAX_STREAM_CHANGES;
    });

    /// Binds to the specified stream requesting the original compression type.
    ///
    /// + request `stream_id` id of the stream to which to bind. If `stream_id` doesn't specify a
    ///   valid stream, the `producer_stream_server_end` is closed by the service with epitaph
    ///   ZX_ERR_INVALID_ARGS.
    /// + request `producer_stream_server_end` server end of the `ProducerStream` channel used to
    ///   commnicate with the stream.
    BindStream(resource struct {
        stream_id StreamId;
        producer_stream_server_end server_end:ProducerStream;
    });

    /// Binds to the specified stream requesting the specified compression type.
    ///
    /// + request `stream_id` id of the stream to which to bind. If `stream_id` doesn't specify a
    ///   valid stream, the `producer_stream_server_end` is closed by the service with epitaph
    ///   ZX_ERR_INVALID_ARGS.
    /// + request `compression_type` the desired compression type. This value may be the type of
    ///   `original_compression` from the `ProducerStreamInfo` for this stream, any of the
    ///   the `available_compression_types' or null if `uncompressed_supported` is true for this
    ///   stream.
    /// + request `producer_stream_server_end` server end of the `ProducerStream` channel used to
    ///   commnicate with the stream.
    /// - response `format` the format of the stream with the specified compression type applied.
    ///   If `compression_type` is the type of `original_compression` from the `ProducerStreamInfo`,
    ///   this value will be identical to `original_format`.
    /// - response `compression` the compression applied to the stream.
    ///   If `compression_type` is the type of `original_compression` from the `ProducerStreamInfo`,
    ///   this value will be identical to `original_compression`.
    BindStreamWithCompression(resource struct {
        stream_id StreamId;
        compression_type fuchsia.mediastreams.CompressionType:optional;
        producer_stream_server_end server_end:ProducerStream;
    }) -> (struct {
        format fuchsia.mediastreams.MediaFormat;
        compression box<fuchsia.mediastreams.Compression>;
    }) error fuchsia.media2.ConnectionError;
};

/// Status of a `Producer`.
type ProducerStatus = table {
    /// Current error, if any. If this value is absent, no error is currently present.
    1: error ProducerError;

    /// Duration of the current content. If this value is absent, the duration of the content
    /// is currently unkonwn.
    2: duration zx.duration;

    /// Metadata regarding the current content. If this value is absent, current metadata is
    /// either unknown or non-existent.
    3: metadata Metadata;

    /// Whether the producer can seek. If this value is absent, seek is not supported.
    4: seek_supported bool;
};

type ProducerError = flexible enum {
    CONTENT_NOT_FOUND = 1;

    FAILED_TO_OPEN_CONTENT = 2;

    OTHER_ERROR = 3;
};

/// A change returned by `Producer.WatchStreamChanges`.
type ProducerStreamChange = flexible union {
    /// Describes a stream of which the client has not been previously informed.
    1: added ProducerStreamInfo;

    /// Describes a stream of which the client has been previously informed but whose properties
    /// have changed.
    2: updated ProducerStreamInfo;

    /// Identifies a stream of which the client has been previously informed but which has been
    /// removed and is no longer valid.
    3: removed StreamId;
};

const MAX_COMPRESSION_TYPES uint32 = 256;

/// Describes a stream exposed by a `Producer`.
type ProducerStreamInfo = table {
    /// The stream identifier. This value is always set by the producer.
    1: id StreamId;

    /// The format of the unconverted stream. This value is always set by the producer.
    2: original_format fuchsia.mediastreams.MediaFormat;

    /// The compression applied to the unconverted stream. If this value is absent, the stream is
    /// uncompressed.
    3: original_compression fuchsia.mediastreams.Compression;

    /// The encryption applied to the undecrypted stream. If this value is absent, the stream is
    /// unencrypted.
    4: encryption fuchsia.mediastreams.Encryption;

    /// The timeline of the stream. If this value is absent, timestamp units are not defined for
    /// the stream.
    5: timestamp_units fuchsia.media2.PacketTimestampUnits;

    /// Metadata regarding this stream. If this value is absent, no metadata is associated with the
    /// stream.
    6: metadata Metadata;

    /// The compression types available as alternatives to `original_compression`. If this value is
    /// absent, no alternative compression types are available.
    7: available_compression_types
            vector<fuchsia.mediastreams.CompressionType>:MAX_COMPRESSION_TYPES;

    // Whether an uncompressed stream is available as an alternative to `original_compression`. If
    // this value is absent, an uncompressed stream is not available as an alternative.
    8: uncompressed_supported bool;
};

/// A stream exposed by a `Producer`.
///
/// When a stream is removed, the `Producer` client can receive a notification to that effect via
/// `Producer.WatchStreamChanges`. In addition, if the client has called `Producer.BindStream` for
/// the removed stream, the service will send an `OnDisconnected` event with status
/// `ZX_ERR_UNAVAILABLE` if a `StreamSink` was connected, then it will close the `ProducerStream`
/// channel with an epitaph of `ZX_ERR_UNAVAILABLE`.
protocol ProducerStream {
    /// Connects a stream sink for the stream with the indicated buffer collection. Multiple stream
    /// sinks may be used sequentially for a given producer stream. This method responds when the
    /// connection is ready or the connect attempt fails.
    /// + request `buffer_collection_token` identifies the logical buffer collection to be used for
    ///   the new connection.
    /// + request `stream_sink` the client end of the `StreamSink` channel for this connection.
    Connect(resource struct {
        buffer_collection_token zx.handle:EVENTPAIR;
        stream_sink client_end:fuchsia.media2.StreamSink;
    }) -> (struct {}) error fuchsia.media2.ConnectionError;

    // TODO: How do we handle decryption?

    /// Disconnects the output stream.
    Disconnect();

    /// Indicates that the current output stream has been disconnected unexpectedly.
    -> OnDisconnected(struct {
        epitaph zx.status;
    });

    /// Indicates that the stream sink previously created is invalid, and the client should create
    /// another one if it wishes to continue sending packets.
    -> OnStreamSinkInvalid();
};