services/media_session/controlling_media_playback.md

   1 # Controlling Media Playback
   2
   3 A media session is a single abstract representation of a single playing source
   4 in the Chrome ecosystem. This could be something like an ARC++ app or a browser
   5 tab.
   6
   7 Sessions request audio focus from the media session service and the service
   8 maintains a connection to each media session on the platform. This can be used
   9 to receive metadata and control media playback in a unified way on Chrome.
  10
  11 # Audio Focus
  12
  13 When audio focus is enabled all the different media sessions will request audio
  14 focus. A media session can request three different types of audio focus:
  15
  16 * Gain - If a gain session acquires focus then all other sessions will stop
  17   playing and will not be resumed even when the session is destroyed. In most
  18   cases, this is the type that will be used.
  19 * Gain Transient - If a transient session acquires focus then all other sessions
  20   will stop playing, but will be resumed when that session is destroyed. This is
  21   used for temporary playbacks.
  22 * Gain Transient May Duck - If a ducking session acquires focus then all other
  23   sessions will continue playing but at a reduced volume. When that session is
  24   destroyed it will continue at the previous volume. This is used for short
  25   sounds e.g. notifications.
  26
  27 Each WebContents (tab) in Chrome has it's own media session and will request
  28 Gain audio focus in most cases. If the media is only a few seconds then it will
  29 request the ducking focus type.
  30
  31 In ARC++ each app can make audio focus requests using the Android Audio Manager
  32 API. Each of these requests is a media session in Chrome and can be any one of
  33 the three above audio focus types.
  34
  35 To reduce the impact of single session audio focus we currently have grouping
  36 enabled. By default, all media sessions will have a unique "group id". All
  37 browser media session have the same group id. When a session acquires focus it
  38 will not pause any other session with the same group id. Likewise, if playback
  39 is resumed automatically all sessions with the same group id will be resumed.
  40 This allows all the browser tabs to share audio focus and play concurrently, but
  41 still behave as individual media sessions. Ducking is unaffected by group ids.
  42
  43 # Active Media Session
  44
  45 The active media session is the session that would be controlled if there is a
  46 user action (e.g. pressing the play/pause key on a keyboard). Part of the state
  47 that the media session exposes is `is_controllable`. If this boolean is true
  48 then the media session can be controlled by the user. The active media session
  49 will be the top most controllable media session.
  50
  51 # Audio Focus Observer
  52
  53 The media session service can be accessed via Mojo and currently lives in the
  54 browser process. Clients can implement [AudioFocusObserver](https://cs.chromium.org/chromium/src/services/media_session/public/mojom/media_session.mojom)
  55 and add themselves as an observer using the [AudioFocusManager](https://cs.chromium.org/chromium/src/services/media_session/public/mojom/media_session.mojom)
  56 mojo API. The observer will then receive notifications when the active media
  57 session changes. This can be used to determine whether there is any current
  58 media playback.
  59
  60 # Media Controller Manager
  61
  62 The media session service also exposes a [MediaControllerManager](https://cs.chromium.org/chromium/src/services/media_session/public/mojom/media_controller.mojom)
  63 mojo API. This can be used to create a [MediaController](https://cs.chromium.org/chromium/src/services/media_session/public/mojom/media_controller.mojom)
  64 instance. These can be used to control and observe a media session. This can
  65 be an individual media session or the active media session.
  66
  67 If the controller is created using `CreateActiveMediaController` then it will
  68 follow the active media session. This means you do not need to create a new
  69 media controller if the active media session changes.
  70
  71 **There is also a MediaSession mojo API. This is used for session / service
  72 communication and should not be used for control.**.
  73
  74 # Media Session Observer
  75
  76 There is also a [MediaSessionObserver](https://cs.chromium.org/chromium/src/services/media_session/public/mojom/media_session.mojom)
  77 mojo API that clients can implement. They can then add themselves as an observer
  78 using the `AddObserver` call on the `MediaController` api. When an observer is
  79 added it will be flushed with all the latest information from the currently
  80 active media session.
  81
  82 Again, this will automatically route to the active media session. If that
  83 changes then we will flush all methods on the observer with the information from
  84 the new active media session.
  85
  86 # Testing
  87
  88 There is a [MockMediaSession](https://cs.chromium.org/chromium/src/services/media_session/public/cpp/test/mock_media_session.h)
  89 C++ class that can be used for simulating a media session in unit tests. The
  90 [//services/media_session/public/cpp/test](https://cs.chromium.org/chromium/src/services/media_session/public/cpp/test/)
  91 directory also contains a number of other useful test utilities.
  92
  93 # Current Media Session service integrations
  94
  95 The following clients are integrated with the media session service and expose
  96 a media session and request audio focus:
  97
  98 * content::WebContents
  99 * ARC++ apps (requires Android Pie)
 100 * Assistant
 101
 102 Questions? - Feel free to reach out to beccahughes@chromium.org.