Bemix Notes

From SlugWiki
Revision as of 15:14, 22 January 2006 by Rob (Talk) (Todo)

Jump to: navigation, search

Bemix is a web-based media player. It supports multiple soundcards and various networked client types, allowing a group to use a centralized server to control several speakers. Commands are issued through URLs, where the URL portion of the address represents the command to be issued, while the query portion of the URL passes in parameters to the server. Media is played via mplayer, enabling any media format to be played provided it is supported in mplayer.


Bemix requires python2.3, mplayer, and an instance of MySQL server running on the local machine to function properly. The MySQL server must contain a "bemix" database with tables "playlist" and "track." The server is designed to serve HTTP requests over port 8080.

The bemix server supports both local and remote speakers. Local speakers are connected to the same machine as the bemix server is running on, and are controlled directly by the server. The server does support multiple soundcards in the same machine. Remote speakers are connected to external machines, and are controlled via the bemix slave protocol.

MySQL Table Schema

The playlist table schema:

| Field      | Type         | Null | Key | Default | Extra          |
| playlistId | int(11)      |      | PRI | NULL    | auto_increment |
| name       | varchar(100) |      |     |         |                |

The track table schama:

| Field       | Type    | Null | Key | Default | Extra          |
| trackId     | int(11) |      | PRI | NULL    | auto_increment |
| playlistId  | int(11) |      |     | 0       |                |
| trackNumber | int(11) |      |     | 0       |                |
| file        | text    | YES  |     | NULL    |                |

Server Commands

All commands are send as URLs with information passed in the query portion. All URLs are relative to, and all URLs have an output=[html, client]. An example URL is All x, y, ... must be properly encoded for URLs. The following commands are available for use by bemix clients.


A player represents a single soundcard. There is one player for every set of speakers that the bemix server controls. Before anything can be played on a player, a playlist must be created, filled with songs, and loaded on the player.

  • play?playerId=x (starts playing the current song on a player)
  • pause?playerId=x (pauses playback on a player, or resumes a paused player)
  • stop?playerId=x (stops playback on a player)
  • loadList?playerId=x&playlistId=y (loads and begins to play a playlist on a player)
  • seek?playerId=x&position=y (seeks the player to a certain position in a song, in seconds)
  • volume?playerId=x&level=y (sets the volume for a player to a level between 0-100)
  • next?playerId=x (moves to the next song in a playlist)
  • previous?playerId=x (moves to the previous song in a playlist)
  • player?playerId=x (gets the name, index of the loaded playlist, current index of the loaded playlist, current time of the current song, total time of the current song, and status of the player where 0=playing, 1=paused, 2=stopped)


A playlist consists of a name and music files that are associated with it. The songs in a playlist are ordered with indices starting at 0. Before anything can be played, a playlist must be created and loaded onto a specific player.

  • create?name=x (creates a new playlist which is assigned a unique playlistId)
  • delete?playlistId=x (deletes a playlist from bemix)
  • add?playlistId=x&song=y (adds a song to a playlist)
  • remove?playlistId=x&index=y (removes a song at a certain index in a playlist from a playlist)
  • playlist?playlistId=x (gets the name and tracks from a playlist)


These commands are used to navigate the filesystem on the server to determine which files are available for playing. All operations on files and directories are relative to the server's root music directory, so /A/Air may actually refer to /mnt/tunes/A/Air on the server.

  • browse?dir=x (returns directories and files that exist at relative path x)


These commands query the bemix server for generalized information about the state of the entire system.

  • players (lists all playerIds available)
  • playlists (lists all playlistIds available)


Each command returns a data structure through HTTP that defines variable names and values. A (variable name, value) combination is referred to as a field. Every command contains at least one success field, whose value may be either true or false. If any tag is false, it should be assumed that the entire command failed. Each command may optionally return a comment field as well, whose value gives some indication of why an operation may have failed.

In addition, most commands return additional information about the state of a particular aspect of the bemix server.

Slave Commands

Slave commands are, in general, identical in form to their "server" counterparts defined above. However, there are additional commands which are defined for the bemix server to communicate with its slaves. The slave server understands all commands understood by the server that are listed under "Player", as well as the "players" command.

Additional Server Commands

The bemix server understands additional commands that are meant to be used only by bemix slaves. Clients should not use these commands themselves.

  • playlistSong?playlistId=x&index=y (gets the name of the song at a specified index in a given playlist)

Client Types

Bemix is capable of dumping data in multiple of formats. Currently only the "client" and "html" formats are planned, but XML/RDF formats are possibility in the future. The format of the export is indicated in the URL by the mandatory output parameter.


The "client" output format returns data in a simple newline-delimited list. String values are not delimited by quote characters, and list items are delimited by commas (including a comma after the final element). The format of each line is name=value, where name is the name of the variable being returned, and value is the value of the variable. No whitespace characters are inserted between name, =, and value.

The order in which the fields are returned is not guaranteed, and it should not be assumed that all tags will be present or in any particular order.

The MIME type of the client output is 'text/plain'.

The result of the browse command

dir0=/P/Porcupine Tree/Coma Divine
dir1=/P/Porcupine Tree/Spiral Circus
dir2=/P/Porcupine Tree/In Absentia
dir3=/P/Porcupine Tree/Insignificance
dir4=/P/Porcupine Tree/Lightbulb Sun
dir5=/P/Porcupine Tree/Metanoia
dir6=/P/Porcupine Tree/On the Sunday of Life
dir7=/P/Porcupine Tree/Recordings
file0=/P/Porcupine Tree/Chloroform (Instrumental Rough Mix).mp3
file1=/P/Porcupine Tree/Disappear (Demo Version 2.0).mp3
file2=/P/Porcupine Tree/Is Not.mp3
file3=/P/Porcupine Tree/2003 Intro Music.mp3
file4=/P/Porcupine Tree/Even Less, Part 2.mp3
file5=/P/Porcupine Tree/London.mp3

The result of the playlists command


The result of the players command with an invalid playerId

comment=playerId not found


When dumping data as HTML, bemix creates pages that can also be used to issue commands to the server. For instance, a browse page generates a link for each directory that is being displayed that points to the browse page for that subdirectory.

HTML output is meant to be used through a webbrowser. If you're interested in manipulating the bemix server through some other means, use the "client" output format described above.


The code base needs to be cleaned up substantially before the 1.0 release of the software. Currently an alpha version, the code works, but is messy.

Beta Version

The beta version will contain various improvements over the current version. This version will add support for slave clients, and will permit slaves to drop in and out at will.


  • The handler for the bemix server parses the incoming url into an action, an output type, and a dictionary of variables. These are then given to the manager.


  • Maintains a list of available bemix-slave instances, their available players, and the available playlists
  • Contains a single method performAction(action, output="client", vars={}) that calls the appropriate method in the many command classes


  • Contains methods that are used by manager.ServerManager to perform actions that bemix-server responds to

Overall Improvements

  • create a SlaveManager to drop-in for the normal manager to be used in the slaves
  • replace the current dispatching in bemix-server with a model that passes in all of the variables
  • find a python module to parse the query string in a URL (rather than the current homebrew method)
  • replace the current server+players & slaveServer+players with server+slavePlayers, where slavePlayers are created on both the local and remote machines -- might create too many open ports; could create a slave manager that has the open port and works like current server (controls the various local players itself), doesn't have to be done over http?

See Also

  • Bemix - Overview information about the Bemix music system