blob: ba218f31f3791e91c28e72f83bbd2f297792ecd1 [file] [log] [blame]
// Copyright 2016 The Chromium 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.mojom;
interface RemoterFactory {
// Create a new Remoter associated with the given RemotingSource and bind it
// to the given interface request. The RemotingSource will be notified when
// the Remoter becomes available for use (or becomes unavailable).
Create(RemotingSource source, Remoter& remoter);
// Interface used by the source to control when media bitstream data is read
// from a data pipe and then sent to the remote endpoint. There is one
// RemotingDataStreamSender per data pipe.
interface RemotingDataStreamSender {
// Consumes |size| bytes of data from the data pipe, which is a chunk of the
// next frame's data payload starting at the given byte |offset|.
// |total_payload_size| indicates the size of the entire data payload for the
// frame. Before this is called, |size| bytes of data must have been written
// into the data pipe.
// Normally, a frame's entire data payload can be pushed through the data pipe
// in one chunk. However, there can be situations where the size of the
// payload exceeds the capacity of the data pipe; and so this API supports
// feeding the frame data through the pipe in multiple chunks.
ConsumeDataChunk(uint32 offset, uint32 size, uint32 total_payload_size);
// Enqueues another frame for transmission to the remote endpoint. Before this
// is called, ConsumeDataChunk() must have been called one or more times to
// provide all of the frame's data.
// Cancel the transmission of all in-flight data to the remote, up to and
// including the last SendFrame() call; and also discard any data chunks
// that were consumed from the data pipe for the next frame. This is used to
// optimize seeking, when it is known that any in-flight data is no longer
// needed by the remote. There is no guarantee as to how much of the in-flight
// data will actually reach the remote before the cancellation takes effect.
enum RemotingStopReason {
ROUTE_TERMINATED, // User-initiated disconnect, etc.
LOCAL_PLAYBACK, // Media switched back to local playback.
SOURCE_GONE, // RemotingSource has been destroyed.
MESSAGE_SEND_FAILED, // Failed to send a message to the sink.
DATA_SEND_FAILED, // Failed to consume from a data pipe or send to the sink.
UNEXPECTED_FAILURE, // Unexpected failure or inconsistent state encountered.
// Interface used by the source to start/stop remoting and send data to the
// sink.
interface Remoter {
// Start a remoting session (once the sink has been reported to be available;
// see RemotingSource). Either RemotingSource.OnStarted() or OnStartFailed()
// will be called to indicate success or failure. Once OnStarted() has been
// invoked, the source may then make calls to SendMessageToSink() and expect
// messages from the remote via RemotingSource.OnMessageFromSink().
// Start remoting the media data streams. This is called after Start() to
// provide data pipes from which the audio/video bitstream data is consumed
// and then transported to the remote device. RemotingDataStreamSenders are
// used by the source to control when data should be consumed from the data
// pipes and sent. One or both pipes (and their corresponding
// RemotingDataStreamSender interface requests) must be provided.
StartDataStreams(handle<data_pipe_consumer>? audio_pipe,
handle<data_pipe_consumer>? video_pipe,
RemotingDataStreamSender&? audio_sender,
RemotingDataStreamSender&? video_sender);
// Stop remoting media. Messages in both directions will be dropped after this
// point as well as any pending or in-transit media bitstream data.
Stop(RemotingStopReason reason);
// Send |message| to the sink. |message| is a serialized protobuf from
// src/media/remoting/proto.
SendMessageToSink(array<uint8> message);
enum RemotingSinkCapabilities {
enum RemotingStartFailReason {
CANNOT_START_MULTIPLE, // Remoting was already active.
ROUTE_TERMINATED, // User-initated disconnect while starting remoting.
// Interface used for sending notifications back to the local source's control
// logic, and to pass messages from the sink back to the local media pipeline.
interface RemotingSource {
// Notify the source that the sink is now available to start remoting. It is
// up to the source's control logic to decide whether/when to start remoting.
// TODO(miu): In a later change, pass detailed information about the sink's
// capabilities (e.g., codec support, DRM keysystem support, etc.).
OnSinkAvailable(RemotingSinkCapabilities capabilities);
// Notify the source that the sink is no longer available for remoting. This
// may happen, for example, because the sink has been shut down, or because
// another source has started remoting.
// One of these is called after the source attempts to start remoting. If
// OnStarted() is called, messages may begin flowing; and this will continue
// until OnStopped() is called. On the other hand, if OnStartFailed() is
// called, then no messages are being passed between source and sink and
// remoting is not taking place.
OnStartFailed(RemotingStartFailReason reason);
// Pass a |message| from the sink back to the source. The |message| consists
// of a serialized protobuf from src/media/remoting/proto. This will only be
// called after OnStarted() and before OnStopped().
OnMessageFromSink(array<uint8> message);
// Notify the source that remoting has terminated. This may or may not be in
// response to a Remoter.Stop() call, as other events (possibly external) may
// have caused remoting to end.
OnStopped(RemotingStopReason reason);