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)
##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:
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
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
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.
USE: Commanding the player to stop current playback
PARAMS: nothing
JSON: nothing
RETURNS: 200 OK 500 Internal Server Error
USE: Commanding the player to pause current playback
PARAMS: nothing
JSON: nothing
RETURNS: 200 OK 500 Internal Server Error
USE: Commanding the player to resume (play) current playback
PARAMS: nothing
JSON: nothing
RETURNS: 200 OK 500 Internal Server Error
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:
?!?
- REST API only answer 192.168.. or 10...* calls?
- Disable the download possibility of py and wsgi files?