// Copyright 2018 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module media_session.mojom;

import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/url.mojom";

// Next MinVersion: 26

[Stable, Extensible]
enum MediaPlaybackState {
  kPaused,
  kPlaying,
};

// LINT.IfChange(MediaSessionAction)
[Stable, Extensible]
enum MediaSessionAction {
  kPlay,
  kPause,
  kPreviousTrack,
  kNextTrack,
  kSeekBackward,
  kSeekForward,
  kSkipAd,
  kStop,
  kSeekTo,
  kScrubTo,
  kEnterPictureInPicture,
  kExitPictureInPicture,
  kSwitchAudioDevice,
  [MinVersion=11] kToggleMicrophone,
  [MinVersion=11] kToggleCamera,
  [MinVersion=11] kHangUp,
  [MinVersion=12] kRaise,
  [MinVersion=13] kSetMute,
  [MinVersion=18] kPreviousSlide,
  [MinVersion=18] kNextSlide,
  [MinVersion=19] kEnterAutoPictureInPicture,
  [MinVersion=25] kSaveVideoFrame,
};
// LINT.ThenChange(//tools/metrics/histograms/enums.xml:MediaSessionAction)

[Stable, Extensible]
enum MediaSessionImageType {
  // The artwork associated with the media session (e.g album art).
  kArtwork,

  // The icon associated with the source of the media session.
  kSourceIcon,

  // The artwork associated with its chapters in the media session.
  [MinVersion=22] kChapter,
};

[Stable, Extensible]
enum MediaPictureInPictureState {
  kNotInPictureInPicture,
  kInPictureInPicture,
};

[Stable, Extensible]
enum MediaAudioVideoState {
  // Unused as of version 10, see |audio_video_states|.
  kDeprecatedUnknown,
  kAudioOnly,
  kAudioVideo,
  [MinVersion=10] kVideoOnly,
};

// Album art in MediaMetadata
// Spec: https://wicg.github.io/mediasession/
[Stable]
struct MediaImage {
  url.mojom.Url src;
  mojo_base.mojom.String16 type;
  array<gfx.mojom.Size> sizes;
};

// Chapter info in MediaMetadata
// Spec: https://wicg.github.io/mediasession/
[Stable]
struct ChapterInformation {
  mojo_base.mojom.String16 title;
  mojo_base.mojom.TimeDelta startTime;
  array<MediaImage> artwork;
};

// MediaMetadata
[Stable]
struct MediaMetadata {
  // These are defined in the spec: https://wicg.github.io/mediasession/
  mojo_base.mojom.String16 title;
  mojo_base.mojom.String16 artist;
  mojo_base.mojom.String16 album;

  // The |source_title| is a human readable title for the source of the media
  // session. This could be the name of the app or the name of the site playing
  // media.
  mojo_base.mojom.String16 source_title;

  // Also defined in the spec: https://wicg.github.io/mediasession/
  [MinVersion=21] array<ChapterInformation>? chapters;
};

// The color type of the bitmap.
[Stable, Extensible]
enum MediaImageBitmapColorType {
  kRGBA_8888,  // On Android, this is Bitmap.Config.ARGB_8888
  kBGRA_8888,
};

// A bitmap image. We use this instead of SkImage or skia.image.Bitmap so we can
// use it in ARC and we do not use ArcBitmap because we need to use it in the
// service.
[Stable]
struct MediaImageBitmap {
  int32 width;
  int32 height;
  array<uint8> pixel_data;
  [MinVersion=5] MediaImageBitmapColorType color_type;
};

[Stable]
struct MediaPosition {
  double playback_rate;
  mojo_base.mojom.TimeDelta duration;
  mojo_base.mojom.TimeDelta position;
  mojo_base.mojom.TimeTicks last_updated_time;
  [MinVersion=13] bool end_of_media;
};

[Stable, Extensible]
enum MicrophoneState {
  [Default] kUnknown,
  kMuted,
  kUnmuted,
};

[Stable, Extensible]
enum CameraState {
  [Default] kUnknown,
  kTurnedOn,
  kTurnedOff,
};

[Stable]
struct RemotePlaybackMetadata {
  string video_codec@0;
  string audio_codec@1;
  bool remote_playback_disabled@2;
  [MinVersion=17] bool remote_playback_started@3;
  // Deprecated, was remoting_device_friendly_name
  [MinVersion=17] string? unused_field@4;
  [MinVersion=18] bool is_encrypted_media@5;
};

