Exposes a shlib interface for media/audio path.

chromecast/public/cast_audio_output_stream.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_AUDIO_OUTPUT_STREAM_H_
+#define CHROMECAST_PUBLIC_CAST_AUDIO_OUTPUT_STREAM_H_
+
+#include <stdint.h>
+
+#include "chromecast_export.h"
+
+namespace chromecast {
+namespace media {
+
+// A simple struct describing an audio stream.
+struct AudioParameters {
+  int sample_rate;        // Sampling frequency/rate.
+  int bits_per_sample;    // Number of bits per sample.
+  int frames_per_buffer;  // Number of frames in a buffer.
+  int channels;           // Number of channels.
+
+  static const int kMaxSampleRate = 192000;
+  static const int kMaxBitsPerSample = 32;
+  static const int kMaxFramesPerBuffer = kMaxSampleRate;
+  static const int kMaxChannels = 32;  // The maximum number of channels.
+};
+
+// This is an interface for a Cast audio output stream. Implementations of this
+// interface are responsible for making calls to an AudioSourceCallback, which
+// is not owned by this class, and which must outlive it.

[gunsch, 2015/07/29 17:22:37]

Let's keep guidance in public APIs to vendor implementations. "Must outlive it"
is our responsibility, not vendor's.

[slan, 2015/07/29 19:51:55]

Done.

+class CastAudioOutputStream {
+ public:
+  // Audio sources must implement AudioSourceCallback. Calls to this interface

[gunsch, 2015/07/29 17:22:36]

Same here, I think this is guidance to us, not the vendor.

[slan, 2015/07/29 19:51:55]

The vendor code is calling the interface from their implementation. (For
example, when their stream impl needs more data, it should know if it is safe to
call this interface on any thread).

+  // must be made on the same thread on which the stream object is created.

[gunsch, 2015/07/29 17:22:37]

Note: Byungchul recently rewrote the other shlibs such that vendor shlib can
invoke our callbacks from any thread. Can we keep that property here?

[slan, 2015/07/29 19:51:55]

Discussed this offline.

Because |dest| is an "out" param, allowing any thread to call this would require
changing this to something like:

class CastAudioOutputStream {
 public:
  class AudioSourceCallback {
   public:
    ...
    void RequestMoreData(int frames, int delay) = 0;
  }
  ...

  void PushData(void* src, int actual_frames) = 0;
}

(Or we could pass in a function pointer as a callback to RequestMoreData())

It seems easier and cleaner to clearly define the threading model, and verify
that it is being used correctly via DCHECKs on the cast_shell side and
compliance tests.

+  class AudioSourceCallback {
+   public:
+    virtual ~AudioSourceCallback() {}
+
+    // The CastAudioOutputStream calls this to request more data from the
+    // source. This method fills |dest| with |frames| frames of interleaved
+    // data, which takes the following struture for N channels:
+    //
+    //   [ch0, ch1, ..., chN, ch0, ch1, ..., chN, ...]
+    //   |<---- Frame 0 ---->|<---- Frame 1 ---->|...|
+    //
+    // |len| is the size of |dest| in bytes, and must satisfy the following:
+    //
+    //   |len| >= |frames| * (num channels) * (bytes per sample)
+    //
+    // where bytes per sample and channels are properties of the stream. These
+    // can be detemined through GetParameters(). |total_bytes_delay| contains
+    // the current number of bytes of delay buffered by the
+    // CastAudioOutputStream. Returns the number of frames successfully filled.
+    virtual int OnMoreData(void* dest,

[gunsch, 2015/07/29 17:22:37]

naming: GetMoreData?

[slan, 2015/07/29 19:51:55]

Done.

+                           uint32_t len,
+                           int32_t frames,
+                           uint32_t total_bytes_delay) = 0;
+
+    // There was an error while playing a buffer. Audio source cannot be
+    // destroyed yet. No direct action needed by the AudioStream, but it is
+    // a good place to stop accumulating sound data since is is likely that
+    // playback will not continue.
+    virtual void OnError(CastAudioOutputStream* stream) = 0;
+  };
+
+  virtual ~CastAudioOutputStream() {}
+
+  // Returns the parameters describing the stream.
+  virtual const AudioParameters GetParameters() const = 0;
+
+  // Open the stream. A call to this method must always be followed by a call to
+  // Close() even if Open() fails. This method may block the caller's thread.
+  virtual bool Open() = 0;
+
+  // Starts playing audio and generating AudioSourceCallback::OnMoreData().
+  // Since implementor of CastAudioOutputStream may have internal buffers, right
+  // after calling this method initial buffers are fetched.
+  //
+  // The output stream does not take ownership of this callback.
+  virtual void Start(AudioSourceCallback* callback) = 0;
+
+  // Stops playing audio. Effect might not be instantaneous as the hardware
+  // might have locked audio data that is processing.
+  virtual void Stop() = 0;
+
+  // Sets the relative volume, with range [0.0, 1.0] inclusive.
+  virtual void SetVolume(double volume) = 0;
+
+  // Gets the relative volume, with range [0.0, 1.0] inclusive. This method may
+  // be .
+  virtual double GetVolume() = 0;
+
+  // Close the stream. This also generates AudioSourceCallback::OnClose().
+  // After calling this method, the object should not be used anymore. Like all
+  // other methods, this must be made on the same thread on which the stream was
+  // created.
+  virtual void Close() = 0;
+};
+
+}  // namespace media
+}  // namespace chromecast
+
+#endif  // CHROMECAST_PUBLIC_CAST_AUDIO_OUTPUT_STREAM_H_