[Chromecast] Add new volume control API to CastMediaShlib

chromecast/public/cast_media_shlib.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CHROMECAST_PUBLIC_CAST_MEDIA_SHLIB_H_
 #define CHROMECAST_PUBLIC_CAST_MEDIA_SHLIB_H_
 
 #include <stdint.h>
 
 #include <string>
 #include <vector>
 
 #include "chromecast_export.h"
 
 namespace chromecast {
 namespace media {
 
 enum SampleFormat : int;
 
 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
 // API calls will be made except for Initialize, which brings the implementation
 // into an initialized state.  A call to Finalize returns the implementation to
 // its uninitialized state.  The implementation must support multiple
 // 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.
   class LoopbackAudioObserver {
    public:
     // Called whenever audio data is about to be output. The |timestamp| is the
     // estimated time in microseconds (relative to CLOCK_MONOTONIC_RAW) that
     // the audio will actually be output. |length| is the length of the audio
     // |data| in bytes. The format of the data is given by |sample_format| and
     // |num_channels|.
@@ skipping 69 matching lines @@
   // being added again first.
   // Once the observer is fully removed (ie. once it is certain that
   // OnLoopbackAudio() will not be called again for the observer), the
   // observer's OnRemoved() method must be called. The OnRemoved() method must
   // be called once for each time that RemoveLoopbackAudioObserver() is called
   // for a given observer, even if the observer was not added. The
   // implementation may call OnRemoved() from any thread.
   // 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
 }  // namespace chromecast
 
 #endif  // CHROMECAST_PUBLIC_CAST_MEDIA_SHLIB_H_