Web Music Score Service
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
wmss Minor bug fixes on ListScore request Dec 7, 2018
.gitignore Initial commit Sep 19, 2017
LICENSE Initial commit Sep 19, 2017
README.md Update README.md Nov 29, 2018

README.md

Web Music Score Service

The Web Music Score Service (WMSS) provides an interface allowing requests for music scores on the web using platform-independent clients. It serves as an intermediate layer between data sets and application clients, providing standard access to MEI and MusicXML files.

wmss

The application relies on datasets encoded using the MusicOWL ontology. For more information on creating MusicOWL datasets see MusicXML to RDF converter.

Index

Configuring WMSS

Server Settings

File: config/settings.conf

port  Listening port for the WMSS server.

service  Service name for the server.

pageSize  Number of records per page in the Score List Document.

defaultRequestMode  Default request mode for the ListScore requests (default full). Supported request modes are: simplified, omitting the movements and performance medium data, and full for a complete Score List Document.

contact  E-mail address of the server administrator.

title  Server title.

logPreview  Number of lines shown in the GetLogging request.

defaultMelodyEncoding  Default encoding type for melody request. Supported encoding formats: pea.

maxFileSize  Maximum file size for inserting new scores.

defaultRDFFormat  RDF format for inserting new scores. Supported RDF formats: JSON-LD, Turtle, RDF/XML and N-Triples.

defaultCommitSize  Number of triples partially committed in the insert scores transaction.

Data Source Settings

(multiple data sources supported)

File: config/sources.conf

id  Data source identifier.

info  Data source complementary information.

active  Indicates if the data source is available for requests. Supported values: true, false.

storage  Data source storage technology. Supported storages: neo4j

type  Data source type. Supported types: lpg (Label Property Graphs)

port  Listening port for the data source.

repository  Data source repository (if applicable).

version  Version of the data source application.

user/password  Credentials for accessing the data source.

Starting the Server

From the console:

$ java -jar wmss-[VERSION].jar

For the source code: Execute the main method of the Java class de.wwu.wmss.web.Start.java

After successfully starting the server you will see a message like this:

Web Music Score Service - University of Münster
Service Name: wmss
Default Protocol: 1.0
WMSS Version: Dev-Unstable-0.0.1
Port: 8295
Application Startup: 2018/11/19 14:46:14
Default Melody Encoding: pea
Time-out: 5000ms
Page Size: 10 records 
System Administrator: jim.jones@math.uni-muenster.de

After seeing this message, you can access the server API via the HTTP requests described bellow.

Requests

The WMSS communication protocol is based on the following HTTP requests: DescribeService, ListScores, GetScore, GetLogging.

DescribeService

Lists all service related information as well as all repositories available:

http://localhost:8295/wmss?request=DescribeService

The Service Description Report collects all available properties and filter possibilities from each available data source, giving the client all possible filters for each filter option, such as tonalities, tempo markings or instruments.

Service Description Report

The Service Description Document is provided as JSON and is structured as follows:

appVersion  WMSS version.

type  ServiceDescriptionReport (Standard value for Service Description Report)

title  Service title of description.

contact  Administrator e-mail address.

service  Service name.

port  Listening port for the service.

timeout  Time-out for server internal requests.

pageSize  Default page size for ListScores request.

startup  Service startup time.

environment  Environment settings.

    java  Java version.

    os  Operating system description.

supportedProtocols  Protocols supported by the service.

datasources  Data sources available in the system.

    id  Data source identifier.

    host  Data source hosting server.

    port  Listening port for the data storage.

    active  Boolean value to enable or disable access to a data source.

    type  Data source type. Currently supported values are database and triplestore.

    storage  Storage technology used in a data source. Currently supported values are: postgresql and graphdb.

    repository  Specific repository of a data storage, e.g database for RDMS or a repository/named graph for triple stores.

    version  Version for the data storage.

    user  Username used for accessing the data source.

    info  Data source description.

    totalScores  Number of available music scores for the data storage.

    formats  Formats available in a data source, e.g. MusicXML, MEI.

    tempoMarkings  Tempo markings available in a data source, e.g. adagion, andante.

    tonalities  Tonalities available in a data source, e.g. C major, E minor.

    collections  Collections available in a data source.

    performanceMediums  Performance mediums (instruments) available in a data source.

            mediumTypeId  Identifier of the performance medium type

            mediumTypeDescription  Description of the performance medium type

            mediums  Performance mediums (instruments) available for a certain performance medium type

                  mediumId  Performance medium identifier.

                  mediumDescription  Performance medium description.

