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   // Called when the user requests stopping the session.
  79   void Stop();
  80
  81   // Returns if the session can be controlled by Resume() and Suspend calls
  82   // above.
  83   bool IsControllable() const;
  84
  85   // Returns if the session is currently suspended.
  86   bool IsSuspended() const;
  87
  88  private:
  89   friend class content::WebContentsUserData<MediaSession>;
  90   friend class ::MediaSessionBrowserTest;
  91
  92   // Resets the |j_media_session_| ref to prevent calling the Java backend
  93   // during content_browsertests.
  94   void ResetJavaRefForTest();
  95   bool IsActiveForTest() const;
  96   Type audio_focus_type_for_test() const;
  97   void RemoveAllPlayersForTest();
  98
  99   enum class State {
 100     ACTIVE,
 101     SUSPENDED,
 102     INACTIVE
 103   };
 104
 105   enum class SuspendType {
 106     // Suspended by the system because a transient sound needs to be played.
 107     SYSTEM,
 108     // Suspended by the UI.
 109     UI,
 110   };
 111
 112   // Representation of a player for the MediaSession.
 113   struct PlayerIdentifier {
 114     PlayerIdentifier(MediaSessionObserver* observer, int player_id);
 115     PlayerIdentifier(const PlayerIdentifier&) = default;
 116
 117     void operator=(const PlayerIdentifier&) = delete;
 118     bool operator==(const PlayerIdentifier& player_identifier) const;
 119
 120     // Hash operator for base::hash_map<>.
 121     struct Hash {
 122       size_t operator()(const PlayerIdentifier& player_identifier) const;
 123     };
 124
 125     MediaSessionObserver* observer;
 126     int player_id;
 127   };
 128   using PlayersMap = base::hash_set<PlayerIdentifier, PlayerIdentifier::Hash>;
 129
 130   explicit MediaSession(WebContents* web_contents);
 131
 132   // Setup the JNI.
 133   void Initialize();
 134
 135   void OnSuspendInternal(SuspendType type);
 136   void OnResumeInternal(SuspendType type);
 137
 138   // Requests audio focus to Android using |j_media_session_|.
 139   // Returns whether the request was granted. If |j_media_session_| is null, it
 140   // will always return true.
 141   bool RequestSystemAudioFocus(Type type);
 142
 143   // To be called after a call to AbandonAudioFocus() in order to call the Java
 144   // MediaSession if the audio focus really need to be abandoned.
 145   void AbandonSystemAudioFocusIfNeeded();
 146
 147   // Notifies WebContents about the state change of the media session.
 148   void UpdateWebContents();
 149
 150   base::android::ScopedJavaGlobalRef<jobject> j_media_session_;
 151   PlayersMap players_;
 152
 153   State audio_focus_state_;
 154   SuspendType suspend_type_;
 155   Type audio_focus_type_;
 156
 157   DISALLOW_COPY_AND_ASSIGN(MediaSession);
 158 };
 159
 160 }  // namespace content
 161
 162 #endif  // CONTENT_BROWSER_MEDIA_ANDROID_MEDIA_SESSION_H_