audio_io.h revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7
11320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Copyright (c) 2012 The Chromium Authors. All rights reserved. 21320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Use of this source code is governed by a BSD-style license that can be 31320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// found in the LICENSE file. 41320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 51320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#ifndef MEDIA_AUDIO_AUDIO_IO_H_ 61320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#define MEDIA_AUDIO_AUDIO_IO_H_ 71320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 81320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/basictypes.h" 91320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "media/audio/audio_buffers_state.h" 101320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "media/base/audio_bus.h" 111320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 121320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Low-level audio output support. To make sound there are 3 objects involved: 131320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - AudioSource : produces audio samples on a pull model. Implements 141320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// the AudioSourceCallback interface. 151320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - AudioOutputStream : uses the AudioSource to render audio on a given 161320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// channel, format and sample frequency configuration. Data from the 171320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// AudioSource is delivered in a 'pull' model. 181320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - AudioManager : factory for the AudioOutputStream objects, manager 191320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// of the hardware resources and mixer control. 201320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 211320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// The number and configuration of AudioOutputStream does not need to match the 221320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// physically available hardware resources. For example you can have: 231320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 241320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// MonoPCMSource1 --> MonoPCMStream1 --> | | --> audio left channel 251320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// StereoPCMSource -> StereoPCMStream -> | mixer | 261320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// MonoPCMSource2 --> MonoPCMStream2 --> | | --> audio right channel 271320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 281320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// This facility's objective is mix and render audio with low overhead using 291320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// the OS basic audio support, abstracting as much as possible the 301320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// idiosyncrasies of each platform. Non-goals: 311320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Positional, 3d audio 321320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Dependence on non-default libraries such as DirectX 9, 10, XAudio 331320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Digital signal processing or effects 341320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Extra features if a specific hardware is installed (EAX, X-fi) 351320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 361320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// The primary client of this facility is audio coming from several tabs. 371320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Specifically for this case we avoid supporting complex formats such as MP3 381320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// or WMA. Complex format decoding should be done by the renderers. 391320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 411320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Models an audio stream that gets rendered to the audio hardware output. 421320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Because we support more audio streams than physically available channels 431320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// a given AudioOutputStream might or might not talk directly to hardware. 441320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// An audio stream allocates several buffers for audio data and calls 451320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// AudioSourceCallback::OnMoreData() periodically to fill these buffers, 461320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// as the data is written to the audio device. Size of each packet is determined 471320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// by |samples_per_packet| specified in AudioParameters when the stream is 481320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// created. 491320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 501320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tuccinamespace media { 511320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 521320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucciclass MEDIA_EXPORT AudioOutputStream { 531320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci public: 541320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Audio sources must implement AudioSourceCallback. This interface will be 551320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // called in a random thread which very likely is a high priority thread. Do 561320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // not rely on using this thread TLS or make calls that alter the thread 571320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // itself such as creating Windows or initializing COM. 581320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci class MEDIA_EXPORT AudioSourceCallback { 591320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci public: 601320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Provide more data by fully filling |dest|. The source will return 611320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // the number of frames it filled. |buffers_state| contains current state 621320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // of the buffers, and can be used by the source to calculate delay. 631320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual int OnMoreData(AudioBus* dest, 641320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci AudioBuffersState buffers_state) = 0; 651320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 661320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual int OnMoreIOData(AudioBus* source, 671320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci AudioBus* dest, 681320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci AudioBuffersState buffers_state) = 0; 691320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 701320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // There was an error while playing a buffer. Audio source cannot be 711320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // destroyed yet. No direct action needed by the AudioStream, but it is 721320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // a good place to stop accumulating sound data since is is likely that 731320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // playback will not continue. 741320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void OnError(AudioOutputStream* stream) = 0; 751320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 761320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci protected: 771320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual ~AudioSourceCallback() {} 781320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci }; 791320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 801320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual ~AudioOutputStream() {} 811320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 821320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Open the stream. false is returned if the stream cannot be opened. Open() 831320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // must always be followed by a call to Close() even if Open() fails. 841320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual bool Open() = 0; 851320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 861320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Starts playing audio and generating AudioSourceCallback::OnMoreData(). 871320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Since implementor of AudioOutputStream may have internal buffers, right 881320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // after calling this method initial buffers are fetched. 891320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // 901320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // The output stream does not take ownership of this callback. 911320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Start(AudioSourceCallback* callback) = 0; 921320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 931320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Stops playing audio. Effect might not be instantaneous as the hardware 941320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // might have locked audio data that is processing. 951320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Stop() = 0; 961320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 971320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Sets the relative volume, with range [0.0, 1.0] inclusive. 981320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void SetVolume(double volume) = 0; 991320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1001320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Gets the relative volume, with range [0.0, 1.0] inclusive. 1011320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void GetVolume(double* volume) = 0; 1021320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1031320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Close the stream. This also generates AudioSourceCallback::OnClose(). 1041320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // After calling this method, the object should not be used anymore. 1051320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Close() = 0; 1061320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci}; 1071320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1081320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Models an audio sink receiving recorded audio from the audio driver. 1091320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucciclass MEDIA_EXPORT AudioInputStream { 1101320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci public: 1111320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci class MEDIA_EXPORT AudioInputCallback { 1121320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci public: 1131320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Called by the audio recorder when a full packet of audio data is 1141320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // available. This is called from a special audio thread and the 1151320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // implementation should return as soon as possible. 1161320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void OnData(AudioInputStream* stream, const uint8* src, 1171320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci uint32 size, uint32 hardware_delay_bytes, 1181320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci double volume) = 0; 1191320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1201320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // There was an error while recording audio. The audio sink cannot be 1211320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // destroyed yet. No direct action needed by the AudioInputStream, but it 1221320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // is a good place to stop accumulating sound data since is is likely that 1231320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // recording will not continue. 1241320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void OnError(AudioInputStream* stream) = 0; 1251320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1261320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci protected: 1271320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual ~AudioInputCallback() {} 1281320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci }; 1291320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1301320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual ~AudioInputStream() {} 1311320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1321320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Open the stream and prepares it for recording. Call Start() to actually 1331320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // begin recording. 1341320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual bool Open() = 0; 1351320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1361320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Starts recording audio and generating AudioInputCallback::OnData(). 1371320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // The input stream does not take ownership of this callback. 1381320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Start(AudioInputCallback* callback) = 0; 1391320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Stops recording audio. Effect might not be instantaneous as there could be 1411320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // pending audio callbacks in the queue which will be issued first before 1421320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // recording stops. 1431320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Stop() = 0; 1441320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1451320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Close the stream. This also generates AudioInputCallback::OnClose(). This 1461320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // should be the last call made on this object. 1471320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void Close() = 0; 1481320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1491320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Returns the maximum microphone analog volume or 0.0 if device does not 1501320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // have volume control. 1511320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual double GetMaxVolume() = 0; 1521320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1531320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Sets the microphone analog volume, with range [0, max_volume] inclusive. 1541320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void SetVolume(double volume) = 0; 1551320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1561320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Returns the microphone analog volume, with range [0, max_volume] inclusive. 1571320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual double GetVolume() = 0; 1581320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1591320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Sets the Automatic Gain Control (AGC) state. 1601320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual void SetAutomaticGainControl(bool enabled) = 0; 1611320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1621320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Returns the Automatic Gain Control (AGC) state. 1631320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci virtual bool GetAutomaticGainControl() = 0; 1641320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci}; 1651320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1661320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci} // namespace media 1671320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1681320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#endif // MEDIA_AUDIO_AUDIO_IO_H_ 1691320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci