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