source/modules/juce_audio_formats/format/juce_AudioFormatManager.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     A class for keeping a list of available audio formats, and for deciding which
  32     one to use to open a given file.
  33
  34     After creating an AudioFormatManager object, you should call registerFormat()
  35     or registerBasicFormats() to give it a list of format types that it can use.
  36
  37     @see AudioFormat
  38
  39     @tags{Audio}
  40 */
  41 class JUCE_API  AudioFormatManager
  42 {
  43 public:
  44     //==============================================================================
  45     /** Creates an empty format manager.
  46
  47         Before it'll be any use, you'll need to call registerFormat() with all the
  48         formats you want it to be able to recognise.
  49     */
  50     AudioFormatManager();
  51
  52     /** Destructor. */
  53     ~AudioFormatManager();
  54
  55     //==============================================================================
  56     /** Adds a format to the manager's list of available file types.
  57
  58         The object passed-in will be deleted by this object, so don't keep a pointer
  59         to it!
  60
  61         If makeThisTheDefaultFormat is true, then the getDefaultFormat() method will
  62         return this one when called.
  63     */
  64     void registerFormat (AudioFormat* newFormat,
  65                          bool makeThisTheDefaultFormat);
  66
  67     /** Handy method to make it easy to register the formats that come with JUCE.
  68         This will add WAV and AIFF to the list, along with any other formats enabled
  69         in either the Projucer or your application's preprocessor definitions.
  70     */
  71     void registerBasicFormats();
  72
  73     /** Clears the list of known formats. */
  74     void clearFormats();
  75
  76     /** Returns the number of currently registered file formats. */
  77     int getNumKnownFormats() const;
  78
  79     /** Returns one of the registered file formats. */
  80     AudioFormat* getKnownFormat (int index) const;
  81
  82     /** Iterator access to the list of known formats. */
  83     AudioFormat** begin() noexcept                       { return knownFormats.begin(); }
  84
  85     /** Iterator access to the list of known formats. */
  86     AudioFormat* const* begin() const noexcept           { return knownFormats.begin(); }
  87
  88     /** Iterator access to the list of known formats. */
  89     AudioFormat** end() noexcept                         { return knownFormats.end(); }
  90
  91     /** Iterator access to the list of known formats. */
  92     AudioFormat* const* end() const noexcept             { return knownFormats.end(); }
  93
  94     /** Looks for which of the known formats is listed as being for a given file
  95         extension.
  96
  97         The extension may have a dot before it, so e.g. ".wav" or "wav" are both ok.
  98     */
  99     AudioFormat* findFormatForFileExtension (const String& fileExtension) const;
 100
 101     /** Returns the format which has been set as the default one.
 102
 103         You can set a format as being the default when it is registered. It's useful
 104         when you want to write to a file, because the best format may change between
 105         platforms, e.g. AIFF is preferred on the Mac, WAV on Windows.
 106
 107         If none has been set as the default, this method will just return the first
 108         one in the list.
 109     */
 110     AudioFormat* getDefaultFormat() const;
 111
 112     /** Returns a set of wildcards for file-matching that contains the extensions for
 113         all known formats.
 114
 115         E.g. if might return "*.wav;*.aiff" if it just knows about wavs and aiffs.
 116     */
 117     String getWildcardForAllFormats() const;
 118
 119     //==============================================================================
 120     /** Searches through the known formats to try to create a suitable reader for
 121         this file.
 122
 123         If none of the registered formats can open the file, it'll return nullptr.
 124         It's the caller's responsibility to delete the reader that is returned.
 125     */
 126     AudioFormatReader* createReaderFor (const File& audioFile);
 127
 128     /** Searches through the known formats to try to create a suitable reader for
 129         this stream.
 130
 131         The stream object that is passed-in will be deleted by this method or by the
 132         reader that is returned, so the caller should not keep any references to it.
 133
 134         The stream that is passed-in must be capable of being repositioned so
 135         that all the formats can have a go at opening it.
 136
 137         If none of the registered formats can open the stream, it'll return nullptr.
 138         If it returns a reader, it's the caller's responsibility to delete the reader.
 139     */
 140     AudioFormatReader* createReaderFor (std::unique_ptr<InputStream> audioFileStream);
 141
 142 private:
 143     //==============================================================================
 144     OwnedArray<AudioFormat> knownFormats;
 145     int defaultFormatIndex = 0;
 146
 147     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatManager)
 148 };
 149
 150 } // namespace juce