HTTP Media Server

A way to listen to your music library from everywhere. Once set up you won't need anything but a browser. Think of it as your own Spotify service over which you have full control. HTTPMS will let you browse through and listen to your music over HTTP(s). Up until now I've had a really bad time listening to my music which is stored back home. I would create a mount over ftp, sshfs or something similar and point the local player to the mounted library. Every time it resulted in some upleasantries. Just imagine searching in a network mounted directory!

No more!

• Web UI
• Features
• Requirements
• Install
• Docker Image
• Configuration
• As an API
• OSX Media Keys Control
• Clients
• Known Issues
• Change Log

Web UI

Have a taste of how its web interface looks like

It comes with a custom jPlayer which can handle playlists with thousands of songs. Which is an imrovement over the original which never included this performance patch.

I feel obliged to say that the music on the screenshot is written and performed by my close friend Velislav Ivanov.

Features

• Uses jplayer to play your music so it will probably work in every browser
• jplayer supports mp3, oga, wav, flac and m4a audio formats
• Interface and media via HTTPS
• HTTP Basic Authenticate
• Playlists
• Media artwork from local files or automatically downloaded from the Cover Art Archive
• Search by track name, artist or album
• Download whole album in a zip file with one click
• Controllable via media keys in OSX with the help of BeardedSpice

Requirements

If you want to install it from source (from here) you will need:

• Go 1.10 or later installed and properly configured.

• go-taglib - Read the install notes

• go-sqlite3 - go get github.com/mattn/go-sqlite3 would probably be enough.

Install

The safest route is installing one of the releases.

If you have an already built version (for example https_1.1.0_linux.tar.gz) it includes an install script which would install HTTPMS in /usr/bin/httpms. You will have to uninstall any previously installed versions first. An uninstall script is provided as well.

If installing from source running go install in the project root directory will compile httpms and move its binary in your $GOPATH. Releases from v1.0.1 onward have their go dependencies vendored in.

If you want to install the latest development version from the master branch, you can just run

go get github.com/ironsmile/httpms

For building a release version you will need packr installed. Then in the root of the project run

make release

This will produce a binary httpms which is ready for distribution. Check its version with

./httpms -v

First Run

Once installed, you are ready to use your media server. After its initial run it will create a configuration file which you will have to edit to suit your needs.

1. Start it with httpms

2. Edit the config.json and add your library paths to the "library" field. This is an important step. Without it, httpms will not know where your media files are.

Docker

Alternatively to installing everything in your environment you can use my docker image.

docker build -t ironsmile/httpms github.com/ironsmile/docker-httpms

It is ready for running or development.

Configuration

HTTPS configuration is saved in a json file, different for every user in the system. Its location is as follows:

• Linux or BSD: $HOME/.httpms/config.json
• Windows: %APPDATA%\httpms\config.json

When started for the first time HTTPMS will create one for you. Here is an example:

{
    // Address and port on which HTTPMS will listen. It is in the form hostname[:port]
    // For exact explanation see the Addr field in the Go's net.http.Server
    // Make sure the user running HTTPMS have permission to bind on the specified
    // port number
    "listen": ":443",

    // true if you want to access HTTPMS over HTTPS or false for plain HTTP.
    // If set to true the "ssl_certificate" field must be configured as well.
    "ssl": true,

    // Provides the paths to the certificate and key files. Must be full paths, not
    // relatives. If "ssl" is false this can be left out.
    "ssl_certificate": {
        "crt": "/full/path/to/certificate/file.crt",
        "key": "/full/path/to/key/file.key"
    },

    // true if you want the server to require HTTP basic authentication. Credentials
    // are set by the 'authentication' field below.
    "basic_authenticate": true,
    
    // User and password for the HTTP basic authentication.
    "authentication": {
        "user": "example",
        "password": "example"
    },

    // An array with all the directories which will be scanned for media. They must be
    // full paths and formatted according to your OS. So for example a Windows path
    // have to be something like "D:\Media\Music".
    // As expected HTTPMS will need permission to read in the library folders.
    "libraries": [
        "/path/to/my/files",
        "/some/more/files/can/be/found/here"
    ],
    
    // Optional configuration on how to scan libraries. Note that this configuration
    // is applied to each library separately.
    "library_scan": {
        // Will wait this much time before actually starting to scan a library.
        // This might be useful when scanning is resource hungry operation and you
        // want to postpone it on start up.
        "initial_wait_duration": "1s",
        
        // With this option a "operation" is defined by this number of scanned files.
        "files_per_operation": 1500,

        // After each "operation", sleep this amount of time.
        "sleep_after_operation": "15ms"
    },

    // When true, HTTPMS will search Cover Art Archive for album artworks when none is
    // found locally. Anything found will be saved in the HTTPMS database and later used
    // instead of further calls to the archive.
    "download_artwork": true
}

List with all directives can be found in the configration wiki.

As an API

You can use HTTPMS as a REST API and write your own player. Or maybe a plugin for your favourite player which would use your HTTPMS installation as a backend.

Authentication

When your server is open you don't have to authenticate requests to the API. Installations protected by username and password require you to authenticate requests when using the API. For this the following methods are supported:

• Bearer token in the Authorization HTTP header (as described in RFC 6750):

Authorization: Bearer token

• Basic authentication (RFC 2617) with your username and password:

Authorization: Basic base64(username:password)

