diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 7fe5a2f4..f93cd645 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -8,6 +8,55 @@ Extension development development of Mopidy extensions should become in the future, not how to currently develop an extension for Mopidy. + +Mopidy started as simply an MPD server that could play music from Spotify. +Early on Mopidy got multiple "frontends" to expose Mopidy to more than just MPD +clients: for example the Last.fm frontend what scrobbles what you've listened +to to your Last.fm account, the MPRIS frontend that integrates Mopidy into the +Ubuntu Sound Menu, and the HTTP server and JavaScript player API making web +based Mopidy clients possible. In Mopidy 0.9 we added support for multiple +music sources without stopping and reconfiguring Mopidy: for example the local +backend for playing music from your disk, the stream backend for playing +Internet radio streams, and the Spotify and SoundCloud backends, for playing +music directly from those services. + +All of these are examples of what you can accomplish by creating a Mopidy +extension. If you want to create your own Mopidy extension for something that +does not exist yet, this guide to extension development will help you get your +extension running in no time, and make it feel the way users would expect your +extension to behave. + + +Anatomy of an extension +======================= + +Extensions are all located in a Python package called ``mopidy_something`` +where "something" is the name of the application, library or web service you +want to integrated with Mopidy. So for example if you plan to add support for a +service named Soundspot to Mopidy, you would name your extension's Python +package ``mopidy_soundspot``. + +The name of the actual extension (the human readable name) however would be +something like "Mopidy-Soundspot". Make sure to include the name "Mopidy" +somewhere in that name and that you check the capitalization. This is the name +users will use when they install your extension from PyPI. + +The extension must be shipped with a ``setup.py`` file and be registered on +`PyPI `_. Also make sure the development version link +in your package details work so that people can easily install the development +version into their virtualenv simply by running e.g. ``pip install +Mopidy-Soundspot==dev``. + +Mopidy extensions must be licensed under an Apache 2.0 (like Mopidy itself), +BSD, MIT or more liberal license to be able to be enlisted in the Mopidy +Extension Registry. Keep in mind that the Mopidy Extension Registry is a +moderated place and libraries will be reviewed upfront if they behave as +required. + + +Notes +===== + An extension wants to: - Be automatically found if installed