Here is the full documentaition of the REST API.

All data returned are in JSON format.

Most endpoints relies on a valid Glewlwyd Bearer token in the header, with a valid signature. For all requests, the username is provided by the Bearer token.

/api/data_source/

GET

Code 200

Content

[
  {
    "name": string, max 128 characters
    "description": string, max 512 characters
    "last_updated": integer, epoch time of the last refresh
    "scope": string, values available are "me" or "all"
  }
]

Code 500

Internal Error

/api/data_source/@data_source_name

GET

Required

@data_source_name: Data Source name

Code 200

Content

{
  "name": string, max 128 characters
  "description": string, max 512 characters
  "last_updated": integer, epoch time of the last refresh
  "scope": string, values available are "me" or "all"
}

Code 404

Data source not found

Code 500

Internal Error

/api/data_source/

POST

{
  "name": string, max 128 characters, mandatory, must be unique for the current user, including data source for all users
  "description": string, max 512 characters, optional
  "path": string, max 1024 characters, mandatory, must correspond to a valid path on the server
  "scope": string, optional, values available are "me" or "all", default "me", only an administrator can create a data source with the scope "all"
}

Code 200

Code 500

Internal Error

OR

Code 400

Error input parameters

Content: json array containing all errors

Note: By design, the user can't change the data source path, name or scope

/api/data_source/@data_source_name

PUT

Required

@data_source_name: Data Source name

{
  "description": string, max 512 characters, optional
}

Code 200

Code 500

Internal Error

OR

Code 400

Error input parameters

Content: json array containing all errors

/api/data_source/@data_source_name

DELETE

Required

@data_source_name: Data Source name

Code 200

Code 404

Data source not found

Code 403

Unauthorized to delete the specified data source

Code 500

Internal Error

/api/data_source/@data_source_name/refresh/@relative_path

PUT

Required

@data_source_name: Data Source name

Optional

@relative_path: Relative path to refresh, default is /

Code 200

Code 404

Data source not found

Code 403

Unauthorized to refresh the specified data source

Code 500

Internal Error

/api/data_source/@data_source_name/refresh

GET

Required

@data_source_name: Data Source name

Code 200

Content

{
  "status": string, values available are "not_running", "pending", "preparing", "running" and "error"
	"read": integer, number of files currently read
	"total": integer, total number of files to refresh
}

Code 404

Data source not found

Code 403

Unauthorized to refresh the specified data source

Code 500

Internal Error

/api/data_source/@data_source_name/refresh/

DELETE

Required

@data_source_name: Data Source name

Code 200

Code 404

Data source not found

Code 403

Unauthorized to refresh the specified data source

Code 500

Internal Error

/api/data_source/@data_source_name/clean

POST

Required

@data_source_name: Data Source name

Code 200

Code 404

Data source not found

Code 403

Unauthorized to clean the specified data source

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/browse/path/@relative_path_to_folder

Example: /api/data_source/dataSource1/browse/path/Open Goldberg Variation/

GET

Required

@data_source_name: Data Source name

Optional

@relative_path_to_folder: Relative path to a folder, default is /

Code 200

Content

[
  { // Example subfolder
    "name": string
    "path": string
    "type": "folder"
  },
  { // Example file
    "name": string
    "path": string
    "type": string, values can be "audio", "video", "image", "other"
    "last_updated": integer, epoch timestamp when the file was last updated in the filesystem
    "tags": {
      "key": "value" // Set of tags using the pair key/value
    }
  }
]

Code 404

Path not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/browse/path/@relative_path_to_file

GET

Required

@data_source_name: Data Source name @relative_path_to_folder: Relative path to a file

Code 200

Content

{
  "name": string
  "path": string
  "type": string, values can be "audio", "video", "image", "other"
  "last_updated": integer, epoch timestamp when the file was last updated in the filesystem
  "tags": {
    "key": "value" // Set of tags using the pair key/value
  }
}

Code 404

Path not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level

GET

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre

Code 200

Content

[ // Array of strings of all the categories available for the selected level
  "cat1",
  "cat2",
  "cat3"
]

Code 404

Level not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level/@category

GET

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name

Code 200

Content

[
  { // Example media
    "name": string
    "path": string
    "type": string, values can be "audio", "video"
    "last_updated": integer, epoch timestamp when the file was last updated in the filesystem
    "tags": {
      "key": "value" // Set of tags using the pair key/value
    }
  }
]

