Chris@148: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@148: 
Chris@148: /*
Chris@148:     Sonic Visualiser
Chris@148:     An audio file viewer and annotation editor.
Chris@148:     Centre for Digital Music, Queen Mary, University of London.
Chris@148:     This file copyright 2006 Chris Cannam.
Chris@148:     
Chris@148:     This program is free software; you can redistribute it and/or
Chris@148:     modify it under the terms of the GNU General Public License as
Chris@148:     published by the Free Software Foundation; either version 2 of the
Chris@148:     License, or (at your option) any later version.  See the file
Chris@148:     COPYING included with this distribution for more information.
Chris@148: */
Chris@148: 
Chris@1098: #ifndef AUDIO_FILE_READER_FACTORY_H
Chris@1098: #define AUDIO_FILE_READER_FACTORY_H
Chris@148: 
Chris@290: #include <QString>
Chris@148: 
Chris@317: #include "FileSource.h"
Chris@1040: #include "base/BaseTypes.h"
Chris@316: 
Chris@148: class AudioFileReader;
Chris@392: class ProgressReporter;
Chris@148: 
Chris@148: class AudioFileReaderFactory
Chris@148: {
Chris@148: public:
Chris@148:     /**
Chris@148:      * Return the file extensions that we have audio file readers for,
Chris@148:      * in a format suitable for use with QFileDialog.  For example,
Chris@148:      * "*.wav *.aiff *.ogg".
Chris@148:      */
Chris@290:     static QString getKnownExtensions();
Chris@148: 
Chris@1313:     enum class Normalisation {
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Do not normalise file data.
Chris@1313:          */
Chris@1313:         None,
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Normalise file data to abs(max) == 1.0.
Chris@1313:          */
Chris@1313:         Peak
Chris@1313:     };
Chris@1313: 
Chris@1313:     enum class GaplessMode {
Chris@1313: 
Chris@1313:         /** 
Chris@1313:          * Any encoder delay and padding found in file metadata will
Chris@1313:          * be compensated for, giving gapless decoding (assuming the
Chris@1313:          * metadata are correct). This is currently only applicable to
Chris@1313:          * mp3 files: all other supported files are always gapless
Chris@1313:          * where the file metadata provides for it. See documentation
Chris@1313:          * for MP3FileReader::GaplessMode for details of the specific
Chris@1313:          * implementation.
Chris@1313:          */
Chris@1313:         Gapless,
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * No delay compensation will happen and the results will be
Chris@1313:          * equivalent to the behaviour of audio readers before the
Chris@1313:          * compensation logic was implemented. This is currently only
Chris@1313:          * applicable to mp3 files: all other supported files are
Chris@1313:          * always gapless where the file metadata provides for it. See
Chris@1313:          * documentation for MP3FileReader::GaplessMode for details of
Chris@1313:          * the specific implementation.
Chris@1313:          */
Chris@1313:         Gappy
Chris@1313:     };
Chris@1313: 
Chris@1313:     enum class ThreadingMode {
Chris@1313:         
Chris@1313:         /** 
Chris@1313:          * Any necessary decoding will happen synchronously when the
Chris@1313:          * reader is created.
Chris@1313:          */
Chris@1313:         NotThreaded,
Chris@1313:         
Chris@1313:         /**        
Chris@1313:          * If the reader supports threaded decoding, it will be used
Chris@1313:          * and the file will be decoded in a background thread. If the
Chris@1313:          * reader does not support threaded decoding, behaviour will
Chris@1313:          * be as for NotThreaded.
Chris@1313:          */
Chris@1313:         Threaded
Chris@1313:     };
Chris@1313: 
Chris@1313:     struct Parameters {
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Sample rate to open the file at. If zero (the default), the
Chris@1313:          * file's native rate will be used. If non-zero, the file will
Chris@1313:          * be automatically resampled to that rate.  You can query
Chris@1313:          * reader->getNativeRate() if you want to find out whether the
Chris@1313:          * file needed to be resampled.
Chris@1313:          */
Chris@1313:         sv_samplerate_t targetRate;
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Normalisation to use. The default is Normalisation::None.
Chris@1313:          */
Chris@1313:         Normalisation normalisation;
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Gapless mode to use. The default is GaplessMode::Gapless.
Chris@1313:          */
Chris@1313:         GaplessMode gaplessMode;
Chris@1313: 
Chris@1313:         /**
Chris@1313:          * Threading mode. The default is ThreadingMode::NotThreaded.
Chris@1313:          */
Chris@1313:         ThreadingMode threadingMode;
Chris@1313:         
Chris@1313:         Parameters() :
Chris@1313:             targetRate(0),
Chris@1313:             normalisation(Normalisation::None),
Chris@1313:             gaplessMode(GaplessMode::Gapless),
Chris@1313:             threadingMode(ThreadingMode::NotThreaded)
Chris@1313:         { }
Chris@1313:     };
Chris@1313:     
Chris@148:     /**
Chris@148:      * Return an audio file reader initialised to the file at the
Chris@148:      * given path, or NULL if no suitable reader for this path is
Chris@148:      * available or the file cannot be opened.
Chris@297:      *
Chris@392:      * If a ProgressReporter is provided, it will be updated with
Chris@1313:      * progress status. This will only be meaningful if decoding is
Chris@1313:      * being carried out in non-threaded mode (either because the
Chris@1313:      * threaded parameter was not supplied or because the specific
Chris@1313:      * file reader used does not support it); in threaded mode,
Chris@1313:      * reported progress will jump straight to 100% before threading
Chris@1313:      * takes over. Caller retains ownership of the reporter object.
Chris@392:      *
Chris@148:      * Caller owns the returned object and must delete it after use.
Chris@148:      */
Chris@327:     static AudioFileReader *createReader(FileSource source,
Chris@1313:                                          Parameters parameters,
Chris@392:                                          ProgressReporter *reporter = 0);
Chris@1592: 
Chris@1592:     /**
Chris@1592:      * Return true if the given source has a file extension that
Chris@1592:      * indicates a supported file type. This does not necessarily mean
Chris@1592:      * that it can be opened; conversely it may theoretically be
Chris@1592:      * possible to open some files without supported extensions,
Chris@1592:      * depending on the readers available.
Chris@1592:      */
Chris@1592:     static bool isSupported(FileSource source);
Chris@148: };
Chris@148: 
Chris@148: #endif
Chris@148: