-
Notifications
You must be signed in to change notification settings - Fork 0
0.7 Player Interaction
In all the methods below, if the player exists but is currently inactive, a 404 response with the X-Udj-Missing-Resource header set to player and the X-Udj-Missing-Reason header set to inactive.
The initial participate method must be called by the user before any other methods on the player are called. The only exception to this is the owner of the player. It is assumed that if the player
is currently active, the owner is participating.
If this method is not called, all other method calls will return a 401 response with the WWW-Authenticate header set to begin-participating.
If the user ceases interaction with the server for a certain period of time, the server MAY consider the user as no longer participating. Interaction is considered calling any of the player interaction
methods below or any of the Active Playlist, Favorites, or Song Sets methods. If the server decides to consider a user as no longer participating, the user must call the initial participate method again
before it can continue interacting with the
player (otherwise all other palyer interaction methods will return a 401 response with the WWW-Autenticate header set to begin-participating).
At any point during participation, the user may be kicked from the player. The user must call the initial participate method again before it can continue interaction with the player (otherwise all other palyer interaction methods will return a 401 response with the WWW-Autenticate header set to kicked).
This method allows the user specified to start participating with the player specified by player_id. If the player requires a password, The request body should have the following JSON in it:
{
'password' : 'password for player'
}
It is also recommended that the client then make a permissions call in order to determine what the client can and can't do while in the specified player. Note that servers may limit the number of users participating with a given player.
User joins player
- HTTP 400 - Bad Request - Invalid JSON provided
- HTTP 401 - Unauthorized - Header
WWW-Authenticateset toplayer-password- Player password is required and either no password was sent or the one sent was incorrect. - HTTP 403 - Forbidden - Header
X-Udj-Forbidden-Reasonset toplayer-full- There is currently no room in the player - HTTP 403 - Forbideen - Header
X-Udj-Forbidden-Reasonset tobanned- User is currently banned. - HTTP 404 - Missing Resource - Header
X-Udj-Missing-Resourceset toplayer,X-Udj-Missing-Reasonset toinactive- The player is currently inactive and users may not join it. - HTTP 415 - Unsupported Media Type -
content-typeheader was not set totext/json
This method informs the server that the calling user is no longer participating with the player. The client SHOULD call this method when they're done participating.
The user leaves the player.
- HTTP 404 - Missing Resource - Header
X-Udj-Missing-Resourceset touser- The user calling the method was never participating with the player in the first place.
Returns a JSON array of [User] objects corresponding to all of the users who are currently participating with the player identified by player_id.
Get the available music for an player that matches the specified query and returns a JSON array of Library Entry objects. An optional maximum number of results can also specified but setting the max_results parameter. The query parameter may not be empty. If it is, a 400 response is returned.
Gets a JSON Array of strings containing all the artists on a given player. The Content-Range header field may be used to restrict the range of responses retrieved from the server. The offset parameter
may be used to retrieve artists starting at a certain offset.
Gets a JSON Array of LibraryEntry JSON objects corresponding to all the songs that the player has which are by the artist specified by artist_name.
May return an empty array if the player has not songs by the given artist.
Get's a JSON Array of Played Active Playlist Entry objects that have been recently played. They are sorted with the song most recently played being at the beginning of the list and the song least recently played at the end of the list. The client may specify the maximum number of Played Active Playlist Entry objects it would like to receive with the max_songs parameter. The server reserves the right to arbitrarily cap the maximum number of results it returns.
Get a random set of songs from the set of available music on the player specified by player_id. A JSON array of Library Entry objects is returned. The number of Library Entry objects returned will be some default value set on the server, but can also be specified using the max_randoms parameter. This parameter will ensure no more than number_desired results are returned. That said, the server may return less than number_desired. number_desired must not be 0. If it is, a 400 response is returned.
For example, if a client wished to retrieve no more than 20 random songs from a player with a player_id of 3, they would use the following URI:
/udj/0_7/players/3/available_music/random_songs?number_of_randoms=20
The server may also reserves the right to arbitrarily cap the maximum number of random songs it will return. However, this cap may not be any lower than 20.
Sets the currently playing song to the song. The method should be supplied with a [SimpleLibraryEntry]((0.7-JSON-Data-Structures#wiki-simple-library-entry) JSON object. This method can only be run by the owner of the player or a player admin (otherwise an Http 403 response is returned). If the lib_id parameter is not specified, a 400 response is returned. If the specified lib_id is not currently on the playlist, a 404 response is returned with the X-Udj-Missing-Resource header set to song. Note that if an admin calls this method but is not active, an Http 401 response will be returned with the WWW-Authenticate header set to begin-participating
Informs the server the the currently playing song has finished playing. This method can only be run by the owner of the player or a player admin (otherwise an Http 403 response is returned). If no song is currently playing, a 404 response is returned with the X-Udj-Missing-Resource header set to song. Note that if an admin calls this method but is not active, an Http 401 response will be returned with the WWW-Authenticate header set to begin-participating