Code 404

Level or category not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level/@category/info

GET

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name

Code 200

Content

{
  "content": string, content of the category info
}

Code 404

Level or category not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level/@category/info

PUT

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name

{
  "content": string, max 16MB, optional
  "cover": string, max 16MB, optional
}

Code 200

Code 404

Level or category not found

Code 500

Internal Error

Code 400

Error input parameters

Content: json array containing all errors

/api/data_source/@data_source/@data_source_name/category/@level/@category/info

DELETE

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name

Code 200

Code 404

Level or category not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level/@category/@sublevel

GET

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name @sublevel: sublevel name, values available are artist, album, year, genre, must be different from @level

Code 200

Content

[ // Array of strings of all the categories available for the selected level
  "cat1",
  "cat2",
  "cat3"
]

Code 404

Level or category or sublevel not found

Code 500

Internal Error

/api/data_source/@data_source/@data_source_name/category/@level/@category/@sublevel/@subcategory

GET

Required

@data_source_name: Data Source name @level: level name of the category, values available are artist, album, year, genre @category: category name @sublevel: sublevel name, values available are artist, album, year, genre, must be different from @level @subcategory: subcategory name

Code 200

Content

[
  { // Example media
    "name": string
    "path": string
    "type": string, values can be "audio", "video"
    "last_updated": integer, epoch timestamp when the file was last updated in the filesystem
    "tags": {
      "key": "value" // Set of tags using the pair key/value
    }
  }
]

Code 404

Level, category, subevel or subcategory not found

Code 400

Error in url parameters

Code 500

Internal Error

/api/playlist/

GET

Code 200

Content

[
  {
    "name": string, max 128 characters
    "description": string, max 512 characters
    "scope": string, values available are "me" or "all"
    "elements": integer, number of media files in the playlist
		"stream": [ // List of streams attached to this playlist
			{
				"name": string, name of the string
				"display_name": string, display name of the stream
				"webradio": boolean
			}
		]
  }
]

Code 500

Internal Error

/api/playlist/@playlist_name

GET

Required

@playlist_name: Playlist name

Optional

offset: Start offset for media list (default 0)

limit: Maximum number of elements in the media list (default 100)

Code 200

Content

{
	"name": string, max 128 characters
	"description": string, max 512 characters
	"scope": string, values available are "me" or "all"
	"elements": integer, number of media files in the playlist
	"media": [ Array of media files in the playlist
		{...}
	],
	"stream": [ // List of streams attached to this playlist
		{
			"name": string, name of the string
			"display_name": string, display name of the stream
			"webradio": boolean
		}
	]
}

Code 404

Playlist not found

Code 500

Internal Error

/api/playlist/

POST

{
  "name": string, max 128 characters, mandatory, name of the  playlist, must be unique for the user
  "description": string, optional, max 512 characters
  "scope": string, values available are "me" or "all", optional, only an administrator can set a scope to "all", default is "me"
  "cover": string, cover image for the playlist in base64 encoding
  "media": [ // List of all media in the playlist
    {
      "data_source": data_source name of the media
      "path": relative path of the media
    }
  ]
}

Code 200

Code 500

Internal Error

OR

Code 400

Error input parameters

Content: json array containing all errors

Note: By design, the user can't change the scope

/api/playlist/@playlist_name

PUT

Required

@playlist_name: Playlist name

{
  "description": string, max 512 characters, optional
  "cover": string, cover image for the playlist in base64 encoding
  "media": [ // List of all media in the playlist
    {
      "data_source": data_source name of the media
      "path": relative path of the media
    }
  ]
}

Code 200

Code 500

Internal Error

OR

Code 400

Error input parameters

Content: json array containing all errors

/api/playlist/@playlist_name

DELETE

Required

@playlist_name: Playlist name

Code 200

Code 404

Playlist not found

Code 403

Unauthorized to delete the specified playlist

Code 500

Internal Error

/api/playlist/@playlist_name/add_media

PUT

Required

@playlist_name: Playlist name

[ // List of all media in the playlist
  {
    "data_source": data_source name of the media
    "path": relative path of the media
  }
]

Code 200

Code 500

Internal Error

Code 404

Playlist not found

Code 403

Unauthorized to delete the specified playlist

OR

Code 400

Error input parameters

Content: json array containing all errors

/api/playlist/@playlist_name/delete_media

DELETE

Required

@playlist_name: Playlist name

