-
Notifications
You must be signed in to change notification settings - Fork 18
/
json.api
160 lines (89 loc) · 4.31 KB
/
json.api
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
This document describes the API calls Spivak Web Interface supports.
## General ##
Most API calls are required to contain the authentication information. This information is provided in a cookie, and is set when the user logs in.
All API calls should use the POST method.
## User authentication ##
### /api/auth/login ###
Input: { name : "username" }
Logs in a singer named "name". At this moment the login always succeeds (there's no check for duplicates), and returns:
Returns: { loggedin : true, name : "logged in name" }
This method will also set a cookie containing the authentication information.
This method can be called without the authentication cookie from login.html only
### /api/auth/logout ###
Input: {}
Returns: { loggedin : false }
Logs out the currently logged user and deletes the cookie.
### /api/auth/status ###
Checks whether the user is logged in.
Input: {}
Returns: { loggedin : false } or { loggedin : true, name : "logged in name" }
## Queue manipulation ##
### /api/addsong ###
Adds a new song into queue for the logged in singer.
Input: { id : <song id from browse/search> }
Output: { result: 0, reason : "failed to add reason" }
or { result: 1, title: "song title", artist: "song artist" }
### /api/queue/list ###
Returns the current singer queue.
Input: {}
Returns: [ { id : 1234, singer: "singername", title: "song title", state: "preparing/queued/playing", removable : true }, ... ]
Songs are returned in the array, in the order queued. If removable : true is present, this user can remove this song by using the remove API.
### /api/queue/remove ###
Schedules the removal of the song from the queue. At this moment there are no checks, so using the API anyone can remove anyone's song.
Due to scheduled nature the song might not be removed immediately.
Input: { id : song queue id }
Output: same as from /api/queue/list
### Search and browse ###
## /api/search ##
Searches for the specific query in the song title or artist name, and returns the first 1000 entries found.
Input: { query: "search query" }
Output: array of song elements (could be empty):
[ { id : <song id to use in addsong>,
artist: "artist",
title: "song title",
type: "song type (KAR, LRC, CDG etc)",
rating: "song rating as assigned by users",
language: "EN/ES/FR as detected - if enabled"
}, ... ]
2. Browsing the collection
### /api/browse ###
Input: {}
Output: [ "A", "B", "C" ... ]
Output is an array of letters containing the unique first letter of all artist names in collection, such as [ "A", "B", "C" ... ] - if there are no artists in collection for a specific letter, it will not be returned. Non-English letters could be returned as well.
Input: { artist : "single letter" }
Output: [ "artist1", "artist2", "artist3"... ]
Output returns an array of artist names in collection starting with this letter (must be a single letter). "P" would return [ "Pink Floyd", "Pink", "Pineapple Nuts" ... ]
Input: { artist : "full artist name" }
Output: the array of songs for this artist (could be empty):
[ { id : <song id to use in addsong>,
artist: "artist",
title: "song title",
type: "song type (KAR, LRC, CDG etc)",
rating: "song rating as assigned by users",
language: "EN/ES/FR as detected - if enabled"
}, ... ]
### Karaoke controls ###
## /api/control/status ##
Returns the current status of karaoke controls:
{
type: controlstatus,
state: "playing/paused/stopped",
Only if the player is not stopped the following is present:
pos: "current player position",
duration: "current player duration",
volume: current volume percentage (0-100),
delay: sound-lyrics delay if any
pitch: current pitch value (only if capable of changing pitch), otherwise "disabled"
tempo: current tempo value (only if capable of changing tempo), otherwise "disabled"
voiceremoval: whether automatic voice removal is on/off (or "disabled" if not supported)
song: "current playing song"
}
### /api/control/adjust ###
Adjusts a sound control.
Input: { a : "controlname", v: "adjust value" }
Control name must be one of: volume, tempo, pitch, delay.
Adjust value must be 1 (increase) or -1 (decrease)
Output: same as control status
### /api/control/action ###
Input: { a: "action" }
Action could be: stop, prev, next, playpause