Audacious
$Id:Doxyfile42802007-03-2104:39:00Znenolod$
|
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 */