[ // List of all media in the playlist
  {
    "data_source": data_source name of the media
    "path": relative path of the media
  }
]

Code 200

Code 500

Internal Error

Code 404

Playlist not found

Code 403

Unauthorized to delete the specified playlist

OR

Code 400

Error input parameters

Content: json array containing all errors

All API that return a media or a list of media can be used to directly start a jukebox or a webradio by simply adding the query parameter webradio or jukebox. You can also add other optional parameters.

A webradio is a single stream that will play all songs at random or in sequence. A jukebox allows the user to choose what media should be played by using its index in the stream list.

/api/data_source/@data_source/@data_source_name/browse/path/@relative_path_to_folder?[webradio|jukebox][&random][&recursive][&format=][&bitrate=][&sample_rate=][&channels=][&name=]

/api/data_source/@data_source/@data_source_name/browse/category/@level/@category/@sublevel/@subcategory?[webradio|jukebox][&random][&format=][&bitrate=][&sample_rate=][&channels=][&name=]

/api/data_source/@data_source/@data_source_name/browse/category/@level/@category/@sublevel/@subcategory?[webradio|jukebox][&random][&format=][&bitrate=][&sample_rate=][&channels=][&name=]

Examples: /api/data_source/dataSource1/browse/path/Open Goldberg Variation?webradio&recursive /api/data_source/dataSource1/browse/path/Open Goldberg Variation/KIMIKO ISHIZAKA - Goldberg Variations BWV 988 - 01 - Aria__44k-24b.mp3?jukebox /api/data_source/dataSource1/browse/category/artist/Kimiko Ishizaka?jukebox&format=flac&sample_rate=48000

GET

Required

@data_source_name: Data Source name @relative_path_to_folder: Relative path to a folder, mandatory for browse/path urls only @level: level name of the category, values available are artist, album, year, genre, mandatory for browse/category only @category: category name, mandatory for browse/category only @sublevel: sublevel name, values available are artist, album, year, genre, must be different from @level, optional for browse/category only @subcategory: subcategory name, optional for browse/category only

Query parameters

Mandatory

Note: obviously you can't combine webradio and jukebox at the same time, if both parameters are set, the result stream will be a webradio.

webradio: Run a webradio stream based on the path or category parameters jukebox: Run a jukebox that can be streamed based on the path or category parameters

Optional

Parameters common to webradio and jukebox

format: format used for the stream, values available are mp3, vorbis and flac bitrate: bitrate used for the stream, for mp3 or vorbis formats only, values available are 32000, 96000, 128000, 192000, 256000, 320000, if format flac is used, bitrate is automatically set to 1411000 sample_rate: sample rate (~frequency) used for the stream, values available are 8000, 11025, 22050, 32000, 44100, 48000 channels: number of channels used for the stream, values available are 1 (mono) or 2 (stereo) name: display name for stream, optional, if not specified, the stream will have a display name corresponding to the path or the category

Parameter used in webradio only

random: if set, the webradio will play all media at random

Parameter used in browse path only

recursive: if set, all the subfolders will be included in the media list

Code 200

Content

{
  "name": string, name of the stream, a 32 characters random sequence generated
  "display_name": string, display name of the stream
  "webradio": boolean true if the stream is a webradio
	"elements": number of elements in the stream
  "format": string, audio format of the stream, values available are `mp3`, `vorbis` or `flac`
  "stereo": boolean, true if the audio stream is stereo
  "sample_rate": integer, sample rate of the audio stream
  "bitrate": integer, bitrate of the audio stream
  "nb_client": integer, number of clients currently listening to the stream
  "last_seen": integer, date in epoch format when the stream was used last, for jukebox streams only
  "stored_playlist": string, name of the playlist the stream is based on, optional
	"clients": [ Array of clients
		{
			"ip_address": string, ip address of the client
			"user_agent": string, user agent of the client
		}
	]
}

Code 404

Path or category not found, or no media are available with the specified parameters

Code 400

Error input parameters

Code 500

Internal Error

/api/playlist/@playlist_name/?[webradio|jukebox][&random][&format=][&bitrate=][&sample_rate=][&channels=][&name=]

Examples: /playlist/playlist1?webradio /playlist/playlist2?jukebox /playlist/playlist1?jukebox&format=flac&sample_rate=48000

GET

Required

@playlist_name: Stored playlist name

Query parameters

Mandatory

Note: obviously you can't combine webradio and jukebox at the same time, if both parameters are set, the result will be a webradio.

