Exposes a shlib interface for media/audio path.

chromecast/public/cast_audio_stream.h

Index: chromecast/public/cast_audio_stream.h
diff --git a/chromecast/public/cast_audio_stream.h b/chromecast/public/cast_audio_stream.h
new file mode 100644
index 0000000000000000000000000000000000000000..00af28e2caa379ecd6e18f423313fd81f7018a62
--- /dev/null
+++ b/chromecast/public/cast_audio_stream.h
@@ -0,0 +1,95 @@
+// 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_STREAM_H_
+#define CHROMECAST_PUBLIC_CAST_AUDIO_STREAM_H_
+
+#include <stdint.h>
+
+#include "chromecast_export.h"
+
+namespace chromecast {
+
+// A simple struct descibing an audio stream, modeled after
+// media::AudioParmameters.

[halliwell, 2015/04/24 15:04:48]

typo: Parameters

[slan, 2015/04/24 16:19:39]

Done.

+// TODO(slan): Add to these as needed.
+struct CHROMECAST_EXPORT 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.
+};
+
+// TODO(slan): This class borrows heavily (er-hem... very heavily) from
+// media::AudioOutputStream. This will be reduced/inflated as needed as
+// dependencies on media/ are broken within externally-facing chromecast
+// interfaces.
+class CHROMECAST_EXPORT CastAudioOutputStream {
+ public:
+  // Audio sources must implement AudioSourceCallback. This interface will be
+  // called in a random thread which very likely is a high priority thread. Do
+  // not rely on using this thread TLS or make calls that alter the thread
+  // itself such as creating Windows or initializing COM.
+  class AudioSourceCallback {
+   public:
+    virtual ~AudioSourceCallback() {}
+
+    // The CastAudioOutputStream calls this to request more data from the
+    // source.
+    // This fills |dest| with |frames| frames of interleaved data. |len| is
+    // the size of |dest| in bytes, and must satisfy the following condition:
+    //
+    //   |len| >= |frames| * (num channels) * (bits per sample) / 8

[halliwell, 2015/04/24 15:04:48]

If we ever had e.g. 20 bit audio, then bits/8 needs rounding up not down.  And
if we explicitly don't support non-multiple-of-8 bit depths, consider enforcing
that by using bytes per sample not bits??

[slan, 2015/04/24 16:19:39]

Good catch. I was making the blind assumption that only multiples of 8 would be
supported. media::AudioBus only natively supports uint8_t, int16_t, and int32_t.

Is there a reasonable case for supporting other bit depths? If not, I will
enforce via bytes_per_sample (which will map [1,2,3] to the respective types
above, as media::AudioBus does).

Please give feedback about use cases.

[halliwell, 2015/04/25 01:34:10]

Someone else probably knows better than me, but based on AudioBus, I'm guessing
Chromium doesn't deal with non-multiple-of-8 bitrates?  Another possibility, if
people like working with bitrates rather than bytes, would just be to have an
assert that bitrate % 8 == 0 so that's documented?

+    //
+    // where bits per sample and channels are properties of the stream.
+    // |total_bytes_delay| contains current number of bytes of delay buffered
+    // by the CastAudioOutputStream. Returns the number of frames successfully
+    // filled.
+    // TODO(slan): Replace these params with an AudioBus-like class.
+    virtual int OnMoreData(void* dest,
+                           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;
+
+    // Called when the stream has been Close()d.
+    virtual void OnClose() = 0;
+  };
+
+  virtual ~CastAudioOutputStream() {}
+
+  // Open the stream. false is returned if the stream cannot be opened.  Open()
+  // must always be followed by a call to Close() even if Open() fails.
+  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.
+  virtual void GetVolume(double* volume) = 0;

[halliwell, 2015/04/24 15:04:48]

Any reason why we don't just return double here?

[slan, 2015/04/24 16:19:39]

No reason. Changed.

+
+  // Close the stream. This also generates AudioSourceCallback::OnClose().
+  // After calling this method, the object should not be used anymore.
+  virtual void Close() = 0;
+};
+
+}  // namespace chromecast
+
+#endif  // CHROMECAST_PUBLIC_CAST_AUDIO_STREAM_H_