Structure

The intention of this page is to document the structure of the project. Herein will reside both the overall project architecture as well as relevant information about each subsystem of the project.

Architecture

Partify is structured roughly into a few main parts:

• The web server. This is where much of the application logic lives that powers the application, including
  • Maintaining synchronization of the Mopidy playlist and Partify play queue
  • Facilitating the queueing of tracks and managing which tracks to play next
  • Subscribing the Mopidy IDLE events to stay aware of changes in the Mopidy server
  • Serving up pages of the front-end to run
• The database. This is where the data needed for the application is stored, including:
  • Users
  • Track metadata (acting a little bit like a cache)
  • The play queue
  • Application configuration information
• The front-end. These are the web pages and associated code that runs in the browser, including:
  • The player and views which allow personal play queue management and visibility into the party-wide play queue
  • User authentication

Design Notes

Separation of Concerns

Functions of the application are intended to be separated into two main parts: a client and an API which the client can use to perform certain functions. In this case the client is the front-end, a collection of web pages that can make requests asynchronously to the API to perform all of the back-end functionality that is needed. The API is exposed by the web server and is intended to be RESTful; that is, in a rough sense the API should make use of HTTP verbs to facilitate access to needed resources. While certain endpoints on the web server will serve code for the front-end to run (i.e. the browser), most of the endpoints will act as ways of accessing the various functions of the application, including track queueing, player status, etc. Each endpoint that does not serve a web page will return a JSON-formatted response including information about the request (whether or not it was successful) as well as any information that needs to be returned from the endpoint.

The Play Queue

Partify manages a list of tracks that are queued to play by users. This is called the global queue. Partify also supports personal play queues, which allow users to specify which tracks they would like to play next when it is their turn to play a track.

The order that tracks are moved from a user's personal queue into the global queue is managed by the application at track addition time. Right now the selection scheme will be round-robin, but will include support for other selection schemes in the future.

Play Queue Synchronization

The application's internal track queue needs to stay in sync with the Mopidy playlist. This is accomplished by trusting that Mopidy's playlist is essentially untouched by other applications or users and that the Mopidy play queue can stay authoritative over the Partify internal play queue. To ensure consistency between the two play queues, each track (or PlayQueueEntry item in Partify) is assigned an ID by Mopidy when the track is added to the Mopidy play queue. This ID is associated with the track in the Partify play queue to keep track of who is playing what. Whenever the Mopidy playlist changes, an event is fired to a listener in Partify who has an IDLE command out with the Mopidy server. When the listener receives this change event it checks to see if the Partify play queue is in sync with the Mopidy play queue. It accomplishes this by retrieving the current play queue from Mopidy and removing Partify play queue entries with no corresponding ID in the Mopidy playlist. Then it checks each entry in the Mopidy play queue for a corresponding entry in the Partify database and makes sure that information about the track in each location is synchronized, using the Mopidy play queue information if it is not in sync. If an entry does not exist for a track in the Partify play queue, one is created. This scheme simplifies the process of ensuring consistency since tracks can be added and removed from Mopidy alone and this mechanism will ensure consistency in one place, rather than being scattered throughout the application logic.

The Front-End

The front-end is templated using the Jinja2 templating engine that comes with Flask. The javascript that runs in the browser is written in Coffeescript, which compiles to Javascript. Much of the front-end magic comes from the Javascript libraries jQuery and jQueryUI, as well as the Blueprint CSS framework.

The Front-End Player

The player in the front end stays in sync with Mopidy by polling an endpoint in the Partify web server once every three seconds to get status about Mopidy's playback. In the intervening time between polls, a Javascript timer on the page updates the playback progress once every second. The player will eventually pull images relating to the artist from Last.fm and will hopefully show the user who played the tracks' avatar at some point.