Skip to main content

Writing Plugins

Writing Ampache Plugins​

It can be a bit daunting to write a plugin for Ampache but this page will be written up to help people with a bit of knowledge take the plunge and write a plugin!

About​

Plugins are called by Ampache to perform a specific function. currently there are multiple display, media notification and art searching plugins that help extend what Ampache can do.

Plugins are placed in: Ampache/modules/plugins/ the name of the file must be ./Name/Name.plugin.php. e.g. Dummy/Dummy.plugin.php.

The file must declare a corresponding class and the name of the class must be prefixed with Ampache. e.g. class AmpacheDummy

Copying an existing plugin is the easiest way to write a new one.

There is an empty example template available here AmpacheExample.php.

This should let you expand and develop your own plugin quickly.

Required Methods​

The following public variables must be declared:

  • (string) name
  • (string) description
  • (int) version - This plugin's version
  • (string) min_ampache - Minimum Ampache DB version required
  • (string) max_ampache - Maximum Ampache DB version supported
    public $name        = 'Dummy Plugin';
    public $description = 'Dummy Plugin to hopefully explain this a bit better';
    public $version     = '000002';
    public $min_ampache = '420000';
    public $max_ampache = '999999';

The following public methods must be implemented:

  • install() - This is usually used to insert preferences like API keys or other values the plugin needs
  • uninstall() - Remove all the things you install here
  • load(User $user) - Loads the preferences you have installed to the database

These functions should all return a boolean on success/failure.

Additional Methods​

The following public methods may be implemented:

  • upgrade() - If you make an update that requires new preferences use upgrade to insert the missing preferences without having to reinstall.

Possible Plugin methods​

Finally, for the plugin to actually be useful one or more of the following hooks should be implemented as a public method:

  • display_home() Display something in the home page / index
  • display_on_footer() Same as home, except in the page footer
  • display_user_field(library_item $libitem = null) This display the module in user page
  • display_map(array $points) Used for graphs and charts
  • external_share(string $public_url, string $share_name) Send a shared object to an external site
  • gather_arts(string $type, array $options, integer $limit) Search for art externally
  • get_avatar_url(User $user)
  • get_lyrics(Song $song)
  • get_location_name(float $latitude float $longitude)
  • get_metadata(array $gather_types, array $media_info) Array of object types and array of info for that object
  • get_photos(string $search_name)
  • get_song_preview(string $track_mbid, string $artist_name, string $title)
  • process_wanted(Wanted $wanted)
  • save_mediaplay(Song $song)
  • save_rating(Rating $rating, integer $new_value)
  • set_flag(Song $song, boolean $flagged)
  • shortener(string $url)
  • stream_control(array $object_ids)
  • stream_song_preview(string $file)
  • display_home() Display someting in the home page / index