webradio: Run a webradio stream based on the path or category parameters jukebox: Run a jukebox that can be streamed based on the path or category parameters

Optional

Parameters common to webradio and jukebox

format: format used for the stream, values available are mp3, vorbis and flac bitrate: bitrate used for the stream, for mp3 or vorbis formats only, values available are 32000, 96000, 128000, 192000, 256000, 320000, if format flac is used, bitrate is automatically set to 1411000 sample_rate: sample rate (~frequency) used for the stream, values available are 8000, 11025, 22050, 32000, 44100, 48000 channels: number of channels used for the stream, values available are 1 (mono) or 2 (stereo) name: display name for stream, optional, if not specified, the stream will have a display name corresponding to the path or the category

Parameter used in webradio only

random: if set, the webradio will play all media at random

Parameter used in browse path only

recursive: if set, all the subfolders will be included in the media list

Code 200

Content

// Playlist response
{
  "name": string, name of the stream, a 32 characters random sequence generated
  "display_name": string, display name of the stream
  "webradio": boolean true if the stream is a webradio
	"elements": number of elements in the stream
  "format": string, audio format of the stream, values available are `mp3`, `vorbis` or `flac`
  "stereo": boolean, true if the audio stream is stereo
  "sample_rate": integer, sample rate of the audio stream
  "bitrate": integer, bitrate of the audio stream
  "nb_client": integer, number of clients currently listening to the stream
  "last_seen": integer, date in epoch format when the stream was used last, for jukebox streams only
  "stored_playlist": string, name of the playlist the stream is based on, optional
	"clients": [ Array of clients
		{
			"ip_address": string, ip address of the client
			"user_agent": string, user agent of the client
		}
	]
}

Code 404

Path or category not found, or no media are available with the specified parameters

Code 400

Error input parameters

Code 500

Internal Error

You can get cover from media files, folders, playlists and categories The query parameter to add is cover

/api/data_source/@data_source/@data_source_name/browse/path/@relative_path?cover[&thumbnail][&base64] /api/data_source/@data_source/@data_source_name/category/@level/@category?cover[&thumbnail][&base64] /api/playlist/@playlist_name?cover[&thumbnail][&base64]

GET

Required

@data_source: data source name, required for data source browse @relative_path: relative path to folder or media file, required for data source path browse @level: level name of the category, values available are artist, album, year, genre, required for data source category browse @category: category name, required for data source category browse @playlist_name: Playlist name, required for playlist browse

Code 200

Content: Raw cover in binary or base64

Code 500

Internal Error

Code 404

Cover not found

Simple search allows to search by folder name, media file name, categories (artist, album, year, genre and title), stored playlist name, and stream display name. All the search criteria must be set in the url. The simple search will be executed in all data source available for the user. All returned list are limited to 100 elements per category.

/api/search?q=[search_pattern]&category=[playlist|stream|folder|file|title|title|artist|album|year|genre]

GET

Required

q: string, search pattern to look for. Search is case insensitive and search if the pattern is contained in the data.

Optional

category: Search category, optional, values available are playlist, stream, folder, file, title, title, artist, album, year, genre, default is non, which means all categories.

Code 200

Content

{
  "playlist": [ // Array of playlist names corresponding the pattern, optional
    "playlist1",
    "playlist2"
    //etc
  ],
  "stream": [ // Array of stream objects corresponding the pattern, optional
    {
      "name": string, name of the stream
      "display_name": string, display name of the stream
      "webradio": boolean, true if the stream is a webradio
    }
  ],
  "folder": [ // Array of folders whose name correspond the pattern, optional
    {
      "data_source": string, name of the data source
      "name": string, name of the folder
      "path": string, relative path of the folder
    }
  ],
  "media": [ // Array of media whose name or metadata correspond the pattern, optional
    {
      "data_source": string, name of the data source
      "name": string, name of the media file
      "path": string, relative path of the media file
    }
  ]
}

Code 400

No pattern specified

Code 500

Internal Error

Advanced search allows to find for media files only, you can specify multiple search criteria, all criteria will be evaluated with a AND combimation.

/api/search

PUT

