juce/source/src/audio/audio_file_formats/juce_AudioFormatWriter.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_AUDIOFORMATWRITER_JUCEHEADER__
  27 #define __JUCE_AUDIOFORMATWRITER_JUCEHEADER__
  28
  29 #include "../../io/files/juce_FileOutputStream.h"
  30 #include "juce_AudioFormatReader.h"
  31 #include "../audio_sources/juce_AudioSource.h"
  32 #include "../../threads/juce_TimeSliceThread.h"
  33 class AudioThumbnail;
  34
  35
  36 //==============================================================================
  37 /**
  38     Writes samples to an audio file stream.
  39
  40     A subclass that writes a specific type of audio format will be created by
  41     an AudioFormat object.
  42
  43     After creating one of these with the AudioFormat::createWriterFor() method
  44     you can call its write() method to store the samples, and then delete it.
  45
  46     @see AudioFormat, AudioFormatReader
  47 */
  48 class JUCE_API  AudioFormatWriter
  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 public:
  72     /** Destructor. */
  73     virtual ~AudioFormatWriter();
  74
  75     //==============================================================================
  76     /** Returns a description of what type of format this is.
  77
  78         E.g. "AIFF file"
  79     */
  80     const String& getFormatName() const noexcept        { return formatName; }
  81
  82     //==============================================================================
  83     /** Writes a set of samples to the audio stream.
  84
  85         Note that if you're trying to write the contents of an AudioSampleBuffer, you
  86         can use AudioSampleBuffer::writeToAudioWriter().
  87
  88         @param samplesToWrite   an array of arrays containing the sample data for
  89                                 each channel to write. This is a zero-terminated
  90                                 array of arrays, and can contain a different number
  91                                 of channels than the actual stream uses, and the
  92                                 writer should do its best to cope with this.
  93                                 If the format is fixed-point, each channel will be formatted
  94                                 as an array of signed integers using the full 32-bit
  95                                 range -0x80000000 to 0x7fffffff, regardless of the source's
  96                                 bit-depth. If it is a floating-point format, you should treat
  97                                 the arrays as arrays of floats, and just cast it to an (int**)
  98                                 to pass it into the method.
  99         @param numSamples       the number of samples to write
 100     */
 101     virtual bool write (const int** samplesToWrite,
 102                         int numSamples) = 0;
 103
 104     //==============================================================================
 105     /** Reads a section of samples from an AudioFormatReader, and writes these to
 106         the output.
 107
 108         This will take care of any floating-point conversion that's required to convert
 109         between the two formats. It won't deal with sample-rate conversion, though.
 110
 111         If numSamplesToRead < 0, it will write the entire length of the reader.
 112
 113         @returns false if it can't read or write properly during the operation
 114     */
 115     bool writeFromAudioReader (AudioFormatReader& reader,
 116                                int64 startSample,
 117                                int64 numSamplesToRead);
 118
 119     /** Reads some samples from an AudioSource, and writes these to the output.
 120
 121         The source must already have been initialised with the AudioSource::prepareToPlay() method
 122
 123         @param source               the source to read from
 124         @param numSamplesToRead     total number of samples to read and write
 125         @param samplesPerBlock      the maximum number of samples to fetch from the source
 126         @returns false if it can't read or write properly during the operation
 127     */
 128     bool writeFromAudioSource (AudioSource& source,
 129                                int numSamplesToRead,
 130                                int samplesPerBlock = 2048);
 131
 132
 133     /** Writes some samples from an AudioSampleBuffer.
 134
 135     */
 136     bool writeFromAudioSampleBuffer (const AudioSampleBuffer& source,
 137                                      int startSample, int numSamples);
 138
 139     //==============================================================================
 140     /** Returns the sample rate being used. */
 141     double getSampleRate() const noexcept       { return sampleRate; }
 142
 143     /** Returns the number of channels being written. */
 144     int getNumChannels() const noexcept         { return numChannels; }
 145
 146     /** Returns the bit-depth of the data being written. */
 147     int getBitsPerSample() const noexcept       { return bitsPerSample; }
 148
 149     /** Returns true if it's a floating-point format, false if it's fixed-point. */
 150     bool isFloatingPoint() const noexcept       { return usesFloatingPointData; }
 151
 152     //==============================================================================
 153     /**
 154         Provides a FIFO for an AudioFormatWriter, allowing you to push incoming
 155         data into a buffer which will be flushed to disk by a background thread.
 156     */
 157     class ThreadedWriter
 158     {
 159     public:
 160         /** Creates a ThreadedWriter for a given writer and a thread.
 161
 162             The writer object which is passed in here will be owned and deleted by
 163             the ThreadedWriter when it is no longer needed.
 164
 165             To stop the writer and flush the buffer to disk, simply delete this object.
 166         */
 167         ThreadedWriter (AudioFormatWriter* writer,
 168                         TimeSliceThread& backgroundThread,
 169                         int numSamplesToBuffer);
 170
 171         /** Destructor. */
 172         ~ThreadedWriter();
 173
 174         /** Pushes some incoming audio data into the FIFO.
 175
 176             If there's enough free space in the buffer, this will add the data to it,
 177
 178             If the FIFO is too full to accept this many samples, the method will return
 179             false - then you could either wait until the background thread has had time to
 180             consume some of the buffered data and try again, or you can give up
 181             and lost this block.
 182
 183             The data must be an array containing the same number of channels as the
 184             AudioFormatWriter object is using. None of these channels can be null.
 185         */
 186         bool write (const float** data, int numSamples);
 187
 188         /** Allows you to specify a thumbnail that this writer should update with the
 189             incoming data.
 190             The thumbnail will be cleared and will the writer will begin adding data to
 191             it as it arrives. Pass a null pointer to stop the writer updating any thumbnails.
 192         */
 193         void setThumbnailToUpdate (AudioThumbnail* thumbnailToUpdate);
 194
 195        #ifndef DOXYGEN
 196         class Buffer; // (only public for VC6 compatibility)
 197        #endif
 198
 199     private:
 200         friend class ScopedPointer<Buffer>;
 201         ScopedPointer<Buffer> buffer;
 202     };
 203
 204 protected:
 205     //==============================================================================
 206     /** The sample rate of the stream. */
 207     double sampleRate;
 208
 209     /** The number of channels being written to the stream. */
 210     unsigned int numChannels;
 211
 212     /** The bit depth of the file. */
 213     unsigned int bitsPerSample;
 214
 215     /** True if it's a floating-point format, false if it's fixed-point. */
 216     bool usesFloatingPointData;
 217
 218     /** The output stream for Use by subclasses. */
 219     OutputStream* output;
 220
 221     /** Used by AudioFormatWriter subclasses to copy data to different formats. */
 222     template <class DestSampleType, class SourceSampleType, class DestEndianness>
 223     struct WriteHelper
 224     {
 225         typedef AudioData::Pointer <DestSampleType, DestEndianness, AudioData::Interleaved, AudioData::NonConst>                DestType;
 226         typedef AudioData::Pointer <SourceSampleType, AudioData::NativeEndian, AudioData::NonInterleaved, AudioData::Const>     SourceType;
 227
 228         static void write (void* destData, int numDestChannels, const int** source,
 229                            int numSamples, const int sourceOffset = 0) noexcept
 230         {
 231             for (int i = 0; i < numDestChannels; ++i)
 232             {
 233                 const DestType dest (addBytesToPointer (destData, i * DestType::getBytesPerSample()), numDestChannels);
 234
 235                 if (*source != nullptr)
 236                 {
 237                     dest.convertSamples (SourceType (*source + sourceOffset), numSamples);
 238                     ++source;
 239                 }
 240                 else
 241                 {
 242                     dest.clearSamples (numSamples);
 243                 }
 244             }
 245         }
 246     };
 247
 248 private:
 249     String formatName;
 250     friend class ThreadedWriter;
 251
 252     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatWriter);
 253 };
 254
 255
 256 #endif   // __JUCE_AUDIOFORMATWRITER_JUCEHEADER__