// 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);
};