home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / k3baudiodecoder.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-05-27  |  7.2 KB  |  255 lines
  1. /* 
  2.  *
  3.  * $Id: k3baudiodecoder.h 619556 2007-01-03 17:38:12Z trueg $
  4.  * Copyright (C) 2003 Sebastian Trueg <trueg@k3b.org>
  5.  *
  6.  * This file is part of the K3b project.
  7.  * Copyright (C) 1998-2007 Sebastian Trueg <trueg@k3b.org>
  8.  *
  9.  * This program is free software; you can redistribute it and/or modify
  10.  * it under the terms of the GNU General Public License as published by
  11.  * the Free Software Foundation; either version 2 of the License, or
  12.  * (at your option) any later version.
  13.  * See the file "COPYING" for the exact licensing terms.
  14.  */
  15.  
  16. #ifndef _K3B_AUDIO_DECODER_H_
  17. #define _K3B_AUDIO_DECODER_H_
  18.  
  19.  
  20. #include <k3bplugin.h>
  21. #include <k3bmsf.h>
  22. #include "k3b_export.h"
  23. #include <kurl.h>
  24.  
  25.  
  26.  
  27. /**
  28.  * Abstract streaming class for all the audio input.
  29.  * Has to output data in the following format:
  30.  * MSBLeft LSBLeft MSBRight LSBRight (big endian byte order)
  31.  *
  32.  * Instances are created by K3bAudioDecoderFactory
  33.  **/
  34. class LIBK3B_EXPORT K3bAudioDecoder : public QObject
  35. {
  36.   Q_OBJECT
  37.  
  38.  public:
  39.   K3bAudioDecoder( QObject* parent = 0, const char* name = 0 );
  40.   virtual ~K3bAudioDecoder();
  41.  
  42.  
  43.   /**
  44.    * Set the file to decode. Be aware that one cannot rely 
  45.    * on the file length until analyseFile() has been called.
  46.    */
  47.   void setFilename( const QString& );
  48.  
  49.   /**
  50.    * Since this may take a while depending on the filetype it is best
  51.    * to run it in a separate thread.
  52.    *
  53.    * This method will also call initDecoder().
  54.    */
  55.   bool analyseFile();
  56.  
  57.   /**
  58.    * @return true if the file was successfully analysed by analyseFile.
  59.    */
  60.   bool isValid() const;
  61.  
  62.   /**
  63.    * Initialize the decoding.
  64.    * Normally there is no need to call this as analyseFile already does so.
  65.    */
  66.   bool initDecoder();
  67.  
  68.   /**
  69.    * initialize the decoding.
  70.    * @param startOffset the number of frames to skip at the beginning of the file.
  71.    *
  72.    * This is the same as calling: initDecoder() and seek(startOffset)
  73.    */
  74.   bool initDecoder( const K3b::Msf& startOffset );
  75.  
  76.   enum MetaDataField {
  77.     META_TITLE,
  78.     META_ARTIST,
  79.     META_SONGWRITER,
  80.     META_COMPOSER,
  81.     META_COMMENT
  82.   };
  83.  
  84.   /**
  85.    * This should at least support "Title" and "Artist"
  86.    *
  87.    * the default implementation returns the infos set via @p addMetaInfo
  88.    * and uses KFileMetaInfo if none was set
  89.    */ 
  90.   virtual QString metaInfo( MetaDataField );
  91.  
  92.   /**
  93.    * The filetype is only used for informational purposes.
  94.    * It is not necessary but highly recommended to implement this method
  95.    * as it enhances usability.
  96.    * @returne The filetype of the decoded file.
  97.    */
  98.   virtual QString fileType() const { return QString::null; }
  99.  
  100.   /**
  101.    * This method may be reimplemented to provide technical information about
  102.    * the file. It should return localized strings.
  103.    *
  104.    * the default implementation returns the infos set via @p addTechnicalInfo
  105.    */
  106.   virtual QStringList supportedTechnicalInfos() const;
  107.  
  108.   /**
  109.    * The framework will call this method with all strings returned by the
  110.    * supportedTechnicalInfos() method. It should return localized strings.
  111.    *
  112.    * the default implementation returns the infos set via @p addTechnicalInfo
  113.    */
  114.   virtual QString technicalInfo( const QString& ) const;
  115.  
  116.   /**
  117.    * returnes -1 on error, 0 when finished, length of data otherwise
  118.    * takes care of padding
  119.    * calls decodeInternal() to actually decode data
  120.    *
  121.    * Fill the data buffer with maximal maxLen bytes.
  122.    */
  123.   int decode( char* data, int maxLen );
  124.  
  125.   /**
  126.    * Cleanup after decoding like closing files.
  127.    * Be aware that this is the counterpart to @p initDecoder().
  128.    *
  129.    * There might happen multiple calls to initDecoder() and cleanup(). 
  130.    */
  131.   virtual void cleanup();
  132.  
  133.   /**
  134.    * Seek to the position pos.
  135.    * Decoding is started new. That means that the data will be padded to
  136.    * length() - pos.
  137.    * returnes true on success;
  138.    */
  139.   bool seek( const K3b::Msf& pos );
  140.  
  141.   /**
  142.    * Be aware that one cannot rely 
  143.    * on the file length until analyseFile() has been called.
  144.    */
  145.   virtual K3b::Msf length() const { return m_length; }
  146.  
  147.   const QString& filename() const { return m_fileName; }
  148.  
  149.   // some helper methods
  150.   static void fromFloatTo16BitBeSigned( float* src, char* dest, int samples );
  151.   static void from16bitBeSignedToFloat( char* src, float* dest, int samples );
  152.   static void from8BitTo16BitBeSigned( char* src, char* dest, int samples );
  153.  
  154.  protected:
  155.   /**
  156.    * Use this method if using the default implementation of @p metaInfo
  157.    */
  158.   void addMetaInfo( MetaDataField, const QString& );
  159.  
  160.   /**
  161.    * Use this method if using the default implementation of @p technicalInfo
  162.    * and @p supportedTechnicalInfos.
  163.    */
  164.   void addTechnicalInfo( const QString&, const QString& );
  165.  
  166.   /**
  167.    * This will be called once before the first call to decodeInternal.
  168.    * Use it to initialize decoding structures if necessary.
  169.    *
  170.    * There might happen multiple calls to initDecoder() and cleanup(). 
  171.    */
  172.   virtual bool initDecoderInternal() = 0;
  173.  
  174.   /**
  175.    * This method should analyze the file to determine the exact length,
  176.    * the samplerate in Hz, and the number of channels. The framework takes care of
  177.    * resampling and converting mono to stereo data.
  178.    * This method may be time consuming.
  179.    */
  180.   virtual bool analyseFileInternal( K3b::Msf& length, int& samplerate, int& channels ) = 0;
  181.  
  182.   /**
  183.    * fill the already allocated data with maximal maxLen bytes of decoded samples.
  184.    * The framework will take care of padding or cutting the decoded data as well
  185.    * as resampling to 44100 Hz and converting mono samples to stereo.
  186.    */
  187.   virtual int decodeInternal( char* data, int maxLen ) = 0;
  188.  
  189.   virtual bool seekInternal( const K3b::Msf& ) { return false; }
  190.  
  191.  private:
  192.   int resample( char* data, int maxLen );
  193.  
  194.   QString m_fileName;
  195.   K3b::Msf m_length;
  196.  
  197.   class Private;
  198.   Private* d;
  199. };
  200.  
  201.  
  202.  
  203. /**
  204.  * PluginFactory that needs to be subclassed in order to create an
  205.  * audio decoder.
  206.  * We need this because K3b uses multiple AudioDecoders of the same type at the 
  207.  * same time.
  208.  */
  209. class LIBK3B_EXPORT K3bAudioDecoderFactory : public K3bPlugin
  210. {
  211.   Q_OBJECT
  212.  
  213.  public:
  214.   K3bAudioDecoderFactory( QObject* parent = 0, const char* name = 0 )
  215.     : K3bPlugin( parent, name ) {
  216.   }
  217.  
  218.   virtual ~K3bAudioDecoderFactory() {
  219.   }
  220.  
  221.   QString group() const { return "AudioDecoder"; }
  222.  
  223.   /**
  224.    * K3b uses this flag to decide which plugins to test first
  225.    * when searching for an audio decoder.
  226.    *
  227.    * Decoders that are specialized on one format are favored over
  228.    * multi-format-decoders.
  229.    */
  230.   virtual bool multiFormatDecoder() const { return false; }
  231.  
  232.   /**
  233.    * This is the most important method of the AudioDecoderFactory.
  234.    * It is used to determine if a certain file can be decoded by the
  235.    * decoder this factory creates.
  236.    * It is important that this method does not work lazy since it will
  237.    * be called with urls to every kind of files and if it returns true
  238.    * a decoder of this type is used for the file.
  239.    */
  240.   virtual bool canDecode( const KURL& filename ) = 0;
  241.  
  242.   virtual K3bAudioDecoder* createDecoder( QObject* parent = 0, const char* name = 0 ) const = 0;
  243.  
  244.   /**
  245.    * Searching for an audiodecoder for @p filename.
  246.    *
  247.    * It first searches the single format decoder and the the multiformat decoder.
  248.    *
  249.    * @returns a newly created decoder on success and 0 when no decoder could be found.
  250.    */
  251.   static K3bAudioDecoder* createDecoder( const KURL& url );
  252. };
  253.  
  254. #endif
  255.