{
  "limit": positive integer, optional, maximum number of elements returned, default is 100
  "offset": positive integer, optional, offset to start the list of elements returned
  "data_source": [ // Array of data source names to make the search, optional, if no data source is specified, the search will be executed in all data source available for the user
    "datasource1",
    "datasource2"
    // etc.
  ],
  "tags": [ // Array of tag search
    {
      "key": string, mandatory, key name to search
      "operator": string, mandatory, operator to use for the search pattern, values available are `equals`, `different`, `contains`, `lower`, `higher`, `between` and `empty`
      "value": string, mandatory if `operator` is not `empty`, otherwise ignored
      "value_max": string, mandatory if `operator` is `between`, otherwise ignored
    }
  ],
  "metrics": { // Object for media metrics
    "nb_play": { // Number of times the medi has been played
      "operator": string, mandatory, values available are `equals`, `different`, `lower`, `higher` and `between`
      "value": positive integer, mandatory
    }
    "played_at":  { // epoch time when the media was played
      "operator": string, mandatory, values available are `equals`, `different`, `lower`, `higher` and `between`
      "value": positive integer, mandatory
    }
    "last_seen":  { // epoch time when the media was last played
      "operator": string, mandatory, values available are `equals`, `different`, `lower`, `higher` and `between`
      "value": positive integer, mandatory
    }
  }
}

Code 200

Content

[
  {
    "data_source": string, name of the data source
    "name": string, name of the media file
    "path": string, relative path of the media file
  }
]

Code 400

No pattern specified

Code 500

Internal Error

/api/stream/

GET

Code 200

Content

[
  {
		"name": string, name of the stream, a 32 characters random sequence generated
		"display_name": string, display name of the stream
		"webradio": boolean true if the stream is a webradio
		"elements": number of elements in the stream
		"format": string, audio format of the stream, values available are `mp3`, `vorbis` or `flac`
		"stereo": boolean, true if the audio stream is stereo
		"sample_rate": integer, sample rate of the audio stream
		"bitrate": integer, bitrate of the audio stream
		"nb_client": integer, number of clients currently listening to the stream
		"last_seen": integer, date in epoch format when the stream was used last, for jukebox streams only
		"stored_playlist": string, name of the playlist the stream is based on, optional
		"clients": [ Array of clients
			{
				"ip_address": string, ip address of the client
				"user_agent": string, user agent of the client
			}
		]
  }
]

Code 500

Internal Error

For a stream to be available to usual media players, we can't use a Oauth2 Bearer token to authenticate the stream, because it's not supported, and would be way too overkill. Instead, all Taliesin stream address use a 32 bytes identifier which is randomly generated, so an unauthorized client needs to guess the stream name to access it.

/api/stream/@stream_name[?index=]

GET

Required

@stream_name: string, stream name specified by the stream info

Optional

index: media index in the stream playlist, for jukebox streams only. If the stream is a jukebox and no index is specified, the server will return a m3u file with all jukebox stream media.

Code 200

Binary data of the stream to be played by the client. The stream sends ICY metatags for a webradio type, so the client application, e.g. VLC or MPD will display the current media information using the following pattern:

[Artist - ][Album ][(Year) - ][Title|filename]

Example: Kimiko Ishizaka - Goldberg Variations BWV 988 (2012) - Variatio 2 a 1 Clav.

Code 404

Stream or index not found

Code 500

Internal Error

For a stream cover to be available to usual media players, we can't use a Oauth2 Bearer token to authenticate the stream, because it's mostly not supported, and because it's way too overkill. Instead, all Taliesin stream address use a randomly generated alphanumeric identifier of 32 characters long, so an unauthorized client needs to guess the stream name to access it.

/api/stream/@stream_name/cover[?index=][&base64]

GET

Required

@stream_name: string, stream name specified by the stream info

Optional

index: media index in the stream playlist, for playlist streams only. base64: return cover in base64 encoding

Code 200

Binary data or base64 encoding of the stream cover.

Code 404

Stream or index not found

Code 500

Internal Error

/api/stream/@stream_name/manage

PUT

Required

@stream_name: string, stream name specified by the stream info

{
  "command": string, name of the command, mandatory
  "parameters": JSON object or array to specify the parameters when needed
}

The commands available are:

