| // 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. |
| using Domain = string:1000; |
| |
| /// Controls for a media player. |
| protocol PlayerControl { |
| /// Plays media. |
| Play(); |
| /// Pauses playback and retains position in media |
| 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. |
| Seek(zx.duration position); |
| /// Skips forward in media by the player's default skip amount. |
| SkipForward(); |
| /// Skips in reverse in media by the player's default skip amount. |
| SkipReverse(); |
| /// Changes media to the next item (e.g. next song in playlist). |
| NextItem(); |
| /// Changes media to the previous item. |
| PrevItem(); |
| /// Sets the playback rate of the media. This will not change the |
| /// playback mode. |
| SetPlaybackRate(float32 playback_rate); |
| /// Sets repeat mode to any of the supported repeat modes. |
| SetRepeatMode(RepeatMode repeat_mode); |
| /// Sets shuffle mode. |
| SetShuffleMode(bool shuffle_on); |
| /// Binds to the session's volume control for control and notifications. |
| 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 { |
| OTHER = 1; |
| AUDIO = 2; |
| VIDEO = 3; |
| MUSIC = 4; |
| TV_SHOW = 5; |
| MOVIE = 6; |
| }; |
| |
| /// Status of a media player. |
| // Next Id: 9 |
| table PlayerStatus { |
| /// Total duration of playing media. |
| /// |
| /// Omit if not known or not applicable. |
| 1: zx.duration duration; |
| /// Whether the playing media is live (such as television or a |
| /// live stream). |
| /// |
| /// If omitted, the default is false. |
| 8: bool is_live; |
| /// State of the player. |
| /// |
| /// Will always be present. |
| 2: PlayerState player_state; |
| /// A playback function that describes the position and rate of |
| /// play through the media as a function of `CLOCK_MONOTONIC`. |
| /// |
| /// Include in order to render a position in media timeline |
| /// for users. Optional. |
| 3: fuchsia.media.TimelineFunction timeline_function; |
| /// Repeat mode of the player. |
| /// |
| /// Will always be present. |
| 4: RepeatMode repeat_mode; |
| /// Shuffle mode of the player. |
| /// |
| /// Will always be present. |
| 5: bool shuffle_on; |
| /// The type of content playing back. |
| /// |
| /// Will always be present. |
| 6: ContentType content_type; |
| /// An error the player may have encountered. |
| /// |
| /// Should only be present in case of error. |
| 7: Error error; |
| }; |
| |
| /// State of a media player. |
| enum PlayerState { |
| /// The initial state of a session if there is no associated media. |
| IDLE = 0; |
| PLAYING = 1; |
| PAUSED = 2; |
| BUFFERING = 3; |
| /// The player cannot recover from this state and will close. |
| ERROR = 4; |
| }; |
| |
| // TODO(turnage): 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; |
| }; |
| |
| /// `PlaybackCapabilities` enumerates the capabilities of a media player, and |
| /// corresponds to the control commands it can execute. |
| table PlayerCapabilities { |
| 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 previous value is retained. If no value is ever |
| /// sent, the default is `true`. |
| 1: bool local; |
| /// The status of the player. |
| /// |
| /// If omitted, the previous status is retained. This must be included |
| /// at least once. |
| 2: PlayerStatus player_status; |
| /// The metadata of the playing media. |
| /// |
| /// If omitted, the previous metadata is retained. Including this at |
| /// least once for each new media is highly recommended. |
| 3: fuchsia.media.Metadata metadata; |
| /// The images associated with the playing media. |
| /// |
| /// If omitted, the previous media images are retained. Send an empty |
| /// vector to clear media images. |
| 4: vector<MediaImage>:16 media_images; |
| /// The capabilities of the player. |
| /// |
| /// If omitted, the previous capabilities are retained. This must be |
| /// sent at least once. |
| 5: PlayerCapabilities player_capabilities; |
| /// The behavior the player would like to engage in when interrupted |
| /// by something, such as an alarm. |
| /// |
| /// If omitted, the previous behavior is retained. If no value is ever |
| /// sent, the default 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; |
| |
| /// Leave hanging to receive a response when the player's |
| /// status changes. |
| WatchInfoChange() -> (PlayerInfoDelta player_info_delta); |
| }; |