Exposes a shlib interface for media/audio path.

chromecast/public/cast_audio_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_STREAM_H_

[gunsch, 2015/04/27 16:09:11]

filename should match class name

[slan, 2015/04/28 00:11:39]

Done.

+#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::AudioParameters.

[byungchul, 2015/04/27 17:38:06]

This file is for oem partners, and supposed to be harder to change api once it
is released. The comment should be self-contained.

[slan, 2015/04/28 00:11:39]

Done.

+// TODO(slan): Add to these as needed.
+struct CHROMECAST_EXPORT AudioParameters {

[byungchul, 2015/04/27 17:38:06]

CHROMECAST_EXPORT not necessary.

[slan, 2015/04/28 00:11:39]

Done.

+  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 {

[byungchul, 2015/04/27 17:38:06]

CHROMECAST_EXPORT not necessary.

[slan, 2015/04/28 00:11:39]

Done.

+ 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 {

[byungchul, 2015/04/27 17:38:06]

What is thread model here? Do we allow callback functions called on a different
thread? Please specify what is allowed and what is not.

[slan, 2015/04/28 00:11:39]

Done.

+   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
+    //
+    // 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,

[byungchul, 2015/04/27 17:38:06]

is void* enough to explain how dest will be filled?

[slan, 2015/04/28 00:11:39]

Documentation added explaining interleaved format.

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

[byungchul, 2015/04/27 17:38:06]

Do we allow this function block the thread?

[slan, 2015/04/28 00:11:39]

I think this call should be able to block the audio thread. Otherwise, the
control flow is misleading. Documentation added.

+
+  // 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.

[byungchul, 2015/04/27 17:38:06]

Do we allow this function blocking the thread?

[slan, 2015/04/28 00:11:39]

This one should block as well. Documentation added.

+  virtual double GetVolume() = 0;
+
+  // 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_