An example of a Service Description Report can be found here.

ListScores

Lists all scores from available repositories.

http://localhost:8295/wmss?request=ListScores

In order to facilitate the music score discovery, the ListScores request offers several filter capabilities:

Data Source

Parameter: source

Constraints the Score List Document to a specific data source:

http://localhost:8295/wmss?request=ListScores&source=neo4j_local

Collections

Parameter: collection

To facilitate the management of large repositories, WMSS offers the possibility to add music scores to specific collections. The collection uri, required for this parameter, is delivered together with the music score in the Score List and Service Description Reports.

 http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&collection=https://url.collection.de

Persons

Parameters: person / personRole

Selects all music scores containing specific persons and optionally with their respective roles. For instance, a request to list all scores from the person "Elgar" as a "Composer" is enconded like this:

 http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&person=http://dbpedia.org/resource/Edward_Elgar&personRole=composer

The personRole parameter may contain the following values:

  • composer
  • arranger
  • encoder
  • dedicatee
  • librettist
  • editor
  • lyricist
  • translator
  • performer

Performance Medium (Instrument)

Parameters: performanceMedium / solo

Selects all music scores containing specific performance mediums. The performance mediums are structure follows the principles adopted by MusicXML 3.0 Standard Sounds. For instance, requesting a list of all scores containing cello voices can be enconded like this:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&performanceMedium=strings.cello

To constraint the search for the given performance medium to only solo mediums, use the solo parameter:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&performanceMedium=strings.cello&solo=true

A complete list of performance mediums containing approx. 900 items can be found here.

Performance Medium Type

Parameter: performanceMediumType

It is also possible to select music scores based on performance medium types, e.g. Strings, Keyboard. The example bellow selects all records that contain movements that are played with bowed string instruments:

http://localhost:8295/wmss?request=ListScores&source=neo4j_local&performanceMediumType=strings

The performanceMediumType paramater is also based on the MusicXML 3.0 Standard Sounds and the following codes:

code medium type code medium type
brass Brass pitched-percussion Pitched Percussion
drum Drums pluck Plucked
key Keyboard rattle Rattle
metal Metals strings Strings
synth Synthesizer voice Voices
wind Wind wood wood

Tempo

Parameters: tempoBeatUnit / tempoBeatsPerMinute

Selects records containing movements played in a specific tempo, e.g. adagio, largo, andante, etc. Tempo markings may vary depending on the country of orign and century of composition, therefore tempo searches are encoded in two abstract parameters, namely tempoBeatsPerMinute and tempoBeatUnit. Beat units indicates the graphical note type to use in a metronome mark, which follows the principles adpoted by the MusicXML Beat-Unit Element. The beats per unit parameter can be provided as a single integer value or an interval thereof. For instance, a quarter beat unit with an interval of 100-125 beats per minute, can be encoded as follows:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&tempoBeatUnit=quarter&tempoBeatsPerMinute=100-125

Date Issued

Parameter: dateIssued

Selects records composed at a given date or time interval, e.g. 1910-1920:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&dateIssued=1910-1920

Dates and intervals must be encoded as yyyyMMdd, yyyyMM or yyyy.

Format

Parameter: format

Selects records available in a specific format. The supported formats are:

  • mei (Music Encoding Initiative files)
  • musicxml (MusicXML files)
http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&format=musicxml

Melody

Parameter: melody

Selects records containing a specific a sequence of notes or phrases (not limited to incipt) throughout the database, encoded using the Plaine & Easie musical notation (PEA). For instance, the value ,8AB'CDxDE - which is going to be used throughout this section - corresponds to ..

melody_sample

Notes: A 3rd octave, B 3rd octave, C 4th octave, D 4th octave, D# 4th octave and E 4th octave.

