Simple and minimalistic Mopidy HTTP client, touch friendly, works in most (mobile) web browsers
JavaScript HTML Python CSS
Switch branches/tags
Nothing to show
Clone or download
xolox Bug fix for issue #1: Exception if playlist has no tracks
Refer to issue 1 on GitHub for details:
Latest commit fa4def1 Jun 8, 2015


Simple Mopidy webclient

The simple Mopidy webclient is an HTTP client for the Mopidy music server that's designed to be simple and minimalistic in an attempt to create a touch friendly web interface that works in most (mobile) web browsers.


Mopidy music server is an awesome piece of software that provides a headless music player compatible with the MPD protocol and is capable of streaming music from Spotify. I'm running Mopidy on two Raspberry Pi computers, one in my living room and one in my bedroom.

The only thing I was missing was a simple client with playback control, volume control and playlist selection that would work on my smart phones, iPad and laptops. Despite the plentitude of HTTP clients referenced in the Mopidy documentation and the fact that any MPD client should work I didn't succeed in finding a client that actually worked well for me on all of the mentioned devices :-(

After wasting two days on my search for a simple Mopidy client that would Just Work (TM) I decided to take up the Mopidy developers' promise that Mopidy is easy to extend by developing my own web interface. It took three iterations to build something I was happy with.

First iteration: Server side PHP
The first proof of concept was a simple PHP script using Mopidy's JSON-RPC API. Once I had playback control implemented I decided that writing PHP makes me sad so I switched to Python (and Flask) instead.
Second iteration: Server side Python
The second proof of concept got a lot further than the first: I implemented playback control, volume control and playlist selection. While working on this implementation it began to dawn on me that a JavaScript client using asynchronous HTTP connections could be a lot more responsive than any server side implementation (and potentially simpler to boot).
Third iteration: Client side JavaScript
JavaScript is not exactly my favorite language but the experience of writing a Mopidy web client wasn't all that bad. Once I had everything running I really appreciated the elegance of only needing HTML, CSS and JavaScript to build a simple but usable Mopidy client! I didn't even use Mopidy.js because I started out by porting Python code built on top of Mopidy's JSON-RPC API.

Getting started

As mentioned in the introduction above the simple Mopidy webclient is a client side JavaScript application. Despite this the client is published as a Python package. This package contains the client side code plus the minimal amount of glue (18 lines of Python code :-) needed to expose the client as a proper Mopidy HTTP extension. The Python package is available on PyPI which means it's very easy to install the client:

$ sudo pip install Mopidy-Simple-Webclient

After installation you need to restart your Mopidy daemon to load the new extension. I'm running Mopidy as a system daemon so I would use the following command:

$ sudo service mopidy restart

Accessing the web interface

Once you've installed the extension and restarted your Mopidy daemon, the Mopidy web interface should look similar to this:

Mopidy webserver start screen.

Click on the 'simple-webclient' link to open the simple Mopidy webclient.

The playlist selection interface

The simple Mopidy webclient doesn't have a playlist / tracklist editing interface and it also doesn't provide a way to browse your music collection. Instead you are expected to create a playlist in a more full featured Mopidy client or Spotify and select this playlist in the simple Mopidy web client. Selecting a playlist looks similar to this:

Playlist selection interface of the simple Mopidy webclient.

Please note that I've only been using Mopidy for a couple of days (at the time I'm writing this) so I'm still getting to grips with how Mopidy works and this means I've only tested the playlist selection interface with Spotify playlists (not with local playlists).

The playback control interface

Once the Mopidy track list (the 'current playlist') contains some tracks the simple Mopidy webclient will switch to the playback control interface which looks like this:

Playback control interface of the simple Mopidy webclient.

Here's an explanation of the main elements in the playback control interface:

  • At the top is the track title, followed by the album name and the artist(s).
  • Below the track info are the playback control buttons. When nothing is playing this shows previous/play/next buttons. While a track is playing this shows previous/pause/stop/next buttons.
  • The line of blue/grey dots is the volume control. HTML5 has fancy slider controls for this but the web browser on my smartphone isn't fancy enough to support those so I created a simple touch friendly control instead.
  • The button "Select playlist" brings you back to the playlist selection interface and the other other two buttons do what you would expect them to :-).

Future improvements

Some ideas for if/when I find the time to continue work on this client:

Real time state changes
It would be awesome to enable instant server → client notifications instead of a 10 second polling interval. It looks like this requires websockets. Not sure those will work on my smart phone. Even if they don't, maybe I can add optional support (graceful degradation)?
Enable cover art
It's not yet clear to me how cover art works in Mopidy, but other clients can do it so I should be able to as well :-)
Enable server side configuration
Mopidy's extension mechanism already forces me to use a configuration file, so why not add some useful options to that, like the ability to change the page title? This is not trivial because it would involve the first "server side" logic in this project (on the other hand that opens the door to functionality not available to pure JavaScript clients).
Upgrade jQuery/Bootstrap, bundle the files
Right now jQuery and Bootstrap are loaded from the Google and Bootstrap CDNs but at some point the referenced versions will disappear from the web. Why not upgrade to the latest versions and bundle the files in the git repository and Python source distributions?


The latest version of the simple Mopidy webclient is available on PyPI and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2014 Peter Odding.

The simple Mopidy webclient uses the following projects:

Mopidy music server
Licensed under the Apache License, refer to the Mopidy license file.
Licensed under the MIT license, refer to the jQuery license file.
The version used is licensed under the Apache License, refer to the Bootstrap license file (newer versions are licensed under the MIT license).
Licensed under the BSD license, refer to the sprintf.js license file (tip: I used to identify the license :-).
Humanity icon theme
Licensed under the Creative Commons Attribution-ShareAlike 3.0 license, refer to the Humanity license file. It's not clear to me if using these icons with attribution and without alterations requires my work to be licensed under the same license as well (I'm hoping it doesn't, I'm afraid it does). If it turns out that this is true I'd rather find a different icon set because using CC BY-SA license for software doesn't make any sense.