SoundPlay plugins

Plugins

SoundPlay makes use of plugins (add-ons) to read files and apply audio effects. This means that its capabilities can be expanded by adding plugins, without requiring a rewrite of SoundPlay. This document describes how these plugins are built.

General information

A SoundPlay plugin file must be located in a folder called "Plugins" that is in the same folder where SoundPlay itself is located.

A plugin file does not need to have a particular name to be identified as a plugin, and the plugin folder is scanned recursively, so you can create subdirectories in it to order your plugins if you wish. Folders that start and end with round brackets are skipped in the recursive scan. You would use this if you need a folder where your plugin stores datafiles for example.

SoundPlay currently scans the plugin folder once when it starts up, so if you add a new plugin, you will need to restart SoundPlay.

The plugin_descriptor structure

A SoundPlay plugin file exports two functions. The first one is defined as

 extern "C" plugin_descriptor _EXPORT **get_plugin_list(void);

it returns a pointer to an array of pointers to plugin_descriptor structures. The array should be terminated with a NULL pointer. Because each plugin_descriptor defines a plugin, and get_plugin_list returns a pointer to an array of pointers to these structures, you can put more than one plugin in a single plugin-file. A plugin_descriptor structure looks like this:

typedef void	op_about();
typedef BView*	op_configure(BMessage *config);
typedef void*	op_instantiate(void **data, const char *name, const char *header, uint32 size, plugin_info *info);
typedef void	op_destroy(void *plugin_ops, void *data);

typedef struct plugin_descriptor
{
	uint32		desc_magic;
	uint32		desc_version;
	char*		id;
	uint32		version;
	uint32		flags;
	char*		name;
	char*		aboutstring;

	op_about	(*About);
	op_configure	(*Configure);
	op_instantiate	(*Instantiate_Plugin);
	op_destroy	(*Destroy_Plugin);	
} plugin_descriptor;

desc_magic is a magic number that you should set to PLUGIN_DESCRIPTOR_MAGIC
desc_version is the current API version, and you should set it to PLUGIN_DESCRIPTOR_VERSION
id is an unique id identifying your plugin. Make sure it is unique, include your name or your developer ID for example
version is the version of your plugin, in case you have multiple versions of the same plugin
flags is a bitfield further defining the plugin. Currently defined are PLUGIN_IS_DECODER, PLUGIN_IS_FILTER, PLUGIN_IS_VISUAL and PLUGIN_IS_INTERFACE, which are mutually exclusive.
name is the name of your plugin. SoundPlay will use this to display in the plugin manager
aboutstring is a more elaborate description of your plugin. It will be show in the plugin manager when your plugin is selected
The About function will be called when the user selects your plugin and clicks the about-button in SoundPlay's plugin manager. You may set this to NULL if you do not wish an about box
The Configure function will be called when the user selects your plugin and clicks the configure-button. You may set this to NULL if your plugin does not require configuration. If implemented, it should return a BView (that SoundPlay will display in a window) and store the configuration (when the view is deleted) in the given BMessage. In the case of filter-plugins, the configuration that this function creates is the "global" configuration, and is used as the initial configuration of any instantiated plugins
Instantiate_Plugin is mandatory, it MUST be implemented. It should create an instance of the plugin and return a pointer to a structure describing the instance. It can set the pointer that its data argument points to a value that will be passed to each plugin-function. For decoder-plugins, the name argument is the full path name of the file to be opened, while header is the first size bytes of the file.
The info argument points to a plugin_info structure, which is defined as:
```
	typedef struct plugin_info
	{
		SoundPlayController *controller;
		entry_ref *ref;
	} plugin_info;
```
controller is a pointer to a SoundPlayController object that can be used to control various functions of SoundPlay.
ref is a pointer to the entry_ref for the plugin itself. The plugin can use this to for example retrieve resources from the plugin file.
Destroy_Plugin should destroy a plugin-instance. It receives the pointer that Instantiate_Plugin returned as well as the data-pointer that Instantiate_Plugin set.

If the plugin is a decoder plugin, Instantiate_Plugin should return a pointer to a decoder_plugin_ops structure

If the plugin is an effect plugin (audio filter or visual effect), Instantiate_Plugin should return a pointer to a filter_plugin_ops structure

If the plugin is a general purpose plugin, Instantiate_Plugin should return a pointer to an interface_plugin_ops structure

Supported types

The second function that a plugin exports is

 extern "C" supported_type _EXPORT *get_supported_types(void);

The function is optional, and if implemented returns a pointer to an array of supported_type structures, which look like this:

 typedef struct supported_type
 {
	char *mimetype;
	char *longdesc;
	char *shortdesc;
	char *extension1;
	char *extension2;
 } supported_type;

The array should contain one supported_type for each supported fileformat, and be terminated with a entry containing a NULL mimetype.

The meaning of the members of supported_type is as follows:

mimetype is the mimetype for the fileformat
longdesc and shortdesc are a long and short-description of the filetype
extension1 and extension2 are two extensions that optionally identify the filetype. SoundPlay will register these in the mime database in both upper and lowercase form.