Duration: Eighth

.. and can be searched like this:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,8AB'CDxDE

Octaves

Parameter: ignoreOctave

To search for melodies encoded in specific octaves, set the parameter ignoreOctave to false (true by default). Note that in the PEA string the 4th octave is assumed, if no octave is explicitly defined. The following example searches for scores matching the sequence A 3rd octave, B 3rd octave, C 4th octave, D 4th octave, D# 4th octave and E 4th octave, all with the duration eighth (as described above):

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,8AB'CDxDE&ignoreOctave=false

Durations

Parameter: ignoreDuration

It is possible to search only for a sequence of pitches, ignoring their durations. It can be achieved by means of setting the parameter ignoreDuration to true (false by default). The following example searches for all scores containing the pitch sequence A, B, C, D, D# and E, ignoring their durations:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,8AB'CDxDE&ignoreDuration=true

Dotted Durations

To extend the note duration add either a . (dot), .. (double dot) or ... (triple dot) right after the note duration, as described at Plaine & Easie rhythmic values. For instance 4.G4.xF4.G4.xF

embedded_sequence

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=4.G4.xF4.G4.xF

Pitches

Parameter: ignorePitch

If you're only looking for a sequence of rhythmical elements (useful for percussionists), just set the parameter ignorePitch to true (false by default). The following example searches for all scores containing a sequence of 6 eighth notes, ignoring pitches:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,8AB'CDxDE&ignorePitch=true

Embedded Sequences (Note sequences inside chords)

Parameter: ignoreChords

It is also possible to look for sequences whose notes are inside of chords. To achieve this, set the parameter ignoreChords to false (true by default).

Consider the following chords ..

three_chords

.. and the following search criteria ,,2GB8G, which are notes embedded in the chords above:

embedded_sequence

To be able to find such an embedded sequence, set the parameter ignoreChords to false:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,,2GB8G&ignoreChords=false

Note: This feature assumes that the elements of such an embedded sequence are notes of the same voice.

Chords search

Parameter: melody

Melodies containing chords can be searched by means of using the PEA chords notation. The PEA notation states that every note of a chord is to be separated by ^, starting by the upper note; then followed by the lower ones.

Searching for the following chord ,,2E^B^,G^'E ..

embedded_sequence

.. can be done like this:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=,,2E^B^,G^'E&ignoreOctave=false

Time signatures

Parameters: melody / time

Time signatures are to be encoded according to the PEA key time signature notation. Time signatures embedded in melodies are preceded by @ and followed by beats and beat unit, separated by /, e.g. @3/4 (three-four or waltz time), @2/4 (march time). Common time signatures can be also represented as @c and will be considered by the system as @4/4.

Examples

Common signature: @c 8ABCDxDE

common_timesignature

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=@c 8ABCDxDE

Waltz time: @3/4 8ABCDxDE

waltz_timesignature

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=@3/4 8ABCDxDE

Alternatively, time signatures alone can be searched using the parameter time:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&time=4/4

See also: UNIMARC field 036 $o — MARC21 field 789 $g — MAB field 681 $h (RISM field 823)

Clefs

Parameters: melody / clef

Clefs are to be encoded according to the PEA clef notation. Clefs embedded in melodies are preceded by %, and are three characters long. The first character specifies the clef shape (G,C,F,g). The second character is - to indicate modern notation, + to indicate mensural notation. The third character (numeric 1-5) indicates the position of the clef on the staff, starting from the bottom line.

Clef examples: G-2 (trebble clef), F-4 (bass clef), C-3 (alto clef), C-4 (tenor clef).

Request example %C-4 ,8AB'CDxD:

tenor_clef

http://localhost:8295/wmss/?source=neo4j_local&request=listscores&melody=%C-4 ,8AB'CDxD

Alternatively, clefs alone can be searched using the parameter clef:

http://localhost:8295/wmss/?source=neo4j_local&request=listscores&clef=F-4

See also: UNIMARC field 036 $m — MARC21 field 789 $e — MAB field 681 $j (RISM field 820)

Measures

Parameters: melody

