From e1ec5b2217b3222b99b6531af7f821d596ea61cc Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sun, 12 Jan 2014 13:26:42 +0100 Subject: [PATCH] docs: How to use backend URI schemes (fixes #429) --- docs/api/backends.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/api/backends.rst b/docs/api/backends.rst index 98502b5e..71124166 100644 --- a/docs/api/backends.rst +++ b/docs/api/backends.rst @@ -12,6 +12,43 @@ backend. If you are working on a frontend and need to access the backends, see the :ref:`core-api` instead. +URIs and routing of requests to the backend +=========================================== + +When Mopidy's core layer is processing a client request, it routes the request +to one or more appropriate backends based on the URIs of the objects the +request touches on. The objects' URIs are compared with the backends' +:attr:`~mopidy.backend.Backend.uri_scheme` to select the relevant backends. + +An often used pattern when implementing Mopidy backends is to create your own +URI scheme which you use for all tracks, playlists, etc. related to your +backend. For example: + +- Spotify already got an URI scheme (``spotify:track:...``, + ``spotify:playlist:...``, etc.) used throughout their applications, and thus + Mopidy-Spotify simply use the same URI scheme. + +- Mopidy-Soundcloud created it's own URI scheme, after the model of Spotify, + and use URIs of the following forms: ``soundcloud:search``, + ``soundcloud:user-...``, ``soundcloud:exp-...``, and ``soundcloud:set-...``. + +- Mopidy differentiates between ``file://...`` URIs handled by + :ref:`ext-stream` and ``local:...`` URIs handled by :ref:`ext-local`. + :ref:`ext-stream` can play ``file://...`` URIs to tracks and playlists + located anywhere on your system, but it doesn't know a thing about the + object before you play it. On the other hand, :ref:`ext-local` scans a + predefined :confval:`local/media_dir` to build a metadata library of all + known tracks. It is thus limited to playing tracks residing in the media + library, but can provide additional features like directory browsing and + search. In other words, we got two different ways of playing local music, + handled by two different backends, and have thus created to different URI + schemes to separate their handling. + +If there isn't an existing URI scheme that fits for your backend's purpose, +you should create your own, and name it after your extension's +:attr:`~mopidy.ext.Extension.ext_name`. + + Backend class =============