// 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/unguessable_token.mojom";
import "services/media_session/public/mojom/media_session.mojom";

// Next MinVersion: 6

// These are the different modes the AudioFocusManager can enforce audio focus.
[Extensible]
enum EnforcementMode {
  // This will default to whatever enforcement mode is configured through
  // feature flags.
  kDefault,

  // This will allow all sessions to play, without the enforcement of a single
  // media session.
  kNone,

  // This will enforce that all media sessions playing have the same audio
  // focus group id. If a session gains focus then all other sessions with
  // a different group id will be ducked/paused. Any session with the same
  // group id will be ignored.
  kSingleGroup,

  // This will enforce that only one media session can be playing at any
  // one time.
  kSingleSession,
};

// These are the different types of audio focus that can be requested.
[Extensible]
enum AudioFocusType {
  // Request permanent audio focus when you plan to play audio for the
  // foreseeable future (for example, when playing music) and you expect the
  // previous holder of audio focus to stop playing.
  kGain,

  // Request transient focus with ducking to indicate that you expect to play
  // audio for only a short time and that it's OK for the previous focus owner
  // to keep playing if it "ducks" (lowers) its audio output.
  kGainTransientMayDuck,

  // Request transient focus when you expect to play audio for only a short
  // time and you expect the previous holder to pause playing.
  kGainTransient,
};

// Contains information about |MediaSessions| that have requested audio focus
// and their current requested type.
struct AudioFocusRequestState {
  MediaSessionInfo session_info;
  AudioFocusType audio_focus_type;

  [MinVersion=2] string? source_name;
  [MinVersion=3] mojo_base.mojom.UnguessableToken? request_id;
};

// The observer for audio focus events.
interface AudioFocusObserver {
  // The given |session| gained audio focus.
  OnFocusGained(AudioFocusRequestState state);

  // The given |session| lost audio focus.
  OnFocusLost(AudioFocusRequestState state);

  // The currently active session changed. The active session is the top most
  // session that is not temporary. This is the session that will be associated
  // with the MediaController interface. If all the media sessions have ended
  // then |session| will be null.
  OnActiveSessionChanged(AudioFocusRequestState? session);
};

// Controls audio focus for an associated request.
// Next Method ID: 5
// Deprecated method IDs: 3
interface AudioFocusRequestClient {
  // Requests updated audio focus for this request. If the request was granted
  // then the callback will resolve.
  RequestAudioFocus@0(MediaSessionInfo session_info, AudioFocusType type) => ();

  // Abandons audio focus for this request.
  AbandonAudioFocus@1();

  // Notifies the audio focus backend when the associated session info changes.
  MediaSessionInfoChanged@2(MediaSessionInfo session_info);

  // Retrieve a unique ID for this request.
  [MinVersion=3] GetRequestId@4()
      => (mojo_base.mojom.UnguessableToken request_id);
};

// Controls audio focus across the entire system.
// Next Method ID: 6
interface AudioFocusManager {
  // Requests audio focus with |type| for the |media_session| with
  // |session_info|. Media sessions should provide a |request| that will
  // provide an AudioFocusRequestClient that can be used to control this
  // request. The callback will resolve when audio focus has been granted.
  RequestAudioFocus@0(AudioFocusRequestClient& client,
                      MediaSession media_session,
                      MediaSessionInfo session_info,
                      AudioFocusType type) => ();

  // Requests audio focus as above but with a |group_id| that is used for
  // grouping sessions together. This is when a group of media sessions
  // will share audio focus.
  [MinVersion=4] RequestGroupedAudioFocus@4(
      AudioFocusRequestClient& client,
      MediaSession media_session,
      MediaSessionInfo session_info,
      AudioFocusType type,
      mojo_base.mojom.UnguessableToken group_id) => ();

  // Gets all the information about all |MediaSessions| that have requested
  // audio focus and their current requested type.
  GetFocusRequests@1() => (array<AudioFocusRequestState> requests);

  // Adds observers that receive audio focus events.
  AddObserver@2(AudioFocusObserver observer);

  // Associates a name with this binding. This will be associated with all
  // audio focus requests made with this binding. It will also be used for
  // associating metrics to a source. If the source name is updated then
  // the audio focus requests will retain the previous source name.
  [MinVersion=2] SetSourceName@3(string name);

  // Sets the enforcement mode for the Audio Focus Manager.
  [MinVersion=5] SetEnforcementMode@5(EnforcementMode mode);
};

// Provides debug information about audio focus requests.
interface AudioFocusManagerDebug {
  // Gets debugging information for a |MediaSession| with |request_id|.
  GetDebugInfoForRequest(mojo_base.mojom.UnguessableToken request_id)
      => (MediaSessionDebugInfo debug_info);
};