If necessary, it is also possible to look for melodies contained in fixed measures. For instance, the melody '4xF8G4xF8A4B8A4G8E4D8E4C,8B will be searched no matter how the notes are distributed:

no_measure

http://localhost:8295/wmss/?source=neo4j_local&request=listscores&melody='4xF8G4xF8A4B8A4G8E4D8E4C,8B

By splitting the melodies with the character /, the system will look for exact matches with the given measure/notes distribution. This example will look for the given melody contained in exactly two measures '4xF8G4xF8A4B8A4/G8E4D8E4C,8B:

measures

http://localhost:8295/wmss/?source=neo4j_local&request=listscores&melody='4xF8G4xF8A4B8A4/G8E4D8E4C,8B

Key signatures

Parameters: melody / key

Keys signatures are to be encoded according to the PEA key signature notation. Key signatures embedded in melodies are preceded by the character $; The symbol x indicates sharpened keys, b flattened keys; the symbol is followed by the capital letters indicating the altered notes.

Sharpened keys have to be encoded in the following order: F♯ C♯ G♯ D♯ A♯ E♯ B♯

Major key Minor Key PEA key
C major A minor $
G major E minor xF
D major B minor xFC
A major F♯ minor xFCG
E major C♯ minor xFCGD
B major G♯ minor xFCGDA
F♯ major D♯ minor xFCGDAE
C♯ major A♯ minor xFCGDAEB

Flattened keys have to be encoded in the following order: B♭ E♭ A♭ D♭ G♭ C♭ F♭

Major key Minor Key PEA key
C major A minor $
F major D minor bB
B♭ major G minor bBE
E♭ major C minor bBEA
A♭ major F minor bBEAD
D♭ major B♭ minor bBEADG
G♭ major E♭ minor bBEADGC
C♭ major A♭ minor bBEADGCF

See also: UNIMARC field 036 $n — MARC21 field 789 $f — MAB field 681 $k (RISM field 826 — first part)

To search for melodies encoded with an specific key signature, place the key before the melody (preceded by space). For instance, searching the previously mentioned melody with the signature G Major / E minor can be done as follows:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody=$xF ,8AB'CDxDE

Alternatively, key signatures alone can be searched using the parameter key. The following request seraches for all music scores containing measures written in C♯ minor:

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&key=xFCGDA
ListScore Request Examples

The following example deals with a melody of 36 notes in containing several durations and octaves:

elgar_theme

http://localhost:8295/wmss/?request=ListScores&source=neo4j_local&melody='4xF8G4xF8A4B8A4G8E4D8E4C,8B4A8B4A'8C4D8C,4B8G4xF8G4E8D4xC8D4xC8E4xF8E4D,,8B4xA8B4G8xF2B&ignoreOctave=false

Score List Report

The Score List Document is provided as JSON and is structured as follows:

An example of a Score List Report can be found here.

GetScore

Retrieves a specific score based on its identifier:

http://localhost:8295/wmss/?request=GetScore&source=neo4j_local&identifier=http://dbpedia.org/resource/Cello_Concerto_(Elgar)

The output format can be selected using the parameter format:

http://localhost:8295/wmss/?request=GetScore&source=neo4j_local&identifier=http://dbpedia.org/resource/Cello_Concerto_(Elgar)&format=musicxml
  • mei (Music Encoding Initiative files)
  • musicxml (MusicXML files)

Logging

Displays the WMSS log file. The parameter logPreview limits the amount of lines displayed. If omitted, the default value in the settings file is assumed. The the last 1000 lines from the log file can be requested as follows:

http://localhost:8295/wmss/?request=Checklog&logPreview=1000

Exceptions

