Skip to content

componentMusicServer

Jump to bottom Edit New page
Sebastian Schlicht edited this page Sep 23, 2013 · 16 revisions

The music server is able to store and handle music files and distribute them to fans, websites and various services if they possess the right to do so.

The music server is split into two servers:

  1. music storage server: this server will store the music files and provide access to the files and the meta data. its purpose is to store all data and check if the files uploaded are valid music files. it will run as embedded service.
  2. music application server: this server will allow streaming of music files and the aggregation to records. it may include the right management for music data.

Requirements

  • Band: self promotion
  • Band: Music Hosting
  • Band: release Management
  • Other Websites: receive content
  • Fan: Wants to listen to new music

API specification (musicStorageServer)

The embedded music storage server will use two ways to communicate errors to the user.
At first all methods use their return values to signalize a general success or failure without handling any information about the concrete error occurred.
Secondly JSON response objects are used to handle this information.
Each response object will contain a status message and a detailed description trying to help the user to find a solution.

Example

{
    "status_message": "you are happy",
    "solution": "clap your hands"
}

Create

You can create single music files only.
You have to pass an unique identifier for the piece of music you want to create.
The server can store additional meta data for the music file passed as a JSON object. VorbisComments fields will be written to all files created but the original one. Besides this original version there will resamples. See reading part for more information.

Example

InputStream musicItemStream = new FileInputStream("myaudiofile.mp3");
CreateResponse response = new CreateResponse();
if (!server.createMusicItem("item1", musicItemStream, "{ \"artist\": \"Testy\" }", response)) {
    System.out.println(response);
} else {
    System.out.println("music item was created successfully");
}

As specified in the interface createMusicItem will return true if the music item was created successfully.
In any other case it will return false and either set the internal server error status code or put one of the responses below on the response object passed.

Responses

  • "music item identifier in use": the identifier passed is already used by an existing music item
  • "meta data malformed": the meta data passed is not a valid JSON String
  • "music item stream invalid": the music item input stream does not contain any supported audio stream

Read

You can access a music file and its meta data by passing its identifier and specifying the version you want to retrieve. See the list for the versions existing below.
You can also read the meta data stored for any number of music items exclusively by passing a list of identifiers.

Music Item Versions

  • original: retrieve the original file uploaded
  • basis: retrieve the basis audio file having the best quality besides the original file
  • stream: retrieve the audio file for streaming purpose having a low(er) bit rate

Example (readMusicItem)

ReadResponse response = new ReadResponse();
MusicData musicItem = server.readMusicItem("item1", MusicItemVersion.STREAM, response);
if (musicItem == null) {
    System.out.println(response);
} else {
    System.out.println("meta data: " + musicItem.getMetaData());
}

As specified in the interface readMusicItem will return a wrapper object containing the music item stream and the meta data stored if the music item was read successfully.
In any other case it will return null and either set the internal server error status code or put one of the responses below on the response object passed.

Responses (readMusicItem)

  • "music item not existing": there is no music item having the identifier passed

Example (readMusicItemMetaData)

ReadResponse response = new ReadResponse();
String[] identifiers = new String[] { "item1", "item2", "item3" };
String[] metaDataObjects = server.readMusicItemMetaData(identifiers, response);
if (metaDataObjects == null) {
    System.out.println(response);
} else {
    for (int i = 0; i < identifiers.length; i++) {
        System.out.println("meta data for \"" + identifiers[i] + "\": " + metaDataObjects[i]);
    }
}

As specified in the interface readMusicItemMetaData will return the meta data stored for the music items passed if it was read successfully.
In any other case it will return null and either set the internal server error status code or put one of the responses below on the response object passed.

Responses (readMusicItemMetaData)

  • "music item not existing": there is no music item having one of the identifiers passed

Update

You can not update the music file but you can update the meta data by passing the music item identifier and a JSON object containing the meta data that will be appended (overriding existing values).

Example

UpdateResponse response = new UpdateResponse();
if (!server.updateMetaData("item1", response)) {
    System.out.println(response);
} else {
    System.out.println("meta data updated successfully");
}

As specified in the interface updateMetaData will return true if the meta data was updated successfully.
In any other case it will return false and either set the internal server error status code or put one of the responses below on the response object passed.

Responses

  • "music item not existing": there is no music item having the identifier passed
  • "meta data malformed": the meta data passed is not a valid JSON String

Delete

You can delete a music file by passing its identifier.

Example

DeleteResponse response = new DeleteResponse();
if (!server.deleteMusicItem("item1", response)) {
    System.out.println(response);
} else {
    System.out.println("music item deleted successfully");
}

As specified in the interface deleteMusicItem will return true if the music item was deleted successfully.
In any other case it will return false and either set the internal server error status code or put one of the responses below on the response object passed.

Responses

  • "music item not existing": there is no music item having the identifier passed

Features

Technologies (musicApplicationServer)

  • we may have a look at IceCast which is a music streaming server accessing source servers via own clients
  • we may also use locality-icecast which is a ShoutCast streaming server in Java (GPL)
  • if we need encryption and it is not available in one of the existing software products we may build an own streaming format, a short example is available which does include encryption neither

sites with CC music and APIs

''' for all examples: don't use this api key in large scale or our IP adress will be blocked '''

Responsible Developer

  • Christian
  • Sebastian
Add a custom footer
Add a custom sidebar
Clone this wiki locally