src/enginebase.h

   1 //Copyright: (C) 2003 Mark Kretschmann
   2 //           (C) 2004 Max Howell, <max.howell@methylblue.com>
   3 //License:   See COPYING
   4
   5 #ifndef AMAROK_ENGINEBASE_H
   6 #define AMAROK_ENGINEBASE_H
   7
   8 #include "plugin/plugin.h" //baseclass
   9 #include "amarok_export.h"
  10
  11 #include <kurl.h>
  12
  13 #include <q3valuelist.h>    //stack alloc
  14 #include <QByteArray>
  15 #include <QHash>
  16 #include <QObject>       //baseclass
  17
  18 #include <sys/types.h>
  19 #include <stdint.h>
  20 #include <vector>
  21
  22 /**
  23  * @class Engine::Base
  24  * @author Mark Kretschmann
  25  * @author Max Howell
  26  *
  27  * This is an abstract base class that you need to derive when making your own backends.
  28  * It is typdefed to EngineBase for your conveniece.
  29  *
  30  * The only key thing to get right is what to return from state(), as some Amarok
  31  * behaviour is dependent on you returning the right state at the right time.
  32  *
  33  *   Empty   = No URL loaded and ready to play
  34  *   Idle    = URL ready for play, but not playing, so before AND after playback
  35  *   Playing = Playing a stream
  36  *   Paused  = Stream playback is paused
  37  *
  38  * Not returning idle when you have reached End-Of-Stream but Amarok has not told you
  39  * to stop would be bad because some components behave differently when the engine is
  40  * Empty or not. You are Idle because you still have a URL assigned.
  41  *
  42  * load( KUrl ) is a key function because after this point your engine is loaded, and
  43  * Amarok will expect you to be able to play the URL until stop() or another load() is
  44  * called.
  45  *
  46  * You must handle your own media, do not rely on Amarok to call stop() before play() etc.
  47  *
  48  * At this time, emitting stateChanged( Engine::Idle ) is not necessary, otherwise you should
  49  * let Amarok know of state changes so it updates the UI correctly.
  50  *
  51  * Basically, reimplement everything virtual and ensure you emit stateChanged() correctly,
  52  * try not to block in any function that is called by Amarok, try to keep the user informed
  53  * with emit statusText()
  54  *
  55  * Only canDecode() needs to be thread-safe. Everything else is only called from the GUI thread.
  56  */
  57
  58 #include "engine_fwd.h"
  59
  60
  61 namespace Engine
  62 {
  63     typedef std::vector<int16_t> Scope;
  64     class SimpleMetaBundle;
  65
  66     class AMAROK_EXPORT Base : public QObject, public Amarok::Plugin
  67     {
  68     Q_OBJECT
  69
  70     signals:
  71         /** Emitted when end of current track is reached. */
  72         void trackEnded();
  73
  74         /** Transmits status message, the message disappears after ~2s. */
  75         void statusText( const QString& );
  76
  77         /**
  78          * Shows a long message in a non-invasive manner, you should prefer
  79          * this over KMessageBoxes, but do use KMessageBox when you must
  80          * interrupt the user or the message is very important.
  81          */
  82         void infoMessage( const QString& );
  83
  84         /** Transmits metadata package. */
  85         void metaData( const Engine::SimpleMetaBundle& );
  86
  87         void metaData( const QHash<qint64, QString> &newMetaData );
  88
  89         /** Signals a change in the engine's state. */
  90         void stateChanged( Engine::State );
  91
  92         /** Shows Amarok config dialog at specified page */
  93         void showConfigDialog( const QByteArray& );
  94
  95     public:
  96         virtual ~Base();
  97
  98         /**
  99          * Initializes the engine. Must be called after the engine was loaded.
 100          * @return True if initialization was successful.
 101          */
 102         virtual bool init() = 0;
 103
 104         /**
 105          * Determines if the engine is able to play a given URL.
 106          * @param url The URL of the file/stream.
 107          * @return True if we can play the URL.
 108          */
 109         virtual bool canDecode( const KUrl &url ) const = 0;
 110
 111         /**
 112          * Determines if current track is a stream.
 113          * @return True if track is a stream.
 114          */
 115         inline bool isStream() { return m_isStream; }
 116
 117         /**
 118          * Load new track for playing.
 119          * @param url URL to be played.
 120          * @param stream True if URL is a stream.
 121          * @return True for success.
 122          */
 123         virtual bool load( const KUrl &url, bool stream = false );
 124
 125         /**
 126          * Load new track and start Playback. Convenience function for Amarok to use.
 127          * @param url URL to be played.
 128          * @param stream True if URL is a stream.
 129          * @return True for success.
 130          */
 131         bool play( const KUrl &u, bool stream = false ) { return load( u, stream ) && play(); }
 132
 133         /**
 134          * Start playback.
 135          * @param offset Start playing at @p msec position.
 136          * @return True for success.
 137          */
 138         virtual bool play( uint offset = 0 ) = 0;
 139
 140         /** Stops playback */
 141         virtual void stop() = 0;
 142
 143         /** Pauses playback */
 144         virtual void pause() = 0;
 145
 146         /** Resumes playback if paused */
 147         virtual void unpause() = 0;
 148
 149          /**
 150          * Get current engine status.
 151          * @return the correct State as described at the enum
 152          */
 153         virtual State state() const = 0;
 154
 155         /** Get time position (msec). */
 156         virtual uint position() const = 0;
 157
 158         /** Get track length (msec). */
 159         virtual uint length() const { return 0; }
 160
 161         /**
 162          * Jump to new time position.
 163          * @param ms New position.
 164          */
 165         virtual void seek( uint ms ) = 0;
 166
 167         /**
 168          * Determines whether media is currently loaded.
 169          * @return True if media is loaded, system is ready to play.
 170          */
 171         inline bool loaded() const { return state() != Empty; }
 172
 173         inline uint volume() const { return m_volume; }
 174
 175         /**
 176          * Fetch the current audio sample buffer.
 177          * @return Audio sample buffer.
 178          */
 179         virtual const Scope &scope() { return m_scope; }
 180
 181         /**
 182          * Set new volume value.
 183          * @param value Volume in range 0 to 100.
 184          */
 185         void setVolume( uint value );
 186
 187         /** Set new crossfade length (msec) */
 188         void setXfadeLength( int value ) { m_xfadeLength = value; }
 189
 190         /** Set whether to crossfade the next track
 191           * Used when the engine is switching tracks automatically
 192           * instead of manually.
 193           */
 194         void setXFadeNextTrack( bool enable ) { m_xfadeNextTrack = enable; }
 195
 196         /** Set whether equalizer is enabled
 197           * You don't need to cache the parameters, setEqualizerParameters is called straight after this
 198           * function, _always_.
 199           */
 200         virtual void setEqualizerEnabled( bool ) {}
 201
 202         /** Set equalizer parameters, all in range -100..100, where 0 = no adjustment
 203           * @param preamp the preamplification value
 204           * @param bandGains a list of 10 integers, ascending in frequency, the exact frequencies you amplify
 205           *                  are not too-important at this time
 206           */
 207         virtual void setEqualizerParameters( int /*preamp*/, const Q3ValueList<int> &/*bandGains*/ ) {}
 208
 209
 210         /** Tries to retrieve metadata for the given url (called only if url
 211          * is not in the collection).  The intended usage is to retrieve
 212          * information for AudiCD tracks when they are added to the playlist
 213          * (i.e. before they are actually played)
 214          * @param url the url of the item
 215          * @param bundle the SimpleMetaBundle to fill
 216          * @return true if metadata found, false otherwise
 217          */
 218         virtual bool metaDataForUrl(const KUrl &, Engine::SimpleMetaBundle &)
 219         { return false; }
 220
 221         /** returns true if this engine performs some special action to play
 222          * audio cds: in this case, the KUrl::List is filled with the urls of
 223          * the songs in the cd...
 224          *
 225          * @param device the cdrom device , with QString::null meaning use engine-specific default value
 226          * @param urls the list of urls for AudioCD tracks to fill
 227          * @return true if the engine has the feature of reading from audio cds, false otherwise (note that this should return true also in case of error if the engine is capable of reading audio cds in general...)
 228          * */
 229         virtual bool getAudioCDContents(const QString &, KUrl::List &)
 230         { return false; }
 231
 232         /** flush the current stream buffer */
 233         virtual bool flushBuffer() { return false; }
 234
 235         /** allow the engine to perform necessary work on changes in the playlist **/
 236         virtual void playlistChanged() { }
 237
 238     protected:
 239         Base();
 240
 241         /** Shows the Amarok configuration dialog at the engine page */
 242         void showEngineConfigDialog() { emit showConfigDialog( "Engine" ); }
 243
 244         virtual void setVolumeSW( uint percent ) = 0;
 245
 246         /** Converts master volume to a logarithmic scale */
 247         static uint makeVolumeLogarithmic( uint volume );
 248
 249         Base( const Base& ); //disable copy constructor
 250         const Base &operator=( const Base& ); //disable copy constructor
 251
 252         int           m_xfadeLength;
 253         bool          m_xfadeNextTrack;
 254
 255     protected:
 256         static const int SCOPESIZE = 1024;
 257         uint  m_volume;
 258         KUrl  m_url;
 259         Scope m_scope;
 260         bool  m_isStream;
 261     };
 262
 263
 264     class SimpleMetaBundle {
 265     public:
 266         QString title;
 267         QString artist;
 268         QString album;
 269         QString comment;
 270         QString genre;
 271         QString bitrate;
 272         QString samplerate;
 273         QString length;
 274         QString year;
 275         QString tracknr;
 276     };
 277 }
 278
 279 #endif