blob: e8544d0cda235fc60a2b87e2141aa92dc0492f0e [file] [log] [blame]
// 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);
};