OpenShot Library | libopenshot-audio 0.2.0
juce_AudioFormatReader.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
34class AudioFormat;
35
36
37//==============================================================================
38/**
39 Reads samples from an audio file stream.
40
41 A subclass that reads a specific type of audio format will be created by
42 an AudioFormat object.
43
44 @see AudioFormat, AudioFormatWriter
45
46 @tags{Audio}
47*/
49{
50protected:
51 //==============================================================================
52 /** Creates an AudioFormatReader object.
53
54 @param sourceStream the stream to read from - this will be deleted
55 by this object when it is no longer needed. (Some
56 specialised readers might not use this parameter and
57 can leave it as nullptr).
58 @param formatName the description that will be returned by the getFormatName()
59 method
60 */
61 AudioFormatReader (InputStream* sourceStream,
62 const String& formatName);
63
64public:
65 /** Destructor. */
66 virtual ~AudioFormatReader();
67
68 //==============================================================================
69 /** Returns a description of what type of format this is.
70
71 E.g. "AIFF"
72 */
73 const String& getFormatName() const noexcept { return formatName; }
74
75 //==============================================================================
76 /** Reads samples from the stream.
77
78 @param destChannels an array of float buffers into which the sample data for each
79 channel will be written. Channels that aren't needed can be null
80 @param numDestChannels the number of array elements in the destChannels array
81 @param startSampleInSource the position in the audio file or stream at which the samples
82 should be read, as a number of samples from the start of the
83 stream. It's ok for this to be beyond the start or end of the
84 available data - any samples that are out-of-range will be returned
85 as zeros.
86 @param numSamplesToRead the number of samples to read. If this is greater than the number
87 of samples that the file or stream contains. the result will be padded
88 with zeros
89 @returns true if the operation succeeded, false if there was an error. Note
90 that reading sections of data beyond the extent of the stream isn't an
91 error - the reader should just return zeros for these regions
92 @see readMaxLevels
93 */
94 bool read (float* const* destChannels, int numDestChannels,
96
97 /** Reads samples from the stream.
98
99 @param destChannels an array of buffers into which the sample data for each
100 channel will be written.
101 If the format is fixed-point, each channel will be written
102 as an array of 32-bit signed integers using the full
103 range -0x80000000 to 0x7fffffff, regardless of the source's
104 bit-depth. If it is a floating-point format, you should cast
105 the resulting array to a (float**) to get the values (in the
106 range -1.0 to 1.0 or beyond)
107 If the format is stereo, then destChannels[0] is the left channel
108 data, and destChannels[1] is the right channel.
109 The numDestChannels parameter indicates how many pointers this array
110 contains, but some of these pointers can be null if you don't want to
111 read data for some of the channels
112 @param numDestChannels the number of array elements in the destChannels array
113 @param startSampleInSource the position in the audio file or stream at which the samples
114 should be read, as a number of samples from the start of the
115 stream. It's ok for this to be beyond the start or end of the
116 available data - any samples that are out-of-range will be returned
117 as zeros.
118 @param numSamplesToRead the number of samples to read. If this is greater than the number
119 of samples that the file or stream contains. the result will be padded
120 with zeros
121 @param fillLeftoverChannelsWithCopies if true, this indicates that if there's no source data available
122 for some of the channels that you pass in, then they should be filled with
123 copies of valid source channels.
124 E.g. if you're reading a mono file and you pass 2 channels to this method, then
125 if fillLeftoverChannelsWithCopies is true, both destination channels will be filled
126 with the same data from the file's single channel. If fillLeftoverChannelsWithCopies
127 was false, then only the first channel would be filled with the file's contents, and
128 the second would be cleared. If there are many channels, e.g. you try to read 4 channels
129 from a stereo file, then the last 3 would all end up with copies of the same data.
130 @returns true if the operation succeeded, false if there was an error. Note
131 that reading sections of data beyond the extent of the stream isn't an
132 error - the reader should just return zeros for these regions
133 @see readMaxLevels
134 */
135 bool read (int* const* destChannels,
136 int numDestChannels,
140
141 /** Fills a section of an AudioBuffer from this reader.
142
143 This will convert the reader's fixed- or floating-point data to
144 the buffer's floating-point format, and will try to intelligently
145 cope with mismatches between the number of channels in the reader
146 and the buffer.
147 */
148 void read (AudioBuffer<float>* buffer,
150 int numSamples,
151 int64 readerStartSample,
153 bool useReaderRightChan);
154
155 /** Finds the highest and lowest sample levels from a section of the audio stream.
156
157 This will read a block of samples from the stream, and measure the
158 highest and lowest sample levels from the channels in that section, returning
159 these as normalised floating-point levels.
160
161 @param startSample the offset into the audio stream to start reading from. It's
162 ok for this to be beyond the start or end of the stream.
163 @param numSamples how many samples to read
164 @param results this array will be filled with Range values for each channel.
165 The array must contain numChannels elements.
166 @param numChannelsToRead the number of channels of data to scan. This must be
167 more than zero, but not more than the total number of channels
168 that the reader contains
169 @see read
170 */
171 virtual void readMaxLevels (int64 startSample, int64 numSamples,
172 Range<float>* results, int numChannelsToRead);
173
174 /** Finds the highest and lowest sample levels from a section of the audio stream.
175
176 This will read a block of samples from the stream, and measure the
177 highest and lowest sample levels from the channels in that section, returning
178 these as normalised floating-point levels.
179
180 @param startSample the offset into the audio stream to start reading from. It's
181 ok for this to be beyond the start or end of the stream.
182 @param numSamples how many samples to read
183 @param lowestLeft on return, this is the lowest absolute sample from the left channel
184 @param highestLeft on return, this is the highest absolute sample from the left channel
185 @param lowestRight on return, this is the lowest absolute sample from the right
186 channel (if there is one)
187 @param highestRight on return, this is the highest absolute sample from the right
188 channel (if there is one)
189 @see read
190 */
191 virtual void readMaxLevels (int64 startSample, int64 numSamples,
192 float& lowestLeft, float& highestLeft,
193 float& lowestRight, float& highestRight);
194
195 /** Scans the source looking for a sample whose magnitude is in a specified range.
196
197 This will read from the source, either forwards or backwards between two sample
198 positions, until it finds a sample whose magnitude lies between two specified levels.
199
200 If it finds a suitable sample, it returns its position; if not, it will return -1.
201
202 There's also a minimumConsecutiveSamples setting to help avoid spikes or zero-crossing
203 points when you're searching for a continuous range of samples
204
205 @param startSample the first sample to look at
206 @param numSamplesToSearch the number of samples to scan. If this value is negative,
207 the search will go backwards
208 @param magnitudeRangeMinimum the lowest magnitude (inclusive) that is considered a hit, from 0 to 1.0
209 @param magnitudeRangeMaximum the highest magnitude (inclusive) that is considered a hit, from 0 to 1.0
210 @param minimumConsecutiveSamples if this is > 0, the method will only look for a sequence
211 of this many consecutive samples, all of which lie
212 within the target range. When it finds such a sequence,
213 it returns the position of the first in-range sample
214 it found (i.e. the earliest one if scanning forwards, the
215 latest one if scanning backwards)
216 */
217 int64 searchForLevel (int64 startSample,
218 int64 numSamplesToSearch,
222
223
224 //==============================================================================
225 /** The sample-rate of the stream. */
226 double sampleRate = 0;
227
228 /** The number of bits per sample, e.g. 16, 24, 32. */
229 unsigned int bitsPerSample = 0;
230
231 /** The total number of samples in the audio stream. */
232 int64 lengthInSamples = 0;
233
234 /** The total number of channels in the audio stream. */
235 unsigned int numChannels = 0;
236
237 /** Indicates whether the data is floating-point or fixed. */
238 bool usesFloatingPointData = false;
239
240 /** A set of metadata values that the reader has pulled out of the stream.
241
242 Exactly what these values are depends on the format, so you can
243 check out the format implementation code to see what kind of stuff
244 they understand.
245 */
247
248 /** The input stream, for use by subclasses. */
250
251 //==============================================================================
252 /** Get the channel layout of the audio stream. */
253 virtual AudioChannelSet getChannelLayout();
254
255 //==============================================================================
256 /** Subclasses must implement this method to perform the low-level read operation.
257
258 Callers should use read() instead of calling this directly.
259
260 @param destChannels the array of destination buffers to fill. Some of these
261 pointers may be null
262 @param numDestChannels the number of items in the destChannels array. This
263 value is guaranteed not to be greater than the number of
264 channels that this reader object contains
265 @param startOffsetInDestBuffer the number of samples from the start of the
266 dest data at which to begin writing
267 @param startSampleInFile the number of samples into the source data at which
268 to begin reading. This value is guaranteed to be >= 0.
269 @param numSamples the number of samples to read
270 */
271 virtual bool readSamples (int** destChannels,
272 int numDestChannels,
274 int64 startSampleInFile,
275 int numSamples) = 0;
276
277
278protected:
279 //==============================================================================
280 /** Used by AudioFormatReader subclasses to copy data to different formats. */
281 template <class DestSampleType, class SourceSampleType, class SourceEndianness>
283 {
286
287 template <typename TargetType>
288 static void read (TargetType* const* destData, int destOffset, int numDestChannels,
289 const void* sourceData, int numSourceChannels, int numSamples) noexcept
290 {
291 for (int i = 0; i < numDestChannels; ++i)
292 {
293 if (void* targetChan = destData[i])
294 {
295 DestType dest (targetChan);
296 dest += destOffset;
297
298 if (i < numSourceChannels)
299 dest.convertSamples (SourceType (addBytesToPointer (sourceData, i * SourceType::getBytesPerSample()), numSourceChannels), numSamples);
300 else
301 dest.clearSamples (numSamples);
302 }
303 }
304 }
305 };
306
307 /** Used by AudioFormatReader subclasses to clear any parts of the data blocks that lie
308 beyond the end of their available length.
309 */
310 static void clearSamplesBeyondAvailableLength (int** destChannels, int numDestChannels,
312 int& numSamples, int64 fileLengthInSamples)
313 {
314 jassert (destChannels != nullptr);
316
317 if (samplesAvailable < numSamples)
318 {
319 for (int i = numDestChannels; --i >= 0;)
320 if (destChannels[i] != nullptr)
321 zeromem (destChannels[i] + startOffsetInDestBuffer, sizeof (int) * (size_t) numSamples);
322
323 numSamples = (int) samplesAvailable;
324 }
325 }
326
327private:
328 String formatName;
329
330 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatReader)
331};
332
333} // namespace juce
334
335/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
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.
InputStream * input
The input stream, for use by subclasses.
StringPairArray metadataValues
A set of metadata values that the reader has pulled out of the stream.
const String & getFormatName() const noexcept
Returns a description of what type of format this is.
static void clearSamplesBeyondAvailableLength(int **destChannels, int numDestChannels, int startOffsetInDestBuffer, int64 startSampleInFile, int &numSamples, int64 fileLengthInSamples)
Used by AudioFormatReader subclasses to clear any parts of the data blocks that lie beyond the end of...
virtual bool readSamples(int **destChannels, int numDestChannels, int startOffsetInDestBuffer, int64 startSampleInFile, int numSamples)=0
Subclasses must implement this method to perform the low-level read operation.
The base class for streams that read data.
A container for holding a set of strings which are keyed by another string.
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.
Used by AudioFormatReader subclasses to copy data to different formats.