• stop: stop the current stream and remove it from the stream list
• replay: replay the current media from the beginning, for webradio only
• skip: skip current media and immediatly play next media, for webradio only
• history: Return the list of media previously played in this stream, for webradio only
• info: Return the stream information
• now: Return the current media information, for webradio only
• next: Return the next media information, for webradio only
• list: Return the list of all media available in this stream
• append_list: Append a list of media in the current stream media list, parameter format is [{data_source: string, path: string, recursive: boolean},{category: string, category_value: string, sub_category: string, sub_category_value: string}]
• has_media: Return a list of media that matches the specified pattern, parameter format is {offset: number, limit: number, media: [{data_source: string, path: string, recursive: boolean},{data_source: string, category: string, category_value: string, subcategory: string, subcategory_value: string}]}
• remove_media: Remove media in the current stream media list, parameter format is {index: integer} or {media: [{data_source: string, path: string, recursive: boolean},{data_source: string, category: string, category_value: string, subcategory: string, subcategory_value: string}]}
• move: Move a media in the stream list to a different index, parameter format is {index: integer, target: integer}
• attach_playlist: Attach the stream to a stored playlist, parameter format is {name: string}
• reload: Reload the stream media list with the attached stored playlist if one is specified

Code 200

Returned data if available, otherwise empty.

The returned data available are:

• Command history, result is in reverse chronological order

[
  {
    "datestamp": string, epoch value when the media was played
    "media": {
      "data_source": string,
      "name": string
      "path": string
      "type": string
      "tags": {
        "key": "value"
      }
    }
  }
]

• Command info

{
  "name": string, name of the stream, a 32 characters random sequence generated
  "display_name": string, display name of the stream
  "webradio": boolean true if the stream is a webradio
	"elements": number of elements in the stream
  "format": string, audio format of the stream, values available are `mp3`, `vorbis` or `flac`
  "stereo": boolean, true if the audio stream is stereo
  "sample_rate": integer, sample rate of the audio stream
  "bitrate": integer, bitrate of the audio stream
  "nb_client": integer, number of clients currently listening to the stream
  "last_seen": integer, date in epoch format when the stream was used last, for jukebox streams only
  "stored_playlist": string, name of the playlist the stream is based on, optional
	"clients": [ Array of clients
		{
			"ip_address": string, ip address of the client
			"user_agent": string, user agent of the client
		}
	]
}
```javascript

- Command `now`
```javascript
{
  "data_source": string,
  "name": string
  "path": string
  "type": string
  "tags": {
    "key": "value"
  }
}

• Command next

{
  "data_source": string,
  "name": string
  "path": string
  "type": string
  "tags": {
    "key": "value"
  }
}

• Command list

[
  {
    "data_source": string,
    "name": string
    "path": string
    "type": string
    "tags": {
      "key": "value"
    }
  }
]

• Command has_media

[
  {
    "datestamp": string, epoch value when the media was played
    "media": {
      "data_source": string,
      "name": string
      "path": string
      "type": string
      "tags": {
        "key": "value"
      }
    }
  }
]

Code 404

Stream not found

Code 403

User can't manage this stream

Code 500

Internal Error

If you feel like it, you can also manage a stream via a Websocket. The commands are exactly the same than with the REST API management, but must be sent to the server as a serialized JSON. The messages sent by the server to the client have the following format:

{
  "command": string, command name
  "result": result of the command
}

Since it seems that most Web browser can't use Oauth2 Bearer tokens in headers to authentify a websocket, the client needs to send the bearer token right after the connection is established to allow communication. The message must have the following format:

{
  "command": "authorization",
  "token": string, token value
}

Then, the token will be verified and if the token is valid, the client and the server will be able to send each other messages via the websocket.

The server will automatically send a result for the now command every time a new media is played. Also, the server will send a result for the stop command if the stream is stopped.

The other commands are the same as the REST API commands.

/api/stream/@stream_name/ws

GET

Required

@stream_name: string, stream name specified by the stream info

{
  "command": string, name of the command, mandatory
  "parameters": JSON object or array to specify the parameters when needed
}

The commands available are:

• stop: stop the current stream and remove it from the stream list
• replay: replay the current media from the beginning, for webradio only
• skip: skip current media and immediatly play next media, for webradio only
• history: Return the list of media previously played in this stream, for webradio only
• info: Return the stream information
• now: Return the current media information, for webradio only
• next: Return the next media information, for webradio only
• list: Return the list of all media available in this stream
• append_list: Append a list of media in the current stream media list, parameter format is [{data_source: string, path: string}]
• has_media: Return a list of media that matches the specified pattern, parameter format is {offset: number, limit: number, media: [{data_source: string, path: string, recursive: boolean},{data_source: string, category: string, category_value: string, subcategory: string, subcategory_value: string}]}
• remove_media: Remove media in the current stream media list, parameter format is {index: integer} or {media: [{data_source: string, path: string, recursive: boolean},{data_source: string, category: string, category_value: string, subcategory: string, subcategory_value: string}]}
• move: Move a media in the stream list to a different index, parameter format is {index: integer, target: integer}
• attach_playlist: Attach the stream to a stored playlist, parameter format is {name: string}
• reload: Reload the stream media list with the attached stored playlist if one is specified

