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         /**begins to fade out the current song*/
 150         virtual void beginFadeOut();
 151          /**
 152          * Get current engine status.
 153          * @return the correct State as described at the enum
 154          */
 155         virtual State state() const = 0;
 156
 157         /** Get time position (msec). */
 158         virtual uint position() const = 0;
 159
 160         /** Get track length (msec). */
 161         virtual uint length() const { return 0; }
 162
 163         /**
 164          * Jump to new time position.
 165          * @param ms New position.
 166          */
 167         virtual void seek( uint ms ) = 0;
 168
 169         /**
 170          * Determines whether media is currently loaded.
 171          * @return True if media is loaded, system is ready to play.
 172          */
 173         inline bool loaded() const { return state() != Empty; }
 174
 175         inline uint volume() const { return m_volume; }
 176
 177         /**
 178          * Fetch the current audio sample buffer.
 179          * @return Audio sample buffer.
 180          */
 181         virtual const Scope &scope() { return m_scope; }
 182
 183         /**
 184          * Set new volume value.
 185          * @param value Volume in range 0 to 100.
 186          */
 187         void setVolume( uint value );
 188
 189         /** Set new crossfade length (msec) */
 190         void setXfadeLength( int value ) { m_xfadeLength = value; }
 191
 192         /** Set whether to crossfade the next track
 193           * Used when the engine is switching tracks automatically
 194           * instead of manually.
 195           */
 196         void setXFadeNextTrack( bool enable ) { m_xfadeNextTrack = enable; }
 197
 198         /** Set whether equalizer is enabled
 199           * You don't need to cache the parameters, setEqualizerParameters is called straight after this
 200           * function, _always_.
 201           */
 202         virtual void setEqualizerEnabled( bool ) {}
 203
 204         /** Set equalizer parameters, all in range -100..100, where 0 = no adjustment
 205           * @param preamp the preamplification value
 206           * @param bandGains a list of 10 integers, ascending in frequency, the exact frequencies you amplify
 207           *                  are not too-important at this time
 208           */
 209         virtual void setEqualizerParameters( int /*preamp*/, const Q3ValueList<int> &/*bandGains*/ ) {}
 210
 211
 212         /** Tries to retrieve metadata for the given url (called only if url
 213          * is not in the collection).  The intended usage is to retrieve
 214          * information for AudiCD tracks when they are added to the playlist
 215          * (i.e. before they are actually played)
 216          * @param url the url of the item
 217          * @param bundle the SimpleMetaBundle to fill
 218          * @return true if metadata found, false otherwise
 219          */
 220         virtual bool metaDataForUrl(const KUrl &, Engine::SimpleMetaBundle &)
 221         { return false; }
 222
 223         /** returns true if this engine performs some special action to play
 224          * audio cds: in this case, the KUrl::List is filled with the urls of
 225          * the songs in the cd...
 226          *
 227          * @param device the cdrom device , with QString::null meaning use engine-specific default value
 228          * @param urls the list of urls for AudioCD tracks to fill
 229          * @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...)
 230          * */
 231         virtual bool getAudioCDContents(const QString &, KUrl::List &)
 232         { return false; }
 233
 234         /** flush the current stream buffer */
 235         virtual bool flushBuffer() { return false; }
 236
 237         /** allow the engine to perform necessary work on changes in the playlist **/
 238         virtual void playlistChanged() { }
 239
 240     protected:
 241         Base();
 242
 243         /** Shows the Amarok configuration dialog at the engine page */
 244         void showEngineConfigDialog() { emit showConfigDialog( "Engine" ); }
 245
 246         virtual void setVolumeSW( uint percent ) = 0;
 247
 248         /** Converts master volume to a logarithmic scale */
 249         static uint makeVolumeLogarithmic( uint volume );
 250
 251         Base( const Base& ); //disable copy constructor
 252         const Base &operator=( const Base& ); //disable copy constructor
 253
 254         int           m_xfadeLength;
 255         bool          m_xfadeNextTrack;
 256
 257     protected:
 258         static const int SCOPESIZE = 1024;
 259         uint  m_volume;
 260         KUrl  m_url;
 261         Scope m_scope;
 262         bool  m_isStream;
 263     };
 264
 265
 266     class SimpleMetaBundle {
 267     public:
 268         QString title;
 269         QString artist;
 270         QString album;
 271         QString comment;
 272         QString genre;
 273         QString bitrate;
 274         QString samplerate;
 275         QString length;
 276         QString year;
 277         QString tracknr;
 278     };
 279 }
 280
 281 #endif