// Contains state information about a MediaSession.
[Stable]
struct MediaSessionInfo {
  [Stable, Extensible]
  enum SessionState {
    // The MediaSession is currently playing media.
    kActive,

    // The MediaSession is currently playing at a reduced volume (ducking).
    kDucking,

    // The MediaSession is currently paused.
    kSuspended,

    // The MediaSession is not currently playing media.
    kInactive,
  };

  // The current audio focus state of the MediaSession.
  SessionState state;

  // If true then we will always duck this MediaSession instead of suspending.
  bool force_duck;

  // The playback state tells the client whether the audio is playing. This is
  // different from the audio focus state as it is common for a media session
  // to hold audio focus sometimes even though it is not actually playing.
  [MinVersion=1] MediaPlaybackState playback_state;

  // If true then the session should be controllable by the user.
  [MinVersion=2] bool is_controllable;

  // If true then we will stop this MediaSession instead of suspending when the
  // session loses focus to a kGain focus type.
  [MinVersion=4] bool prefer_stop_for_gain_focus_loss;

  // If true then the session is considered to be sensitive (e.g. from an
  // off the record profile). This may result in it being hidden from certain
  // UIs (e.g. lock screen media controls).
  // DEPRECATED, use |hide_metadata| instead.
  [MinVersion=6] bool deprecated_is_sensitive;

  // The picture-in-picture state tells the client whether the media is
  // currently in a picture-in-picture window.
  [MinVersion=7] MediaPictureInPictureState picture_in_picture_state;

  // The audio/video state of the Media Session (if known).
  // DEPRECATED, use |audio_video_states| instead.
  [MinVersion=8] MediaAudioVideoState deprecated_audio_video_state;

  // The audio_sink_id tells the client the device_id of the audio output device
  // being used for this media session. A null audio_sink_id implies that the
  // default device is being used.
  [MinVersion=9] string? audio_sink_id;

  // The audio/video states of all the players in the Media Session (if known).
  [MinVersion=10] array<MediaAudioVideoState>? audio_video_states;

  // Tracks whether the microphone is muted in WebRTC sessions.
  [MinVersion=11] MicrophoneState microphone_state;

  // Tracks whether the camera is turned on in WebRTC sessions.
  [MinVersion=11] CameraState camera_state;

  // Tracks whether the media player is muted.
  [MinVersion=12] bool muted;

  // Tracks whether the associated WebContents has a presentation.
  [MinVersion=14] bool has_presentation;

  // Stores the Media metadata used for Remote Playback.
  [MinVersion=15] RemotePlaybackMetadata? remote_playback_metadata;

  // If true then media metadata will be hidden from the OS' media controllers.
  [MinVersion=16] bool hide_metadata;

  // Indicates if this MediaSession should be ignored when finding a new active
  // session. This occurs for instanced web app system media controls that
  // cause the browser to never want to track web app media sessions.
  [MinVersion=20] bool ignore_for_active_session;

  // Indicates if this MediaSession has any players that meet the visibility
  // threshold defined by |HTMLVideoElement| (kVisibilityThreshold) and tracked
  // by the |MediaVideoVisibilityTracker|.
  [MinVersion=21] bool meets_visibility_threshold;

  // Indicates if this MediaSession can enter browser-initiated automatic
  // picture-in-picture.
  [MinVersion=24] bool can_enter_browser_initiated_autopip;
};

// Contains debugging information about a MediaSession. This will be displayed
// on the Media Internals WebUI.
[Stable]
struct MediaSessionDebugInfo {
  // A unique name for the MediaSession.
  string name;

  // The owner of the MediaSession.
  string owner;

  // State information stored in a string e.g. Ducked.
  string state;
};

// The observer for observing media session events.
// Next Method ID: 5
[Stable]
interface MediaSessionObserver {
  // Call when the info associated with the session changed.
  MediaSessionInfoChanged@0(MediaSessionInfo info);

  // Called when the observed MediaSession has changed metadata. The metadata
  // can be null to be reset, e.g. the media that was being played has been
  // stopped.
  MediaSessionMetadataChanged@1(MediaMetadata? metadata);

  // Called when the media session action list has changed. This tells the
  // observer which actions can be used to control the session.
  MediaSessionActionsChanged@2(array<MediaSessionAction> action);

  // Called when the images associated with a media session change.
  MediaSessionImagesChanged@3(
      map<MediaSessionImageType, array<MediaImage>> images);

  // Called when the position associated with the session has changed.
  MediaSessionPositionChanged@4(MediaPosition? position);
};