Code 200

Returned data if available, otherwise empty.

The returned data available are:

• Command history, result is in reverse chronological order

{
  "command": "history"
  "result": [
    {
      "datestamp": string, epoch value when the media was played
      "media": {
        "data_source": string,
        "name": string
        "path": string
        "type": string
        "tags": {
          "key": "value"
        }
      }
    }
  ]
}

• Command info

{
  "command": "info"
  "result":
	{
		"name": string, name of the stream, a 32 characters random sequence generated
		"display_name": string, display name of the stream
		"webradio": boolean true if the stream is a webradio
		"elements": number of elements in the stream
		"format": string, audio format of the stream, values available are `mp3`, `vorbis` or `flac`
		"stereo": boolean, true if the audio stream is stereo
		"sample_rate": integer, sample rate of the audio stream
		"bitrate": integer, bitrate of the audio stream
		"nb_client": integer, number of clients currently listening to the stream
		"last_seen": integer, date in epoch format when the stream was used last, for jukebox streams only
		"stored_playlist": string, name of the playlist the stream is based on, optional
		"clients": [ Array of clients
			{
				"ip_address": string, ip address of the client
				"user_agent": string, user agent of the client
			}
		]
	}
}
```javascript

- Command `now`
```javascript
{
  "command": "now"
  "result": {
    "data_source": string,
    "name": string
    "path": string
    "type": string
    "tags": {
      "key": "value"
    }
  }
}

• Command next

{
  "command": "next"
  "result": {
    "data_source": string,
    "name": string
    "path": string
    "type": string
    "tags": {
      "key": "value"
    }
  }
}

• Command list

{
  "command": "next"
  "result": [
    {
      "data_source": string,
      "name": string
      "path": string
      "type": string
      "tags": {
        "key": "value"
      }
    }
  ]
}

• Command has_media

[
  {
    "datestamp": string, epoch value when the media was played
    "media": {
      "data_source": string,
      "name": string
      "path": string
      "type": string
      "tags": {
        "key": "value"
      }
    }
  }
]

Code 404

Stream not found

Code 403

User can't manage this stream

Code 500

Internal Error

/api/users/

GET

Code 200

Content

[
  {
    "username": string, max 128 characters
  }
]

Code 401

User does not have scope taliesin_admin available.

Code 500

Internal Error

/api/config/@type

GET

Required

@type: string, type to get the configuration. Values available are: "audio_file_extension", "video_file_extension", "subtitle_file_extension", "image_file_extension", "cover_file_pattern", "external_player"

Code 200

Content

[
  // Array of string values
]

Note: The type "external_player" will return an array of string that need to be parsed as JSON values themselves

Code 500

Internal Error

/api/config/@type

PUT

Required

@type: string, type to get the configuration. Values available are: "audio_file_extension", "video_file_extension", "subtitle_file_extension", "image_file_extension", "cover_file_pattern", "external_player"

Code 200

Content

[
  // Array of string values
]

Notes:

• The type "external_player" should contain a JSON object stringified.
• The order of elements for the type "cover_file_pattern" will determine the pattern.

Code 401

User does not have scope taliesin_admin available.

Code 500

Internal Error

/config

GET

Code 200

Content

[
  "api_prefix": string, prefix for the API URLs, default is "api"
	"oauth_scope_user": string, scope value required for a normal user, default is "taliesin",
	"oauth_scope_admin": string, scope value required for an administrator, default is "taliesin_admin",
	"default_stream_format": string, default value for webradio stream format if none is specified, values available are "mp3", "vorbis", "flac"
	"default_stream_channels": number, default channels available if none specified, values available are 1 (mono) and 2 (stereo)
	"default_stream_sample_rate": number, default sample rate if none specified, values available are 8000, 11025, 22050, 32000, 44100 or 48000
	"default_stream_bitrate": number, default bitrate if none is specified, values available are 32000, 96000, 128000, 192000, 256000 or 320000
]

Note: Authentication isn't required for this API

Code 500

Internal Error