Home

Welcome to the rameplayer wiki!

The foremost purpose of this wiki is to define the interactions between different services and GUI.

Services: omx_server
lcd_server
media_indexer (reads the metadata)
downloader (downloader manager for online media)

REST calls

edit

REST API

##Some Fundemental Decissions:

• RESTfull API

Tries to follow general guidelines at least what comes to retrieving metadata, but because it uses only JSON and have some RPC commands it is not 100% pure. It uses HTTP status codes to signify success or failure of some sort. http://www.restapitutorial.com/httpstatuscodes.html

• There is NO authentication

Any client able to access the rameplayer will be able to get information provided by the API. Later we can add authentication if needed or limit request to come only on LAN.

• In rameplayer context REST client and servers are as follows:

• client is Web GUI
• server is the rest_service

• No Case sensitivity

use of "_" when have to make separation between words

• JSON only

in HTTP request "Accept: application/json" in HTTP response "Content-Type: application/json"

• Time information delivery using ISO 8601

https://en.wikipedia.org/wiki/ISO_8601

• supports milliseconds.

E.g. to be used in time defined playback

• It uses URI to specify id's instead of query parameters

e.g. GET /api/media/albums/1 instead of

GET /api/media/albums?id=1

Because in REST query is used like it names says query of items not as singular way to refer them.

• Use of plurals when items can be many (albums, tracks) when only one is possible using singular (player)

##REST API CALLS:

GET /api/media/albums/1

Returns Album id number 1 from media library

USE: GUI can populate the view for playback selection.

PARAMS: fields string (OPTIONAL)

JSON:

{ "album_id": 1, "album": "Album Name", "artist": "Album Artist", "tracks": [{ "tracks": 1, "title": "Song title", "filename": "file_001.mp3", "duration": "142.031756" },
// Another track
] }

RETURNS:

200 OK

404 Not Found

COMMENTS:

1.1 not repeating the artist and album info in track-array (since with jw-media there are always the same usually something like this for all tracks: "artist": "Artist NAme", "album": "MUSIC—Piano") 1.2 I did selectively copy the ffprope metada (not returning all the info). You have to dig the originals to see what i didn't include.. 1.3 I copied the ffprope produced format section as it's own object inside track object. 1.4 To speed up the initial GUI population you can give the tag names you want to includ: Since including all the existing metadata (like chapter data) would lead into large json not needed in all cases. This will ensure maximum flexibility and speed when constructing GUI e.g. in the case of AV book view. Reference: https://developers.google.com/+/web/api/rest/#partial-response

e.g. track&title

---

GET /api/media/albums/2/tracks/1

Returns the track info for specified album 2 and track 1

USE: GUI can selectively get more info (e.g. chapters) from specific track

JSON:
{
"medialib_track_no": 1, "title": "Song's title""format": {
medialib_filepath: "file_001.mp3","duration": "142.031756",
},
"chapters": [{
"id": 0,
"time_base": "1/2997",
"start": 0,
"start_time": "0.000000",
"end": 6100,
"end_time": "2.035369",
"tags": {
"title": "Start"
}
},
{
"id": 1,
"time_base": "1/2997",
"start": 6100,
"start_time": "2.035369",
"end": 33200,
"end_time": "11.077744",
"tags": {
"title": "Chapter 1"
}
}]
}

RETURNS:

200 OK

404 Not Found

---

POST /api/player/play?filepath="/media/002.m4v"

OR POST /api/player/play?album=1&track=2

USE:
Commanding the player to start playing media optionally specified to start delay time or some absolute time.

PARAMS:
filepath string OR album number track number absolute_time string ISO 8601(optional) delay_time_ms number time in ms (optional)

JSON: nothing

RETURNS: 200 OK 404 Not Found 500 Internal Server Error

COMMENTS:

3.1 omx_player talks only with the files. So either GUI keeps tracks on the filepath or RESTAPIi goes trough the metadata and calls the right filename with right path. Raising the abstraction little bit.

Or do we want to support both approaches? So depending the GUI it can either send filename or album/track pair (not so difficult to implement in REST side). We can for example start with the filename approach..

3.2 Using POST here because calling the same method again will not have same results (due changed server state). We are here invoking server to do (process) something not returning data (this is to follow REST principles)

3.3 I ended up using following verb syntax in the URI i.e. having a command play there (which is not according to REST principles that do not work together with RPC needs - I studied quite a bit..) but I preferred that over query action=play syntax.

---

POST /api/player/stop

USE: Commanding the player to stop current playback

PARAMS: nothing

JSON: nothing

RETURNS: 200 OK 500 Internal Server Error

---

POST /api/player/pause

USE: Commanding the player to pause current playback

PARAMS: nothing

JSON: nothing

RETURNS: 200 OK 500 Internal Server Error

---

POST /api/player/resume

USE: Commanding the player to resume (play) current playback

PARAMS: nothing

JSON: nothing

RETURNS: 200 OK 500 Internal Server Error

---

POST /api/player/prepare?filepath="/media/002.m4v"

USE:

Commanding the player to prepare (read the file in advance to buffer)?

PARAMS:

filepath string

JSON:

nothing

RETURNS:

200 OK

404 Not Found

500 Internal Server Error

COMMENTS:

?!?

Things to consider:

• REST API only answer 192.168.. or 10...* calls?
• Disable the download possibility of py and wsgi files?