Home

Awesome

vosbox is a HTML5 PHP/jQuery based jukebox.

Screenshot of vosbox

It supports

Given an arbitrary mess of MP3s in any directory structure, vosbox will find all MP3s, prefering high-quality files.

Album art will be extracted and resized using the <imagemagick.org> library from the MP3 file with the fantastic http://GetID3.org/ library, or loaded from the containing folder.

vosbox currently supports sqlite or file based backends, with support for any other database easy to implement.

A native android app that uses the API is planned.

Dependencies

Usage

  1. Serve www/ with Apache and PHP
  2. Crawl any directory (read permissions required) with cli/crawl.sh <directory>
  3. Watch that directory, if required, for new songs with cli/watch.sh <directory>

Example Apache configuration (000-default.conf)

The use of a .htaccess file is recommended to enable password protection.

<VirtualHost *:80>
	DocumentRoot /path/to/vosbox/www
	ServerName pibox.local # This should be the FQDN of the Pi
	ServerAlias pibox vosbox.local vosbox # Any aliases should go here
	<Directory /path/to/vosbox/www>
		AllowOverride All # Allows setting of basic auth etc. via .htaccess files
		Order allow,deny  # Replace these two lines with 'Require all granted' for apache >2.4
		Allow from all
	</Directory>
</VirtualHost>

To enable SSL, using a self-signed certificate:

<IfModule mod_ssl.c>
	<VirtualHost *:443>
		DocumentRoot /path/to/vosbox/www
		ServerName pibox.local # This should be the FQDN of the Pi
		ServerAlias pibox vosbox.local vosbox # Any aliases should go here
		SSLEngine On
		SSLCertificateFile /path/to/ssl/certificate
		SSLCertificateKeyFile /path/to/ssl/keyfile
		#SSLCACertificateFile /path/to/ssl/CAcertificate  # You probably won't need these two options unless you know what they are
		#SSLCertificateChainFile /path/to/ssl/CAchaincertificate
		<Directory /path/to/vosbox/www>
			AllowOverride All # Allows setting of basic auth etc. via .htaccess files
			Order allow,deny  # Replace these two lines with 'Require all granted' for apache >2.4
			Allow from all
		</Directory>
	</VirtualHost>
</IfModule>

Thanks to @frillip for this.

Keyboard shortcuts

f       : search
up/down : prev/next
d       : download active song
space   : pause/play
s       : shuffle

Mouse functions

Search results: Left click to play, right click to enqueue.

Playlist: Left click to play, right click to delete

JSON API

Songs are returned as the following JSON-formatted objects:

{
	title      : "The song name",
	artist     : "The artist name",
	album      : "The album name",
	year       : "2009",
	genre      : "Indie",
	id         : "74a12d502d7393e139e2fcca51200d67",
	albumArtId : "b092c997d98e13a21431c9ce58b80fbf"
}

The vosbox search engine (VSE)

The search engine that powers vosbox is very different to a standard fulltext search engine.

How it indexes:

  1. A PHP object per item, with descriptive attributes is added
  2. This object is scraped for unique lower-case alphanumeric keywords (using the tokeniser)
  3. The object is stored under an ID (specified or created automatically)
  4. Per keyword, the ID is associated in a reverse-map list

How it searches:

  1. The search string is tokenised in the same manner
  2. For each keyword, the corresponding list of IDs is intersected with the last (by the backend)
  3. The resulting intersection of IDs is used to return a set number of corresponding objects

This can be acheived with, currently, a file based or sqlite based backend.

The idea is that avoiding fulltext search queries with multiple wildcards results in a speed increase.

Configuration

In order to choose a different indexer, simply create var/config.php and define the constant INDEXER to be either sqlite or keystore. Redis is also planned, and will involve defining some more constants.

Vosbox uses the following excellent libraries: