Server/Spec

Types

#define		kPostData_SINGER			"singer"
#define		kPostData_SINGER_NAME			"singername"
#define		kPostData_PASSWORD			"password"
#define		kPostData_PASSWORD_CONFIRM		"confirm"
#define		kPostData_SUBMIT			"submit"
#define		kPostData_PLAYLIST			"playlist"
#define		kPostData_ORDER_BY			"orderby"
#define		kPostData_SEARCH			"search"
#define		kPostData_PITCH				"pitch"
#define		kPostData_TEMPO				"tempo"
#define		kPostData_SONG				"song"
#define		kPostData_INDEX				"index"
#define		kPostData_INDEX_OLD			"oldIndex"
#define		kPostData_PLI				"piIx"		// Play List Item index
#define		kPostData_ERROR				"error"

CWS_StringTable		g_CWS_StringTable[] = {
	{	CWS_Path_NONE,			"nothing"			}, 
	{	CWS_Path_PING,			"ping"				},
	{	CWS_Path_LOGIN,			""				}, 
	{	CWS_Path_LOGOUT,		"logout"			}, 
	{	CWS_Path_MAIN,			"main"				}, 
	{	CWS_Path_HELP,			"help"				}, 
	{	CWS_Path_NEW_SINGER,		"newsinger"			},
	{	CWS_Path_SINGERS,		"singers"			}, 
	{	CWS_Path_ROTATION,		"rotation"			}, 
	{	CWS_Path_KJ_ROTATION,		"kj_rotation"			}, 
	{	CWS_Path_PLAYLISTS,		"playlists"			}, 
	{	CWS_Path_SONGS,			"songs"				}, 
	{	CWS_Path_SEARCH,		"search"			}, 
	{	CWS_Path_DROP,			"drop"				}, 
	{	CWS_Path_REORDER,		"rearrange"			},
	{	CWS_Path_REMOVE,		"remove"			},
	{	CWS_Path_PITCH,			kPostData_PITCH			},
	{	CWS_Path_TEMPO,			kPostData_TEMPO			},
	{	CWS_Path_SCRIPT_MAIN,		"main.js"			},
        {       CWS_Path_INFO,                  "info"                          },
	{	CWS_Path_NEW_PLAYLIST,		"new_playlist"			},
	{	CWS_Path_CMD,			"command"			},
};

typedef enum {
	CWS_OrderBy_NONE = -1, 

	CWS_OrderBy_INDEX, 
	CWS_OrderBy_NAME, 
	CWS_OrderBy_ARTIST, 
	CWS_OrderBy_ALBUM, 
	CWS_OrderBy_PITCH, 

	CWS_OrderBy_NUMTYPES
} CWS_OrderByType;

Doc

You may use Bonjour to discover the web server and port. Everything is URL Encoded except for the search strings.

If you search for "\*" (no quotes) you'll get the entire library. If you append an "F" on the end, it'll come in JSON format.

send a CWS_Path_PING periodically so the session does not time out (the app let's the KJ set a timeout to whatever they want, so 30 seconds is probably a good period)

CWS_Path_LOGIN: revokes whatever auth had been established, and CWS_Path_LOGOUT will clear any cookies, then they both send you to the login screen.

CWS_Path_MAIN: will do one of three things: if the singer is logged in, it goes to the singer's main screen. If the singer is NOT logged in but CAN be authenticated, it logs the singer in, then sends to the singer's main screen. otherwise, it goes to the login screen.

CWS_Path_HELP: shows the help screen.

CWS_Path_NEW_SINGER: requires as params: kPostData_SUBMIT (empty string), kPostData_SINGER_NAME, kPostData_PASSWORD, and kPostData_PASSWORD_CONFIRM, it will then create a new singer, or return an error: that the singer name already exists, that no password was specified, or that the passwords don't match, then send the user to the singer's login screen.

CWS_Path_SINGERS: returns a plist of all singers, so you can put them in a menu to choose from.

CWS_Path_KJ_ROTATION: returns a plist of all singers who are marked "Here", even if there is no password set. Each singer includes the name of the song they will sing or sang IN THE CURRENT rotation. Also is a list of all songs (with album names) in their "Tonight" list (so you can implement the "Switchable Songs" feature. Note the index of this (1-based) list is is ALWAYS 1 since when you pick a song that is NOT first, it gets moved to the first position immediately. You must re-fetch this entire list after you switch a song. Also included is a (1-based) list of all albums (manufacturers) for the current song, so you may implement the "Switchable Albums" feature. Allow reordering of this list ONLY if the logged in singer is a KJ.

CWS_Path_ROTATION: returns a plist of singers like above, but all rotations are shown for the rest of the night. Singers may be listed more than once, but with different songs each time. Switchable Albums is supported on this list, but NOT Switchable Songs. Reordering of this list is not allowed.

CWS_Path_PLAYLISTS: only works if a singer is logged in, it returns the list of playlists that are owned by the singer. currently there are three ("Tonight", "History" and "Favorites") but be prepared to show a variable number.

CWS_Path_SONGS: singer must be logged in, requires params: kPostData_PLAYLIST (name), kPostData_ORDER_BY (CWS_OrderByType value) (optional), kPostData_SEARCH (search string (NOT URL ENCODED!)). returns a plist containing the songs in the playlist. also pings. must send some search string to get a list of songs.

CWS_Path_SEARCH:, singer must be logged in, requires param: kPostData_SEARCH (search string (NOT URL ENCODED!)), searches main Library playlist

CWS_Path_DROP: adds song to singer playlist. singer must be logged in, requires params: kPostData_PLAYLIST (name), kPostData_SONG (Song ID, not PLI ID).

CWS_Path_REORDER: changes order of playlist. singer must be logged in, requires parms: kPostData_PLAYLIST, kPostData_INDEX_OLD, kPostData_INDEX. These are playlist indexes, as determined when sorted by "#"

CWS_Path_REMOVE: removes a song from a playlist. singer must be logged in. required params: kPostData_PLAYLIST, kPostData_PLI (playlist item ID of playlist)

CWS_Path_PITCH: changes pitch of a song. singer must be logged in. required params: kPostData_SONG (song ID), kPostData_PITCH (integer value [-6..+6])

CWS_Path_TEMPO: changes tempo of a song. singer must be logged in. required params: kPostData_SONG (song ID), kPostData_PITCH (float value [0.5..1.5])

CWS_Path_INFO: returns a dictionary containing: "version" (app vers), "os" (current platform), "kjid" (KJ Identifier), "ownid" (md5 hash of user's serial number), "serverid" (md5 hash of IP address), "venue" (name)

CWS_Path_NEW_PLAYLIST: required: kPostData_SUBMIT (empty string), kPostData_NAME, kPostData_ADMIN_PASSWORD

CWS_Path_CMD: required data: kPostData_CMD_ID, which is any of the Scripting commands