OpenShot Library | libopenshot-audio  0.2.0
juce_AudioFormatWriter.h
1 
2 /** @weakgroup juce_audio_formats-format
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  By using JUCE, you agree to the terms of both the JUCE 5 End-User License
15  Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
16  27th April 2017).
17 
18  End User License Agreement: www.juce.com/juce-5-licence
19  Privacy Policy: www.juce.com/juce-5-privacy-policy
20 
21  Or: You may also use this code under the terms of the GPL v3 (see
22  www.gnu.org/licenses).
23 
24  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
25  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
26  DISCLAIMED.
27 
28  ==============================================================================
29 */
30 
31 namespace juce
32 {
33 
34 //==============================================================================
35 /**
36  Writes samples to an audio file stream.
37 
38  A subclass that writes a specific type of audio format will be created by
39  an AudioFormat object.
40 
41  After creating one of these with the AudioFormat::createWriterFor() method
42  you can call its write() method to store the samples, and then delete it.
43 
44  @see AudioFormat, AudioFormatReader
45 
46  @tags{Audio}
47 */
49 {
50 protected:
51  //==============================================================================
52  /** Creates an AudioFormatWriter object.
53 
54  @param destStream the stream to write to - this will be deleted
55  by this object when it is no longer needed
56  @param formatName the description that will be returned by the getFormatName()
57  method
58  @param sampleRate the sample rate to use - the base class just stores
59  this value, it doesn't do anything with it
60  @param numberOfChannels the number of channels to write - the base class just stores
61  this value, it doesn't do anything with it
62  @param bitsPerSample the bit depth of the stream - the base class just stores
63  this value, it doesn't do anything with it
64  */
65  AudioFormatWriter (OutputStream* destStream,
66  const String& formatName,
67  double sampleRate,
68  unsigned int numberOfChannels,
69  unsigned int bitsPerSample);
70 
71  //==============================================================================
72  /** Creates an AudioFormatWriter object.
73 
74  @param destStream the stream to write to - this will be deleted
75  by this object when it is no longer needed
76  @param formatName the description that will be returned by the getFormatName()
77  method
78  @param sampleRate the sample rate to use - the base class just stores
79  this value, it doesn't do anything with it
80  @param audioChannelLayout the channel layout to use for the writer - the base class
81  just stores this value, it doesn't do anything with it
82  @param bitsPerSample the bit depth of the stream - the base class just stores
83  this value, it doesn't do anything with it
84  */
85  AudioFormatWriter (OutputStream* destStream,
86  const String& formatName,
87  double sampleRate,
88  const AudioChannelSet& audioChannelLayout,
89  unsigned int bitsPerSample);
90 
91 public:
92  /** Destructor. */
93  virtual ~AudioFormatWriter();
94 
95  //==============================================================================
96  /** Returns a description of what type of format this is.
97 
98  E.g. "AIFF file"
99  */
100  const String& getFormatName() const noexcept { return formatName; }
101 
102  //==============================================================================
103  /** Writes a set of samples to the audio stream.
104 
105  Note that if you're trying to write the contents of an AudioBuffer, you
106  can use writeFromAudioSampleBuffer().
107 
108  @param samplesToWrite an array of arrays containing the sample data for
109  each channel to write. This is a zero-terminated
110  array of arrays, and can contain a different number
111  of channels than the actual stream uses, and the
112  writer should do its best to cope with this.
113  If the format is fixed-point, each channel will be formatted
114  as an array of signed integers using the full 32-bit
115  range -0x80000000 to 0x7fffffff, regardless of the source's
116  bit-depth. If it is a floating-point format, you should treat
117  the arrays as arrays of floats, and just cast it to an (int**)
118  to pass it into the method.
119  @param numSamples the number of samples to write
120  */
121  virtual bool write (const int** samplesToWrite, int numSamples) = 0;
122 
123  /** Some formats may support a flush operation that makes sure the file is in a
124  valid state before carrying on.
125  If supported, this means that by calling flush periodically when writing data
126  to a large file, then it should still be left in a readable state if your program
127  crashes.
128  It goes without saying that this method must be called from the same thread that's
129  calling write()!
130  If the format supports flushing and the operation succeeds, this returns true.
131  */
132  virtual bool flush();
133 
134  //==============================================================================
135  /** Reads a section of samples from an AudioFormatReader, and writes these to
136  the output.
137 
138  This will take care of any floating-point conversion that's required to convert
139  between the two formats. It won't deal with sample-rate conversion, though.
140 
141  If numSamplesToRead < 0, it will write the entire length of the reader.
142 
143  @returns false if it can't read or write properly during the operation
144  */
145  bool writeFromAudioReader (AudioFormatReader& reader,
146  int64 startSample,
147  int64 numSamplesToRead);
148 
149  /** Reads some samples from an AudioSource, and writes these to the output.
150 
151  The source must already have been initialised with the AudioSource::prepareToPlay() method
152 
153  @param source the source to read from
154  @param numSamplesToRead total number of samples to read and write
155  @param samplesPerBlock the maximum number of samples to fetch from the source
156  @returns false if it can't read or write properly during the operation
157  */
158  bool writeFromAudioSource (AudioSource& source,
159  int numSamplesToRead,
160  int samplesPerBlock = 2048);
161 
162 
163  /** Writes some samples from an AudioBuffer. */
164  bool writeFromAudioSampleBuffer (const AudioBuffer<float>& source,
165  int startSample, int numSamples);
166 
167  /** Writes some samples from a set of float data channels. */
168  bool writeFromFloatArrays (const float* const* channels, int numChannels, int numSamples);
169 
170  //==============================================================================
171  /** Returns the sample rate being used. */
172  double getSampleRate() const noexcept { return sampleRate; }
173 
174  /** Returns the number of channels being written. */
175  int getNumChannels() const noexcept { return (int) numChannels; }
176 
177  /** Returns the bit-depth of the data being written. */
178  int getBitsPerSample() const noexcept { return (int) bitsPerSample; }
179 
180  /** Returns true if it's a floating-point format, false if it's fixed-point. */
181  bool isFloatingPoint() const noexcept { return usesFloatingPointData; }
182 
183  //==============================================================================
184  /**
185  Provides a FIFO for an AudioFormatWriter, allowing you to push incoming
186  data into a buffer which will be flushed to disk by a background thread.
187  */
189  {
190  public:
191  /** Creates a ThreadedWriter for a given writer and a thread.
192 
193  The writer object which is passed in here will be owned and deleted by
194  the ThreadedWriter when it is no longer needed.
195 
196  To stop the writer and flush the buffer to disk, simply delete this object.
197  */
199  TimeSliceThread& backgroundThread,
200  int numSamplesToBuffer);
201 
202  /** Destructor. */
203  ~ThreadedWriter();
204 
205  /** Pushes some incoming audio data into the FIFO.
206 
207  If there's enough free space in the buffer, this will add the data to it,
208 
209  If the FIFO is too full to accept this many samples, the method will return
210  false - then you could either wait until the background thread has had time to
211  consume some of the buffered data and try again, or you can give up
212  and lost this block.
213 
214  The data must be an array containing the same number of channels as the
215  AudioFormatWriter object is using. None of these channels can be null.
216  */
217  bool write (const float* const* data, int numSamples);
218 
219  /** Receiver for incoming data. */
221  {
222  public:
223  IncomingDataReceiver() = default;
224  virtual ~IncomingDataReceiver() = default;
225 
226  virtual void reset (int numChannels, double sampleRate, int64 totalSamplesInSource) = 0;
227  virtual void addBlock (int64 sampleNumberInSource, const AudioBuffer<float>& newData,
228  int startOffsetInBuffer, int numSamples) = 0;
229  };
230 
231  /** Allows you to specify a callback that this writer should update with the
232  incoming data.
233  The receiver will be cleared and the writer will begin adding data to it
234  as the data arrives. Pass a null pointer to remove the current receiver.
235 
236  The object passed-in must not be deleted while this writer is still using it.
237  */
238  void setDataReceiver (IncomingDataReceiver*);
239 
240  /** Sets how many samples should be written before calling the AudioFormatWriter::flush method.
241  Set this to 0 to disable flushing (this is the default).
242  */
243  void setFlushInterval (int numSamplesPerFlush) noexcept;
244 
245  private:
246  class Buffer;
247  std::unique_ptr<Buffer> buffer;
248  };
249 
250 protected:
251  //==============================================================================
252  /** The sample rate of the stream. */
253  double sampleRate;
254 
255  /** The number of channels being written to the stream. */
256  unsigned int numChannels;
257 
258  /** The bit depth of the file. */
259  unsigned int bitsPerSample;
260 
261  /** True if it's a floating-point format, false if it's fixed-point. */
263 
264  /** The audio channel layout that the writer should use */
266 
267  /** The output stream for use by subclasses. */
269 
270  /** Used by AudioFormatWriter subclasses to copy data to different formats. */
271  template <class DestSampleType, class SourceSampleType, class DestEndianness>
272  struct WriteHelper
273  {
276 
277  static void write (void* destData, int numDestChannels, const int* const* source,
278  int numSamples, const int sourceOffset = 0) noexcept
279  {
280  for (int i = 0; i < numDestChannels; ++i)
281  {
282  const DestType dest (addBytesToPointer (destData, i * DestType::getBytesPerSample()), numDestChannels);
283 
284  if (*source != nullptr)
285  {
286  dest.convertSamples (SourceType (*source + sourceOffset), numSamples);
287  ++source;
288  }
289  else
290  {
291  dest.clearSamples (numSamples);
292  }
293  }
294  }
295  };
296 
297 private:
298  String formatName;
299  friend class ThreadedWriter;
300 
301  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatWriter)
302 };
303 
304 } // namespace juce
305 
306 /** @}*/
juce::AudioFormatWriter::getFormatName
const String & getFormatName() const noexcept
Returns a description of what type of format this is.
Definition: juce_AudioFormatWriter.h:100
juce::AudioFormatWriter::sampleRate
double sampleRate
The sample rate of the stream.
Definition: juce_AudioFormatWriter.h:253
juce::AudioFormatWriter::getBitsPerSample
int getBitsPerSample() const noexcept
Returns the bit-depth of the data being written.
Definition: juce_AudioFormatWriter.h:178
juce::AudioSource
Base class for objects that can produce a continuous stream of audio.
Definition: juce_AudioSource.h:113
juce::AudioBuffer< float >
juce::AudioFormatWriter::bitsPerSample
unsigned int bitsPerSample
The bit depth of the file.
Definition: juce_AudioFormatWriter.h:259
juce::AudioFormatWriter::getNumChannels
int getNumChannels() const noexcept
Returns the number of channels being written.
Definition: juce_AudioFormatWriter.h:175
juce::AudioFormatWriter::usesFloatingPointData
bool usesFloatingPointData
True if it's a floating-point format, false if it's fixed-point.
Definition: juce_AudioFormatWriter.h:262
juce::AudioFormatWriter::ThreadedWriter::Buffer
Definition: juce_AudioFormatWriter.cpp:213
JUCE_API
#define JUCE_API
This macro is added to all JUCE public class declarations.
Definition: juce_StandardHeader.h:143
juce::AudioData::Pointer::convertSamples
void convertSamples(Pointer source, int numSamples) const noexcept
Writes a stream of samples into this pointer from another pointer.
Definition: juce_AudioDataConverters.h:446
juce::AudioFormatWriter::WriteHelper
Used by AudioFormatWriter subclasses to copy data to different formats.
Definition: juce_AudioFormatWriter.h:272
juce::OutputStream
The base class for streams that write data to some kind of destination.
Definition: juce_OutputStream.h:41
juce::TimeSliceThread
A thread that keeps a list of clients, and calls each one in turn, giving them all a chance to run so...
Definition: juce_TimeSliceThread.h:86
juce::AudioChannelSet
Represents a set of audio channel types.
Definition: juce_AudioChannelSet.h:50
juce::AudioFormatWriter::ThreadedWriter::IncomingDataReceiver
Receiver for incoming data.
Definition: juce_AudioFormatWriter.h:220
juce::AudioFormatWriter::output
OutputStream * output
The output stream for use by subclasses.
Definition: juce_AudioFormatWriter.h:268
juce::AudioData::Pointer
Used as a template parameter for AudioData::Pointer.
Definition: juce_AudioDataConverters.h:358
juce::AudioData::Pointer::clearSamples
void clearSamples(int numSamples) const noexcept
Sets a number of samples to zero.
Definition: juce_AudioDataConverters.h:490
juce::AudioFormatWriter::getSampleRate
double getSampleRate() const noexcept
Returns the sample rate being used.
Definition: juce_AudioFormatWriter.h:172
juce::AudioFormatWriter::ThreadedWriter
Provides a FIFO for an AudioFormatWriter, allowing you to push incoming data into a buffer which will...
Definition: juce_AudioFormatWriter.h:188
juce::AudioFormatWriter::isFloatingPoint
bool isFloatingPoint() const noexcept
Returns true if it's a floating-point format, false if it's fixed-point.
Definition: juce_AudioFormatWriter.h:181
juce::String
The JUCE String class!
Definition: juce_String.h:42
juce::AudioFormatWriter
Writes samples to an audio file stream.
Definition: juce_AudioFormatWriter.h:48
juce::AudioFormatWriter::numChannels
unsigned int numChannels
The number of channels being written to the stream.
Definition: juce_AudioFormatWriter.h:256
juce::AudioFormatReader
Reads samples from an audio file stream.
Definition: juce_AudioFormatReader.h:48
juce::AudioFormatWriter::channelLayout
AudioChannelSet channelLayout
The audio channel layout that the writer should use.
Definition: juce_AudioFormatWriter.h:265