Skip to main content

Plugin system overview

Introduction​

Volumio introduces the concept of plugins to expand its functionality, and allow an easy sharing of the tweaks and improvements usually generated by the community. Imagine Volumio's plugins as apps that install on your Volumio device, extending its functionalities.

We've worked hard to create a standardized layout to make it easier to develop any kind of plugins. And, more importantly, we strive to offer Volumio users a flawless experience by validating and testing each plugin before it's published on Volumio's plugin store.

What is plugin ?​

A plugin is meant to add one specific functionality. It could be music_service, system features, audio interface add on and almost everything developers (Volumio and community) can imagine.

Some examples can be:

  • Adding a new music service to Volumio, like Deezer or a Webradio provider
  • Adding a way to manage a specific OLED Display
  • Adding a facility to control an external apparatus, such as an amplifier

How can users install plugins ?​

Plugins are meant to be installed by users directly from the Volumio Plugins store, accessible from within Volumio User Interface.

caution

Do not suggest users to install plugins manually. For a better experience for the whole community, plugins shall be verified and published on Volumio's plugins store rather than being installed manually.

Plugin beta / stable channels​

Since Volumio3 the plugins store has a stable channel (available for everyone) and a beta channel (available for beta testers). This enables developers to release test versions of a plugin so it can be tested by a small selection of people before it is publicly available. This ensures that the plugin is properly tested before it's publicly released, ensuring quality of the plugin and volumio as a whole.

To enable the beta channel go to: http://{yourvolumioaddress}/dev and click "Plugins test mode"

Technical overview of a plugin​

It is provided as zip file which contains all needed files for it to work, either directly included in the zip file or available via a an install script that will download them automatically.

Plugins are installed at

/data/plugins/

And they are organized in subfolder per categories. When installing plugin, a folder is created in:

/data/plugins/mycategory/myplugins

All plugins related files (extracted from zip and resulting from install sh script will be found here).

Existing Plugin Categories​

info

PLEASE NOTE: Categories name must be lowercase and separated by _ .

audio_interface​

This typically collects plugins that add an audio interface, aka an external and not browsable music source. Typical examples are:

  • Airplay
  • UpNp
  • Bluetooth
  • Equalizer, DSP...
music_service​

Those are browsable music sources, typically:

  • MPD (for local files)
  • Webradios Directories
  • Streaming Services like Spotify

system_hardware​

  • USB / Serial / GPIO connected peripherals like buttons, leds, sensors, amps
  • CPU Speed
  • Amplifier activation
  • Remote controls

system_controller​

System controller are usually core-plugins, meant to handle vital parts of Volumio.

  • Networking
  • Network Attached Storage
  • Core updater services

user_interface​

User interface plugins are meant to allow external communication to Volumio. Developing a new one will be useful to add API Rest Capability, or to extend Volumio interoperability with third party apps and controllers. Some examples:

  • Visual interfaces
  • On screen keyboards
  • Touch displayes

What features can be added​

This features could be miscellaneous, such as new online music provider, new radio stream, management of the GPIO (for supported devices), various DSP, display and plenty of other useful things ! The only limitation is your imagination !

tip

A good way to understand how a plugin is made and find inspiration for your own developement is to browse the plugin sources repository

Plugin Configuration files​

While first start, Volumio will create a folder that contains saved parameter in a config.json stored in:

/data/configuration/mycategory/myplugin

The plugins.json file​

The plugins.json file stores the status of core plugins in /volumio/app/plugins/plugins.json and extra plugins found in /data/plugins/plugins.json. Those files store the name of loaded plugins and their status.

caution

If you create a new plugin MANUALLY, you MUST add a plugin reference to plugins.json files in /data/plugins/plugins.json. If such reference is not found, volumio will automatically delete your plugin folder.

The plugins json contains informations on plugins status:

  • Enabled, which can be true or false
  • Started, which can be true or false

Add your information under your plugin relevant category. For example, if I'm adding a music_service plugin called "google_music", the relevant section will look like

{
  "music_service": {
    "google_music": {
      "enabled": {
        "type": "boolean",
        "value": true
      },
      "status": {
        "type": "string",
        "value": "STARTED"
      }
    },
    ...