Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
plugin.h
Go to the documentation of this file.
1 /*
2  * plugin.h
3  * Copyright 2005-2010 Audacious Development Team
4  *
5  * This file is part of Audacious.
6  *
7  * Audacious is free software: you can redistribute it and/or modify it under
8  * the terms of the GNU General Public License as published by the Free Software
9  * Foundation, version 2 or version 3 of the License.
10  *
11  * Audacious is distributed in the hope that it will be useful, but WITHOUT ANY
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
13  * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License along with
16  * Audacious. If not, see <http://www.gnu.org/licenses/>.
17  *
18  * The Audacious team does not consider modular code linking to Audacious or
19  * using our public API to be a derived work.
20  */
21 
22 #ifndef AUDACIOUS_PLUGIN_H
23 #define AUDACIOUS_PLUGIN_H
24 
25 #include <audacious/api.h>
26 #include <audacious/types.h>
27 #include <libaudcore/audio.h>
28 #include <libaudcore/index.h>
29 #include <libaudcore/tuple.h>
30 #include <libaudcore/vfs.h>
31 
32 /* "Magic" bytes identifying an Audacious plugin header. */
33 #define _AUD_PLUGIN_MAGIC 0x8EAC8DE2
34 
35 /* API version. Plugins are marked with this number at compile time.
36  *
37  * _AUD_PLUGIN_VERSION is the current version; _AUD_PLUGIN_VERSION_MIN is
38  * the oldest one we are backward compatible with. Plugins marked older than
39  * _AUD_PLUGIN_VERSION_MIN or newer than _AUD_PLUGIN_VERSION are not loaded.
40  *
41  * Before releases that add new pointers to the end of the API tables, increment
42  * _AUD_PLUGIN_VERSION but leave _AUD_PLUGIN_VERSION_MIN the same.
43  *
44  * Before releases that break backward compatibility (e.g. remove pointers from
45  * the API tables), increment _AUD_PLUGIN_VERSION *and* set
46  * _AUD_PLUGIN_VERSION_MIN to the same value. */
47 
48 #define _AUD_PLUGIN_VERSION_MIN 38 /* 3.2-alpha2 */
49 #define _AUD_PLUGIN_VERSION 38
50 
51 /* A NOTE ON THREADS
52  *
53  * How thread-safe a plugin must be depends on the type of plugin. Note that
54  * some parts of the Audacious API are *not* thread-safe and therefore cannot be
55  * used in some parts of some plugins; for example, input plugins cannot use
56  * GUI-related calls or access the playlist except in about() and configure().
57  *
58  * Thread-safe plugins: transport, playlist, input, effect, and output. These
59  * must be mostly thread-safe. init() and cleanup() may be called from
60  * secondary threads; however, no other functions provided by the plugin will be
61  * called at the same time. about() and configure() will be called only from
62  * the main thread. All other functions provided by the plugin may be called
63  * from any thread and from multiple threads simultaneously.
64  *
65  * Exceptions:
66  * - Because many existing input plugins are not coded to handle simultaneous
67  * calls to play(), play() will only be called from one thread at a time. New
68  * plugins should not rely on this exception, though.
69  * - Some combinations of calls, especially for output and effect plugins, make
70  * no sense; for example, flush() in an output plugin will only be called
71  * after open_audio() and before close_audio().
72  *
73  * Single-thread plugins: visualization, general, and interface. Functions
74  * provided by these plugins will only be called from the main thread. */
75 
76 /* CROSS-PLUGIN MESSAGES
77  *
78  * Since 3.2, Audacious implements a basic messaging system between plugins.
79  * Messages are sent using aud_plugin_send_message() and received through the
80  * take_message() method specified in the header of the receiving plugin.
81  * Plugins that do not need to receive messages can set take_message() to NULL.
82  *
83  * Each message includes a code indicating the type of message, a pointer to
84  * some data, and a value indicating the size of that data. What the message
85  * data contains is entirely up to the two plugins involved. For this reason, it
86  * is crucial that both plugins agree on the meaning of the message codes used.
87  *
88  * Once the message is sent, an integer error code is returned. If the receiving
89  * plugin does not provide the take_message() method, ENOSYS is returned. If
90  * take_message() does not recognize the message code, it should ignore the
91  * message and return EINVAL. An error code of zero represents success. Other
92  * error codes may be used with more specific meanings.
93  *
94  * For the time being, aud_plugin_send_message() should only be called from the
95  * program's main thread. */
96 
97 #define PLUGIN_COMMON_FIELDS \
98  int magic; /* checked against _AUD_PLUGIN_MAGIC */ \
99  int version; /* checked against _AUD_PLUGIN_VERSION */ \
100  int type; /* PLUGIN_TYPE_XXX */ \
101  int size; /* size in bytes of the struct */ \
102  const char * name; \
103  bool_t (* init) (void); \
104  void (* cleanup) (void); \
105  int (* take_message) (const char * code, const void * data, int size); \
106  void (* about) (void); \
107  void (* configure) (void); \
108  PluginPreferences * settings;
109 
110 struct _Plugin
111 {
113 };
114 
116 {
118  const char * const * schemes; /* array ending with NULL */
120 };
121 
123 {
125  const char * const * extensions; /* array ending with NULL */
126  bool_t (* load) (const char * path, VFSFile * file,
127  char * * title, /* pooled */
128  Index * filenames, /* of (char *), pooled */
129  Index * tuples); /* of (Tuple *) */
130  bool_t (* save) (const char * path, VFSFile * file, const char * title,
131  Index * filenames, /* of (char *) */
132  Index * tuples); /* of (Tuple *) */
133 };
134 
136 {
138 
139  /* During probing, plugins with higher priority (10 to 0) are tried first. */
141 
142  /* Returns current volume for left and right channels (0 to 100). */
143  void (* get_volume) (int * l, int * r);
144 
145  /* Changes volume for left and right channels (0 to 100). */
146  void (* set_volume) (int l, int r);
147 
148  /* Begins playback of a PCM stream. <format> is one of the FMT_*
149  * enumeration values defined in libaudcore/audio.h. Returns nonzero on
150  * success. */
151  bool_t (* open_audio) (int format, int rate, int chans);
152 
153  /* Ends playback. Any buffered audio data is discarded. */
154  void (* close_audio) (void);
155 
156  /* Returns how many bytes of data may be passed to a following write_audio()
157  * call. NULL if the plugin supports only blocking writes (not recommended). */
158  int (* buffer_free) (void);
159 
160  /* Waits until buffer_free() will return a size greater than zero.
161  * output_time(), pause(), and flush() may be called meanwhile; if flush()
162  * is called, period_wait() should return immediately. NULL if the plugin
163  * supports only blocking writes (not recommended). */
164  void (* period_wait) (void);
165 
166  /* Buffers <size> bytes of data, in the format given to open_audio(). */
167  void (* write_audio) (void * data, int size);
168 
169  /* Waits until all buffered data has been heard by the user. */
170  void (* drain) (void);
171 
172  /* Returns time count (in milliseconds) of how much data has been written. */
173  int (* written_time) (void);
174 
175  /* Returns time count (in milliseconds) of how much data has been heard by
176  * the user. */
177  int (* output_time) (void);
178 
179  /* Pauses the stream if <p> is nonzero; otherwise unpauses it.
180  * write_audio() will not be called while the stream is paused. */
181  void (* pause) (bool_t p);
182 
183  /* Discards any buffered audio data and sets the time counter (in
184  * milliseconds) of data written. */
185  void (* flush) (int time);
186 
187  /* Sets the time counter (in milliseconds) of data written without
188  * discarding any buffered audio data. If <time> is less than the amount of
189  * buffered data, following calls to output_time() will return negative
190  * values. */
191  void (* set_written_time) (int time);
192 };
193 
195 {
197 
198  /* All processing is done in floating point. If the effect plugin wants to
199  * change the channel count or sample rate, it can change the parameters
200  * passed to start(). They cannot be changed in the middle of a song. */
201  void (* start) (int * channels, int * rate);
202 
203  /* process() has two options: modify the samples in place and leave the data
204  * pointer unchanged or copy them into a buffer of its own. If it sets the
205  * pointer to dynamically allocated memory, it is the plugin's job to free
206  * that memory. process() may return different lengths of audio than it is
207  * passed, even a zero length. */
208  void (* process) (float * * data, int * samples);
209 
210  /* Optional. A seek is taking place; any buffers should be discarded. */
211  void (* flush) (void);
212 
213  /* Exactly like process() except that any buffers should be drained (i.e.
214  * the data processed and returned). finish() will be called a second time
215  * at the end of the last song in the playlist. */
216  void (* finish) (float * * data, int * samples);
217 
218  /* Optional. For effects that change the length of the song, these
219  * functions allow the correct time to be displayed. */
220  int (* decoder_to_output_time) (int time);
221  int (* output_to_decoder_time) (int time);
222 
223  /* Effects with lowest order (0 to 9) are applied first. */
224  int order;
225 
226  /* If the effect does not change the number of channels or the sampling
227  * rate, it can be enabled and disabled more smoothly. */
229 };
230 
231 struct OutputAPI
232 {
233  /* In a multi-thread plugin, only one of these functions may be called at
234  * once (but see pause and abort_write for exceptions to this rule). */
235 
236  /* Prepare the output system for playback in the specified format. Returns
237  * nonzero on success. If the call fails, no other output functions may be
238  * called. */
239  int (* open_audio) (int format, int rate, int channels);
240 
241  /* Informs the output system of replay gain values for the current song so
242  * that volume levels can be adjusted accordingly, if the user so desires.
243  * This may be called at any time during playback should the values change. */
245 
246  /* Pass audio data to the output system for playback. The data must be in
247  * the format passed to open_audio, and the length (in bytes) must be an
248  * integral number of frames. This function blocks until all the data has
249  * been written (though it may not yet be heard by the user); if the output
250  * system is paused; this may be indefinitely. See abort_write for a way to
251  * interrupt a blocked call. */
252  void (* write_audio) (void * data, int length);
253 
254  /* End playback. Any audio data currently buffered by the output system
255  * will be discarded. After the call, no other output functions, except
256  * open_audio, may be called. */
257  void (* close_audio) (void);
258 
259  /* Pause or unpause playback. This function may be called during a call to
260  * write_audio, in which write_audio will block until playback is unpaused
261  * (but see abort_write to prevent the call from blocking). */
262  void (* pause) (bool_t pause);
263 
264  /* Discard any audio data currently buffered by the output system, and set
265  * the time counter to a new value. This function is intended to be used
266  * for seeking. */
267  void (* flush) (int time);
268 
269  /* Returns the time counter. Note that this represents the amount of audio
270  * data passed to the output system, not the amount actually heard by the
271  * user. This function is useful for handling a changed audio format:
272  * First, save the time counter using this function. Second, call
273  * close_audio and then open_audio with the new format (note that the call
274  * may fail). Finally, restore the time counter using flush. */
275  int (* written_time) (void);
276 
277  /* Returns TRUE if there is data remaining in the output buffer; FALSE if
278  * all data written to the output system has been heard by the user. This
279  * function should be polled (1/50 second is a reasonable delay between
280  * calls) at the end of a song before calling close_audio. Once it returns
281  * FALSE, close_audio can be called without cutting off any of the end of
282  * the song. */
283  bool_t (* buffer_playing) (void);
284 
285  /* Interrupt a call to write_audio so that it returns immediately. This
286  * works even when the call is blocked by pause. Buffered audio data is
287  * discarded as in flush. Until flush is called or the output system is
288  * reset, further calls to write_audio will have no effect and return
289  * immediately. This function is intended to be used in seeking or
290  * stopping in a multi-thread plugin. To seek, the handler function (called
291  * in the main thread) should first set a flag for the decoding thread and
292  * then call abort_write. When the decoding thread notices the flag, it
293  * should do the actual seek, call flush, and finally clear the flag. Once
294  * the flag is cleared, the handler function may return. */
295  void (* abort_write) (void);
296 };
297 
298 typedef const struct _InputPlayback InputPlayback;
299 
301 {
302  /* Pointer to the output API functions. */
303  const struct OutputAPI * output;
304 
305  /* Allows the plugin to associate data with a playback instance. */
306  void (* set_data) (InputPlayback * p, void * data);
307 
308  /* Returns the pointer passed to set_data. */
309  void * (* get_data) (InputPlayback * p);
310 
311  /* Signifies that the plugin has started playback is ready to accept mseek,
312  * pause, and stop calls. */
313  void (* set_pb_ready) (InputPlayback * p);
314 
315  /* Updates attributes of the stream. "bitrate" is in bits per second.
316  * "samplerate" is in hertz. */
317  void (* set_params) (InputPlayback * p, int bitrate, int samplerate,
318  int channels);
319 
320  /* Updates metadata for the stream. Caller gives up ownership of one
321  * reference to the tuple. */
322  void (* set_tuple) (InputPlayback * playback, Tuple * tuple);
323 
324  /* If replay gain settings are stored in the tuple associated with the
325  * current song, this function can be called (after opening audio) to apply
326  * those settings. If the settings are changed in a call to set_tuple, this
327  * function must be called again to apply the updated settings. */
328  void (* set_gain_from_playlist) (InputPlayback * playback);
329 };
330 
332 {
334 
335  /* Nonzero if the files handled by the plugin may contain more than one
336  * song. When reading the tuple for such a file, the plugin should set the
337  * FIELD_SUBSONG_NUM field to the number of songs in the file. For all
338  * other files, the field should be left unset.
339  *
340  * Example:
341  * 1. User adds a file named "somefile.xxx" to the playlist. Having
342  * determined that this plugin can handle the file, Audacious opens the file
343  * and calls probe_for_tuple(). probe_for_tuple() sees that there are 3
344  * songs in the file and sets FIELD_SUBSONG_NUM to 3.
345  * 2. For each song in the file, Audacious opens the file and calls
346  * probe_for_tuple() -- this time, however, a question mark and song number
347  * are appended to the file name passed: "somefile.sid?2" refers to the
348  * second song in the file "somefile.sid".
349  * 3. When one of the songs is played, Audacious opens the file and calls
350  * play() with a file name modified in this way.
351  */
353 
354  /* Pointer to an array (terminated with NULL) of file extensions associated
355  * with file types the plugin can handle. */
356  const char * const * extensions;
357  /* Pointer to an array (terminated with NULL) of MIME types the plugin can
358  * handle. */
359  const char * const * mimes;
360  /* Pointer to an array (terminated with NULL) of custom URI schemes the
361  * plugin can handle. */
362  const char * const * schemes;
363 
364  /* How quickly the plugin should be tried in searching for a plugin to
365  * handle a file which could not be identified from its extension. Plugins
366  * with priority 0 are tried first, 10 last. */
367  int priority;
368 
369  /* Must return nonzero if the plugin can handle this file. If the file
370  * could not be opened, "file" will be NULL. (This is normal in the case of
371  * special URI schemes like cdda:// that do not represent actual files.) */
372  bool_t (* is_our_file_from_vfs) (const char * filename, VFSFile * file);
373 
374  /* Must return a tuple containing metadata for this file, or NULL if no
375  * metadata could be read. If the file could not be opened, "file" will be
376  * NULL. Audacious takes over one reference to the tuple returned. */
377  Tuple * (* probe_for_tuple) (const char * filename, VFSFile * file);
378 
379  /* Optional. Must write metadata from a tuple to this file. Must return
380  * nonzero on success or zero on failure. "file" will never be NULL. */
381  /* Bug: This function does not support special URI schemes like cdda://,
382  * since no file name is passed. */
383  bool_t (* update_song_tuple) (const Tuple * tuple, VFSFile * file);
384 
385  /* Optional, and not recommended. Must show a window with information about
386  * this file. If this function is provided, update_song_tuple should not be. */
387  /* Bug: Implementing this function duplicates user interface code and code
388  * to open the file in each and every plugin. */
389  void (* file_info_box) (const char * filename);
390 
391  /* Optional. Must try to read an "album art" image embedded in this file.
392  * Must return nonzero on success or zero on failure. If the file could not
393  * be opened, "file" will be NULL. On success, must fill "data" with a
394  * pointer to a block of data allocated with g_malloc and "size" with the
395  * size in bytes of that block. The data may be in any format supported by
396  * GTK. Audacious will free the data when it is no longer needed. */
397  bool_t (* get_song_image) (const char * filename, VFSFile * file,
398  void * * data, int64_t * size);
399 
400  /* Must try to play this file. "playback" is a structure containing output-
401  * related functions which the plugin may make use of. It also contains a
402  * "data" pointer which the plugin may use to refer private data associated
403  * with the playback state. This pointer can then be used from pause,
404  * mseek, and stop. If the file could not be opened, "file" will be NULL.
405  * "start_time" is the position in milliseconds at which to start from, or
406  * -1 to start from the beginning of the file. "stop_time" is the position
407  * in milliseconds at which to end playback, or -1 to play to the end of the
408  * file. "paused" specifies whether playback should immediately be paused.
409  * Must return nonzero if some of the file was successfully played or zero
410  * on failure. */
411  bool_t (* play) (InputPlayback * playback, const char * filename,
412  VFSFile * file, int start_time, int stop_time, bool_t pause);
413 
414  /* Must pause or unpause a file currently being played. This function will
415  * be called from a different thread than play, but it will not be called
416  * before the plugin calls set_pb_ready or after stop is called. */
417  void (* pause) (InputPlayback * playback, bool_t paused);
418 
419  /* Optional. Must seek to the given position in milliseconds within a file
420  * currently being played. This function will be called from a different
421  * thread than play, but it will not be called before the plugin calls
422  * set_pb_ready or after stop is called. */
423  void (* mseek) (InputPlayback * playback, int time);
424 
425  /* Must signal a currently playing song to stop and cause play to return.
426  * This function will be called from a different thread than play. It will
427  * only be called once. It should not join the thread from which play is
428  * called. */
429  void (* stop) (InputPlayback * playback);
430 
431  /* Advanced, for plugins that do not use Audacious's output system. Use at
432  * your own risk. */
433  int (* get_time) (InputPlayback * playback);
434  int (* get_volume) (int * l, int * r);
435  int (* set_volume) (int l, int r);
436 };
437 
439 {
441 
443 
444  /* GtkWidget * (* get_widget) (void); */
445  void * (* get_widget) (void);
446 };
447 
449 {
451 
452  /* reset internal state and clear display */
453  void (* clear) (void);
454 
455  /* 512 frames of a single-channel PCM signal */
456  void (* render_mono_pcm) (const float * pcm);
457 
458  /* 512 frames of an interleaved multi-channel PCM signal */
459  void (* render_multi_pcm) (const float * pcm, int channels);
460 
461  /* intensity of frequencies 1/512, 2/512, ..., 256/512 of sample rate */
462  void (* render_freq) (const float * freq);
463 
464  /* GtkWidget * (* get_widget) (void); */
465  void * (* get_widget) (void);
466 };
467 
469 {
471 
472  /* is_shown() may return nonzero even if the interface is not actually
473  * visible; for example, if it is obscured by other windows or minimized.
474  * is_focused() only returns nonzero if the interface is actually visible;
475  * in X11, this should be determined by whether the interface has the
476  * toplevel focus. show() should show and raise the interface, so that both
477  * is_shown() and is_focused() will return nonzero. */
478  void (* show) (bool_t show);
479  bool_t (* is_shown) (void);
480 
481  void (* show_error) (const char * markup);
482  void (* show_filebrowser) (bool_t play_button);
483  void (* show_jump_to_track) (void);
484 
485  void (* run_gtk_plugin) (void /* GtkWidget */ * widget, const char * name);
486  void (* stop_gtk_plugin) (void /* GtkWidget */ * widget);
487 
488  void (* install_toolbar) (void /* GtkWidget */ * button);
489  void (* uninstall_toolbar) (void /* GtkWidget */ * button);
490 
491  /* added after 3.0-alpha1 */
492  bool_t (* is_focused) (void);
493 };
494 
495 #undef PLUGIN_COMMON_FIELDS
496 
497 #define AUD_PLUGIN(stype, itype, ...) \
498 AudAPITable * _aud_api_table = NULL; \
499 stype _aud_plugin_self = { \
500  .magic = _AUD_PLUGIN_MAGIC, \
501  .version = _AUD_PLUGIN_VERSION, \
502  .type = itype, \
503  .size = sizeof (stype), \
504  __VA_ARGS__}; \
505 stype * get_plugin_info (AudAPITable * table) { \
506  _aud_api_table = table; \
507  return & _aud_plugin_self; \
508 }
509 
510 #define AUD_TRANSPORT_PLUGIN(...) AUD_PLUGIN (TransportPlugin, PLUGIN_TYPE_TRANSPORT, __VA_ARGS__)
511 #define AUD_PLAYLIST_PLUGIN(...) AUD_PLUGIN (PlaylistPlugin, PLUGIN_TYPE_PLAYLIST, __VA_ARGS__)
512 #define AUD_INPUT_PLUGIN(...) AUD_PLUGIN (InputPlugin, PLUGIN_TYPE_INPUT, __VA_ARGS__)
513 #define AUD_EFFECT_PLUGIN(...) AUD_PLUGIN (EffectPlugin, PLUGIN_TYPE_EFFECT, __VA_ARGS__)
514 #define AUD_OUTPUT_PLUGIN(...) AUD_PLUGIN (OutputPlugin, PLUGIN_TYPE_OUTPUT, __VA_ARGS__)
515 #define AUD_VIS_PLUGIN(...) AUD_PLUGIN (VisPlugin, PLUGIN_TYPE_VIS, __VA_ARGS__)
516 #define AUD_GENERAL_PLUGIN(...) AUD_PLUGIN (GeneralPlugin, PLUGIN_TYPE_GENERAL, __VA_ARGS__)
517 #define AUD_IFACE_PLUGIN(...) AUD_PLUGIN (IfacePlugin, PLUGIN_TYPE_IFACE, __VA_ARGS__)
518 
519 #define PLUGIN_HAS_FUNC(p, func) \
520  ((p)->size > (char *) & (p)->func - (char *) (p) && (p)->func)
521 
522 #endif /* AUDACIOUS_PLUGIN_H */