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.
 closed 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.
     strict 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.
     strict Pause();

     /// Stops playback. The session should close.
     strict 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.
     strict Seek(struct {
         position zx.Duration;
     });

     /// 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.
     strict 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.
     strict 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.
     strict 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.
     strict 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.
     strict SetPlaybackRate(struct {
         playback_rate float32;
     });

     /// 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.
     strict SetRepeatMode(struct {
         repeat_mode RepeatMode;
     });

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

     /// 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.
     strict BindVolumeControl(resource struct {
         volume_control_request server_end:fuchsia.media.audio.VolumeControl;
     });
 };

 /// The type of content playing back, which should be set to the largest
 /// applicable value.
 type ContentType = strict enum {
     /// 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
 type PlayerStatus = table {
     /// 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: duration zx.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: is_live bool;

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

     /// 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: timeline_function fuchsia.media.TimelineFunction;

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

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

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

     /// 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.
 type PlayerState = strict enum {
     /// 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.
 type Error = strict enum {
     OTHER = 1;
 };

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

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

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

 type PlayerCapabilityFlags = strict bits : 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.
 type PlayerCapabilities = table {
     /// Indicates which capabilities are supported by the player. See `PlayerControl` for
     /// details.
     1: flags PlayerCapabilityFlags;
 };

 /// 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`.
 type InterruptionBehavior = strict enum {
     /// 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.
 type PlayerInfoDelta = table {
     /// 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: local bool;

     /// 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: player_status PlayerStatus;

     /// The metadata of the playing media.
     ///
     /// If omitted, the metadata is unchanged. Initially, there is no metadata.
     3: metadata fuchsia.media.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: media_images vector<MediaImage>:16;

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

     /// 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: interruption_behavior InterruptionBehavior;
 };

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

     /// Gets the net player info change using the hanging get pattern.
     strict WatchInfoChange() -> (struct {
         player_info_delta PlayerInfoDelta;
     });
 };
	// 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.
	closed 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.
	strict 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.
	strict Pause();

	/// Stops playback. The session should close.
	strict 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.
	strict Seek(struct {
	position zx.Duration;
	});

	/// 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.
	strict 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.
	strict 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.
	strict 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.
	strict 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.
	strict SetPlaybackRate(struct {
	playback_rate float32;
	});

	/// 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.
	strict SetRepeatMode(struct {
	repeat_mode RepeatMode;
	});

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

	/// 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.
	strict BindVolumeControl(resource struct {
	volume_control_request server_end:fuchsia.media.audio.VolumeControl;
	});
	};

	/// The type of content playing back, which should be set to the largest
	/// applicable value.
	type ContentType = strict enum {
	/// 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
	type PlayerStatus = table {
	/// 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: duration zx.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: is_live bool;

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

	/// 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: timeline_function fuchsia.media.TimelineFunction;

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

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

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

	/// 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.
	type PlayerState = strict enum {
	/// 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.
	type Error = strict enum {
	OTHER = 1;
	};

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

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

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

	type PlayerCapabilityFlags = strict bits : 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.
	type PlayerCapabilities = table {
	/// Indicates which capabilities are supported by the player. See `PlayerControl` for
	/// details.
	1: flags PlayerCapabilityFlags;
	};

	/// 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`.
	type InterruptionBehavior = strict enum {
	/// 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.
	type PlayerInfoDelta = table {
	/// 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: local bool;

	/// 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: player_status PlayerStatus;

	/// The metadata of the playing media.
	///
	/// If omitted, the metadata is unchanged. Initially, there is no metadata.
	3: metadata fuchsia.media.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: media_images vector<MediaImage>:16;

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

	/// 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: interruption_behavior InterruptionBehavior;
	};

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

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