audio_focus.mojom | Explore in Territory

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

// Next MinVersion: 10

// These are the different modes the AudioFocusManager can enforce audio focus.
[Stable, 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.
[Stable, 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,

  // Request audio focus for playback can be mixed with other types of audio.
  // It has no effect on other holders of audio focus.
  kAmbient,
};

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

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

// The observer for audio focus events.
// Next method id: 2
[Stable]
interface AudioFocusObserver {
  // The given |session| gained audio focus.
  OnFocusGained@0(AudioFocusRequestState state);

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

  // The given |request_id| will no longer be used. This is the |request_id|
  // attribute of the AudioFocusRequestState struct given in |OnFocusGained()|
  // and |OnFocusLost()|.
  [MinVersion=8] OnRequestIdReleased@2(
      mojo_base.mojom.UnguessableToken request_id);
};

// Controls audio focus for an associated request.
// Next Method ID: 5
// Deprecated method IDs: 3, 4
[Stable]
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);
};

// Controls audio focus across the entire system. After binding
// AudioFocusManager clients should call SetSource to identify themselves to
// the media session service.
// Next Method ID: 9
// Deprecated method IDs: 3
[Stable, Uuid="acb554fd-5b45-4759-8e8e-ad4be348fba8"]
interface AudioFocusManager {
  // Requests audio focus with |type| for the |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 with the id of the request when audio focus has been
  // granted.
  RequestAudioFocus@0(pending_receiver<AudioFocusRequestClient> client,
                      pending_remote<MediaSession> session,
                      MediaSessionInfo session_info,
                      AudioFocusType type) =>
                          (mojo_base.mojom.UnguessableToken request_id);

  // Requests audio focus with |type| for the |session| with |session_info|.
  // Media sessions should provide a |request| that will provide an
  // AudioFocusRequestClient that can be used to control this request.
  // |request_id| should be generated by the client and should be unique. If it
  // is not valid then the request will fail. |group_id| is used for grouping
  // sessions together. This is when a group of sessions will share audio focus.
  // Returns whether the request succeeded.
  [MinVersion=4] RequestGroupedAudioFocus@4(
      mojo_base.mojom.UnguessableToken request_id,
      pending_receiver<AudioFocusRequestClient> client,
      pending_remote<MediaSession> session,
      MediaSessionInfo session_info,
      AudioFocusType type,
      mojo_base.mojom.UnguessableToken group_id) => (bool success);

  // 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(pending_remote<AudioFocusObserver> observer);

  // Associates a source with this binding. This will be associated with all
  // audio focus requests made with this binding and we expect that this should
  // be called at most once per binding. The |identity| will be used for
  // filtering requests from the same context (e.g. profile). The |name| will
  // be used for associating metrics to a source. If the source is updated then
  // the audio focus requests will retain the previous source name.
  [MinVersion=6] SetSource@6(
      mojo_base.mojom.UnguessableToken identity, string name);

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

  // Adds observers that receive audio focus events only for their associated
  // source.
  [MinVersion=7] AddSourceObserver@7(
      mojo_base.mojom.UnguessableToken source_id,
      pending_remote<AudioFocusObserver> observer);

  // Gets all the information about all |MediaSessions| that have requested
  // audio focus and their current requested type for the given source.
  [MinVersion=7] GetSourceFocusRequests@8(
      mojo_base.mojom.UnguessableToken source_id)
          => (array<AudioFocusRequestState> requests);

  // Informs the AudioFocusManager that the given request ID will no longer be
  // used. This is the |request_id| provided by the client in
  // |RequestGroupedAudioFocus()|.
  [MinVersion=8] RequestIdReleased@9(
      mojo_base.mojom.UnguessableToken request_id);
};

// Provides debug information about audio focus requests.
// Next method id: 1
[Stable, Uuid="c3b8b522-9a66-49cf-881b-c5fd19391b76"]
interface AudioFocusManagerDebug {
  // Gets debugging information for a |MediaSession| with |request_id|.
  GetDebugInfoForRequest@0(mojo_base.mojom.UnguessableToken request_id)
      => (MediaSessionDebugInfo debug_info);
};
chromium/services/media_session/public/mojom/audio_focus.mojom
