beets/docs/plugins/web.rst

Web Plugin
==========

The ``web`` plugin is a very basic alternative interface to beets that
supplements the CLI. It can't do much right now, and the interface is a little
clunky, but you can use it to query and browse your music and---in browsers that
support HTML5 Audio---you can even play music.

While it's not meant to replace the CLI, a graphical interface has a number of
advantages in certain situations. For example, when editing a tag, a natural CLI
makes you retype the whole thing---common GUI conventions can be used to just
edit the part of the tag you want to change. A graphical interface could also
drastically increase the number of people who can use beets.

Install
-------

The Web interface depends on `Flask`_. To get it, just run ``pip install
flask``.

.. _Flask: http://flask.pocoo.org/

If you require `CORS`_ (Cross-origin resource sharing), then you also
need `flask-cors`_. This can be installed by running ``pip install flask-cors``.

.. _flask-cors: https://github.com/CoryDolphin/flask-cors
.. _CORS: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing

Finally, enable the ``web`` plugin in your configuration
(see :ref:`using-plugins`).

Run the Server
--------------

Then just type ``beet web`` to start the server and go to
http://localhost:8337/. This is what it looks like:

.. image:: beetsweb.png

You can also specify the hostname and port number used by the Web server. These
can be specified on the command line or in the ``[web]`` section of your
:doc:`configuration file </reference/config>`.

On the command line, use ``beet web [HOSTNAME] [PORT]``. Or the configuration
options below.

Usage
-----

Type queries into the little search box. Double-click a track to play it with
`HTML5 Audio`_.

.. _HTML5 Audio: http://www.w3.org/TR/html-markup/audio.html

Configuration
-------------

To configure the plugin, make a ``web:`` section in your
configuration file. The available options are:

- **host**: The server hostname. Set this to 0.0.0.0 to bind to all interfaces.
  Default: Bind to 127.0.0.1.
- **port**: The server port.
  Default: 8337.
- **cors**: The CORS origin. See below.
  Default: CORS is disabled.

Implementation
--------------

The Web backend is built using a simple REST+JSON API with the excellent
`Flask`_ library. The frontend is a single-page application written with
`Backbone.js`_. This allows future non-Web clients to use the same backend API.

.. _Flask: http://flask.pocoo.org/
.. _Backbone.js: http://documentcloud.github.com/backbone/

Eventually, to make the Web player really viable, we should use a Flash fallback
for unsupported formats/browsers. There are a number of options for this:

* `audio.js`_
* `html5media`_
* `MediaElement.js`_

.. _audio.js: http://kolber.github.com/audiojs/
.. _html5media: http://html5media.info/
.. _MediaElement.js: http://mediaelementjs.com/

Cross-origin resource sharing (CORS)
------------------------------------

This is only required if you intend to access the API from a browser using JavaScript and
the JavaScript is not hosted by the beets web server.

The browser will check if the resources the JavaScript is trying to access is coming from the
same source as the the Script and give an error similar to the following:

``XMLHttpRequest cannot load http://beets:8337/item/xx. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://webserver' is therefore not allowed access.``

To prevent this, `CORS`_ is used. To enable CORS, set the ``cors`` configuration option to the origin
of your JavaScript or set it to ``'*'`` to enable access from all origins. Note that there are
security implications if you set the origin to ``'*'``, please research this before enabling it.

For example::

    web:
        host: 0.0.0.0
        cors: 'http://webserver'


JSON API
--------


``GET /item/``
++++++++++++++

Responds with a list of all tracks in the beets library. ::

    {
      "items": [
        {
          "id": 6,
          "title": "A Song",
          ...
        }, {
          "id": 12,
          "title": "Another Song",
          ...
        }
        ...
      ]
    }


``GET /item/6``
+++++++++++++++

Looks for an item with id *6* in the beets library and responds with its JSON
representation. ::

    {
      "id": 6,
      "title": "A Song",
      ...
    }

If there is no item with that id responds with a *404* status
code.


``GET /item/6,12,13``
+++++++++++++++++++++

Response with a list of tracks with the ids *6*, *12* and *13*.  The format of
the response is the same as for `GET /item/`_. It is *not guaranteed* that the
response includes all the items requested. If a track is not found it is silently
dropped from the response.


``GET /item/query/querystring``
+++++++++++++++++++++++++++++++

Returns a list of tracks matching the query. The *querystring* must be a valid query as described in :doc:`/reference/query`. ::

    {
      "results": [
        { "id" : 6,  "title": "A Song" },
        { "id" : 12, "title": "Another Song" }
      ]
    }


``GET /item/6/file``
++++++++++++++++++++

Sends the  media file for the track. If the item or its corresponding file do
not exist a *404* status code is returned.


Albums
++++++

For albums, the following endpoints are provided:

* ``GET /album/``

* ``GET /album/5``

* ``GET /album/5,7``

* ``GET /album/query/querystring``

The interface and response format is similar to the item API, except replacing
the encapsulation key ``"items"`` with ``"albums"`` when requesting ``/album/``
or ``/album/5,7``. In addition we can request the cover art of an album with
``GET /album/5/art``.


``GET /stats``
++++++++++++++

Responds with the number of tracks and albums in the database. ::

    {
      "items": 5,
      "albums": 3
    }