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
31namespace 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{
50protected:
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 */
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 */
86 const String& formatName,
87 double sampleRate,
88 const AudioChannelSet& audioChannelLayout,
89 unsigned int bitsPerSample);
90
91public:
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. */
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
250protected:
251 //==============================================================================
252 /** The sample rate of the stream. */
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>
273 {
274 using DestType = AudioData::Pointer <DestSampleType, DestEndianness, AudioData::Interleaved, AudioData::NonConst>;
275 using SourceType = AudioData::Pointer <SourceSampleType, AudioData::NativeEndian, AudioData::NonInterleaved, AudioData::Const>;
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
297private:
298 String formatName;
299 friend class ThreadedWriter;
300
301 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatWriter)
302};
303
304} // namespace juce
305
306/** @}*/
A multi-channel buffer containing floating point audio samples.
Represents a set of audio channel types.
Used as a template parameter for AudioData::Pointer.
void clearSamples(int numSamples) const noexcept
Sets a number of samples to zero.
void convertSamples(Pointer source, int numSamples) const noexcept
Writes a stream of samples into this pointer from another pointer.
Reads samples from an audio file stream.
Provides a FIFO for an AudioFormatWriter, allowing you to push incoming data into a buffer which will...
Writes samples to an audio file stream.
unsigned int numChannels
The number of channels being written to the stream.
double sampleRate
The sample rate of the stream.
bool usesFloatingPointData
True if it's a floating-point format, false if it's fixed-point.
const String & getFormatName() const noexcept
Returns a description of what type of format this is.
unsigned int bitsPerSample
The bit depth of the file.
virtual bool write(const int **samplesToWrite, int numSamples)=0
Writes a set of samples to the audio stream.
int getNumChannels() const noexcept
Returns the number of channels being written.
double getSampleRate() const noexcept
Returns the sample rate being used.
bool isFloatingPoint() const noexcept
Returns true if it's a floating-point format, false if it's fixed-point.
AudioChannelSet channelLayout
The audio channel layout that the writer should use.
int getBitsPerSample() const noexcept
Returns the bit-depth of the data being written.
OutputStream * output
The output stream for use by subclasses.
Base class for objects that can produce a continuous stream of audio.
The base class for streams that write data to some kind of destination.
The JUCE String class!
Definition juce_String.h:43
A thread that keeps a list of clients, and calls each one in turn, giving them all a chance to run so...
#define JUCE_API
This macro is added to all JUCE public class declarations.
Used by AudioFormatWriter subclasses to copy data to different formats.