File indexing completed on 2024-06-16 04:33:42

0001 /*
0002     SPDX-FileCopyrightText: 2010 Michal Malek <michalm@jabster.pl>
0003     SPDX-FileCopyrightText: 1998-2008 Sebastian Trueg <trueg@k3b.org>
0004 
0005     SPDX-License-Identifier: GPL-2.0-or-later
0006 */
0007 
0008 #ifndef _K3B_AUDIO_ENCODER_H_
0009 #define _K3B_AUDIO_ENCODER_H_
0010 
0011 #include "k3bplugin.h"
0012 
0013 #include "k3bmsf.h"
0014 #include "k3b_export.h"
0015 
0016 #include <QHash>
0017 
0018 
0019 namespace K3b {
0020     /**
0021      * The base class for all audio encoders.
0022      * Do not be alarmed by the number of methods since most of them
0023      * do not need to be touched. They are just there to keep the API
0024      * clean and extendable.
0025      *
0026      * see the skeleton files for further help.
0027      */
0028     class LIBK3B_EXPORT AudioEncoder : public Plugin
0029     {
0030         Q_OBJECT
0031 
0032     public:
0033         explicit AudioEncoder( QObject* parent = 0 );
0034         ~AudioEncoder() override;
0035 
0036         // TODO: if the following methods are to be activated the config methods in
0037         //       PluginConfigWidget also need to be changed since they do not allow
0038         //       to use an extern config object yet.
0039         //       Perhaps these two methods should even go into Plugin.
0040         /**
0041          * This calls readConfig using the k3bcore config object
0042          */
0043         // void readConfig();
0044 
0045         /**
0046          * Force the plugin to read it's configuration
0047          */
0048         // virtual void readConfig( KConfig* );
0049 
0050         QString category() const override { return "AudioEncoder"; }
0051 
0052         QString categoryName() const override;
0053 
0054         /**
0055          * This should return the fileextensions supported by the filetype written in the
0056          * encoder.
0057          * May return an empty list in which case the encoder will not be usable (this may come
0058          * in handy if the encoder is based on some external program or lib which is not
0059          * available on runtime.)
0060          */
0061         virtual QStringList extensions() const = 0;
0062 
0063         /**
0064          * The filetype as presented to the user.
0065          */
0066         virtual QString fileTypeComment( const QString& extension ) const = 0;
0067 
0068         /**
0069          * Determine the filesize of the encoded file (~)
0070          * default implementation returns -1 (unknown)
0071          * First parameter is the extension to be used
0072          */
0073         virtual long long fileSize( const QString&, const Msf& ) const { return -1; }
0074 
0075         enum MetaDataField {
0076             META_TRACK_TITLE,
0077             META_TRACK_ARTIST,
0078             META_TRACK_COMMENT,
0079             META_TRACK_NUMBER,
0080             META_ALBUM_TITLE,
0081             META_ALBUM_ARTIST,
0082             META_ALBUM_COMMENT,
0083             META_YEAR,
0084             META_GENRE };
0085 
0086         typedef QHash<MetaDataField, QVariant> MetaData;
0087 
0088         /**
0089          * The default implementation opens the file for writing with
0090          * writeData. Normally this does not need to be reimplemented.
0091          * @param extension the filetype to be used.
0092          * @param filename path to an output file
0093          * @param length length of the track
0094          * @param metaData meta data associated with the track
0095          */
0096         virtual bool openFile( const QString& extension,
0097                                const QString& filename,
0098                                const Msf& length,
0099                                const MetaData& metaData );
0100 
0101 
0102         /**
0103          * The default implementation returns true if openFile (default implementation) has been
0104          * successfully called. Normally this does not need to be reimplemented but it has to be
0105          * if openFile is reimplemented.
0106          */
0107         virtual bool isOpen() const;
0108 
0109         /**
0110          * The default implementation closes the file opened by openFile
0111          * (default implementation)
0112          * Normally this does not need to be reimplemented but it has to be
0113          * if openFile is reimplemented.
0114          */
0115         virtual void closeFile();
0116 
0117         /**
0118          * The default implementation returns the filename set in openFile
0119          * or QString() if no file has been opened.
0120          * Normally this does not need to be reimplemented but it has to be
0121          * if openFile is reimplemented.
0122          */
0123         virtual QString filename() const;
0124 
0125         /**
0126          * Returns the amount of actually written bytes or -1 if an error
0127          * occurred.
0128          *
0129          * Be aware that the returned amount of written data may very well differ
0130          * from len since the data is encoded.
0131          */
0132         qint64 encode( const char*, qint64 len );
0133 
0134         /**
0135          * Use this signal in case of an error to provide the user with information
0136          * about the problem.
0137          */
0138         virtual QString lastErrorString() const;
0139 
0140     protected:
0141         /**
0142          * Called by the default implementation of openFile
0143          * This calls initEncoderInternal.
0144          */
0145         bool initEncoder( const QString& extension, const Msf& length, const MetaData& metaData );
0146 
0147         /**
0148          * Called by the default implementation of openFile
0149          * This calls finishEncoderInternal.
0150          */
0151         void finishEncoder();
0152 
0153         /**
0154          * Use this to write the data to the file when
0155          * using the default implementation of openFile
0156          * Returns the number of bytes actually written.
0157          */
0158         qint64 writeData( const char*, qint64 len );
0159 
0160         /**
0161          * initzialize the decoder structures.
0162          * default implementation does nothing
0163          * this may already write data.
0164          */
0165         virtual bool initEncoderInternal( const QString& extension, const Msf& length, const MetaData& metaData );
0166 
0167         /**
0168          * reimplement this if the encoder needs to do some
0169          * finishing touch.
0170          */
0171         virtual void finishEncoderInternal();
0172 
0173         /**
0174          * encode the data and write it with writeData (when using
0175          * the default)
0176          * The data will always be 16bit 44100 Hz stereo little endian samples.
0177          * Should return the amount of actually written bytes (may be 0) and -1
0178          * on error.
0179          */
0180         // TODO: use qint16* instead of char*
0181         // FIXME: why little endian while CDs use big endian???
0182         virtual qint64 encodeInternal( const char*, qint64 len ) = 0;
0183 
0184         /**
0185          * Use this in combination with the default implementation of lastError()
0186          */
0187         void setLastError( const QString& );
0188 
0189     private:
0190         class Private;
0191         Private* d;
0192     };
0193 }
0194 
0195 #endif