blob: edba82a255ce3c874f853af8c5950da15a8ce354 [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.
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(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.
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(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.
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.
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.
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.
protocol Player {
compose PlayerControl;
/// Gets the net player info change using the hanging get pattern.
WatchInfoChange() -> (struct {
player_info_delta PlayerInfoDelta;
});
};