MusicRest

This is a RESTful web service which allows you to upload traditional tunes in ABC notation and then have them transcoded into a variety of formats. In particular, you can use MusicRest to see a tune score in pdf, ps or png format or to listen to the tune (using a variety of tempi and instruments) in wav or midi format. It supports two different approaches for doing this:

1. Content Negotiation. You issue a request to the tune's URL and set the Accept request header to the required content type.

2. Explicit URL. You append the name of the requested content type to the basic URL of the tune. For example, if you append /wav it will be returned in wav format (irrespective of the contents of the Accept header).

Author: John Watson john.watson@gmx.co.uk

Usage

Genres and Rhythms

Although MusicRest is potentially useful for any genre of music, the current release is restricted to four - Irish, Scandi, Scottish and Klezmer. Each genre is configured with a set of standard rhythms for the genre - for example, whilst Irish uses jigs, reels, hornpipes etc., Scandi uses polska, marsch, schottis etc. Tunes in each genre are kept in separate collections; when posting a new tune, you must supply an appropriate rhythm (ABC's R header).

URL Scheme

URL path segments in italics represent fixed text; those in bold type are variable. For example, the text 'genre' is fixed whilst agenre can be any of irish, scandi, scottish or klezmer. The following URLs are supported:

Tunes

• GET / musicrest / genre - get a list of genres.

• GET / musicrest / genre / agenre - get a list of rhythms appropriate for the genre.

• GET / musicrest / genre / agenre / tune - get a paged list of tunes.

• POST / musicrest / genre / agenre / tune - submit a tune in ABC format.

• GET / musicrest / genre / agenre / exists - return true if the genre exists

• GET / musicrest / genre / agenre / tune / atune - get a tune in the format suggested by the Accept header.

• DELETE / musicrest / genre / agenre / tune / atune - delete the tune from the database.

• GET / musicrest / genre / agenre / tune / atune / exists - return true if the tune exists

• GET / musicrest / genre / agenre / tune / atune / format - get a tune the requested format (which can be abc, html, wav, pdf, ps or midi)

• POST / musicrest / genre / agenre / tune / atune / abc - add an alternative title to the tune

• GET / musicrest / genre / search - get a paged list of tunes that correspond to the search parameters.

• POST / musicrest / genre / transcode - submit a tune to temporary storage to check the validity of the ABC

A user must be logged in before he can submit or test-transcode a tune. Only the original submitter or the administrator user is allowed to delete tunes.

Production of wav output is still supported, but deprecated. It is too expensive to produce server-side unless you have a powerful server and a large data cache.

Comments

• GET / musicrest / genre / agenre / tune / atune / comments - get the comments attached to a tune

• POST / musicrest / genre / agenre / tune / atune / comments - add or edit a comment and attach it to a tune

• GET / musicrest / genre / agenre / tune / atune / comment / auser / acommentid - get a particular comment (written by the user with this id)

• DELETE / musicrest / genre / agenre / tune / atune / comment / auser / acommentid - delete this comment

• DELETE / musicrest / genre / agenre / comments - delete all comments in the genre

Users

There is also a fairly conventional set of URLs for user maintenance.

URL Parameters

URLs that return lists take optional paging parameters indicating the number of entries on a page and the identity of the page to display. The URL that requests a tune in wav format takes optional parameters indicating the tunes's instrument, tempo and transposition.

Content Negotiation

It is possible to request a tune in a format that corresponds to any of the following MIME types:

• text/plain
• text/xml
• text/html
• text/vnd.abc
• application/json
• audio/midi
• audio/wav
• application/postscript
• application/pdf
• image/png

Most lists may be obtained in xml, html or json format.

Runtime Dependencies

Linux is required for its transcoding services. MusicRest has been tested under Ubuntu 12.04. The following must be installed or present before the service can be run:

• a JVM (Java 1.8 or better)
• MongoDB (2.4.14)
• AbcMidi (3.10 or better)
• Abcm2ps (5.9.25 or better)
• ImageMagick (8:6.6.9.7-5ubuntu or better)
• Timidity (2.13.2 or better)

The scripts directory contains shell scripts that invoke the transcoding services. You must be sure to make these executable ( chmod +x )

Configuration

This is by means of musicrest.conf which must be supplied as a JVM -D startup parameter. The settings are largely self explanatory. The cache directory for transcode indicates that the transcoding scripts are file-based and the results of such scripts are allowed to remain in the file cache. Once the cache reaches its maximum allowed size for a time dependent on cacheClearInterval (a time in minutes) then the cache is cleared. Setting this to zero disables cache clearance. Get tune requests are served from the cache where this is possible. If you are supporting the generation of wav responses, you probably need to clear the cache periodically because of the large number of bulky .wav files that can be generated.

Email is used simply to finish user registration or to remind users of passwords. Email settings must of course be valid for the carrier in question.

corsOrigins allows any of the nominated servers to make available scripts that use XmlHttpRequest to access midi content in the MusicRest server.

musicrest {
  server {
    host = "localhost"
    port = 8080
  }
  transcode {
    scriptDir = "scripts"
    cacheDir = "cache/main"
    cacheClearInterval = 60
    cacheMaxSizeMb = 2000
  }
  database {
    host   = "localhost"
    port   = 27017
    dbName = "tunedb"
    login = "musicrest"
    password = "changeit"
    poolSize = 60
  }
  paging {
    defaultSize = 10
  }
  mail {
    host = "smtp.gmail.com"
    port = "587"
    login = "youraccount@gmail.com"
    password = "change1t"
    fromAddress = "youraccount@gmail.com"
  }
  security {
    corsOrigins = ["http://localhost:9000", "http://www.otherhost.org"]
  }
}

Web Front End

There is no web front end included within this project. However tradtunedb and tunebank-frontend use musicrest as a backend service.

Build and Deploy

Source Code

Code is written in scala 2.11.7 and built with sbt (currently 1.8.0).

   "io.spray"            %   "spray-can_2.11"     % "1.3.4",
   "io.spray"            %   "spray-routing_2.11" % "1.3.4",
   "io.spray"            %   "spray-caching_2.11" % "1.3.4",
   "io.spray"            %   "spray-testkit_2.11" % "1.3.4",
   "com.typesafe.akka"   %%  "akka-actor"         % "2.4.11",
   "com.typesafe.akka"   %%  "akka-testkit"       % "2.4.11",
   "org.scalaz"          %%  "scalaz-core"        % "7.1.6",
   "org.scalaz.stream"   %%  "scalaz-stream"      % "0.8",
   "org.mongodb"         %%  "casbah"             % "3.1.1",
   "net.liftweb"         %   "lift-webkit_2.11"   % "3.0-M8",
   "javax.mail"          %   "mail"               % "1.4.7",
   "org.specs2"          %%  "specs2"             % "2.5-scalaz-7.1.6" % "test",
   "io.argonaut"         %%  "argonaut"           % "6.1" % "test"

Spray uses logback for logging, but there is an unfortunate dependency on slf4j brought in by Casbah.

_Bootstrapping the Database

Firstly, create a MongoDB database, configure an admin user and determine the name of the database you wish to use (e.g. tunedb). The admin user needs the following permissions - userAdminAnyDatabase, readWriteAnyDatabase and dbAdminAnyDatabase. Then set up a user within this database with readWrite permissions for use in the database section of the MusicRest configuration file shown above.

Before MusicRest can be used, you need to set an administrator user within MusicRest itself and also set up the genres and rhythms the system recognizes. These are held on the database and can be set up by means of the scripts userinsert.sh and genreinsert.sh. These scripts should be run with mongod without the --auth parameter (because of what seems to be a Mongo 2.4/Casbah 3.1.1 bug which disallows creating indexes). Once the scripts are complete and the user and genre collections inspected, then reboot with --auth in place. There are also scripts to import tunes into or export tunes from the database in bulk.

Build Instructions

1. Install the runtime dependencies. Administer Mongo with appropriate users. Start Mongo and configure MusicRest with the name of the Mongo database and the user credentials you wish to use

2. Launch sbt

3. compile - compiles the source

4. test - runs the tests (requires a valid Mongo connection)

5. run and then choose the Boot option to start the service.

Alternatively, you can build and then run a single jar assembly using:

1. sbt assembly

2. run.sh

Other Links

• Blog
• Spray