audio_io.h revision ab8f6f0bd665d3c1ff476eb06c58c42630e462d4 
1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef MEDIA_AUDIO_AUDIO_IO_H_
6#define MEDIA_AUDIO_AUDIO_IO_H_
7
8#include "base/basictypes.h"
9#include "media/audio/audio_buffers_state.h"
10#include "media/base/audio_bus.h"
11
12// Low-level audio output support. To make sound there are 3 objects involved:
13// - AudioSource : produces audio samples on a pull model. Implements
14//   the AudioSourceCallback interface.
15// - AudioOutputStream : uses the AudioSource to render audio on a given
16//   channel, format and sample frequency configuration. Data from the
17//   AudioSource is delivered in a 'pull' model.
18// - AudioManager : factory for the AudioOutputStream objects, manager
19//   of the hardware resources and mixer control.
20//
21// The number and configuration of AudioOutputStream does not need to match the
22// physically available hardware resources. For example you can have:
23//
24//  MonoPCMSource1 --> MonoPCMStream1 --> |       | --> audio left channel
25//  StereoPCMSource -> StereoPCMStream -> | mixer |
26//  MonoPCMSource2 --> MonoPCMStream2 --> |       | --> audio right channel
27//
28// This facility's objective is mix and render audio with low overhead using
29// the OS basic audio support, abstracting as much as possible the
30// idiosyncrasies of each platform. Non-goals:
31// - Positional, 3d audio
32// - Dependence on non-default libraries such as DirectX 9, 10, XAudio
33// - Digital signal processing or effects
34// - Extra features if a specific hardware is installed (EAX, X-fi)
35//
36// The primary client of this facility is audio coming from several tabs.
37// Specifically for this case we avoid supporting complex formats such as MP3
38// or WMA. Complex format decoding should be done by the renderers.
39
40
41// Models an audio stream that gets rendered to the audio hardware output.
42// Because we support more audio streams than physically available channels
43// a given AudioOutputStream might or might not talk directly to hardware.
44// An audio stream allocates several buffers for audio data and calls
45// AudioSourceCallback::OnMoreData() periodically to fill these buffers,
46// as the data is written to the audio device. Size of each packet is determined
47// by |samples_per_packet| specified in AudioParameters  when the stream is
48// created.
49
50namespace media {
51
52class MEDIA_EXPORT AudioOutputStream {
53 public:
54  // Audio sources must implement AudioSourceCallback. This interface will be
55  // called in a random thread which very likely is a high priority thread. Do
56  // not rely on using this thread TLS or make calls that alter the thread
57  // itself such as creating Windows or initializing COM.
58  class MEDIA_EXPORT AudioSourceCallback {
59   public:
60    // Provide more data by fully filling |dest|.  The source will return
61    // the number of frames it filled.  |buffers_state| contains current state
62    // of the buffers, and can be used by the source to calculate delay.
63    virtual int OnMoreData(AudioBus* dest,
64                           AudioBuffersState buffers_state) = 0;
65
66    // There was an error while playing a buffer. Audio source cannot be
67    // destroyed yet. No direct action needed by the AudioStream, but it is
68    // a good place to stop accumulating sound data since is is likely that
69    // playback will not continue.
70    virtual void OnError(AudioOutputStream* stream) = 0;
71
72   protected:
73    virtual ~AudioSourceCallback() {}
74  };
75
76  virtual ~AudioOutputStream() {}
77
78  // Open the stream. false is returned if the stream cannot be opened.  Open()
79  // must always be followed by a call to Close() even if Open() fails.
80  virtual bool Open() = 0;
81
82  // Starts playing audio and generating AudioSourceCallback::OnMoreData().
83  // Since implementor of AudioOutputStream may have internal buffers, right
84  // after calling this method initial buffers are fetched.
85  //
86  // The output stream does not take ownership of this callback.
87  virtual void Start(AudioSourceCallback* callback) = 0;
88
89  // Stops playing audio. Effect might not be instantaneous as the hardware
90  // might have locked audio data that is processing.
91  virtual void Stop() = 0;
92
93  // Sets the relative volume, with range [0.0, 1.0] inclusive.
94  virtual void SetVolume(double volume) = 0;
95
96  // Gets the relative volume, with range [0.0, 1.0] inclusive.
97  virtual void GetVolume(double* volume) = 0;
98
99  // Close the stream. This also generates AudioSourceCallback::OnClose().
100  // After calling this method, the object should not be used anymore.
101  virtual void Close() = 0;
102};
103
104// Models an audio sink receiving recorded audio from the audio driver.
105class MEDIA_EXPORT AudioInputStream {
106 public:
107  class MEDIA_EXPORT AudioInputCallback {
108   public:
109    // Called by the audio recorder when a full packet of audio data is
110    // available. This is called from a special audio thread and the
111    // implementation should return as soon as possible.
112    // TODO(henrika): should be pure virtual when old OnData() is phased out.
113    virtual void OnData(AudioInputStream* stream,
114                        const AudioBus* source,
115                        uint32 hardware_delay_bytes,
116                        double volume) {};
117
118    // TODO(henrika): don't use; to be removed.
119    virtual void OnData(AudioInputStream* stream,
120                        const uint8* src,
121                        uint32 size,
122                        uint32 hardware_delay_bytes,
123                        double volume) {};
124
125    // There was an error while recording audio. The audio sink cannot be
126    // destroyed yet. No direct action needed by the AudioInputStream, but it
127    // is a good place to stop accumulating sound data since is is likely that
128    // recording will not continue.
129    virtual void OnError(AudioInputStream* stream) = 0;
130
131   protected:
132    virtual ~AudioInputCallback() {}
133  };
134
135  virtual ~AudioInputStream() {}
136
137  // Open the stream and prepares it for recording. Call Start() to actually
138  // begin recording.
139  virtual bool Open() = 0;
140
141  // Starts recording audio and generating AudioInputCallback::OnData().
142  // The input stream does not take ownership of this callback.
143  virtual void Start(AudioInputCallback* callback) = 0;
144
145  // Stops recording audio. Effect might not be instantaneous as there could be
146  // pending audio callbacks in the queue which will be issued first before
147  // recording stops.
148  virtual void Stop() = 0;
149
150  // Close the stream. This also generates AudioInputCallback::OnClose(). This
151  // should be the last call made on this object.
152  virtual void Close() = 0;
153
154  // Returns the maximum microphone analog volume or 0.0 if device does not
155  // have volume control.
156  virtual double GetMaxVolume() = 0;
157
158  // Sets the microphone analog volume, with range [0, max_volume] inclusive.
159  virtual void SetVolume(double volume) = 0;
160
161  // Returns the microphone analog volume, with range [0, max_volume] inclusive.
162  virtual double GetVolume() = 0;
163
164  // Sets the Automatic Gain Control (AGC) state.
165  virtual void SetAutomaticGainControl(bool enabled) = 0;
166
167  // Returns the Automatic Gain Control (AGC) state.
168  virtual bool GetAutomaticGainControl() = 0;
169
170  // Returns the current muting state for the microphone.
171  virtual bool IsMuted() = 0;
172};
173
174}  // namespace media
175
176#endif  // MEDIA_AUDIO_AUDIO_IO_H_
177