Authentication tokens can be acquired using the /login/token/ endpoint described below. Using tokens is the preferred method since it does not expose your username and password in every request. Once acquired users must register the tokens using the /register/token/ endpoint in order to "activate" them. Tokens which are not registered may or may not work. Tokens may have expiration date or they may not. Integration applications must provide a mechanism for token renewal.

Endpoints

• Search
• Browse
• Play a Song
• Download an Album
• Album Artwork
  • Get Artwork
  • Upload Artwork
  • Remove Artwork
• Token Request
• Register Token

Search

One can do a search query at the following endpoint

GET /search/?q={query}

wich would return an JSON array with tracks. Every object in the JSON represents a single track which matches the query. Example:

[
   {
      "album" : "Battlefield Vietnam",
      "title" : "Somebody to Love",
      "track" : 10,
      "artist" : "Jefferson Airplane",
      "id" : 18,
      "album_id" : 2,
      "format": "mp3"
   },
   {
      "album" : "Battlefield Vietnam",
      "artist" : "Jefferson Airplane",
      "track" : 14,
      "format": "flac",
      "title" : "White Rabbit",
      "album_id" : 2,
      "id" : 22
   }
]

The most importat thing here is the track ID at the id key. It can be used for playing this track. The other interesting thing is album_id. Tracks can be grouped in albums using this value. And the last field of particular interest is track. It is the position of this track in the album.

Browse

A way to browse through the whole collection is via the browse API call. It allows you to get its albums or artists in an ordered and paginated manner.

GET /browse/[?by=artist|album][&per-page={number}][&page={number}][&order-by=id|name][&order=desc|asc]

The returned JSON contains the data for the current page, the number of all pages for the current browse method and URLs of the next or previous pages.

{
  "pages_count": 12,
  "next": "/browse/?page=4&per-page=10",
  "previous": "/browse/?page=2&per-page=10",
  "data": [ /* different data types are returned, determined by the `by` parmeter */ ]
}

For the moment there are two possible values for the by parameter. Consequently there are two types of data that can be returned: "artist" and "album" (which is the default).

by=artist

would result in value such as

{
  "artist": "Jefferson Airplane",
  "artist_id": 73
}

by=album

would result in value such as

{
  "album": "Battlefield Vietnam"
  "artist": "Jefferson Airplane",
  "album_id": 2
}

Additional parameters

per-page: controls how many items would be present in the data field for every particular page. The default is 10.

page: the generated data would be for this page. The default is 1.

order-by: controls how the results would be ordered. The value id means the ordering would be done by the album or artist ID, depending on the by argument. The same goes for the name value. Defaults to name.

order: controls if the order would ascending (with value asc) or descending (with value desc). Defaults to asc.

Play a Song

GET /file/{trackID}

This endpoint would return you the media file as is. A song's trackID can be found with the search API call.

Download an Album

GET /album/{albumID}

This endpoint would return you an archive which contains the songs of the whole album.

Album Artwork

HTTPMS supports album artwork. Here are all the methods for managing it through the API.

Get Artwork

GET /album/{albumID}/artwork

Returns a bitmap image with artwork for this album if one is available. Searching for artwork works like this: the album's directory would be scanned for any images (png/jpeg/gif/tiff files) and if anyone of them looks like an artwork, it would be shown. If this fails, you can configure HTTPMS to search in the MusicBrainz Cover Art Archive. By default no external calls are made.

Upload Artwork

PUT /album/{albumID}/artwork

Can be used to upload artwork directly on the HTTPMS server. This artwork will be stored in the server database and will not create any files in the library paths. The image should be send in the body of the request in binary format without any transformations. Only images up to 5MB are accepted. Example:

curl -i -X PUT \
  --data-binary @/path/to/file.jpg \
  http://127.0.0.1:9996/album/18/artwork

Remove Artwork

DELETE /album/{albumID}/artwork

Will remove the artwork from the server database. Note, this will not touch any files on the file system. Thus it is futile to call it for artwork which was found on disk.

Token Request

POST /login/token/
{
  "username": "your-username",
  "password": "your-password"
}

You have to send your username and password as a JSON in the body of the request as described above. Provided they are correct you will receive the following response:

{
  "token": "new-authentication-token"
}

Before you can use this token for accessing the API you will have to register it with on "Register Token" endpoint.

Register Token

POST /register/token/

This endpoint registers the newly generated tokens with HTTPMS. Only registered tokens will work. Requests at this endpoint must authenticate themselves using a previously generated token.

Media Keys Control For OSX

You can control your HTTPMS web interface with the media keys the same way you can control any native media player. To achieve this a third-party program is required: BearderSpice. Sadly, HTTPMS is not included in the default web strategies bundled-in with the program. You will have to import the strategy file included in this repo yourself.

How to do it:

1. Install BeardedSpice. Here's the download link
2. Then go to BeardedSpice's Preferences -> General -> Media Controls -> Import
3. Select the bearded-spice.js strategy from this repo

Or with images:

BeardedSpice Preferences:

Select "Import" under Genral tab:

Select the bearded-spice.js file:

Then you are good to go. Smash those media buttons!

Clients

You are not restricted to using the web UI. The server has a RESTful API which can easily be used from other clients. I will try to keep a list with all of the known clients here:

• httpms-android is a Android client for HTTPMS
• httpms-rhythmbox is HTTPMS client plugin for Gnome's Rhythmbox

Known Issues

• Non-ASCII searches are case sensitive.