// Copyright 2018 The Chromium Authors. All rights reserved.
// 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/mojo/geometry.mojom";
import "url/mojom/url.mojom";

// Next MinVersion: 4

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

[Extensible]
enum MediaSessionAction {
  kPlay,
  kPause,
  kPreviousTrack,
  kNextTrack,
  kSeekBackward,
  kSeekForward,
  kSkipAd,
  kStop,
};

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

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

// MediaMetadata
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;

  // TODO(beccahughes): Remove this
  array<MediaImage> artwork;

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

// Contains state information about a MediaSession.
struct MediaSessionInfo {
  [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;
};

// Contains debugging information about a MediaSession. This will be displayed
// on the Media Internals WebUI.
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: 4
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);
};

// A MediaSession manages the media session and audio focus for a given
// WebContents or ARC app.
// TODO(https://crbug.com/875004): migrate media session from content/public
// to mojo.
// Next Method ID: 12
interface MediaSession {
  [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(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. 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();
};