[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..f06b161553cc00aa7ae73adf08b291d6a8cf7dd2 100644
--- a/chromecast/public/cast_media_shlib.h
+++ b/chromecast/public/cast_media_shlib.h
@@ -21,6 +21,31 @@ class MediaPipelineBackend;
 struct MediaPipelineDeviceParams;
 class VideoPlane;
 
+// Audio content types for volume control. Each content type has a separate
+// volume and mute state.
+enum class AudioContentType {
+  kMedia,          // Normal audio playback; also used for system sound effects.
+  kAlarm,          // Alarm sounds.
+  kCommunication,  // Voice communication, eg assistant TTS.
+};
+
+// 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 +55,15 @@ 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
+// resources are revoked; since Finalize() is called when resources are revoked,
+// and we need volume control to keep working, we need separate initialization.
+// Therefore, 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().

[halliwell, 2017/02/24 21:37:21]

This is kind of clumsy.  Would it be clearer just to make a new class for the
volume functions with its own init/finalize?

[kmackay, 2017/02/24 23:53:29]

Maybe? But the new class would probably ideally live in the same shlib, since
the volume control relates to the content_type passed in
MediaPipelineBackendParams - so it's a lot easier to implement if both are in
the same shlib.

[halliwell, 2017/02/25 00:43:46]

Yep, agreed, keeping in same shared lib makes sense.  It doesn't necessarily
stop us having another class, e.g. CastMediaVolume, implemented in the same
shlib.  We already have other classes (e.g. VideoPlane) in the same lib.  What
do you think?

[kmackay, 2017/02/25 02:01:08]

Sure, sounds fine to me

[kmackay, 2017/02/25 05:57:02]

I wouldn't implement it like VideoPlane though; I think the "static weak method"
model is a lot better than the "abstract class" method for shlib APIs, since it
allows us to add new methods without requiring a system update. That means that
the new CastMediaVolume class won't have any obvious ties to the CastMediaShlib
class.

[kmackay, 2017/02/26 21:16:42]

Done.

 class CHROMECAST_EXPORT CastMediaShlib {
  public:
   // Observer for audio loopback data.
@@ -119,6 +153,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