audio_converter.h revision c2e0dbddbe15c98d52c4786dac06cb8952a8ae6d 
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// AudioConverter is a complete mixing, resampling, buffering, and channel
6// mixing solution for converting data from one set of AudioParameters to
7// another.
8//
9// For efficiency, pieces are only invoked when necessary; i.e.,
10//    - The resampler is only used if sample rates differ.
11//    - The FIFO is only used if buffer sizes differ.
12//    - The channel mixer is only used if channel layouts differ.
13//
14// Additionally, since resampling is the most expensive operation, input mixing
15// and channel down mixing are done prior to resampling.  Likewise, channel up
16// mixing is performed after resampling.
17
18#ifndef MEDIA_BASE_AUDIO_CONVERTER_H_
19#define MEDIA_BASE_AUDIO_CONVERTER_H_
20
21#include <list>
22
23#include "base/callback.h"
24#include "base/memory/scoped_ptr.h"
25#include "base/time.h"
26#include "media/audio/audio_parameters.h"
27#include "media/base/media_export.h"
28
29namespace media {
30
31class AudioBus;
32class AudioPullFifo;
33class ChannelMixer;
34class MultiChannelResampler;
35
36// Converts audio data between two AudioParameters formats.  Sample usage:
37//   AudioParameters input(...), output(...);
38//   AudioConverter ac(input, output);
39//   scoped_ptr<AudioBus> output_audio_bus = AudioBus::Create(output);
40//   ac.AddInput(<AudioConverter::InputCallback* 1>);
41//   ac.AddInput(<AudioConverter::InputCallback* 2>);
42//   ac.Convert(output_audio_bus.get());
43//
44// Convert() will ask for input audio data from each InputCallback and convert
45// the data into the provided AudioBus.
46class MEDIA_EXPORT AudioConverter {
47 public:
48  // Interface for inputs into the converter.  Each InputCallback is added or
49  // removed from Convert() processing via AddInput() and RemoveInput().
50  class MEDIA_EXPORT InputCallback {
51   public:
52    // Method for providing more data into the converter.  Expects |audio_bus|
53    // to be completely filled with data upon return; zero padded if not enough
54    // frames are available to satisfy the request.  The return value is the
55    // volume level of the provided audio data.  If a volume level of zero is
56    // returned no further processing will be done on the provided data, else
57    // the volume level will be used to scale the provided audio data.
58    virtual double ProvideInput(AudioBus* audio_bus,
59                                base::TimeDelta buffer_delay) = 0;
60
61   protected:
62    virtual ~InputCallback() {}
63  };
64
65  // Constructs an AudioConverter for converting between the given input and
66  // output parameters.  Specifying |disable_fifo| means all InputCallbacks are
67  // capable of handling arbitrary buffer size requests; i.e. one call might ask
68  // for 10 frames of data (indicated by the size of AudioBus provided) and the
69  // next might ask for 20.  In synthetic testing, disabling the FIFO yields a
70  // ~20% speed up for common cases.
71  AudioConverter(const AudioParameters& input_params,
72                 const AudioParameters& output_params,
73                 bool disable_fifo);
74  ~AudioConverter();
75
76  // Converts audio from all inputs into the |dest|.  |dest| must be sized for
77  // data matching the output AudioParameters provided during construction.  If
78  // an |initial_delay| is specified, it will be propagated to each input.
79  void Convert(AudioBus* dest);
80  void ConvertWithDelay(const base::TimeDelta& initial_delay, AudioBus* dest);
81
82  // Adds or removes an input from the converter.  RemoveInput() will call
83  // Reset() if no inputs remain after the specified input is removed.
84  void AddInput(InputCallback* input);
85  void RemoveInput(InputCallback* input);
86
87  // Flushes all buffered data.
88  void Reset();
89
90 private:
91  // Provides input to the MultiChannelResampler.  Called by the resampler when
92  // more data is necessary.
93  void ProvideInput(int resampler_frame_delay, AudioBus* audio_bus);
94
95  // Provides input to the AudioPullFifo.  Called by the fifo when more data is
96  // necessary.
97  void SourceCallback(int fifo_frame_delay, AudioBus* audio_bus);
98
99  // Set of inputs for Convert().
100  typedef std::list<InputCallback*> InputCallbackSet;
101  InputCallbackSet transform_inputs_;
102
103  // Used to buffer data between the client and the output device in cases where
104  // the client buffer size is not the same as the output device buffer size.
105  scoped_ptr<AudioPullFifo> audio_fifo_;
106
107  // Handles resampling.
108  scoped_ptr<MultiChannelResampler> resampler_;
109
110  // Handles channel transforms.  |unmixed_audio_| is a temporary destination
111  // for audio data before it goes into the channel mixer.
112  scoped_ptr<ChannelMixer> channel_mixer_;
113  scoped_ptr<AudioBus> unmixed_audio_;
114
115  // Temporary AudioBus destination for mixing inputs.
116  scoped_ptr<AudioBus> mixer_input_audio_bus_;
117
118  // Since resampling is expensive, figure out if we should downmix channels
119  // before resampling.
120  bool downmix_early_;
121
122  // Used to calculate buffer delay information for InputCallbacks.
123  base::TimeDelta input_frame_duration_;
124  base::TimeDelta output_frame_duration_;
125  base::TimeDelta initial_delay_;
126  int resampler_frame_delay_;
127
128  // Number of channels of input audio data.  Set during construction via the
129  // value from the input AudioParameters class.  Preserved to recreate internal
130  // AudioBus structures on demand in response to varying frame size requests.
131  const int input_channel_count_;
132
133  DISALLOW_COPY_AND_ASSIGN(AudioConverter);
134};
135
136}  // namespace media
137
138#endif  // MEDIA_BASE_AUDIO_CONVERTER_H_
139