[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;
 
+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
 // 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

[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.
   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_