[Chromecast] Add new volume control API to CastMediaShlib

chromecast/public/cast_media_shlib.h

Index: chromecast/public/cast_media_shlib.h
diff --git a/chromecast/public/cast_media_shlib.h b/chromecast/public/cast_media_shlib.h
index 430b0065ffa815d2d474f0982accf4b5b6051424..be552e734e092e27489a63bdf1d9e6deb3372469 100644
--- a/chromecast/public/cast_media_shlib.h
+++ b/chromecast/public/cast_media_shlib.h
@@ -21,6 +21,29 @@ class MediaPipelineBackend;
 struct MediaPipelineDeviceParams;
 class VideoPlane;
 
+enum class AudioContentType {
+  kMedia,

[alokp, 2017/02/24 17:34:26]

Add comments about what they mean.

Should we rename kTts to kCommunication to make it more generic.

[kmackay, 2017/02/24 19:01:06]

Done.

+  kAlarm,
+  kTts,
+};
+
+// Observer for volume/mute state changes. This is useful to detect volume
+// changes that occur outside of cast_shell. Add/RemoveVolumeObserver() must not
+// be called synchronously from OnVolumeChange() or OnMuteChange().
+class VolumeObserver {
+ public:
+  // Called whenever the volume changes for a given stream |type|. May be called
+  // on an arbitrary thread.
+  virtual void OnVolumeChange(AudioContentType type, float new_volume) = 0;
+
+  // Called whenever the mute state changes for a given stream |type|. May be
+  // called on an arbitrary thread.
+  virtual void OnMuteChange(AudioContentType type, bool new_muted) = 0;
+
+ protected:
+  virtual ~VolumeObserver() = default;
+};
+
 // Provides access to platform-specific media systems and hardware resources.
 // In cast_shell, all usage is from the browser process.  An implementation is
 // assumed to be in an uninitialized state initially.  When uninitialized, no
@@ -30,6 +53,13 @@ class VideoPlane;
 // transitions between these states, to support resource grant/revoke events and
 // also to allow multiple unit tests to bring up the media systems in isolation
 // from other tests.
+//
+// Volume control must run separately since it needs to be functional even when

[alokp, 2017/02/24 17:34:26]

It seems clunky to have a separate Initialize/Finalize for volume specifically.
What is the concern with using the existing Initialize/Finalize? It is not clear
from the comment.

[kmackay, 2017/02/24 19:01:06]

I added more detail to the comment.

+// resources are revoked. Initialize() and Finalize() have no impact on the
+// volume control API; instead, InitializeVolume() is called to initialize the
+// volume control (before any volume control API methods are called), and
+// FinalizeVolume() is called to clean up the volume control. All volume control
+// methods are called on the same thread that calls InitializeVolume().
 class CHROMECAST_EXPORT CastMediaShlib {
  public:
   // Observer for audio loopback data.
@@ -119,6 +149,49 @@ class CHROMECAST_EXPORT CastMediaShlib {
   // This function is optional to implement.
   static void RemoveLoopbackAudioObserver(LoopbackAudioObserver* observer)
       __attribute__((__weak__));
+
+  // Initializes platform-specific volume control. Only called when volume
+  // control is in an uninitialized state.
+  static void InitializeVolume(const std::vector<std::string>& argv)
+      __attribute__((__weak__));
+
+  // Tears down platform-specific volume control and returns to the
+  // uninitialized state.
+  static void FinalizeVolume() __attribute__((__weak__));
+
+  // Adds a volume observer.
+  static void AddVolumeObserver(VolumeObserver* observer)
+      __attribute__((__weak__));
+  // Removes a volume observer. After this is called, the implementation must
+  // not call any more methods on the observer.
+  static void RemoveVolumeObserver(VolumeObserver* observer)
+      __attribute__((__weak__));
+
+  // Gets/sets the output volume for a given audio stream |type|. The volume
+  // |level| is in the range [0.0, 1.0].
+  static float GetVolume(AudioContentType type) __attribute__((__weak__));
+  static void SetVolume(AudioContentType type, float level)
+      __attribute__((__weak__));
+
+  // Gets/sets the mute state for a given audio stream |type|.
+  static bool IsMuted(AudioContentType type) __attribute__((__weak__));
+  static void SetMuted(AudioContentType type, bool muted)
+      __attribute__((__weak__));
+
+  // Limits the output volume for a given stream |type| to no more than |limit|.
+  // This does not affect the logical volume for the stream type; the volume
+  // returned by GetVolume() should not change, and no OnVolumeChange() event
+  // should be sent to observers.
+  static void SetOutputLimit(AudioContentType type, float limit)
+      __attribute__((__weak__));
+
+  // Converts a volume level in the range [0.0, 1.0] to/from a volume in dB.
+  // The volume in dB should be decibels SPL at 1m from the device; if that
+  // is not known, then the volume in dB should be full-scale (so a volume level
+  // of 1.0 would be 0.0 dBFS, and any lower volume level would be negative).
+  // May be called from multiple processes.
+  static float VolumeToDb(float volume) __attribute__((__weak__));
+  static float DbToVolume(float db) __attribute__((__weak__));
 };
 
 }  // namespace media