content/browser/media/android/media_session.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_BROWSER_MEDIA_ANDROID_MEDIA_SESSION_H_
   6 #define CONTENT_BROWSER_MEDIA_ANDROID_MEDIA_SESSION_H_
   7
   8 #include <jni.h>
   9
  10 #include "base/android/scoped_java_ref.h"
  11 #include "base/id_map.h"
  12 #include "content/common/content_export.h"
  13 #include "content/public/browser/web_contents_observer.h"
  14 #include "content/public/browser/web_contents_user_data.h"
  15
  16 class MediaSessionBrowserTest;
  17
  18 namespace content {
  19
  20 class MediaSessionObserver;
  21
  22 // MediaSession manages the Android AudioFocus for a given WebContents. It is
  23 // requesting the audio focus, pausing when requested by the system and dropping
  24 // it on demand.
  25 // The audio focus can be of two types: Transient or Content. A Transient audio
  26 // focus will allow other players to duck instead of pausing and will be
  27 // declared as temporary to the system. A Content audio focus will not be
  28 // declared as temporary and will not allow other players to duck. If a given
  29 // WebContents can only have one audio focus at a time, it will be Content in
  30 // case of Transient and Content audio focus are both requested.
  31 // Android system interaction occurs in the Java counterpart to this class.
  32 class CONTENT_EXPORT MediaSession
  33     : public WebContentsObserver,
  34       protected WebContentsUserData<MediaSession> {
  35  public:
  36   enum class Type {
  37     Content,
  38     Transient
  39   };
  40
  41   static bool RegisterMediaSession(JNIEnv* env);
  42
  43   // Returns the MediaSession associated to this WebContents. Creates one if
  44   // none is currently available.
  45   static MediaSession* Get(WebContents* web_contents);
  46
  47   ~MediaSession() override;
  48
  49   // Adds the given player to the current media session. Returns whether the
  50   // player was successfully added. If it returns false, AddPlayer() should be
  51   // called again later.
  52   bool AddPlayer(MediaSessionObserver* observer, int player_id, Type type);
  53
  54   // Removes the given player from the current media session. Abandons audio
  55   // focus if that was the last player in the session.
  56   void RemovePlayer(MediaSessionObserver* observer, int player_id);
  57
  58   // Removes all the players associated with |observer|. Abandons audio focus if
  59   // these were the last players in the session.
  60   void RemovePlayers(MediaSessionObserver* observer);
  61
  62   // Called when the Android system requests the MediaSession to be suspended.
  63   // Called by Java through JNI.
  64   void OnSuspend(JNIEnv* env, jobject obj, jboolean temporary);
  65
  66   // Called when the Android system requests the MediaSession to be resumed.
  67   // Called by Java through JNI.
  68   void OnResume(JNIEnv* env, jobject obj);
  69
  70   // Called when the user requests resuming the session. No-op if the session is
  71   // not controllable.
  72   void Resume();
  73
  74   // Called when the user requests suspending the session. No-op if the session
  75   // is not controllable.
  76   void Suspend();
  77
  78   // Returns if the session can be controlled by Resume() and Suspend calls
  79   // above.
  80   bool IsControllable() const;
  81
  82   // Returns if the session is currently suspended.
  83   bool IsSuspended() const;
  84
  85  private:
  86   friend class content::WebContentsUserData<MediaSession>;
  87   friend class ::MediaSessionBrowserTest;
  88
  89   // Resets the |j_media_session_| ref to prevent calling the Java backend
  90   // during content_browsertests.
  91   void ResetJavaRefForTest();
  92   bool IsActiveForTest() const;
  93   Type audio_focus_type_for_test() const;
  94   void RemoveAllPlayersForTest();
  95
  96   enum class State {
  97     ACTIVE,
  98     SUSPENDED,
  99     INACTIVE
 100   };
 101
 102   enum class SuspendType {
 103     // Suspended by the system because a transient sound needs to be played.
 104     SYSTEM,
 105     // Suspended by the UI.
 106     UI,
 107   };
 108
 109   // Representation of a player for the MediaSession.
 110   struct PlayerIdentifier {
 111     PlayerIdentifier(MediaSessionObserver* observer, int player_id);
 112     PlayerIdentifier(const PlayerIdentifier&) = default;
 113
 114     void operator=(const PlayerIdentifier&) = delete;
 115     bool operator==(const PlayerIdentifier& player_identifier) const;
 116
 117     // Hash operator for base::hash_map<>.
 118     struct Hash {
 119       size_t operator()(const PlayerIdentifier& player_identifier) const;
 120     };
 121
 122     MediaSessionObserver* observer;
 123     int player_id;
 124   };
 125   using PlayersMap = base::hash_set<PlayerIdentifier, PlayerIdentifier::Hash>;
 126
 127   explicit MediaSession(WebContents* web_contents);
 128
 129   // Setup the JNI.
 130   void Initialize();
 131
 132   void OnSuspendInternal(SuspendType type);
 133   void OnResumeInternal(SuspendType type);
 134
 135   // Requests audio focus to Android using |j_media_session_|.
 136   // Returns whether the request was granted. If |j_media_session_| is null, it
 137   // will always return true.
 138   bool RequestSystemAudioFocus(Type type);
 139
 140   // To be called after a call to AbandonAudioFocus() in order to call the Java
 141   // MediaSession if the audio focus really need to be abandoned.
 142   void AbandonSystemAudioFocusIfNeeded();
 143
 144   // Notifies WebContents about the state change of the media session.
 145   void UpdateWebContents();
 146
 147   base::android::ScopedJavaGlobalRef<jobject> j_media_session_;
 148   PlayersMap players_;
 149
 150   State audio_focus_state_;
 151   SuspendType suspend_type_;
 152   Type audio_focus_type_;
 153
 154   DISALLOW_COPY_AND_ASSIGN(MediaSession);
 155 };
 156
 157 }  // namespace content
 158
 159 #endif  // CONTENT_BROWSER_MEDIA_ANDROID_MEDIA_SESSION_H_