// A MediaSession manages the media session and audio focus for a given
// WebContents or ARC app.
// Next Method ID: 28
[Stable]
interface MediaSession {
  [Stable, Extensible]
  enum SuspendType {
    // Suspended by the system because a transient sound needs to be played.
    kSystem,
    // Suspended by the UI.
    kUI,
    // Suspended by the page via script or user interaction.
    kContent,
  };

  // Returns information about the MediaSession.
  GetMediaSessionInfo@0() => (MediaSessionInfo info);

  // Returns debug information about the MediaSession.
  GetDebugInfo@1() => (MediaSessionDebugInfo info);

  // Let the media session start ducking such that the volume multiplier
  // is reduced.
  StartDucking@2();

  // Let the media session stop ducking such that the volume multiplier is
  // recovered.
  StopDucking@3();

  // Suspend the media session.
  // |type| represents the origin of the request.
  Suspend@4(SuspendType suspend_type);

  // Resume the media session.
  // |type| represents the origin of the request.
  Resume@5(SuspendType suspend_type);

  AddObserver@6(pending_remote<MediaSessionObserver> observer);

  // Skip to the previous track. If there is no previous track then this will
  // be a no-op.
  PreviousTrack@7();

  // Skip to the next track. If there is no next track then this will be a
  // no-op.
  NextTrack@8();

  // Seek the media session from the current position. If the media cannot
  // seek then this will be a no-op. The |seek_time| is the time delta that
  // the media will seek by and supports both positive and negative values.
  // This value cannot be zero. The |kDefaultSeekTimeSeconds| provides a
  // default value for seeking by a few seconds.
  Seek@9(mojo_base.mojom.TimeDelta seek_time);

  // Stop the media session.
  // |type| represents the origin of the request.
  Stop@10(SuspendType suspend_type);

  // Skip ad.
  SkipAd@11();

  // Gets/Downloads the bitmap version of a MediaImage at least
  // |minimum_size_px| and closest to |desired_size_px|. If the download
  // failed, was too small or the image did not come from the media session
  // then returns a null image.
  GetMediaImageBitmap@12(
      MediaImage image, int32 minimum_size_px, int32 desired_size_px)
          => (MediaImageBitmap? image);

  // Seek the media session to a non-negative |seek_time| from the beginning of
  // the current playing media. If the media cannot seek then this will be a
  // no-op.
  SeekTo@13(mojo_base.mojom.TimeDelta seek_time);

  // Scrub ("fast seek") the media session to a non-negative |seek_time| from
  // the beginning of the current playing media. If the media cannot scrub then
  // this will be a no-op. The client should call |SeekTo| to finish the
  // scrubbing operation.
  ScrubTo@14(mojo_base.mojom.TimeDelta seek_time);

  // Enter picture-in-picture.
  EnterPictureInPicture@15();

  // Exit picture-in-picture.
  ExitPictureInPicture@16();

  // Routes the audio from this Media Session to the given output device. If
  // |id| is null, we will route to the default output device.
  SetAudioSinkId@17(string? id);

  // Mute or unmute the microphone for a WebRTC session.
  [MinVersion=11] ToggleMicrophone@18();

  // Turn on or off the camera for a WebRTC session.
  [MinVersion=11] ToggleCamera@19();

  // Hang up a WebRTC session.
  [MinVersion=11] HangUp@20();

  // Display the source of the MediaSession (e.g. show the tab or the
  // application).
  [MinVersion=12] Raise@21();

  // Mute or unmute the media player.
  [MinVersion=13] SetMute@22(bool mute);

  // Request Media Remoting once there are available sinks.
  [MinVersion=16] RequestMediaRemoting@23();

  // Go back to previous slide.
  [MinVersion=18] PreviousSlide@24();

  // Go to next slide.
  [MinVersion=18] NextSlide@25();

  // Automatically enter picture-in-picture from a non-user source (e.g. in
  // reaction to content being hidden).
  [MinVersion=19] EnterAutoPictureInPicture@26();

  // Returns whether or not MediaSession has any players that contain a video
  // that is sufficiently visible.
  //
  // A sufficiently visible video is one that meets the visibility threshold
  // defined by |HTMLVideoElement| (kVisibilityThreshold). |HTMLVideoElement|
  // visibility is computed by the |MediaVideoVisibilityTracker|.
  [MinVersion=23] GetVisibility@27() => (bool has_sufficiently_visible_video);

  // Save the current video frame.
  [MinVersion=25] SaveVideoFrame@28();
};