Skip to content

Latest commit

 

History

History
98 lines (71 loc) · 4.13 KB

audio_focus.md

File metadata and controls

98 lines (71 loc) · 4.13 KB
Raw

Audio Focus Handling

A MediaSession collects all audio-producing objects in one tab. It is usually unpleasant when multiple MediaSessions play sound at the same time. Audio focus handling manages the MediaSessions and mixes them in proper ways. This is part of the default media session on desktop project.

[TOC]

Processing model

Audio focus types

There are "persistent" and "transient" audio focus types.

  • Persistent audios are used for long media playback, and they should not mix with each other. When they start to play, they should pause all other playbacks.
  • Transient audios are used for short media playback such as a ping for incoming message. When they start to play, they should play on top of other playbacks and the other playbacks should duck (have reduced volume).

MediaSession

Audio-producing objects should join MediaSession when they want to produce sound. MediaSession has the following states:

  • ACTIVE: the MediaSession has audio focus and its audio-producing objects can play.
  • SUSPENDED: the MediaSession does not have audio focus. All audio-producing objects are paused and can be resumed when the session gains audio focus.
  • INACTIVE: the MediaSession does not have audio focus, and there is no audio-producing objects in this MediaSession.

Besides, MediaSession has a DUCKING flag, which means its managed audio-producing objects has lowered volume. The flag is orthogonal with MediaSession state.

AudioFocusManager

AudioFocusManager is a global instance which manages the state of MediaSessions. It is used for platforms (e.g. Android) that do not have a system audio focus.

When an audio-producing object wants to play audio, it should join MediaSession and tell which kind of audio focus type it requires. MediaSession will then request audio focus from AudioFocusManager, and will allow the object to play sound if successful. AudioFocusManager will notify other MediaSessions if their states are changed.

When an audio-producing object stops playing audio, it should be removed from its MediaSession, and MediaSession should abandon its audio focus if its audio-producing objects is empty. AudioFocusManager will notify other MediaSessions of state change if necessary.

The algorithm for handling audio focus

AudioFocusManager uses a stack implementation. It keeps track of all ACTIVE/SUSPENDED MediaSessions. When a MediaSession requests audio focus, it will be put at the top of the stack, and will be removed from the stack when it abandons audio focus.

The algorithm is as follows:

  • When a MediaSession requests audio focus:

    • Remove it from the audio focus stack if it's already there, and place it at the top of audio focus stack, grant focus to the session and let it play.

    • If the session is persistent, suspend all the other sessions on the stack.

    • If the session is transient, we should duck any active persistent audio focus entry if present:

      • If the next top entry is transient, do nothing, since if there is any persistent session that is active, it is already ducking.
      • If the next top entry is persistent, let the next top entry start ducking, since it is the only active persistent session.

  • When a MediaSession abandons audio focus:

    • If the session is not on the top, just remove it from the stack.

    • If the session is on the top, remove it from the stack.

      • If the stack becomes empty, do nothing.
      • If the next top session is transient, do nothing.
      • If the next top session is persistent, stop ducking it.

Handling Pepper

Pepper is different from media elements since it has a different model. Pepper cannot be paused, but its volume can be changed. When considering Pepper, the above algorithm must be modified.

When Pepper joins MediaSession, it should request persistent focus type. When AudioFocusManager wants to suspend a MediaSession, it must check whether the session has Pepper instance, and if yes, it should duck the session instead.

Also, whenever a session abandons focus, and the next top session is INACTIVE, AudioFocusManager should find the next session having Pepper and unduck it.