sdk/fidl/fuchsia.media.sessions2/player.fidl - fuchsia - Git at Google

 // Copyright 2019 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.media.sessions2;

 using zx;
 using fuchsia.media;
 using fuchsia.media.audio;

 /// A domain identifies the ecosystem in which the session takes place.
 ///
 /// Domains should take the form of
 ///
 ///    `domain://<unique name for protocol>.version`
 ///
 /// The `|` symbol is reserved and should not be used in a domain string.
 alias Domain = string:1000;

 /// Controls for a media player. `PlayerCapabilities` expresses which of the methods in this
 /// protocol are supported by the player. Because capabilties are dynamic, and a client cannot
 /// always know what capabilities will be supported when the method call reaches the service,
 /// calling a method that is not supported is simply ignored. In general, clients should not
 /// expect methods to work unless the player indicates sustained support.
 protocol PlayerControl {
     /// Plays media. If this method is not supported as indicated by the absence of the `PLAY`
     /// flag in `PlayerCapabilities`, this method does nothing.
     Play();

     /// Pauses playback and retains position in media. If this method is not supported as indicated
     /// by the absence of the `PAUSE` flag in `PlayerCapabilities`, this method does nothing.
     Pause();

     /// Stops playback. The session should close.
     Stop();

     /// Seeks to a specific position in media. Implementations are free to
     /// enter an error state if the position is out of bounds. `position`
     /// is an offset from the beginning of the media. If this method is not supported as indicated
     /// by the absence of the `SEEK` flag in `PlayerCapabilities`, this method does nothing.
     Seek(zx.duration position);

     /// Skips forward in media by the player's default skip amount. If this method is not supported
     /// as indicated by the absence of the `SKIP_FORWARD` flag in `PlayerCapabilities`, this method
     /// does nothing.
     SkipForward();

     /// Skips in reverse in media by the player's default skip amount. If this method is not
     /// supported as indicated by the absence of the `SKIP_REVERSE` flag in `PlayerCapabilities`,
     /// this method does nothing.
     SkipReverse();

     /// Changes media to the next item (e.g. next song in playlist). If this method is not
     /// supported as indicated by the absence of the `CHANGE_TO_NEXT_ITEM` flag in
     /// `PlayerCapabilities`, this method does nothing.
     NextItem();

     /// Changes media to the previous item. If this method is not
     /// supported as indicated by the absence of the `CHANGE_TO_PREV_ITEM` flag in
     /// `PlayerCapabilities`, this method does nothing.
     PrevItem();

     /// Sets the playback rate of the media. This will not change the playback mode. If this method
     /// is not supported as indicated by the absense of the `SET_PLAYBACK_RATE` flag in
     /// `PlayerCapabilities`, this method does nothing.
     SetPlaybackRate(float32 playback_rate);

     /// Sets repeat mode to any of the supported repeat modes.
     /// Whether this method takes effect depends on the `PlayerCapabilities` and `repeat_mode`:
     ///   * [`OFF`] is always supported.
     ///   * [`GROUP`] requires the `REPEAT_GROUPS` capability, and is otherwise ignored.
     ///   * [`SINGLE`] requires the `REPEAT_SINGLE` capability, and is otherwise ignored.
     SetRepeatMode(RepeatMode repeat_mode);

     /// Sets shuffle mode. If this method is not supported as indicated by the absence of the
     /// `SHUFFLE` flag in `PlayerCapabilities`, this method does nothing.
     SetShuffleMode(bool shuffle_on);

     /// Binds to the session's volume control for control and notifications. If this method is not
     /// supported as indicated by the absence of the `HAS_GAIN_CONTROL` flag in
     /// `PlayerCapabilities`, the channel handle passed as `volume_control_request` is closed
     /// by the service.
     BindVolumeControl(
         request<fuchsia.media.audio.VolumeControl> volume_control_request);
 };

 /// The type of content playing back, which should be set to the largest
 /// applicable value.
 enum ContentType {
     /// Content does not qualify for any of the other values.
     OTHER = 1;

     /// Audio-only content that does not qualify as music.
     AUDIO = 2;

     /// Video-only or audio-video content that does not qualify as a TV show or a movie.
     VIDEO = 3;

     /// Audio-only content generally recognized as music.
     MUSIC = 4;

     /// Audio-video content that is part of a television or streaming series.
     TV_SHOW = 5;

     /// Audio-video content consisting of a feature film.
     MOVIE = 6;
 };

 /// Status of a media player.
 // Next Id: 9
 table PlayerStatus {
     /// Total duration of playing media.
     ///
     /// If this value is omitted, the duration is unknown, not applicable or unchanged. Initially,
     /// the duration is assumed to be unknown.
     1: zx.duration duration;

     /// Whether the playing media is live (such as television or a live stream).
     ///
     /// If this field is omitted, the value is unchanged. Initially, the value is false.
     8: bool is_live;

     /// State of the player.
     ///
     /// If this field is omitted, the value is unchanged. Initially, the value is `IDLE`.
     2: PlayerState player_state;

     /// A playback function that describes the position and rate of
     /// play through the media as a function of `CLOCK_MONOTONIC`.
     ///
     /// If this field is omitted, the value is unchanged. Initially, `reference_delta` is 1 and
     /// the remaining constituent fields are 0.
     3: fuchsia.media.TimelineFunction timeline_function;

     /// Repeat mode of the player.
     ///
     /// If this field is omitted, the value is unchanged. Initially, the value is `NONE`.
     4: RepeatMode repeat_mode;

     /// Shuffle mode of the player.
     ///
     /// If this field is omitted, the value is unchanged. Initially, the value is false.
     5: bool shuffle_on;

     /// The type of content playing back.
     ///
     /// If this field is omitted, the value is unchanged. Initially, the value is `OTHER`.
     6: ContentType content_type;

     /// An error the player may have encountered.
     ///
     /// This field is omitted unless there is an error. Once an error is indicated, it cannot
     /// be rescinded.
     7: Error error;
 };

 /// State of a media player.
 enum PlayerState {
     /// The initial state of a session if there is no associated media.
     IDLE = 0;

     /// The player is playing.
     PLAYING = 1;

     /// The player is paused.
     PAUSED = 2;

     /// The player would be playing, but is temporarily paused for buffering.
     BUFFERING = 3;

     /// The player cannot recover from this state and will close.
     ERROR = 4;
 };

 // TODO(dalesat): Add error codes for frontends as they are discovered to be useful.
 enum Error {
     OTHER = 1;
 };

 /// Modes of repeating playback of the current media.
 enum RepeatMode {
     /// No repeat.
     OFF = 0;

     /// Repeat the relevant group of media (e.g. playlist).
     GROUP = 1;

     /// Repeat the currently playing media.
     SINGLE = 2;
 };

 bits PlayerCapabilityFlags : uint32 {
     /// If set, the player can `Play()`.
     PLAY = 0x1;

     /// If set, the player can `Pause()`.
     PAUSE = 0x4;

     /// If set, the player can `Seek()`.
     SEEK = 0x8;

     /// If set, the player can `SkipForward()`.
     SKIP_FORWARD = 0x10;

     /// If set, the player can `SkipReverse()`.
     SKIP_REVERSE = 0x20;

     /// If set, the player can shuffle media.
     SHUFFLE = 0x40;

     // If set, the player can `NextItem()` if there is a next item.
     CHANGE_TO_NEXT_ITEM = 0x80;

     // If set, the player can `PrevItem()` if there is a previous item.
     CHANGE_TO_PREV_ITEM = 0x100;

     /// If set, the player can `BindGainControl()`.
     HAS_GAIN_CONTROL = 0x200;

     /// If set, the player can repeat groups.
     REPEAT_GROUPS = 0x400;

     /// If set, the player can repeat single media items.
     REPEAT_SINGLE = 0x800;

     /// If set, the player can accept playback rate changes.
     SET_PLAYBACK_RATE = 0x1000;
 };

 /// Describes the capabilities of a player.
 table PlayerCapabilities {
     /// Indicates which capabilities are supported by the player. See `PlayerControl` for
     /// details.
     1: PlayerCapabilityFlags flags;
 };

 /// The behavior enforced on the player when it is
 /// interrupted, such as by an alarm.
 ///
 /// Interruptions are detected using the player's usage.
 ///
 /// By default the interruption behavior is `NONE`.
 enum InterruptionBehavior {
     /// Interruptions have no effect on the player
     /// and it may continue in spite of reduced audibility.
     NONE = 0;

     /// With this behavior, when playback is interrupted, the player
     /// will be paused until the interruption is over, so the user
     /// does not miss any content.
     PAUSE = 1;
 };

 /// When emitted, fields that have changed should be set.
 /// The first emission to a new client should be a snapshot.
 table PlayerInfoDelta {
     /// Whether the entry point for the media into our device network is the
     /// local machine; this should be true if this is the device streaming
     /// from a music service, but false or omitted if this machine is just
     /// receiving an audio stream to act as a speaker.
     ///
     /// If omitted, the value is unchanged. Initially, this value is `true`.
     1: bool local;

     /// The status of the player.
     ///
     /// If omitted, all constituent values are unchanged. If a field within `PlayerStatus` is
     /// omitted, its value is unchanged. Initial values are indicated for each field in
     /// `player_status`.
     2: PlayerStatus player_status;

     /// The metadata of the playing media.
     ///
     /// If omitted, the metadata is unchanged. Initially, there is no metadata.
     3: fuchsia.media.Metadata metadata;

     /// The images associated with the playing media.
     ///
     /// If omitted, the media images are unchanged. An empty
     /// vector indicates that there are no media images, which is also the initial state.
     4: vector<MediaImage>:16 media_images;

     /// The capabilities of the player.
     ///
     /// If omitted, the capabilities are unchanged. Initially, the player is assumed to have no
     /// capabilities.
     5: PlayerCapabilities player_capabilities;

     /// The behavior the player would like to engage in when interrupted
     /// by something, such as an alarm.
     ///
     /// If omitted, the behavior is unchanged. Initially, the value is `NONE`.
     6: InterruptionBehavior interruption_behavior;
 };

 /// `Player` is a handle for a media player. Unsupported commands are
 /// no-ops.  Consult `PlaybackCapabilities`, sent by to learn which
 /// commands are supported.
 protocol Player {
     compose PlayerControl;

     /// Gets the net player info change using the hanging get pattern.
     WatchInfoChange() -> (PlayerInfoDelta player_info_delta);
 };
	// Copyright 2019 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.media.sessions2;

	using zx;
	using fuchsia.media;
	using fuchsia.media.audio;

	/// A domain identifies the ecosystem in which the session takes place.
	///
	/// Domains should take the form of
	///
	/// `domain://<unique name for protocol>.version`
	///
	/// The `\|` symbol is reserved and should not be used in a domain string.
	alias Domain = string:1000;

	/// Controls for a media player. `PlayerCapabilities` expresses which of the methods in this
	/// protocol are supported by the player. Because capabilties are dynamic, and a client cannot
	/// always know what capabilities will be supported when the method call reaches the service,
	/// calling a method that is not supported is simply ignored. In general, clients should not
	/// expect methods to work unless the player indicates sustained support.
	protocol PlayerControl {
	/// Plays media. If this method is not supported as indicated by the absence of the `PLAY`
	/// flag in `PlayerCapabilities`, this method does nothing.
	Play();

	/// Pauses playback and retains position in media. If this method is not supported as indicated
	/// by the absence of the `PAUSE` flag in `PlayerCapabilities`, this method does nothing.
	Pause();

	/// Stops playback. The session should close.
	Stop();

	/// Seeks to a specific position in media. Implementations are free to
	/// enter an error state if the position is out of bounds. `position`
	/// is an offset from the beginning of the media. If this method is not supported as indicated
	/// by the absence of the `SEEK` flag in `PlayerCapabilities`, this method does nothing.
	Seek(zx.duration position);

	/// Skips forward in media by the player's default skip amount. If this method is not supported
	/// as indicated by the absence of the `SKIP_FORWARD` flag in `PlayerCapabilities`, this method
	/// does nothing.
	SkipForward();

	/// Skips in reverse in media by the player's default skip amount. If this method is not
	/// supported as indicated by the absence of the `SKIP_REVERSE` flag in `PlayerCapabilities`,
	/// this method does nothing.
	SkipReverse();

	/// Changes media to the next item (e.g. next song in playlist). If this method is not
	/// supported as indicated by the absence of the `CHANGE_TO_NEXT_ITEM` flag in
	/// `PlayerCapabilities`, this method does nothing.
	NextItem();

	/// Changes media to the previous item. If this method is not
	/// supported as indicated by the absence of the `CHANGE_TO_PREV_ITEM` flag in
	/// `PlayerCapabilities`, this method does nothing.
	PrevItem();

	/// Sets the playback rate of the media. This will not change the playback mode. If this method
	/// is not supported as indicated by the absense of the `SET_PLAYBACK_RATE` flag in
	/// `PlayerCapabilities`, this method does nothing.
	SetPlaybackRate(float32 playback_rate);

	/// Sets repeat mode to any of the supported repeat modes.
	/// Whether this method takes effect depends on the `PlayerCapabilities` and `repeat_mode`:
	/// * [`OFF`] is always supported.
	/// * [`GROUP`] requires the `REPEAT_GROUPS` capability, and is otherwise ignored.
	/// * [`SINGLE`] requires the `REPEAT_SINGLE` capability, and is otherwise ignored.
	SetRepeatMode(RepeatMode repeat_mode);

	/// Sets shuffle mode. If this method is not supported as indicated by the absence of the
	/// `SHUFFLE` flag in `PlayerCapabilities`, this method does nothing.
	SetShuffleMode(bool shuffle_on);

	/// Binds to the session's volume control for control and notifications. If this method is not
	/// supported as indicated by the absence of the `HAS_GAIN_CONTROL` flag in
	/// `PlayerCapabilities`, the channel handle passed as `volume_control_request` is closed
	/// by the service.
	BindVolumeControl(
	request<fuchsia.media.audio.VolumeControl> volume_control_request);
	};

	/// The type of content playing back, which should be set to the largest
	/// applicable value.
	enum ContentType {
	/// Content does not qualify for any of the other values.
	OTHER = 1;

	/// Audio-only content that does not qualify as music.
	AUDIO = 2;

	/// Video-only or audio-video content that does not qualify as a TV show or a movie.
	VIDEO = 3;

	/// Audio-only content generally recognized as music.
	MUSIC = 4;

	/// Audio-video content that is part of a television or streaming series.
	TV_SHOW = 5;

	/// Audio-video content consisting of a feature film.
	MOVIE = 6;
	};

	/// Status of a media player.
	// Next Id: 9
	table PlayerStatus {
	/// Total duration of playing media.
	///
	/// If this value is omitted, the duration is unknown, not applicable or unchanged. Initially,
	/// the duration is assumed to be unknown.
	1: zx.duration duration;

	/// Whether the playing media is live (such as television or a live stream).
	///
	/// If this field is omitted, the value is unchanged. Initially, the value is false.
	8: bool is_live;

	/// State of the player.
	///
	/// If this field is omitted, the value is unchanged. Initially, the value is `IDLE`.
	2: PlayerState player_state;

	/// A playback function that describes the position and rate of
	/// play through the media as a function of `CLOCK_MONOTONIC`.
	///
	/// If this field is omitted, the value is unchanged. Initially, `reference_delta` is 1 and
	/// the remaining constituent fields are 0.
	3: fuchsia.media.TimelineFunction timeline_function;

	/// Repeat mode of the player.
	///
	/// If this field is omitted, the value is unchanged. Initially, the value is `NONE`.
	4: RepeatMode repeat_mode;

	/// Shuffle mode of the player.
	///
	/// If this field is omitted, the value is unchanged. Initially, the value is false.
	5: bool shuffle_on;

	/// The type of content playing back.
	///
	/// If this field is omitted, the value is unchanged. Initially, the value is `OTHER`.
	6: ContentType content_type;

	/// An error the player may have encountered.
	///
	/// This field is omitted unless there is an error. Once an error is indicated, it cannot
	/// be rescinded.
	7: Error error;
	};

	/// State of a media player.
	enum PlayerState {
	/// The initial state of a session if there is no associated media.
	IDLE = 0;

	/// The player is playing.
	PLAYING = 1;

	/// The player is paused.
	PAUSED = 2;

	/// The player would be playing, but is temporarily paused for buffering.
	BUFFERING = 3;

	/// The player cannot recover from this state and will close.
	ERROR = 4;
	};

	// TODO(dalesat): Add error codes for frontends as they are discovered to be useful.
	enum Error {
	OTHER = 1;
	};

	/// Modes of repeating playback of the current media.
	enum RepeatMode {
	/// No repeat.
	OFF = 0;

	/// Repeat the relevant group of media (e.g. playlist).
	GROUP = 1;

	/// Repeat the currently playing media.
	SINGLE = 2;
	};

	bits PlayerCapabilityFlags : uint32 {
	/// If set, the player can `Play()`.
	PLAY = 0x1;

	/// If set, the player can `Pause()`.
	PAUSE = 0x4;

	/// If set, the player can `Seek()`.
	SEEK = 0x8;

	/// If set, the player can `SkipForward()`.
	SKIP_FORWARD = 0x10;

	/// If set, the player can `SkipReverse()`.
	SKIP_REVERSE = 0x20;

	/// If set, the player can shuffle media.
	SHUFFLE = 0x40;

	// If set, the player can `NextItem()` if there is a next item.
	CHANGE_TO_NEXT_ITEM = 0x80;

	// If set, the player can `PrevItem()` if there is a previous item.
	CHANGE_TO_PREV_ITEM = 0x100;

	/// If set, the player can `BindGainControl()`.
	HAS_GAIN_CONTROL = 0x200;

	/// If set, the player can repeat groups.
	REPEAT_GROUPS = 0x400;

	/// If set, the player can repeat single media items.
	REPEAT_SINGLE = 0x800;

	/// If set, the player can accept playback rate changes.
	SET_PLAYBACK_RATE = 0x1000;
	};

	/// Describes the capabilities of a player.
	table PlayerCapabilities {
	/// Indicates which capabilities are supported by the player. See `PlayerControl` for
	/// details.
	1: PlayerCapabilityFlags flags;
	};

	/// The behavior enforced on the player when it is
	/// interrupted, such as by an alarm.
	///
	/// Interruptions are detected using the player's usage.
	///
	/// By default the interruption behavior is `NONE`.
	enum InterruptionBehavior {
	/// Interruptions have no effect on the player
	/// and it may continue in spite of reduced audibility.
	NONE = 0;

	/// With this behavior, when playback is interrupted, the player
	/// will be paused until the interruption is over, so the user
	/// does not miss any content.
	PAUSE = 1;
	};

	/// When emitted, fields that have changed should be set.
	/// The first emission to a new client should be a snapshot.
	table PlayerInfoDelta {
	/// Whether the entry point for the media into our device network is the
	/// local machine; this should be true if this is the device streaming
	/// from a music service, but false or omitted if this machine is just
	/// receiving an audio stream to act as a speaker.
	///
	/// If omitted, the value is unchanged. Initially, this value is `true`.
	1: bool local;

	/// The status of the player.
	///
	/// If omitted, all constituent values are unchanged. If a field within `PlayerStatus` is
	/// omitted, its value is unchanged. Initial values are indicated for each field in
	/// `player_status`.
	2: PlayerStatus player_status;

	/// The metadata of the playing media.
	///
	/// If omitted, the metadata is unchanged. Initially, there is no metadata.
	3: fuchsia.media.Metadata metadata;

	/// The images associated with the playing media.
	///
	/// If omitted, the media images are unchanged. An empty
	/// vector indicates that there are no media images, which is also the initial state.
	4: vector<MediaImage>:16 media_images;

	/// The capabilities of the player.
	///
	/// If omitted, the capabilities are unchanged. Initially, the player is assumed to have no
	/// capabilities.
	5: PlayerCapabilities player_capabilities;

	/// The behavior the player would like to engage in when interrupted
	/// by something, such as an alarm.
	///
	/// If omitted, the behavior is unchanged. Initially, the value is `NONE`.
	6: InterruptionBehavior interruption_behavior;
	};

	/// `Player` is a handle for a media player. Unsupported commands are
	/// no-ops. Consult `PlaybackCapabilities`, sent by to learn which
	/// commands are supported.
	protocol Player {
	compose PlayerControl;

	/// Gets the net player info change using the hanging get pattern.
	WatchInfoChange() -> (PlayerInfoDelta player_info_delta);
	};