source/modules/juce_audio_formats/format/juce_AudioFormat.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     Subclasses of AudioFormat are used to read and write different audio
  32     file formats.
  33
  34     @see AudioFormatReader, AudioFormatWriter, WavAudioFormat, AiffAudioFormat
  35
  36     @tags{Audio}
  37 */
  38 class JUCE_API  AudioFormat
  39 {
  40 public:
  41     //==============================================================================
  42     /** Destructor. */
  43     virtual ~AudioFormat();
  44
  45     //==============================================================================
  46     /** Returns the name of this format.
  47         e.g. "WAV file" or "AIFF file"
  48     */
  49     const String& getFormatName() const;
  50
  51     //==============================================================================
  52     /** Returns all the file extensions that might apply to a file of this format.
  53         The first item will be the one that's preferred when creating a new file.
  54         So for a wav file this might just return ".wav"; for an AIFF file it might
  55         return two items, ".aif" and ".aiff"
  56     */
  57     virtual StringArray getFileExtensions() const;
  58
  59     /** Returns true if this the given file can be read by this format.
  60         Subclasses shouldn't do too much work here, just check the extension or
  61         file type. The base class implementation just checks the file's extension
  62         against one of the ones that was registered in the constructor.
  63     */
  64     virtual bool canHandleFile (const File& fileToTest);
  65
  66     /** Returns a set of sample rates that the format can read and write. */
  67     virtual Array<int> getPossibleSampleRates() = 0;
  68
  69     /** Returns a set of bit depths that the format can read and write. */
  70     virtual Array<int> getPossibleBitDepths() = 0;
  71
  72     /** Returns true if the format can do 2-channel audio. */
  73     virtual bool canDoStereo() = 0;
  74
  75     /** Returns true if the format can do 1-channel audio. */
  76     virtual bool canDoMono() = 0;
  77
  78     /** Returns true if the format uses compressed data. */
  79     virtual bool isCompressed();
  80
  81     /** Returns true if the channel layout is supported by this format. */
  82     virtual bool isChannelLayoutSupported (const AudioChannelSet& channelSet);
  83
  84     /** Returns a list of different qualities that can be used when writing.
  85
  86         Non-compressed formats will just return an empty array, but for something
  87         like Ogg-Vorbis or MP3, it might return a list of bit-rates, etc.
  88
  89         When calling createWriterFor(), an index from this array is passed in to
  90         tell the format which option is required.
  91     */
  92     virtual StringArray getQualityOptions();
  93
  94     //==============================================================================
  95     /** Tries to create an object that can read from a stream containing audio
  96         data in this format.
  97
  98         The reader object that is returned can be used to read from the stream, and
  99         should then be deleted by the caller.
 100
 101         @param sourceStream                 the stream to read from - the AudioFormatReader object
 102                                             that is returned will delete this stream when it no longer
 103                                             needs it.
 104         @param deleteStreamIfOpeningFails   if no reader can be created, this determines whether this method
 105                                             should delete the stream object that was passed-in. (If a valid
 106                                             reader is returned, it will always be in charge of deleting the
 107                                             stream, so this parameter is ignored)
 108         @see AudioFormatReader
 109     */
 110     virtual AudioFormatReader* createReaderFor (InputStream* sourceStream,
 111                                                 bool deleteStreamIfOpeningFails) = 0;
 112
 113     /** Attempts to create a MemoryMappedAudioFormatReader, if possible for this format.
 114         If the format does not support this, the method will return nullptr;
 115     */
 116     virtual MemoryMappedAudioFormatReader* createMemoryMappedReader (const File& file);
 117     virtual MemoryMappedAudioFormatReader* createMemoryMappedReader (FileInputStream* fin);
 118
 119     /** Tries to create an object that can write to a stream with this audio format.
 120
 121         The writer object that is returned can be used to write to the stream, and
 122         should then be deleted by the caller.
 123
 124         If the stream can't be created for some reason (e.g. the parameters passed in
 125         here aren't suitable), this will return nullptr.
 126
 127         @param streamToWriteTo      the stream that the data will go to - this will be
 128                                     deleted by the AudioFormatWriter object when it's no longer
 129                                     needed. If no AudioFormatWriter can be created by this method,
 130                                     the stream will NOT be deleted, so that the caller can re-use it
 131                                     to try to open a different format, etc
 132         @param sampleRateToUse      the sample rate for the file, which must be one of the ones
 133                                     returned by getPossibleSampleRates()
 134         @param numberOfChannels     the number of channels
 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     /** Tries to create an object that can write to a stream with this audio format.
 157
 158         The writer object that is returned can be used to write to the stream, and
 159         should then be deleted by the caller.
 160
 161         If the stream can't be created for some reason (e.g. the parameters passed in
 162         here aren't suitable), this will return nullptr.
 163
 164         @param streamToWriteTo      the stream that the data will go to - this will be
 165                                     deleted by the AudioFormatWriter object when it's no longer
 166                                     needed. If no AudioFormatWriter can be created by this method,
 167                                     the stream will NOT be deleted, so that the caller can re-use it
 168                                     to try to open a different format, etc
 169         @param sampleRateToUse      the sample rate for the file, which must be one of the ones
 170                                     returned by getPossibleSampleRates()
 171         @param channelLayout        the channel layout for the file. Use isChannelLayoutSupported
 172                                     to check if the writer supports this layout.
 173         @param bitsPerSample        the bits per sample to use - this must be one of the values
 174                                     returned by getPossibleBitDepths()
 175         @param metadataValues       a set of metadata values that the writer should try to write
 176                                     to the stream. Exactly what these are depends on the format,
 177                                     and the subclass doesn't actually have to do anything with
 178                                     them if it doesn't want to. Have a look at the specific format
 179                                     implementation classes to see possible values that can be
 180                                     used
 181         @param qualityOptionIndex   the index of one of compression qualities returned by the
 182                                     getQualityOptions() method. If there aren't any quality options
 183                                     for this format, just pass 0 in this parameter, as it'll be
 184                                     ignored
 185         @see AudioFormatWriter
 186     */
 187     virtual AudioFormatWriter* createWriterFor (OutputStream* streamToWriteTo,
 188                                                 double sampleRateToUse,
 189                                                 const AudioChannelSet& channelLayout,
 190                                                 int bitsPerSample,
 191                                                 const StringPairArray& metadataValues,
 192                                                 int qualityOptionIndex);
 193
 194 protected:
 195     /** Creates an AudioFormat object.
 196
 197         @param formatName       this sets the value that will be returned by getFormatName()
 198         @param fileExtensions   an array of file extensions - these will be returned by getFileExtensions()
 199     */
 200     AudioFormat (String formatName, StringArray fileExtensions);
 201
 202     /** Creates an AudioFormat object.
 203
 204         @param formatName       this sets the value that will be returned by getFormatName()
 205         @param fileExtensions   a whitespace-separated list of file extensions - these will
 206                                 be returned by getFileExtensions()
 207     */
 208     AudioFormat (StringRef formatName, StringRef fileExtensions);
 209
 210 private:
 211     //==============================================================================
 212     String formatName;
 213     StringArray fileExtensions;
 214 };
 215
 216 } // namespace juce