juce/source/src/audio/audio_file_formats/juce_AudioFormat.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_AUDIOFORMAT_JUCEHEADER__
  27 #define __JUCE_AUDIOFORMAT_JUCEHEADER__
  28
  29 #include "juce_AudioFormatReader.h"
  30 #include "juce_AudioFormatWriter.h"
  31 #include "../../containers/juce_Array.h"
  32
  33
  34 //==============================================================================
  35 /**
  36     Subclasses of AudioFormat are used to read and write different audio
  37     file formats.
  38
  39     @see AudioFormatReader, AudioFormatWriter, WavAudioFormat, AiffAudioFormat
  40 */
  41 class JUCE_API  AudioFormat
  42 {
  43 public:
  44     //==============================================================================
  45     /** Destructor. */
  46     virtual ~AudioFormat();
  47
  48     //==============================================================================
  49     /** Returns the name of this format.
  50
  51         e.g. "WAV file" or "AIFF file"
  52     */
  53     const String& getFormatName() const;
  54
  55     /** Returns all the file extensions that might apply to a file of this format.
  56
  57         The first item will be the one that's preferred when creating a new file.
  58
  59         So for a wav file this might just return ".wav"; for an AIFF file it might
  60         return two items, ".aif" and ".aiff"
  61     */
  62     const StringArray& getFileExtensions() const;
  63
  64     //==============================================================================
  65     /** Returns true if this the given file can be read by this format.
  66
  67         Subclasses shouldn't do too much work here, just check the extension or
  68         file type. The base class implementation just checks the file's extension
  69         against one of the ones that was registered in the constructor.
  70     */
  71     virtual bool canHandleFile (const File& fileToTest);
  72
  73     /** Returns a set of sample rates that the format can read and write. */
  74     virtual const Array <int> getPossibleSampleRates() = 0;
  75
  76     /** Returns a set of bit depths that the format can read and write. */
  77     virtual const Array <int> getPossibleBitDepths() = 0;
  78
  79     /** Returns true if the format can do 2-channel audio. */
  80     virtual bool canDoStereo() = 0;
  81
  82     /** Returns true if the format can do 1-channel audio. */
  83     virtual bool canDoMono() = 0;
  84
  85     /** Returns true if the format uses compressed data. */
  86     virtual bool isCompressed();
  87
  88     /** Returns a list of different qualities that can be used when writing.
  89
  90         Non-compressed formats will just return an empty array, but for something
  91         like Ogg-Vorbis or MP3, it might return a list of bit-rates, etc.
  92
  93         When calling createWriterFor(), an index from this array is passed in to
  94         tell the format which option is required.
  95     */
  96     virtual StringArray getQualityOptions();
  97
  98     //==============================================================================
  99     /** Tries to create an object that can read from a stream containing audio
 100         data in this format.
 101
 102         The reader object that is returned can be used to read from the stream, and
 103         should then be deleted by the caller.
 104
 105         @param sourceStream                 the stream to read from - the AudioFormatReader object
 106                                             that is returned will delete this stream when it no longer
 107                                             needs it.
 108         @param deleteStreamIfOpeningFails   if no reader can be created, this determines whether this method
 109                                             should delete the stream object that was passed-in. (If a valid
 110                                             reader is returned, it will always be in charge of deleting the
 111                                             stream, so this parameter is ignored)
 112         @see AudioFormatReader
 113     */
 114     virtual AudioFormatReader* createReaderFor (InputStream* sourceStream,
 115                                                 bool deleteStreamIfOpeningFails) = 0;
 116
 117     /** Tries to create an object that can write to a stream with this audio format.
 118
 119         The writer object that is returned can be used to write to the stream, and
 120         should then be deleted by the caller.
 121
 122         If the stream can't be created for some reason (e.g. the parameters passed in
 123         here aren't suitable), this will return 0.
 124
 125         @param streamToWriteTo      the stream that the data will go to - this will be
 126                                     deleted by the AudioFormatWriter object when it's no longer
 127                                     needed. If no AudioFormatWriter can be created by this method,
 128                                     the stream will NOT be deleted, so that the caller can re-use it
 129                                     to try to open a different format, etc
 130         @param sampleRateToUse      the sample rate for the file, which must be one of the ones
 131                                     returned by getPossibleSampleRates()
 132         @param numberOfChannels     the number of channels - this must be either 1 or 2, and
 133                                     the choice will depend on the results of canDoMono() and
 134                                     canDoStereo()
 135         @param bitsPerSample        the bits per sample to use - this must be one of the values
 136                                     returned by getPossibleBitDepths()
 137         @param metadataValues       a set of metadata values that the writer should try to write
 138                                     to the stream. Exactly what these are depends on the format,
 139                                     and the subclass doesn't actually have to do anything with
 140                                     them if it doesn't want to. Have a look at the specific format
 141                                     implementation classes to see possible values that can be
 142                                     used
 143         @param qualityOptionIndex   the index of one of compression qualities returned by the
 144                                     getQualityOptions() method. If there aren't any quality options
 145                                     for this format, just pass 0 in this parameter, as it'll be
 146                                     ignored
 147         @see AudioFormatWriter
 148     */
 149     virtual AudioFormatWriter* createWriterFor (OutputStream* streamToWriteTo,
 150                                                 double sampleRateToUse,
 151                                                 unsigned int numberOfChannels,
 152                                                 int bitsPerSample,
 153                                                 const StringPairArray& metadataValues,
 154                                                 int qualityOptionIndex) = 0;
 155
 156 protected:
 157     /** Creates an AudioFormat object.
 158
 159         @param formatName       this sets the value that will be returned by getFormatName()
 160         @param fileExtensions   a zero-terminated list of file extensions - this is what will
 161                                 be returned by getFileExtension()
 162     */
 163     AudioFormat (const String& formatName,
 164                  const StringArray& fileExtensions);
 165
 166 private:
 167     //==============================================================================
 168     String formatName;
 169     StringArray fileExtensions;
 170 };
 171
 172
 173 #endif   // __JUCE_AUDIOFORMAT_JUCEHEADER__