Code Message Hint
E0001 No request type provided The request type has to provided in the parameter request, containing one of the following request types: ListScores, GetScores, DescribeService, Checklog.
E0002 Invalid request parameter Provide one of the following request types: ListScores, GetScores, DescribeService, Checklog.
E0003 Invalid document format Provide one of the following XML formats: musicxml, mei
E0004 Invalid time signature Time signatures must be encoded in the following format: beat unit / beats. Examples: 3/4, 4/4, 6/8, c (meaning common time and interpreted as 4/4).
E0005 Invalid data source The provided data source does not exist. Check the sources.conf file and try again.
E0006 Invalid melody encoding The following melody encodings are currently supported: pea (Plaine & Easie)
E0007 Invalid score identifier Make sure you're providing a valid score identifier at the parapeter identifier.
E0008 Invalid request mode Please provide one of the following values: full, simplified.
E0009 Invalid melody length A melody must contain at least three valid elements.
E0010 Invalid tempo beats per minute Provide either a positive integer or an interval thereof, e.g. 148, 98-104.
E0011 Invalid tempo beat unit Provide one of the following beat units: maxima, longa, breve, whole, half, quarter, eighth, 16th, 32nd, 64th, 128th, 256th, 512th, 1024th.
E0012 Invalid date or interval Provide a date or an inverval thereof in the following formats: 'yyyy, yyyymm, yyyymmdd. For example: 1898, 189805, 19890501, 19890501-19900215, 1989-1990
E0013 Request type not supported Check the request section at the settings file
E0014 Invalid RDF file Make sure that the imported file is properly encoded in one of the following formats: JSON-LD, Turtle, RDF/XML and N-Triples
E0015 Invalid RDF format Please provide one for the following formats in the format parameter: JSON-LD, Turtle, RDF/XML and N-Triples
E0016 Invalid key Provide one of the following keys: $ (C major/A minor), xF (G major/E minor), xFC (D major/B minor), xFCG (A major/F# minor), xFCGD (E major/C# minor), xFCGDA (B major/G# minor), xFCGDAE (F# major/D# minor), xFCGDAEB (C# major/A# minor),bB (F major/D minor), bBE (Bb major/G minor), bBEA (Eb major/C minor), bBEAD (Ab major/F minor), bBEADG (Db major/Bb minor), bBEADGC (Gb major/Eb minor), bBEADGCF (Cb major/Ab minor)
E0017 Invalid clef The clef code is preceded by %, and is three characters long. The first character specifies the clef shape (G,C,F,g). The second character is - to indicate modern notation, + to indicate mensural notation. The third character (numeric 1-5) indicates the position of the clef on the staff, starting from the bottom line. Examples: G-2, C-3, F-4.

Importing Scores

New music scores can be inserted ther via POST requests, which requires the following parameters:

source  Data source where the file will be inserted. See Service Description Report for more details.

format  Indicates the file RDF format. Supported formats are: JSON-LD, Turtle, RDF/XML and N-Triples

commitSize  Commits a partial transaction every n triples. Useful for large RDF files.

Example using CURL:

curl -F file=@elgar_cello_concerto_op.85.nt "http://localhost:8295/wmss/import?source=neo4j_local&format=n-triples&commitsize=10000"

If everything goes well, you will recieve a ImportReport:

{
  "timeElapsed": "780 ms",
  "size": 1,
  "files": [
    {
      "file": "elgar_cello_concerto_op.85.nt",
      "size": "2 MB",
      "records": 10846
    }
  ],
  "type": "ImportReport"
}

For inserting multiple files just add extra -F parameters to your command:

curl -F file=@file2.nt -F file=@file2.nt "http://localhost:8295/wmss/import?source=neo4j_local&format=n-triples&commitsize=10000"

DeleteScore

Deletes a specific score based on its identifier:

http://localhost:8295/wmss/?source=neo4j_local&request=DeleteScore&identifier=http://dbpedia.org/resource/Cello_Concerto_(Elgar)

If the score was successfully deleted, the DeleteScoreReport is shown:

{
 "type": "DeleteScoreReport",
  "score": [
    {
      "scoreIdentifier": "http://dbpedia.org/resource/Cello_Concerto_(Elgar)",
      "title": "Cellokonzert e-Moll op. 85",
      "collection": "https://url.collection.de"
    }
  ] 
}

Service Exception Report

The Service Exception Report is provided as JSON and is structured as follows:

{
  "type": "ExceptionReport",
  "code": "E0009",
  "message": "Invalid data source [fake_repo].",
  "hint": "The provided data source cannot be found. Check the 'Service Description Report' for more information on the available data sources."  
}