Audacious $Id:Doxyfile42802007-03-2104:39:00Znenolod$
plugin.h
Go to the documentation of this file.
00001 /*
00002  * plugin.h
00003  * Copyright 2005-2010 Audacious Development Team
00004  *
00005  * This file is part of Audacious.
00006  *
00007  * Audacious is free software: you can redistribute it and/or modify it under
00008  * the terms of the GNU General Public License as published by the Free Software
00009  * Foundation, version 2 or version 3 of the License.
00010  *
00011  * Audacious is distributed in the hope that it will be useful, but WITHOUT ANY
00012  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
00013  * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * Audacious. If not, see <http://www.gnu.org/licenses/>.
00017  *
00018  * The Audacious team does not consider modular code linking to Audacious or
00019  * using our public API to be a derived work.
00020  */
00021 
00022 #ifndef AUDACIOUS_PLUGIN_H
00023 #define AUDACIOUS_PLUGIN_H
00024 
00025 #include <glib.h>
00026 #include <gmodule.h>
00027 
00028 #include <audacious/api.h>
00029 #include <audacious/types.h>
00030 #include <libaudcore/audio.h>
00031 #include <libaudcore/index.h>
00032 #include <libaudcore/tuple.h>
00033 #include <libaudcore/vfs.h>
00034 
00035 /* "Magic" bytes identifying an Audacious plugin header. */
00036 #define _AUD_PLUGIN_MAGIC 0x8EAC8DE2
00037 
00038 /* API version.  Plugins are marked with this number at compile time.
00039  *
00040  * _AUD_PLUGIN_VERSION is the current version; _AUD_PLUGIN_VERSION_MIN is
00041  * the oldest one we are backward compatible with.  Plugins marked older than
00042  * _AUD_PLUGIN_VERSION_MIN or newer than _AUD_PLUGIN_VERSION are not loaded.
00043  *
00044  * Before releases that add new pointers to the end of the API tables, increment
00045  * _AUD_PLUGIN_VERSION but leave _AUD_PLUGIN_VERSION_MIN the same.
00046  *
00047  * Before releases that break backward compatibility (e.g. remove pointers from
00048  * the API tables), increment _AUD_PLUGIN_VERSION *and* set
00049  * _AUD_PLUGIN_VERSION_MIN to the same value. */
00050 
00051 #define _AUD_PLUGIN_VERSION_MIN 31 /* 3.0-alpha2 */
00052 #define _AUD_PLUGIN_VERSION     31
00053 
00054 /* A NOTE ON THREADS
00055  *
00056  * How thread-safe a plugin must be depends on the type of plugin.  Note that
00057  * some parts of the Audacious API are *not* thread-safe and therefore cannot be
00058  * used in some parts of some plugins; for example, input plugins cannot use
00059  * GUI-related calls or access the playlist except in about() and configure().
00060  *
00061  * Thread-safe plugins: transport, playlist, input, effect, and output.  These
00062  * must be mostly thread-safe.  init() and cleanup() may be called from
00063  * secondary threads; however, no other functions provided by the plugin will be
00064  * called at the same time.  about() and configure() will be called only from
00065  * the main thread.  All other functions provided by the plugin may be called
00066  * from any thread and from multiple threads simultaneously.
00067  *
00068  * Exceptions:
00069  * - Because many existing input plugins are not coded to handle simultaneous
00070  *   calls to play(), play() will only be called from one thread at a time.  New
00071  *   plugins should not rely on this exception, though.
00072  * - Some combinations of calls, especially for output and effect plugins, make
00073  *   no sense; for example, flush() in an output plugin will only be called
00074  *   after open_audio() and before close_audio().
00075  *
00076  * Single-thread plugins: visualization, general, and interface.  Functions
00077  * provided by these plugins will only be called from the main thread. */
00078 
00079 #define PLUGIN_COMMON_FIELDS \
00080     gint magic; /* checked against _AUD_PLUGIN_MAGIC */ \
00081     gint version; /* checked against _AUD_PLUGIN_VERSION */ \
00082     gint type; /* PLUGIN_TYPE_XXX */ \
00083     gint size; /* size in bytes of the struct */ \
00084     const gchar * name; \
00085     gboolean (* init) (void); \
00086     void (* cleanup) (void); \
00087     void (* about) (void); \
00088     void (* configure) (void); \
00089     PluginPreferences * settings;
00090 
00091 struct _Plugin
00092 {
00093     PLUGIN_COMMON_FIELDS
00094 };
00095 
00096 struct _TransportPlugin
00097 {
00098     PLUGIN_COMMON_FIELDS
00099     const gchar * const * schemes; /* array ending with NULL */
00100     const VFSConstructor * vtable;
00101 };
00102 
00103 struct _PlaylistPlugin
00104 {
00105     PLUGIN_COMMON_FIELDS
00106         const gchar * const * extensions; /* array ending with NULL */
00107         gboolean (* load) (const gchar * path, VFSFile * file, gchar * * title,
00108      struct index * filenames, /* of (gchar *) */
00109      struct index * tuples); /* of (Tuple *) */
00110         gboolean (* save) (const gchar * path, VFSFile * file, const gchar * title,
00111      struct index * filenames, /* of (gchar *) */
00112      struct index * tuples); /* of (Tuple *) */
00113 };
00114 
00115 struct _OutputPlugin
00116 {
00117     PLUGIN_COMMON_FIELDS
00118 
00119     /* During probing, plugins with higher priority (10 to 0) are tried first. */
00120     gint probe_priority;
00121 
00122     /* Returns current volume for left and right channels (0 to 100). */
00123     void (* get_volume) (gint * l, gint * r);
00124 
00125     /* Changes volume for left and right channels (0 to 100). */
00126     void (* set_volume) (gint l, gint r);
00127 
00128     /* Begins playback of a PCM stream.  <format> is one of the FMT_*
00129      * enumeration values defined in libaudcore/audio.h.  Returns nonzero on
00130      * success. */
00131     gboolean (* open_audio) (gint format, gint rate, gint chans);
00132 
00133     /* Ends playback.  Any buffered audio data is discarded. */
00134     void (* close_audio) (void);
00135 
00136     /* Returns how many bytes of data may be passed to a following write_audio()
00137      * call.  NULL if the plugin supports only blocking writes (not recommended). */
00138     gint (* buffer_free) (void);
00139 
00140     /* Waits until buffer_free() will return a size greater than zero.
00141      * output_time(), pause(), and flush() may be called meanwhile; if flush()
00142      * is called, period_wait() should return immediately.  NULL if the plugin
00143      * supports only blocking writes (not recommended). */
00144     void (* period_wait) (void);
00145 
00146     /* Buffers <size> bytes of data, in the format given to open_audio(). */
00147     void (* write_audio) (void * data, gint size);
00148 
00149     /* Waits until all buffered data has been heard by the user. */
00150     void (* drain) (void);
00151 
00152     /* Returns time count (in milliseconds) of how much data has been written. */
00153     gint (* written_time) (void);
00154 
00155     /* Returns time count (in milliseconds) of how much data has been heard by
00156      * the user. */
00157     gint (* output_time) (void);
00158 
00159     /* Pauses the stream if <p> is nonzero; otherwise unpauses it.
00160      * write_audio() will not be called while the stream is paused. */
00161     void (* pause) (gboolean p);
00162 
00163     /* Discards any buffered audio data and sets the time counter (in
00164      * milliseconds) of data written. */
00165     void (* flush) (gint time);
00166 
00167     /* Sets the time counter (in milliseconds) of data written without
00168      * discarding any buffered audio data.  If <time> is less than the amount of
00169      * buffered data, following calls to output_time() will return negative
00170      * values. */
00171     void (* set_written_time) (gint time);
00172 };
00173 
00174 struct _EffectPlugin
00175 {
00176     PLUGIN_COMMON_FIELDS
00177 
00178     /* All processing is done in floating point.  If the effect plugin wants to
00179      * change the channel count or sample rate, it can change the parameters
00180      * passed to start().  They cannot be changed in the middle of a song. */
00181     void (* start) (gint * channels, gint * rate);
00182 
00183     /* process() has two options: modify the samples in place and leave the data
00184      * pointer unchanged or copy them into a buffer of its own.  If it sets the
00185      * pointer to dynamically allocated memory, it is the plugin's job to free
00186      * that memory.  process() may return different lengths of audio than it is
00187      * passed, even a zero length. */
00188     void (* process) (gfloat * * data, gint * samples);
00189 
00190     /* A seek is taking place; any buffers should be discarded. */
00191     void (* flush) (void);
00192 
00193     /* Exactly like process() except that any buffers should be drained (i.e.
00194      * the data processed and returned).  finish() will be called a second time
00195      * at the end of the last song in the playlist. */
00196     void (* finish) (gfloat * * data, gint * samples);
00197 
00198     /* For effects that change the length of the song, these functions allow the
00199      * correct time to be displayed. */
00200     gint (* decoder_to_output_time) (gint time);
00201     gint (* output_to_decoder_time) (gint time);
00202 
00203     /* Effects with lowest order (0 to 9) are applied first. */
00204     gint order;
00205 
00206     /* If the effect does not change the number of channels or the sampling
00207      * rate, it can be enabled and disabled more smoothly. */
00208     gboolean preserves_format;
00209 };
00210 
00211 struct OutputAPI
00212 {
00213     /* In a multi-thread plugin, only one of these functions may be called at
00214      * once (but see pause and abort_write for exceptions to this rule). */
00215 
00216     /* Prepare the output system for playback in the specified format.  Returns
00217      * nonzero on success.  If the call fails, no other output functions may be
00218      * called. */
00219     gint (* open_audio) (gint format, gint rate, gint channels);
00220 
00221     /* Informs the output system of replay gain values for the current song so
00222      * that volume levels can be adjusted accordingly, if the user so desires.
00223      * This may be called at any time during playback should the values change. */
00224     void (* set_replaygain_info) (ReplayGainInfo * info);
00225 
00226     /* Pass audio data to the output system for playback.  The data must be in
00227      * the format passed to open_audio, and the length (in bytes) must be an
00228      * integral number of frames.  This function blocks until all the data has
00229      * been written (though it may not yet be heard by the user); if the output
00230      * system is paused; this may be indefinitely.  See abort_write for a way to
00231      * interrupt a blocked call. */
00232     void (* write_audio) (void * data, gint length);
00233 
00234     /* End playback.  Any audio data currently buffered by the output system
00235      * will be discarded.  After the call, no other output functions, except
00236      * open_audio, may be called. */
00237     void (* close_audio) (void);
00238 
00239     /* Pause or unpause playback.  This function may be called during a call to
00240      * write_audio, in which write_audio will block until playback is unpaused
00241      * (but see abort_write to prevent the call from blocking). */
00242     void (* pause) (gboolean pause);
00243 
00244     /* Discard any audio data currently buffered by the output system, and set
00245      * the time counter to a new value.  This function is intended to be used
00246      * for seeking. */
00247     void (* flush) (gint time);
00248 
00249     /* Returns the time counter.  Note that this represents the amount of audio
00250      * data passed to the output system, not the amount actually heard by the
00251      * user.  This function is useful for handling a changed audio format:
00252      * First, save the time counter using this function.  Second, call
00253      * close_audio and then open_audio with the new format (note that the call
00254      * may fail).  Finally, restore the time counter using flush. */
00255     gint (* written_time) (void);
00256 
00257     /* Returns TRUE if there is data remaining in the output buffer; FALSE if
00258      * all data written to the output system has been heard by the user.  This
00259      * function should be polled (1/50 second is a reasonable delay between
00260      * calls) at the end of a song before calling close_audio.  Once it returns
00261      * FALSE, close_audio can be called without cutting off any of the end of
00262      * the song. */
00263     gboolean (* buffer_playing) (void);
00264 
00265     /* Interrupt a call to write_audio so that it returns immediately.  This
00266      * works even when the call is blocked by pause.  Buffered audio data is
00267      * discarded as in flush.  Until flush is called or the output system is
00268      * reset, further calls to write_audio will have no effect and return
00269      * immediately.  This function is intended to be used in seeking or
00270      * stopping in a multi-thread plugin.  To seek, the handler function (called
00271      * in the main thread) should first set a flag for the decoding thread and
00272      * then call abort_write.  When the decoding thread notices the flag, it
00273      * should do the actual seek, call flush, and finally clear the flag.  Once
00274      * the flag is cleared, the handler function may return. */
00275     void (* abort_write) (void);
00276 };
00277 
00278 typedef const struct _InputPlayback InputPlayback;
00279 
00280 struct _InputPlayback
00281 {
00282     /* Pointer to the output API functions. */
00283     const struct OutputAPI * output;
00284 
00285     /* Allows the plugin to associate data with a playback instance. */
00286     void (* set_data) (InputPlayback * p, void * data);
00287 
00288     /* Returns the pointer passed to set_data. */
00289     void * (* get_data) (InputPlayback * p);
00290 
00291     /* Signifies that the plugin has started playback is ready to accept mseek,
00292      * pause, and stop calls. */
00293     void (* set_pb_ready) (InputPlayback * p);
00294 
00295     /* Updates attributes of the stream.  "bitrate" is in bits per second.
00296      * "samplerate" is in hertz. */
00297     void (* set_params) (InputPlayback * p, gint bitrate, gint samplerate,
00298      gint channels);
00299 
00300     /* Updates metadata for the stream.  Caller gives up ownership of one
00301      * reference to the tuple. */
00302     void (* set_tuple) (InputPlayback * playback, Tuple * tuple);
00303 
00304     /* If replay gain settings are stored in the tuple associated with the
00305      * current song, this function can be called (after opening audio) to apply
00306      * those settings.  If the settings are changed in a call to set_tuple, this
00307      * function must be called again to apply the updated settings. */
00308     void (* set_gain_from_playlist) (InputPlayback * playback);
00309 };
00310 
00311 struct _InputPlugin
00312 {
00313     PLUGIN_COMMON_FIELDS
00314 
00315     /* Nonzero if the files handled by the plugin may contain more than one
00316      * song.  When reading the tuple for such a file, the plugin should set the
00317      * FIELD_SUBSONG_NUM field to the number of songs in the file.  For all
00318      * other files, the field should be left unset.
00319      *
00320      * Example:
00321      * 1. User adds a file named "somefile.xxx" to the playlist.  Having
00322      * determined that this plugin can handle the file, Audacious opens the file
00323      * and calls probe_for_tuple().  probe_for_tuple() sees that there are 3
00324      * songs in the file and sets FIELD_SUBSONG_NUM to 3.
00325      * 2. For each song in the file, Audacious opens the file and calls
00326      * probe_for_tuple() -- this time, however, a question mark and song number
00327      * are appended to the file name passed: "somefile.sid?2" refers to the
00328      * second song in the file "somefile.sid".
00329      * 3. When one of the songs is played, Audacious opens the file and calls
00330      * play() with a file name modified in this way.
00331      */
00332     gboolean have_subtune;
00333 
00334     /* Pointer to an array (terminated with NULL) of file extensions associated
00335      * with file types the plugin can handle. */
00336     const gchar * const * extensions;
00337     /* Pointer to an array (terminated with NULL) of MIME types the plugin can
00338      * handle. */
00339     const gchar * const * mimes;
00340     /* Pointer to an array (terminated with NULL) of custom URI schemes the
00341      * plugin can handle. */
00342     const gchar * const * schemes;
00343 
00344     /* How quickly the plugin should be tried in searching for a plugin to
00345      * handle a file which could not be identified from its extension.  Plugins
00346      * with priority 0 are tried first, 10 last. */
00347     gint priority;
00348 
00349     /* Must return nonzero if the plugin can handle this file.  If the file
00350      * could not be opened, "file" will be NULL.  (This is normal in the case of
00351      * special URI schemes like cdda:// that do not represent actual files.) */
00352     gboolean (* is_our_file_from_vfs) (const gchar * filename, VFSFile * file);
00353 
00354     /* Must return a tuple containing metadata for this file, or NULL if no
00355      * metadata could be read.  If the file could not be opened, "file" will be
00356      * NULL.  Audacious takes over one reference to the tuple returned. */
00357     Tuple * (* probe_for_tuple) (const gchar * filename, VFSFile * file);
00358 
00359     /* Optional.  Must write metadata from a tuple to this file.  Must return
00360      * nonzero on success or zero on failure.  "file" will never be NULL. */
00361     /* Bug: This function does not support special URI schemes like cdda://,
00362      * since no file name is passed. */
00363     gboolean (* update_song_tuple) (const Tuple * tuple, VFSFile * file);
00364 
00365     /* Optional, and not recommended.  Must show a window with information about
00366      * this file.  If this function is provided, update_song_tuple should not be. */
00367     /* Bug: Implementing this function duplicates user interface code and code
00368      * to open the file in each and every plugin. */
00369     void (* file_info_box) (const gchar * filename);
00370 
00371     /* Optional.  Must try to read an "album art" image embedded in this file.
00372      * Must return nonzero on success or zero on failure.  If the file could not
00373      * be opened, "file" will be NULL.  On success, must fill "data" with a
00374      * pointer to a block of data allocated with g_malloc and "size" with the
00375      * size in bytes of that block.  The data may be in any format supported by
00376      * GTK.  Audacious will free the data when it is no longer needed. */
00377     gboolean (* get_song_image) (const gchar * filename, VFSFile * file,
00378      void * * data, gint * size);
00379 
00380     /* Must try to play this file.  "playback" is a structure containing output-
00381      * related functions which the plugin may make use of.  It also contains a
00382      * "data" pointer which the plugin may use to refer private data associated
00383      * with the playback state.  This pointer can then be used from pause,
00384      * mseek, and stop. If the file could not be opened, "file" will be NULL.
00385      * "start_time" is the position in milliseconds at which to start from, or
00386      * -1 to start from the beginning of the file.  "stop_time" is the position
00387      * in milliseconds at which to end playback, or -1 to play to the end of the
00388      * file.  "paused" specifies whether playback should immediately be paused.
00389      * Must return nonzero if some of the file was successfully played or zero
00390      * on failure. */
00391     gboolean (* play) (InputPlayback * playback, const gchar * filename,
00392      VFSFile * file, gint start_time, gint stop_time, gboolean pause);
00393 
00394     /* Must pause or unpause a file currently being played.  This function will
00395      * be called from a different thread than play, but it will not be called
00396      * before the plugin calls set_pb_ready or after stop is called. */
00397     void (* pause) (InputPlayback * playback, gboolean paused);
00398 
00399     /* Optional.  Must seek to the given position in milliseconds within a file
00400      * currently being played.  This function will be called from a different
00401      * thread than play, but it will not be called before the plugin calls
00402      * set_pb_ready or after stop is called. */
00403     void (* mseek) (InputPlayback * playback, gint time);
00404 
00405     /* Must signal a currently playing song to stop and cause play to return.
00406      * This function will be called from a different thread than play.  It will
00407      * only be called once. It should not join the thread from which play is
00408      * called. */
00409     void (* stop) (InputPlayback * playback);
00410 
00411     /* Advanced, for plugins that do not use Audacious's output system.  Use at
00412      * your own risk. */
00413     gint (* get_time) (InputPlayback * playback);
00414     gint (* get_volume) (gint * l, gint * r);
00415     gint (* set_volume) (gint l, gint r);
00416 };
00417 
00418 struct _GeneralPlugin
00419 {
00420     PLUGIN_COMMON_FIELDS
00421 
00422     gboolean enabled_by_default;
00423 
00424     /* GtkWidget * (* get_widget) (void); */
00425     void * (* get_widget) (void);
00426 };
00427 
00428 struct _VisPlugin
00429 {
00430     PLUGIN_COMMON_FIELDS
00431 
00432     gint num_pcm_chs_wanted;
00433     gint num_freq_chs_wanted;
00434 
00435     void (*playback_start) (void);
00436     void (*playback_stop) (void);
00437     void (*render_pcm) (gint16 pcm_data[2][512]);
00438 
00439     /* The range of intensities is 0 - 32767 (though theoretically it is
00440      * possible for the FFT to result in bigger values, making the final
00441      * intensity negative due to overflowing the 16bit signed integer.)
00442      *
00443      * If output is mono, only freq_data[0] is filled.
00444      */
00445     void (*render_freq) (gint16 freq_data[2][256]);
00446 
00447     /* GtkWidget * (* get_widget) (void); */
00448     void * (* get_widget) (void);
00449 };
00450 
00451 struct _IfacePlugin
00452 {
00453     PLUGIN_COMMON_FIELDS
00454 
00455     /* is_shown() may return nonzero even if the interface is not actually
00456      * visible; for example, if it is obscured by other windows or minimized.
00457      * is_focused() only returns nonzero if the interface is actually visible;
00458      * in X11, this should be determined by whether the interface has the
00459      * toplevel focus.  show() should show and raise the interface, so that both
00460      * is_shown() and is_focused() will return nonzero. */
00461     void (* show) (gboolean show);
00462     gboolean (* is_shown) (void);
00463 
00464     void (* show_error) (const gchar * markup);
00465     void (* show_filebrowser) (gboolean play_button);
00466     void (* show_jump_to_track) (void);
00467 
00468     void /* GtkWidget */ * (* run_gtk_plugin) (void /* GtkWidget */ * widget,
00469      const gchar * name);
00470     void * (* stop_gtk_plugin) (void /* GtkWidget */ * widget);
00471 
00472     void (* install_toolbar) (void /* GtkWidget */ * button);
00473     void (* uninstall_toolbar) (void /* GtkWidget */ * button);
00474 
00475     /* added after 3.0-alpha1 */
00476     gboolean (* is_focused) (void);
00477 };
00478 
00479 #undef PLUGIN_COMMON_FIELDS
00480 
00481 #define AUD_PLUGIN(stype, itype, ...) \
00482 AudAPITable * _aud_api_table = NULL; \
00483 stype _aud_plugin_self = { \
00484  .magic = _AUD_PLUGIN_MAGIC, \
00485  .version = _AUD_PLUGIN_VERSION, \
00486  .type = itype, \
00487  .size = sizeof (stype), \
00488  __VA_ARGS__}; \
00489 G_MODULE_EXPORT stype * get_plugin_info (AudAPITable * table) { \
00490     _aud_api_table = table; \
00491     return & _aud_plugin_self; \
00492 }
00493 
00494 #define AUD_TRANSPORT_PLUGIN(...) AUD_PLUGIN (TransportPlugin, PLUGIN_TYPE_TRANSPORT, __VA_ARGS__)
00495 #define AUD_PLAYLIST_PLUGIN(...) AUD_PLUGIN (PlaylistPlugin, PLUGIN_TYPE_PLAYLIST, __VA_ARGS__)
00496 #define AUD_INPUT_PLUGIN(...) AUD_PLUGIN (InputPlugin, PLUGIN_TYPE_INPUT, __VA_ARGS__)
00497 #define AUD_EFFECT_PLUGIN(...) AUD_PLUGIN (EffectPlugin, PLUGIN_TYPE_EFFECT, __VA_ARGS__)
00498 #define AUD_OUTPUT_PLUGIN(...) AUD_PLUGIN (OutputPlugin, PLUGIN_TYPE_OUTPUT, __VA_ARGS__)
00499 #define AUD_VIS_PLUGIN(...) AUD_PLUGIN (VisPlugin, PLUGIN_TYPE_VIS, __VA_ARGS__)
00500 #define AUD_GENERAL_PLUGIN(...) AUD_PLUGIN (GeneralPlugin, PLUGIN_TYPE_GENERAL, __VA_ARGS__)
00501 #define AUD_IFACE_PLUGIN(...) AUD_PLUGIN (IfacePlugin, PLUGIN_TYPE_IFACE, __VA_ARGS__)
00502 
00503 #define PLUGIN_HAS_FUNC(p, func) \
00504  ((p)->size > (void *) & (p)->func - (void *) (p) && (p)->func)
00505 
00506 #endif /* AUDACIOUS_PLUGIN_H */