Every call to the WaveBox API requires authentication data, whether it is the "s" session key parameter sent in GET or POST parameters, or the wavebox_session cookie issued by the server. Unless otherwise specified, all other parameters are optional. Each API call is prefixed by /api/ in the URL. Responses are encoded in gzip or deflate if requested, in order to compress large responses.
Used to create a new session ID for an existing user. The session ID returned is used to access all other API calls.
URL: /api/login
Example: http://localhost:6500/api/login?u=test&p=test
Parameters
Name | Description | Required |
---|---|---|
u | The username of the identity you would like to use to access the API | ✓ |
p | The password associated with the above username | ✓ |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
sessionId | The session id for this login session. |
Used to destroy the current session for an existing user. The session ID returned is the one which was destroyed.
URL: /api/logout
Example: http://localhost:6500/api/logout
Parameters
Name | Description | Required |
---|---|---|
n/a | n/a |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
sessionId | The session id destroyed by logging out. |
Used to return information about all albums known to WaveBox, or with the 'id' parameter, information about a specific album. On invalid id, a null album object will be sent.
URL: /api/albums/:id
Example: http://localhost:6500/api/albums/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the album you would like information about. If null, information about all albums known by the server will be retrieved. | |
limit | Modifies the requested result set to only include a subset of results, just like SQL LIMIT x,y. | |
range | Fetches a list of all items within the comma-separated alphanumeric range. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
albums | An array of album objects, which contain information about the album(s) requested. The structure of the album object is discussed in the Data Structures segment. |
songs | An array of song objects, which contain information about the songs in the requested album. Null if ‘id’ is not specified. The structure of the song object is discussed in the Data Structures segment. |
Used to return a binary art file, which is tied to an album via an art ID. With parameter ‘id’ specified, will attempt to fetch the album art with this ID. Will return HTTP 404 error if no art found.
Note that the Art API handler can use either ImageMagick or GDI to resize an image. On Mac OSX and UNIX, ImageMagick will be tried, followed by GDI on failure. On Windows, GDI will be used.
In addition, note that the handler will send a HTTP Last-Modified header, so clients may cache art for a faster response.
URL: /api/art/:id
Example: http://localhost:6500/api/art/125?size=500
Parameters:
Name | Description | Required |
---|---|---|
id | The art id for the art you would like to receive | ✓ |
size | The horizontal size of the image you would like to receive. The aspect ratio will be maintained. i.e. If an image is 600x500 and you specify size=300, then the resulting image will be 300x250. If size is not specified, the original image file is returned. | |
s | The sessionId of the active session you would like to use to access the API. | ✓ |
Returns
Name | Description |
---|---|
Binary art file on success | Returns binary art file directly to client. Returns HTTP 404 error if art does not exist. |
Used to return information about all artists known to WaveBox, or with the ‘id’ parameter, information about a specific artist. On invalid id, a null artist object will be sent.
URL: /api/artists
Example: http://localhost:6500/api/artists/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the artist you would like information about. If null, information about all artists known by the server will be retrieved. | |
includeSongs | If set to false, or not included, songs array will be empty. Otherwise, songs array will contain all associated songs for this artist. Default: false | |
lastfmInfo | Attempt to fetch additional information about this artist using the Last.fm API. Default: false. | |
limit | Modifies the requested result set to only include a subset of results, just like SQL LIMIT x,y. | |
range | Fetches a list of all items within the comma-separated alphanumeric range. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
artists | An array of artist objects, which contain information about the artist(s) requested. The structure of the artist object is discussed in the Data Structures segment. |
albums | An array of album objects, which contain information about the album(s) requested. The structure of the album object is discussed in the Data Structures segment. Null if no artist ID is supplied. |
songs | An array of song objects, which contain information about the songs in the requested album. Empty array if ‘id’ is not specified, includeSongs not specified, or includeSongs is false. The structure of the song object is discussed in the Data Structures segment. |
lastfmInfo | An object containing information about a specific artist, from the Last.fm API. Null if not requested, or if no information returned. |
URL: /api/database
Example: http://localhost:6500/api/database/20000
Parameters
Name | Description | Required |
---|---|---|
id | The query ID at which you wish to begin retrieving the query log. Any queries occuring after this ID will be returned. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
WaveBox media database | Returns the entire SQLite database file, with no ‘id’ specified. Also returns special ‘WaveBox-LastQueryId’ HTTP header. |
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
queries | An array of queries occuring after the specified ID, containing ‘id’, ‘query’, and ‘values’. Used for differential update of remote database. |
URL: /api/folders
Example: http://localhost:6500/api/folders/20000
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the folder you would like information about. If null, information about all top-level folders known by the server will be retrieved. | |
recursiveMedia | If a folder ID is specified, recursiveMedia=true will return all songs for all folders below the associated folder in the directory structure. Default: false | |
mediaFolders | If no id is specified, and this is true, return the media folders instead of the list of top level folders. Default: false | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
folders | An array of folder objects, which contain information about the folder(s) requested. The structure of the folder object is discussed in the Data Structures segment. |
containingFolder | The parent folder object of the folder specified by this folder ID, or if at deepest folder level, the currently focused folder. |
songs | An array of song objects, which contain information about the songs in the requested folder. Empty array if ‘id’ is not specified, or no songs present in folder. The structure of the song object is discussed in the Data Structures segment. |
videos | An array of video objects, which contain information about the songs in the requested folder. Empty array if ‘id’ is not specified, or no videos present in folder. The structure of this object is discussed in the Data Structures segment. |
URL: /api/genres
Example: http://localhost:6500/api/genres/20000
Parameters
Name | Description | Required |
---|---|---|
id | The ID of a specific genre. By default, will return all artists containing a genre matching this ID. | |
type | Specifies the type of objects to retrieve, which match this genre ID. Possible values are “folders”, “albums”, “songs”, and “artists” (default). | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
genres | An array of genre objects, which contain information about the genre(s) requested. The structure of the genre object is discussed in the Data Structures segment. |
folders | An array of folder objects, which contain information about the folder(s) requested. The structure of the folder object is discussed in the Data Structures segment. |
artists | An array of artist objects, which contain information about the artists matching the requested genre. Empty array if ‘id’ is not specified, or no artists present in genre. The structure of the artist object is discussed in the Data Structures segment. |
albums | An array of album objects, which contain information about the albums matching the requested genre. Empty array if ‘id’ is not specified, or no albums matching the requested genre. The structure of the album object is discussed in the Data Structures segment. |
songs | An array of song objects, which contain information about the songs matching the requested genre. Empty array if ‘id’ is not specified, or no songs matching the requested genre. The structure of the song object is discussed in the Data Structures segment. |
Used to manipulate the jukebox function of WaveBox. This includes functions such as “play”, “pause”, “stop”, and other related actions. Can potentially return an error, the status of the jukebox, and the jukebox’s current playlist.
The “playlist”, “add”, “remove”, “move”, and “clear” actions manipulate the jukebox play queue.
- Add takes only a song ID or a list of song IDs
- Remove takes an index or a comma-delimited list of indexes in the jukebox playlist
- Move takes a from index and a to index as a comma-delimited tuple. e.g. action=move&index=1,2 would move the song at index 1 to index 2
“play”, “pause”, “stop”, “prev”, and “next” control the jukebox player.
- Play takes an index of the jukebox playlist, or if no index and paused or stopped, plays the current index
Note: Songs must be added to the jukebox’s playlist before they can be played.
URL: /api/jukebox
Example: http://localhost:6500/api/jukebox/125?action=add
Parameters
Name | Description | Required |
---|---|---|
action | The action to be performed, defaults to “status”. Possible values are: “play”, “pause”, “stop”, “prev”, “next”, “status”, “playlist”, “add”, “remove”, “move”, “clear” | |
id | Only used (and required) with the “add” action. Contains a comma delimited list of song IDs to add to the playlist | (✓) |
index | Only used (and required) with actions that modify the playlist such as “add”, “remove”, or “move”. When using “remove”, may be a comma-delimited list of indexes to remove. When using “move”, this is a single comma-delimited pair of indexes with the first being the ‘from’ index and the second being the ‘to’ index. | (✓) |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
jukeboxStatus | An object containing information on the jukebox player. The structure is discussed in the Data Structures segment. |
jukeboxPlaylist | An object describing the jukebox play queue. The structure is discussed in the Data Structures segment. |
Returns information about a podcast or an episode, or alternatively performs an action on a podcast or an episode. If an action is not specified, information will be returned.
URL: /api/podcast
Example: http://localhost:6500/api/podcasts/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the podcast you are requesting | |
episodeId | The ID of an episode of a specific podcast with specified podcastId | |
action | Action you would like to perform. Possible actions include “add”, “delete”, or “edit”. If not specified, information is returned instead of an action being performed. | |
url | The (url encoded) url of the podcast to add. Used with the “add” action only. | |
keepCap | The number of episodes to keep for the podcast. Only used with the “add” and “edit” actions. | |
The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
podcasts | An array of podcast objects. The structure of the podcast object is discussed in the Data Structures segment. |
episodes | An array of podcast episode objects. The structure of the podcast episode object is discussed in the Data Structures segment. |
Used to submit Last.fm song plays and submissions. Can be used to submit multiple offline events. Since the last.fm API supports only 100 scrobbles per API call, WaveBox behaves the same way. Only the first 100 scrobbles in a call will be acted upon.
URL: /api/scrobble
Example: http://localhost:6500/api/scrobble/125?action=nowPlaying
Parameters
Name | Description | Required |
---|---|---|
action | Defines what function will be performed for the call. Valid values are “auth”, “scrobble”, or “nowPlaying”. If not specified, WaveBox assumes “auth”. Auth takes no parameters and returns whether or not last.fm is authenticated for the user account associated with the session ID. If not, it returns a URL to direct the user to in order to do so. For “scrobble”, the event parameter is required. For “nowPlaying”, the id parameter is required. | |
id | The id of the song being played. Only used with the “nowPlaying” action. | (✓) |
event | A comma-delimited list of id/unix-timestamp tuples. All timestamps should be in UTC time zone. Only used with the “scrobble” action. Example: 10,213214621231,1231,213214821231 | (✓) |
s | The sessionId of the active session you would like to use to access the API. Scrobbles will be recorded for this user. | ✓ |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
authUrl | Returned when “auth” is called if the user is not authenticated. Also returned when “scrobble” is called if the scrobble fails because the user is not authenticated. |
Returns lists of objects matching the specified parameter ‘query’, optionally filtering types with a comma-separated list. By default, searches using the item’s name, but can also search on other fields. In addition, can either fuzzy-search or exact match if specified.
URL: /api/search
Example: http://localhost:6500/api/search?query=Taylor+Swift
Parameters
Name | Description | Required |
---|---|---|
query | A search string by which to query for in the database. By default, the item’s name is queried, unless a ‘field’ parameter is specified. | ✓ |
field | Determines which database field will be queried, when searching for items. Can be any valid database column in any media database. (e.g. “song_id”, “video_id”, “song_file_name”, etc.) | |
exact | Determines if WaveBox will only search for exact matches in the database. If false, will attempt to match using SQLite LIKE operator. Default is false. | |
type | Comma-separated list of item types in which to query. Defaults to all types. Some examples could be “artists,songs”, “songs,videos”, “artists,albums,songs”, etc. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
artists | An array of artist objects matching the search query results. The structure of the artist object is discussed in the Data Structures segment. |
albums | An array of album objects matching the search query results. The structure of the album object is discussed in the Data Structures segment. |
songs | An array of song objects matching the search query results. The structure of the song object is discussed in the Data Structures segment. |
videos | An array of video objects matching the search query results. The structure of the video object is discussed in the Data Structures segment. |
Returns the settings information, or if a JSON object is specified, updates setting(s) by merging it with the current settings.
URL: /api/settings
Example: http://localhost:6500/api/settings?json={"port":6500}
Parameters
Name | Description | Required |
---|---|---|
json | JSON object which will overwrite any matching settings, and merge with the existing settings. Parameter is sent URL encoded, and URL decoded on the server side. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
settings | An object containing settings information. The structure of the user object is discussed in the Data Structures segment. |
Returns a list of all songs known to WaveBox. When a parameter ‘id’ is specified, returns the song with that matching song ID. This response can be very large, so it is recommended to grab subsets using a combination of the ‘range’ and ‘limit’ parameters where applicable.
URL: /api/songs
Example: http://localhost:6500/api/songs/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of a song in the WaveBox database, which returns a single song object matching this ID. | |
limit | Modifies the requested result set to only include a subset of results, just like SQL LIMIT x,y. | |
range | Fetches a list of all items within the comma-separated alphanumeric range. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
songs | An array of song objects, which contain information about all songs, or the song matching parameter ‘id’. The structure of the song object is discussed in the Data Structures segment. |
Currently only used to update server play counts. In the future, additional statistics may be supported. May be used to submit multiple offline actions.
URL: /api/stats
Example: http://localhost:6500/api/stats?event=10,0,213214621231
Parameters
Name | Description | Required |
---|---|---|
event | A comma delimited list of id/event-type/unix-timestamp events. All timestamps should be UTC time zone. Example: 10,0,213214621231,1231,0,213214821231,122,0,213214381231,130,0,21321439231 | ✓ |
s | The sessionId of the active session you would like to use to access the API. Stats will be recorded for this user. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
Returns the current server status information. May be used to check if the server is online or for other purposes.
URL: /api/status
Example: http://localhost:6500/api/status?extended=true
Parameters
Name | Description | Required |
---|---|---|
extended | Determines if server will return extended status metrics, which involve database heavy operations. These operations are cached on first run, however, and only need to be regenerated when a destructive operation occurs on the database. Default: false | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
status | An object containing server status information. The structure of the status object is discussed in the Data Structures segment. |
Used to retrieve a song or video stream. Will always return the untouched original media file.
URL: /api/stream
Example: http://localhost:6500/api/stream/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the media item you would like to stream. If null, information about all songs known by the server will be retrieved. | ✓ |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error (if unsuccessful) | An object containing information about any error that may have occurred. NO JSON IS RETURNED ON SUCCESS, ONLY BINARY DATA. The structure of the error object is discussed in the Data Structures segment. |
Used to retrieve a song or video stream. Returns a transcoded copy of the original file.
URL: /api/transcode
Example: http://localhost:6500/api/transcode/125?transType=opus&transQuality=medium
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the media item you would like to stream. | ✓ |
transType | The transcoding format. For audio, options include: “MP3” (defualt), “AAC”, “OGG”, and “OPUS”. For video, options include: “MPEGTS”, and “X264” (default) | |
transQuality | The transcoding quality. Defaults to “Medium”. Options include: “Low”, “Medium”, “High”, “Extreme”, or integer bitrate value. Word values will produce VBR files while bitrate values will produce CBR files. | |
isDirect | Sends stream directly from memory to the socket, instead of creating an intermediate file first. Default: false | |
offsetSeconds | Used to write a file beginning at a specified time offset, for connection inconsistencies | |
lengthSeconds | Specify how much of a file to stream, but default to the entire file | |
estimateContentLength | Determines whether or not WaveBox will attempt to estimate the size of the transcoded file. Default: false | |
width | Determines the output width of a transcoded video file | |
height | Determines the output height of a transcoded video file | |
maintainAspect | Determines if WaveBox will maintain the aspect ratio of an input video file. Default: true | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
Transcoded file | A data stream of the transcoded input file, for playing in clients |
error (if unsuccessful) | An object containing information about any error that may have occurred. NO JSON IS RETURNED ON SUCCESS, ONLY BINARY DATA. The structure of the error object is discussed in the Data Structures segment. |
URL: /api/transcodehls
Example: http://localhost:6500/api/transcodehls/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the media item you would like to stream. | ✓ |
width | Determines the output width of a transcoded video file | |
height | Determines the output height of a transcoded video file | |
maintainAspect | Determines if WaveBox will maintain the aspect ratio of an input video file. Default: true | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
Transcoded file | A data stream of the transcoded input file, for playing in clients |
error (if unsuccessful) | An object containing information about any error that may have occurred. NO JSON IS RETURNED ON SUCCESS, ONLY BINARY DATA. The structure of the error object is discussed in the Data Structures segment. |
Used to retrieve or update user information.
URL: /api/users
Example: http://localhost:6500/api/users/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of the user. | |
action | Action you would like to perform. Possible actions include “killSession”, which will remove a session with specified ‘rowId’. | |
rowId | Used to identify a certain session, in conjunction with an ‘action’ parameter. | |
testUser | Used to create a test user, with an optional expiration time of ‘durationSeconds’. | |
durationSeconds | Used to set the duration for which a test account may remain active. The account is deleted after this time. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
user | An object containing user information. The structure of the user object is discussed in the Data Structures segment. |
Returns a list of all videos known to WaveBox. When a parameter ‘id’ is specified, returns the video with that matching video ID.
URL: /api/videos
Example: http://localhost:6500/api/videos/125
Parameters
Name | Description | Required |
---|---|---|
id | The ID of a video in the WaveBox database, which returns a single video object matching this ID. | |
s | The sessionId of the active session you would like to use to access the API. |
Returns
Name | Description |
---|---|
error | An object containing information about any error that may have occurred. Null if the call is successful. The structure of the error object is discussed in the Data Structures segment. |
songs | An array of video objects, which contain information about all videos, or the video matching parameter ‘id’. The structure of the video object is discussed in the Data Structures segment. |