diff --git a/config.sample b/config.sample index d7788b9..897cdd7 100644 --- a/config.sample +++ b/config.sample @@ -1,89 +1,89 @@ -[base] -; A database URI. See the 'schema' folder for schema creation scripts. Note that -; you don't have to run these scripts yourself. -; Default: sqlite:////tmp/supysonic/supysonic.db -;database_uri = sqlite:////var/supysonic/supysonic.db -;database_uri = mysql://supysonic:supysonic@localhost/supysonic -;database_uri = postgres://supysonic:supysonic@localhost/supysonic - -; Optional, restrict scanner to these extensions. Default: none -;scanner_extensions = mp3 ogg - -; Should the scanner follow symbolic links? Default: no -follow_symlinks = no - -[webapp] -; Optional cache directory. Default: /tmp/supysonic -cache_dir = /var/supysonic/cache - -; Main cache max size in MB. Default: 512 -cache_size = 512 - -; Transcode cache max size in MB. Default: 1024 (1GB) -transcode_cache_size = 1024 - -; Optional rotating log file. Default: none -log_file = /var/supysonic/supysonic.log - -; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. -; Default: WARNING -log_level = WARNING - -; Enable the Subsonic REST API. You'll most likely want to keep this on, here -; for testing purposes. Default: on -;mount_api = on - -; Enable the administrative web interface. Default: on -;mount_webui = on - -; Space separated list of prefixes that should be ignored on index endpoints -; Default: El La Le Las Les Los The -index_ignored_prefixes = El La Le Las Les Los The - -[daemon] -; Socket file the daemon will listen on for incoming management commands -; Default: /tmp/supysonic/supysonic.sock -socket = /var/run/supysonic.sock - -; Defines if the file watcher should be started. Default: yes -run_watcher = yes - -; Delay in seconds before triggering scanning operation after a change have been -; detected. -; This prevents running too many scans when multiple changes are detected for a -; single file over a short time span. Default: 5 -wait_delay = 5 - -; Command used by the jukebox -jukebox_command = mplayer -ss %offset %path - -; Optional rotating log file for the scanner daemon. Logs to stderr if empty -log_file = /var/supysonic/supysonic-daemon.log -log_level = INFO - -[lastfm] -; API and secret key to enable scrobbling. http://www.last.fm/api/accounts -; Defaults: none -;api_key = -;secret = - -[transcoding] -; Programs used to convert from one format/bitrate to another. Defaults: none -transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - -transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - -decoder_mp3 = mpg123 --quiet -w - %srcpath -decoder_ogg = oggdec -o %srcpath -decoder_flac = flac -d -c -s %srcpath -encoder_mp3 = lame --quiet -b %outrate - - -encoder_ogg = oggenc2 -Q -M %outrate - - -; Default format, used when a client requests a bitrate lower than the original -; file and no specific format -default_transcode_target = mp3 - -[mimetypes] -; Extension to mimetype mappings in case your system has some trouble guessing -; Default: none -;mp3 = audio/mpeg -;ogg = audio/vorbis - +[base] +; A database URI. See the 'schema' folder for schema creation scripts. Note that +; you don't have to run these scripts yourself. +; Default: sqlite:////tmp/supysonic/supysonic.db +;database_uri = sqlite:////var/supysonic/supysonic.db +;database_uri = mysql://supysonic:supysonic@localhost/supysonic +;database_uri = postgres://supysonic:supysonic@localhost/supysonic + +; Optional, restrict scanner to these extensions. Default: none +;scanner_extensions = mp3 ogg + +; Should the scanner follow symbolic links? Default: no +follow_symlinks = no + +[webapp] +; Optional cache directory. Default: /tmp/supysonic +cache_dir = /var/supysonic/cache + +; Main cache max size in MB. Default: 512 +cache_size = 512 + +; Transcode cache max size in MB. Default: 1024 (1GB) +transcode_cache_size = 1024 + +; Optional rotating log file. Default: none +log_file = /var/supysonic/supysonic.log + +; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. +; Default: WARNING +log_level = WARNING + +; Enable the Subsonic REST API. You'll most likely want to keep this on, here +; for testing purposes. Default: on +;mount_api = on + +; Enable the administrative web interface. Default: on +;mount_webui = on + +; Space separated list of prefixes that should be ignored on index endpoints +; Default: El La Le Las Les Los The +index_ignored_prefixes = El La Le Las Les Los The + +[daemon] +; Socket file the daemon will listen on for incoming management commands +; Default: /tmp/supysonic/supysonic.sock +socket = /var/run/supysonic.sock + +; Defines if the file watcher should be started. Default: yes +run_watcher = yes + +; Delay in seconds before triggering scanning operation after a change have been +; detected. +; This prevents running too many scans when multiple changes are detected for a +; single file over a short time span. Default: 5 +wait_delay = 5 + +; Command used by the jukebox +jukebox_command = mplayer -ss %offset %path + +; Optional rotating log file for the scanner daemon. Logs to stderr if empty +log_file = /var/supysonic/supysonic-daemon.log +log_level = INFO + +[lastfm] +; API and secret key to enable scrobbling. http://www.last.fm/api/accounts +; Defaults: none +;api_key = +;secret = + +[transcoding] +; Programs used to convert from one format/bitrate to another. Defaults: none +transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - +transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - +decoder_mp3 = mpg123 --quiet -w - %srcpath +decoder_ogg = oggdec -o %srcpath +decoder_flac = flac -d -c -s %srcpath +encoder_mp3 = lame --quiet -b %outrate - - +encoder_ogg = oggenc2 -Q -M %outrate - + +; Default format, used when a client requests a bitrate lower than the original +; file and no specific format +default_transcode_target = mp3 + +[mimetypes] +; Extension to mimetype mappings in case your system has some trouble guessing +; Default: none +;mp3 = audio/mpeg +;ogg = audio/vorbis + diff --git a/docs/api.rst b/docs/api.rst index 60d5f00..dd3e40e 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,1483 +1,1483 @@ -Subsonic API breakdown -====================== - -This page lists all the API methods and their parameters up to the version -1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features -Supysonic support, plan on supporting, or won't. - -At the moment, the current target API version is 1.10.2. - -The following information was gathered by *diff*-ing various snapshots of the -`Subsonic API page`__. - -__ http://www.subsonic.org/pages/api.jsp - -Methods and parameters listing ------------------------------- - -Statuses explanation: - -* πŸ“…: planned -* βœ”οΈ: done -* ❌: done as not supported -* πŸ”΄: won't be implemented -* ❔: not decided yet - -The version column specifies the API version which added the related method or -parameter. When no version is given, it means the item was introduced prior to -or with version 1.8.0. - -All methods / pseudo-TOC -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. table:: - :widths: 55 30 15 - - =========================== ====== = - Method Vers. - =========================== ====== = - ping_ βœ”οΈ - getLicense_ βœ”οΈ - getMusicFolders_ βœ”οΈ - getIndexes_ βœ”οΈ - getMusicDirectory_ βœ”οΈ - getGenres_ 1.9.0 βœ”οΈ - getArtists_ βœ”οΈ - getArtist_ βœ”οΈ - getAlbum_ βœ”οΈ - getSong_ βœ”οΈ - getVideos_ ❌ - getVideoInfo_ 1.15.0 πŸ”΄ - getArtistInfo_ 1.11.0 πŸ“… - getArtistInfo2_ 1.11.0 πŸ“… - getAlbumInfo_ 1.14.0 πŸ“… - getAlbumInfo2_ 1.14.0 πŸ“… - getSimilarSongs_ 1.11.0 ❔ - getSimilarSongs2_ 1.11.0 ❔ - getTopSongs_ 1.13.0 ❔ - getAlbumList_ βœ”οΈ - getAlbumList2_ βœ”οΈ - getRandomSongs_ βœ”οΈ - getSongsByGenre_ 1.9.0 βœ”οΈ - getNowPlaying_ βœ”οΈ - getStarred_ βœ”οΈ - getStarred2_ βœ”οΈ - :ref:`search ` βœ”οΈ - search2_ βœ”οΈ - search3_ βœ”οΈ - getPlaylists_ βœ”οΈ - getPlaylist_ βœ”οΈ - createPlaylist_ βœ”οΈ - updatePlaylist_ βœ”οΈ - deletePlaylist_ βœ”οΈ - stream_ βœ”οΈ - download_ βœ”οΈ - hls_ 1.9.0 πŸ”΄ - getCaptions_ 1.15.0 πŸ”΄ - getCoverArt_ βœ”οΈ - getLyrics_ βœ”οΈ - getAvatar_ ❌ - star_ βœ”οΈ - unstar_ βœ”οΈ - setRating_ βœ”οΈ - scrobble_ βœ”οΈ - getShares_ ❌ - createShare_ ❌ - updateShare_ ❌ - deleteShare_ ❌ - getPodcasts_ ❔ - getNewestPodcasts_ 1.14.0 ❔ - refreshPodcasts_ 1.9.0 ❔ - createPodcastChannel_ 1.9.0 ❔ - deletePodcastChannel_ 1.9.0 ❔ - deletePodcastEpisode_ 1.9.0 ❔ - downloadPodcastEpisode_ 1.9.0 ❔ - jukeboxControl_ βœ”οΈ - getInternetRadioStations_ 1.9.0 βœ”οΈ - createInternetRadioStation_ 1.16.0 βœ”οΈ - updateInternetRadioStation_ 1.16.0 βœ”οΈ - deleteInternetRadioStation_ 1.16.0 βœ”οΈ - getChatMessages_ βœ”οΈ - addChatMessage_ βœ”οΈ - getUser_ βœ”οΈ - getUsers_ 1.9.0 βœ”οΈ - createUser_ βœ”οΈ - updateUser_ 1.10.2 βœ”οΈ - deleteUser_ βœ”οΈ - changePassword_ βœ”οΈ - getBookmarks_ 1.9.0 ❔ - createBookmark_ 1.9.0 ❔ - deleteBookmark_ 1.9.0 ❔ - getPlayQueue_ 1.12.0 ❔ - savePlayQueue_ 1.12.0 ❔ - getScanStatus_ 1.15.0 βœ”οΈ - startScan_ 1.15.0 βœ”οΈ - =========================== ====== = - -Global -^^^^^^ - -Parameters used for any request - -.. table:: - :widths: 55 30 15 - - ===== ====== = - P. Vers. - ===== ====== = - ``u`` βœ”οΈ - ``p`` βœ”οΈ - ``t`` 1.13.0 πŸ”΄ - ``s`` 1.13.0 πŸ”΄ - ``v`` βœ”οΈ - ``c`` βœ”οΈ - ``f`` βœ”οΈ - ===== ====== = - -Error codes - -.. table:: - :widths: 55 30 15 - - == ====== = - # Vers. - == ====== = - 0 βœ”οΈ - 10 βœ”οΈ - 20 βœ”οΈ - 30 βœ”οΈ - 40 βœ”οΈ - 41 1.15.0 πŸ“… - 50 βœ”οΈ - 60 βœ”οΈ - 70 βœ”οΈ - == ====== = - -System -^^^^^^ - -.. _ping: - -``ping`` - βœ”οΈ - - No parameter - -.. _getLicense: - -``getLicense`` - βœ”οΈ - - No parameter - -Browsing -^^^^^^^^ - -.. _getMusicFolders: - -``getMusicFolders`` - βœ”οΈ - - No parameter - -.. _getIndexes: - -``getIndexes`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - =================== ===== = - Parameter Vers. - =================== ===== = - ``musicFolderId`` βœ”οΈ - ``ifModifiedSince`` βœ”οΈ - =================== ===== = - -.. _getMusicDirectory: - -``getMusicDirectory`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _getGenres: - -``getGenres`` - βœ”οΈ 1.9.0 - - No parameter - -.. _getArtists: - -``getArtists`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``musicFolderId`` 1.14.0 πŸ“… - ================= ====== = - -.. _getArtist: - -``getArtist`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _getAlbum: - -``getAlbum`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _getSong: - -``getSong`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _getVideos: - -``getVideos`` - ❌ - - No parameter - -.. _getVideoInfo: - -``getVideoInfo`` - πŸ”΄ 1.15.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``id`` 1.15.0 πŸ”΄ - ========= ====== = - -.. _getArtistInfo: - -``getArtistInfo`` - πŸ“… 1.11.0 - - .. table:: - :widths: 55 30 15 - - ===================== ====== = - Parameter Vers. - ===================== ====== = - ``id`` 1.11.0 πŸ“… - ``count`` 1.11.0 πŸ“… - ``includeNotPresent`` 1.11.0 πŸ“… - ===================== ====== = - -.. _getArtistInfo2: - -``getArtistInfo2`` - πŸ“… 1.11.0 - - .. table:: - :widths: 55 30 15 - - ===================== ====== = - Parameter Vers. - ===================== ====== = - ``id`` 1.11.0 πŸ“… - ``count`` 1.11.0 πŸ“… - ``includeNotPresent`` 1.11.0 πŸ“… - ===================== ====== = - -.. _getAlbumInfo: - -``getAlbumInfo`` - πŸ“… 1.14.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``id`` 1.14.0 πŸ“… - ========= ====== = - -.. _getAlbumInfo2: - -``getAlbumInfo2`` - πŸ“… 1.14.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``id`` 1.14.0 πŸ“… - ========= ====== = - -.. _getSimilarSongs: - -``getSimilarSongs`` - ❔ 1.11.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``id`` 1.11.0 ❔ - ``count`` 1.11.0 ❔ - ========= ====== = - -.. _getSimilarSongs2: - -``getSimilarSongs2`` - ❔ 1.11.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``id`` 1.11.0 ❔ - ``count`` 1.11.0 ❔ - ========= ====== = - -.. _getTopSongs: - -``getTopSongs`` - ❔ 1.13.0 - - .. table:: - :widths: 55 30 15 - - ========== ====== = - Parameter Vers. - ========== ====== = - ``artist`` 1.13.0 ❔ - ``count`` 1.13.0 ❔ - ========== ====== = - -Album/song lists -^^^^^^^^^^^^^^^^ - -.. _getAlbumList: - -``getAlbumList`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``type`` βœ”οΈ - ``size`` βœ”οΈ - ``offset`` βœ”οΈ - ``fromYear`` βœ”οΈ - ``toYear`` βœ”οΈ - ``genre`` βœ”οΈ - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - - .. versionadded:: 1.10.1 - ``byYear`` and ``byGenre`` were added to ``type`` - -.. _getAlbumList2: - -``getAlbumList2`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``type`` βœ”οΈ - ``size`` βœ”οΈ - ``offset`` βœ”οΈ - ``fromYear`` βœ”οΈ - ``toYear`` βœ”οΈ - ``genre`` βœ”οΈ - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - - .. versionadded:: 1.10.1 - ``byYear`` and ``byGenre`` were added to ``type`` - -.. _getRandomSongs: - -``getRandomSongs`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ===== = - Parameter Vers. - ================= ===== = - ``size`` βœ”οΈ - ``genre`` βœ”οΈ - ``fromYear`` βœ”οΈ - ``toYear`` βœ”οΈ - ``musicFolderId`` βœ”οΈ - ================= ===== = - -.. _getSongsByGenre: - -``getSongsByGenre`` - βœ”οΈ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``genre`` 1.9.0 βœ”οΈ - ``count`` 1.9.0 βœ”οΈ - ``offset`` 1.9.0 βœ”οΈ - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - -.. _getNowPlaying: - -``getNowPlaying`` - βœ”οΈ - - No parameter - -.. _getStarred: - -``getStarred`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - -.. _getStarred2: - -``getStarred2`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - -Searching -^^^^^^^^^ - -.. _search-: - -``search`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============= ===== = - Parameter Vers. - ============= ===== = - ``artist`` βœ”οΈ - ``album`` βœ”οΈ - ``title`` βœ”οΈ - ``any`` βœ”οΈ - ``count`` βœ”οΈ - ``offset`` βœ”οΈ - ``newerThan`` βœ”οΈ - ============= ===== = - -.. _search2: - -``search2`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``query`` βœ”οΈ - ``artistCount`` βœ”οΈ - ``artistOffset`` βœ”οΈ - ``albumCount`` βœ”οΈ - ``albumOffset`` βœ”οΈ - ``songCount`` βœ”οΈ - ``songOffset`` βœ”οΈ - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - -.. _search3: - -``search3`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ================= ====== = - Parameter Vers. - ================= ====== = - ``query`` βœ”οΈ - ``artistCount`` βœ”οΈ - ``artistOffset`` βœ”οΈ - ``albumCount`` βœ”οΈ - ``albumOffset`` βœ”οΈ - ``songCount`` βœ”οΈ - ``songOffset`` βœ”οΈ - ``musicFolderId`` 1.12.0 πŸ“… - ================= ====== = - -Playlists -^^^^^^^^^ - -.. _getPlaylists: - -``getPlaylists`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``username`` βœ”οΈ - ============ ===== = - -.. _getPlaylist: - -``getPlaylist`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _createPlaylist: - -``createPlaylist`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============== ===== = - Parameter Vers. - ============== ===== = - ``playlistId`` βœ”οΈ - ``name`` βœ”οΈ - ``songId`` βœ”οΈ - ============== ===== = - -.. _updatePlaylist: - -``updatePlaylist`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ===================== ===== = - Parameter Vers. - ===================== ===== = - ``playlistId`` βœ”οΈ - ``name`` βœ”οΈ - ``comment`` βœ”οΈ - ``public`` 1.9.0 βœ”οΈ - ``songIdToAdd`` βœ”οΈ - ``songIndexToRemove`` βœ”οΈ - ===================== ===== = - -.. _deletePlaylist: - -``deletePlaylist`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -Media retrieval -^^^^^^^^^^^^^^^ - -.. _stream: - -``stream`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========================= ====== = - Parameter Vers. - ========================= ====== = - ``id`` βœ”οΈ - ``maxBitRate`` βœ”οΈ - ``format`` βœ”οΈ - ``timeOffset`` ❌ - ``size`` ❌ - ``estimateContentLength`` βœ”οΈ - ``converted`` 1.15.0 πŸ”΄ - ========================= ====== = - -.. _download: - -``download`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ========= ===== = - -.. _hls: - -``hls`` - πŸ”΄ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ============== ====== = - Parameter Vers. - ============== ====== = - ``id`` 1.9.0 πŸ”΄ - ``bitRate`` 1.9.0 πŸ”΄ - ``audioTrack`` 1.15.0 πŸ”΄ - ============== ====== = - -.. _getCaptions: - -``getCaptions`` - πŸ”΄ 1.15.0 - - .. table:: - :widths: 55 30 15 - - ========== ====== = - Parameter Vers. - ========== ====== = - ``id`` 1.15.0 πŸ”΄ - ``format`` 1.15.0 πŸ”΄ - ========== ====== = - -.. _getCoverArt: - -``getCoverArt`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` βœ”οΈ - ``size`` βœ”οΈ - ========= ===== = - -.. _getLyrics: - -``getLyrics`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========== ===== = - Parameter Vers. - ========== ===== = - ``artist`` βœ”οΈ - ``title`` βœ”οΈ - ========== ===== = - -.. _getAvatar: - -``getAvatar`` - ❌ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``username`` ❌ - ============ ===== = - -Media annotation -^^^^^^^^^^^^^^^^ - -.. _star: - -``star`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``id`` βœ”οΈ - ``albumId`` βœ”οΈ - ``artistId`` βœ”οΈ - ============ ===== = - -.. _unstar: - -``unstar`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``id`` βœ”οΈ - ``albumId`` βœ”οΈ - ``artistId`` βœ”οΈ - ============ ===== = - -.. _setRating: - -``setRating`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========== ===== = - Parameter Vers. - ========== ===== = - ``id`` βœ”οΈ - ``rating`` βœ”οΈ - ========== ===== = - -.. _scrobble: - -``scrobble`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============== ===== = - Parameter Vers. - ============== ===== = - ``id`` βœ”οΈ - ``time`` 1.9.0 βœ”οΈ - ``submission`` βœ”οΈ - ============== ===== = - -Sharing -^^^^^^^ - -.. _getShares: - -``getShares`` - ❌ - - No parameter - -.. _createShare: - -``createShare`` - ❌ - - .. table:: - :widths: 55 30 15 - - =============== ===== = - Parameter Vers. - =============== ===== = - ``id`` ❌ - ``description`` ❌ - ``expires`` ❌ - =============== ===== = - -.. _updateShare: - -``updateShare`` - ❌ - - .. table:: - :widths: 55 30 15 - - =============== ===== = - Parameter Vers. - =============== ===== = - ``id`` ❌ - ``description`` ❌ - ``expires`` ❌ - =============== ===== = - -.. _deleteShare: - -``deleteShare`` - ❌ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` ❌ - ========= ===== = - -Podcast -^^^^^^^ - -.. _getPodcasts: - -``getPodcasts`` - ❔ - - .. table:: - :widths: 55 30 15 - - =================== ===== = - Parameter Vers. - =================== ===== = - ``includeEpisodes`` 1.9.0 ❔ - ``id`` 1.9.0 ❔ - =================== ===== = - -.. _getNewestPodcasts: - -``getNewestPodcasts`` - ❔ 1.14.0 - - .. table:: - :widths: 55 30 15 - - ========= ====== = - Parameter Vers. - ========= ====== = - ``count`` 1.14.0 ❔ - ========= ====== = - -.. _refreshPodcasts: - -``refreshPodcasts`` - ❔ 1.9.0 - - No parameter - -.. _createPodcastChannel: - -``createPodcastChannel`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``url`` 1.9.0 ❔ - ========= ===== = - -.. _deletePodcastChannel: - -``deletePodcastChannel`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` 1.9.0 ❔ - ========= ===== = - -.. _deletePodcastEpisode: - -``deletePodcastEpisode`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` 1.9.0 ❔ - ========= ===== = - -.. _downloadPodcastEpisode: - -``downloadPodcastEpisode`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``id`` 1.9.0 ❔ - ========= ===== = - -Jukebox -^^^^^^^ - -.. _jukeboxControl: - -``jukeboxControl`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========== ===== = - Parameter Vers. - ========== ===== = - ``action`` βœ”οΈ - ``index`` βœ”οΈ - ``offset`` βœ”οΈ - ``id`` βœ”οΈ - ``gain`` ❌ - ========== ===== = - -Internet radio -^^^^^^^^^^^^^^ - -.. _getInternetRadioStations: - -``getInternetRadioStations`` - ❔ 1.9.0 - - No parameter - -.. _createInternetRadioStation: - -``createInternetRadioStation`` - ❔ 1.16.0 - - .. table:: - :widths: 55 30 15 - - =============== ====== = - Parameter Vers. - =============== ====== = - ``streamUrl`` 1.16.0 ❔ - ``name`` 1.16.0 ❔ - ``homepageUrl`` 1.16.0 ❔ - =============== ====== = - -.. _updateInternetRadioStation: - -``updateInternetRadioStation`` - ❔ 1.16.0 - - .. table:: - :widths: 55 30 15 - - =============== ====== = - Parameter Vers. - =============== ====== = - ``id`` 1.16.0 ❔ - ``streamUrl`` 1.16.0 ❔ - ``name`` 1.16.0 ❔ - ``homepageUrl`` 1.16.0 ❔ - =============== ====== = - -.. _deleteInternetRadioStation: - -``deleteInternetRadioStation`` - ❔ 1.16.0 - - .. table:: - :widths: 55 30 15 - - =============== ====== = - Parameter Vers. - =============== ====== = - ``id`` 1.16.0 ❔ - =============== ====== = - -Chat -^^^^ - -.. _getChatMessages: - -``getChatMessages`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ========= ===== = - Parameter Vers. - ========= ===== = - ``since`` βœ”οΈ - ========= ===== = - -.. _addChatMessage: - -``addChatMessage`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - =========== ===== = - Parameter Vers. - =========== ===== = - ``message`` βœ”οΈ - =========== ===== = - -User management -^^^^^^^^^^^^^^^ - -.. _getUser: - -``getUser`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``username`` βœ”οΈ - ============ ===== = - -.. _getUsers: - -``getUsers`` - βœ”οΈ 1.9.0 - - No parameter - -.. _createUser: - -``createUser`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ======================= ====== = - Parameter Vers. - ======================= ====== = - ``username`` βœ”οΈ - ``password`` βœ”οΈ - ``email`` βœ”οΈ - ``ldapAuthenticated`` - ``adminRole`` βœ”οΈ - ``settingsRole`` - ``streamRole`` - ``jukeboxRole`` βœ”οΈ - ``downloadRole`` - ``uploadRole`` - ``playlistRole`` - ``coverArtRole`` - ``commentRole`` - ``podcastRole`` - ``shareRole`` - ``videoConversionRole`` 1.14.0 - ``musicFolderId`` 1.12.0 πŸ“… - ======================= ====== = - -.. _updateUser: - -``updateUser`` - βœ”οΈ 1.10.2 - - .. table:: - :widths: 55 30 15 - - ======================= ====== = - Parameter Vers. - ======================= ====== = - ``username`` 1.10.2 βœ”οΈ - ``password`` 1.10.2 βœ”οΈ - ``email`` 1.10.2 βœ”οΈ - ``ldapAuthenticated`` 1.10.2 - ``adminRole`` 1.10.2 βœ”οΈ - ``settingsRole`` 1.10.2 - ``streamRole`` 1.10.2 - ``jukeboxRole`` 1.10.2 βœ”οΈ - ``downloadRole`` 1.10.2 - ``uploadRole`` 1.10.2 - ``coverArtRole`` 1.10.2 - ``commentRole`` 1.10.2 - ``podcastRole`` 1.10.2 - ``shareRole`` 1.10.2 - ``videoConversionRole`` 1.14.0 - ``musicFolderId`` 1.12.0 πŸ“… - ``maxBitRate`` 1.13.0 πŸ“… - ======================= ====== = - -.. _deleteUser: - -``deleteUser`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``username`` βœ”οΈ - ============ ===== = - -.. _changePassword: - -``changePassword`` - βœ”οΈ - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``username`` βœ”οΈ - ``password`` βœ”οΈ - ============ ===== = - -Bookmarks -^^^^^^^^^ - -.. _getBookmarks: - -``getBookmarks`` - ❔ 1.9.0 - - No parameter - -.. _createBookmark: - -``createBookmark`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - ============ ===== = - Parameter Vers. - ============ ===== = - ``id`` 1.9.0 ❔ - ``position`` 1.9.0 ❔ - ``comment`` 1.9.0 ❔ - ============ ===== = - -.. _deleteBookmark: - -``deleteBookmark`` - ❔ 1.9.0 - - .. table:: - :widths: 55 30 15 - - =============== ===== = - Parameter Vers. - =============== ===== = - ``id`` 1.9.0 ❔ - =============== ===== = - -.. _getPlayQueue: - -``getPlayQueue`` - ❔ 1.12.0 - - No parameter - -.. _savePlayQueue: - -``savePlayQueue`` - ❔ 1.12.0 - - .. table:: - :widths: 55 30 15 - - ============ ====== = - Parameter Vers. - ============ ====== = - ``id`` 1.12.0 ❔ - ``current`` 1.12.0 ❔ - ``position`` 1.12.0 ❔ - ============ ====== = - -Library scanning -^^^^^^^^^^^^^^^^ - -.. _getScanStatus: - -``getScanStatus`` - βœ”οΈ 1.15.0 - - No parameter - -.. _startScan: - -``startScan`` - βœ”οΈ 1.15.0 - - No parameter - -Changes by version ------------------- - -Version 1.9.0 -^^^^^^^^^^^^^ - -Added methods: - -* getGenres_ -* getSongsByGenre_ -* hls_ -* refreshPodcasts_ -* createPodcastChannel_ -* deletePodcastChannel_ -* deletePodcastEpisode_ -* downloadPodcastEpisode_ -* getInternetRadioStations_ -* getUsers_ -* getBookmarks_ -* createBookmark_ -* deleteBookmark_ - -Added method parameters: - -* updatePlaylist_ - - * ``public`` - -* scrobble_ - - * ``time`` - -* getPodcasts_ - - * ``includeEpisodes`` - * ``id`` - -Version 1.10.1 -^^^^^^^^^^^^^^ - -Added method parameters: - -* getAlbumList_ - - * ``fromYear`` - * ``toYear`` - * ``genre`` - -* getAlbumList2_ - - * ``fromYear`` - * ``toYear`` - * ``genre`` - -Version 1.10.2 -^^^^^^^^^^^^^^ - -Added methods: - -* updateUser_ - -Version 1.11.0 -^^^^^^^^^^^^^^ - -Added methods: - -* getArtistInfo_ -* getArtistInfo2_ -* getSimilarSongs_ -* getSimilarSongs2_ - -Version 1.12.0 -^^^^^^^^^^^^^^ - -Added methods: - -* getPlayQueue_ -* savePlayQueue_ - -Added method parameters: - -* getAlbumList_ - - * ``musicFolderId`` - -* getAlbumList2_ - - * ``musicFolderId`` - -* getSongsByGenre_ - - * ``musicFolderId`` - -* getStarred_ - - * ``musicFolderId`` - -* getStarred2_ - - * ``musicFolderId`` - -* search2_ - - * ``musicFolderId`` - -* search3_ - - * ``musicFolderId`` - -* createUser_ - - * ``musicFolderId`` - -* updateUser_ - - * ``musicFolderId`` - -Version 1.13.0 -^^^^^^^^^^^^^^ - -Added global parameters: - -* ``t`` -* ``s`` - -Added methods: - -* getTopSongs_ - -Added method parameters: - -* updateUser_ - - * ``maxBitRate`` - -Version 1.14.0 -^^^^^^^^^^^^^^ - -Added methods: - -* getAlbumInfo_ -* getAlbumInfo2_ -* getNewestPodcasts_ - -Added method parameters: - -* getArtists_ - - * ``musicFolderId`` - -* createUser_ - - * ``videoConversionRole`` - -* updateUser_ - - * ``videoConversionRole`` - -Version 1.15.0 -^^^^^^^^^^^^^^ - -Added error code ``41`` - -Added methods: - -* getVideoInfo_ -* getCaptions_ -* getScanStatus_ -* startScan_ - -Added method parameters: - -* stream_ - - * ``converted`` - -* hls_ - - * ``audioTrack`` - -Version 1.16.0 -^^^^^^^^^^^^^^ - -Added methods: - -* createInternetRadioStation_ -* updateInternetRadioStation_ -* deleteInternetRadioStation_ +Subsonic API breakdown +====================== + +This page lists all the API methods and their parameters up to the version +1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features +Supysonic support, plan on supporting, or won't. + +At the moment, the current target API version is 1.10.2. + +The following information was gathered by *diff*-ing various snapshots of the +`Subsonic API page`__. + +__ http://www.subsonic.org/pages/api.jsp + +Methods and parameters listing +------------------------------ + +Statuses explanation: + +* πŸ“…: planned +* βœ”οΈ: done +* ❌: done as not supported +* πŸ”΄: won't be implemented +* ❔: not decided yet + +The version column specifies the API version which added the related method or +parameter. When no version is given, it means the item was introduced prior to +or with version 1.8.0. + +All methods / pseudo-TOC +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. table:: + :widths: 55 30 15 + + =========================== ====== = + Method Vers. + =========================== ====== = + ping_ βœ”οΈ + getLicense_ βœ”οΈ + getMusicFolders_ βœ”οΈ + getIndexes_ βœ”οΈ + getMusicDirectory_ βœ”οΈ + getGenres_ 1.9.0 βœ”οΈ + getArtists_ βœ”οΈ + getArtist_ βœ”οΈ + getAlbum_ βœ”οΈ + getSong_ βœ”οΈ + getVideos_ ❌ + getVideoInfo_ 1.15.0 πŸ”΄ + getArtistInfo_ 1.11.0 πŸ“… + getArtistInfo2_ 1.11.0 πŸ“… + getAlbumInfo_ 1.14.0 πŸ“… + getAlbumInfo2_ 1.14.0 πŸ“… + getSimilarSongs_ 1.11.0 ❔ + getSimilarSongs2_ 1.11.0 ❔ + getTopSongs_ 1.13.0 ❔ + getAlbumList_ βœ”οΈ + getAlbumList2_ βœ”οΈ + getRandomSongs_ βœ”οΈ + getSongsByGenre_ 1.9.0 βœ”οΈ + getNowPlaying_ βœ”οΈ + getStarred_ βœ”οΈ + getStarred2_ βœ”οΈ + :ref:`search ` βœ”οΈ + search2_ βœ”οΈ + search3_ βœ”οΈ + getPlaylists_ βœ”οΈ + getPlaylist_ βœ”οΈ + createPlaylist_ βœ”οΈ + updatePlaylist_ βœ”οΈ + deletePlaylist_ βœ”οΈ + stream_ βœ”οΈ + download_ βœ”οΈ + hls_ 1.9.0 πŸ”΄ + getCaptions_ 1.15.0 πŸ”΄ + getCoverArt_ βœ”οΈ + getLyrics_ βœ”οΈ + getAvatar_ ❌ + star_ βœ”οΈ + unstar_ βœ”οΈ + setRating_ βœ”οΈ + scrobble_ βœ”οΈ + getShares_ ❌ + createShare_ ❌ + updateShare_ ❌ + deleteShare_ ❌ + getPodcasts_ ❔ + getNewestPodcasts_ 1.14.0 ❔ + refreshPodcasts_ 1.9.0 ❔ + createPodcastChannel_ 1.9.0 ❔ + deletePodcastChannel_ 1.9.0 ❔ + deletePodcastEpisode_ 1.9.0 ❔ + downloadPodcastEpisode_ 1.9.0 ❔ + jukeboxControl_ βœ”οΈ + getInternetRadioStations_ 1.9.0 βœ”οΈ + createInternetRadioStation_ 1.16.0 βœ”οΈ + updateInternetRadioStation_ 1.16.0 βœ”οΈ + deleteInternetRadioStation_ 1.16.0 βœ”οΈ + getChatMessages_ βœ”οΈ + addChatMessage_ βœ”οΈ + getUser_ βœ”οΈ + getUsers_ 1.9.0 βœ”οΈ + createUser_ βœ”οΈ + updateUser_ 1.10.2 βœ”οΈ + deleteUser_ βœ”οΈ + changePassword_ βœ”οΈ + getBookmarks_ 1.9.0 ❔ + createBookmark_ 1.9.0 ❔ + deleteBookmark_ 1.9.0 ❔ + getPlayQueue_ 1.12.0 ❔ + savePlayQueue_ 1.12.0 ❔ + getScanStatus_ 1.15.0 βœ”οΈ + startScan_ 1.15.0 βœ”οΈ + =========================== ====== = + +Global +^^^^^^ + +Parameters used for any request + +.. table:: + :widths: 55 30 15 + + ===== ====== = + P. Vers. + ===== ====== = + ``u`` βœ”οΈ + ``p`` βœ”οΈ + ``t`` 1.13.0 πŸ”΄ + ``s`` 1.13.0 πŸ”΄ + ``v`` βœ”οΈ + ``c`` βœ”οΈ + ``f`` βœ”οΈ + ===== ====== = + +Error codes + +.. table:: + :widths: 55 30 15 + + == ====== = + # Vers. + == ====== = + 0 βœ”οΈ + 10 βœ”οΈ + 20 βœ”οΈ + 30 βœ”οΈ + 40 βœ”οΈ + 41 1.15.0 πŸ“… + 50 βœ”οΈ + 60 βœ”οΈ + 70 βœ”οΈ + == ====== = + +System +^^^^^^ + +.. _ping: + +``ping`` + βœ”οΈ + + No parameter + +.. _getLicense: + +``getLicense`` + βœ”οΈ + + No parameter + +Browsing +^^^^^^^^ + +.. _getMusicFolders: + +``getMusicFolders`` + βœ”οΈ + + No parameter + +.. _getIndexes: + +``getIndexes`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + =================== ===== = + Parameter Vers. + =================== ===== = + ``musicFolderId`` βœ”οΈ + ``ifModifiedSince`` βœ”οΈ + =================== ===== = + +.. _getMusicDirectory: + +``getMusicDirectory`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getGenres: + +``getGenres`` + βœ”οΈ 1.9.0 + + No parameter + +.. _getArtists: + +``getArtists`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.14.0 πŸ“… + ================= ====== = + +.. _getArtist: + +``getArtist`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getAlbum: + +``getAlbum`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getSong: + +``getSong`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getVideos: + +``getVideos`` + ❌ + + No parameter + +.. _getVideoInfo: + +``getVideoInfo`` + πŸ”΄ 1.15.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.15.0 πŸ”΄ + ========= ====== = + +.. _getArtistInfo: + +``getArtistInfo`` + πŸ“… 1.11.0 + + .. table:: + :widths: 55 30 15 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getArtistInfo2: + +``getArtistInfo2`` + πŸ“… 1.11.0 + + .. table:: + :widths: 55 30 15 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getAlbumInfo: + +``getAlbumInfo`` + πŸ“… 1.14.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getAlbumInfo2: + +``getAlbumInfo2`` + πŸ“… 1.14.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getSimilarSongs: + +``getSimilarSongs`` + ❔ 1.11.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getSimilarSongs2: + +``getSimilarSongs2`` + ❔ 1.11.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getTopSongs: + +``getTopSongs`` + ❔ 1.13.0 + + .. table:: + :widths: 55 30 15 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``artist`` 1.13.0 ❔ + ``count`` 1.13.0 ❔ + ========== ====== = + +Album/song lists +^^^^^^^^^^^^^^^^ + +.. _getAlbumList: + +``getAlbumList`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``type`` βœ”οΈ + ``size`` βœ”οΈ + ``offset`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``genre`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + + .. versionadded:: 1.10.1 + ``byYear`` and ``byGenre`` were added to ``type`` + +.. _getAlbumList2: + +``getAlbumList2`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``type`` βœ”οΈ + ``size`` βœ”οΈ + ``offset`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``genre`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + + .. versionadded:: 1.10.1 + ``byYear`` and ``byGenre`` were added to ``type`` + +.. _getRandomSongs: + +``getRandomSongs`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ===== = + Parameter Vers. + ================= ===== = + ``size`` βœ”οΈ + ``genre`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``musicFolderId`` βœ”οΈ + ================= ===== = + +.. _getSongsByGenre: + +``getSongsByGenre`` + βœ”οΈ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``genre`` 1.9.0 βœ”οΈ + ``count`` 1.9.0 βœ”οΈ + ``offset`` 1.9.0 βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getNowPlaying: + +``getNowPlaying`` + βœ”οΈ + + No parameter + +.. _getStarred: + +``getStarred`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getStarred2: + +``getStarred2`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Searching +^^^^^^^^^ + +.. _search-: + +``search`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============= ===== = + Parameter Vers. + ============= ===== = + ``artist`` βœ”οΈ + ``album`` βœ”οΈ + ``title`` βœ”οΈ + ``any`` βœ”οΈ + ``count`` βœ”οΈ + ``offset`` βœ”οΈ + ``newerThan`` βœ”οΈ + ============= ===== = + +.. _search2: + +``search2`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _search3: + +``search3`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Playlists +^^^^^^^^^ + +.. _getPlaylists: + +``getPlaylists`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getPlaylist: + +``getPlaylist`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _createPlaylist: + +``createPlaylist`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============== ===== = + Parameter Vers. + ============== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``songId`` βœ”οΈ + ============== ===== = + +.. _updatePlaylist: + +``updatePlaylist`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ===================== ===== = + Parameter Vers. + ===================== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``comment`` βœ”οΈ + ``public`` 1.9.0 βœ”οΈ + ``songIdToAdd`` βœ”οΈ + ``songIndexToRemove`` βœ”οΈ + ===================== ===== = + +.. _deletePlaylist: + +``deletePlaylist`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +Media retrieval +^^^^^^^^^^^^^^^ + +.. _stream: + +``stream`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========================= ====== = + Parameter Vers. + ========================= ====== = + ``id`` βœ”οΈ + ``maxBitRate`` βœ”οΈ + ``format`` βœ”οΈ + ``timeOffset`` ❌ + ``size`` ❌ + ``estimateContentLength`` βœ”οΈ + ``converted`` 1.15.0 πŸ”΄ + ========================= ====== = + +.. _download: + +``download`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _hls: + +``hls`` + πŸ”΄ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ============== ====== = + Parameter Vers. + ============== ====== = + ``id`` 1.9.0 πŸ”΄ + ``bitRate`` 1.9.0 πŸ”΄ + ``audioTrack`` 1.15.0 πŸ”΄ + ============== ====== = + +.. _getCaptions: + +``getCaptions`` + πŸ”΄ 1.15.0 + + .. table:: + :widths: 55 30 15 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``id`` 1.15.0 πŸ”΄ + ``format`` 1.15.0 πŸ”΄ + ========== ====== = + +.. _getCoverArt: + +``getCoverArt`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ``size`` βœ”οΈ + ========= ===== = + +.. _getLyrics: + +``getLyrics`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========== ===== = + Parameter Vers. + ========== ===== = + ``artist`` βœ”οΈ + ``title`` βœ”οΈ + ========== ===== = + +.. _getAvatar: + +``getAvatar`` + ❌ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` ❌ + ============ ===== = + +Media annotation +^^^^^^^^^^^^^^^^ + +.. _star: + +``star`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _unstar: + +``unstar`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _setRating: + +``setRating`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========== ===== = + Parameter Vers. + ========== ===== = + ``id`` βœ”οΈ + ``rating`` βœ”οΈ + ========== ===== = + +.. _scrobble: + +``scrobble`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============== ===== = + Parameter Vers. + ============== ===== = + ``id`` βœ”οΈ + ``time`` 1.9.0 βœ”οΈ + ``submission`` βœ”οΈ + ============== ===== = + +Sharing +^^^^^^^ + +.. _getShares: + +``getShares`` + ❌ + + No parameter + +.. _createShare: + +``createShare`` + ❌ + + .. table:: + :widths: 55 30 15 + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _updateShare: + +``updateShare`` + ❌ + + .. table:: + :widths: 55 30 15 + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _deleteShare: + +``deleteShare`` + ❌ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` ❌ + ========= ===== = + +Podcast +^^^^^^^ + +.. _getPodcasts: + +``getPodcasts`` + ❔ + + .. table:: + :widths: 55 30 15 + + =================== ===== = + Parameter Vers. + =================== ===== = + ``includeEpisodes`` 1.9.0 ❔ + ``id`` 1.9.0 ❔ + =================== ===== = + +.. _getNewestPodcasts: + +``getNewestPodcasts`` + ❔ 1.14.0 + + .. table:: + :widths: 55 30 15 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``count`` 1.14.0 ❔ + ========= ====== = + +.. _refreshPodcasts: + +``refreshPodcasts`` + ❔ 1.9.0 + + No parameter + +.. _createPodcastChannel: + +``createPodcastChannel`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``url`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastChannel: + +``deletePodcastChannel`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastEpisode: + +``deletePodcastEpisode`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _downloadPodcastEpisode: + +``downloadPodcastEpisode`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +Jukebox +^^^^^^^ + +.. _jukeboxControl: + +``jukeboxControl`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========== ===== = + Parameter Vers. + ========== ===== = + ``action`` βœ”οΈ + ``index`` βœ”οΈ + ``offset`` βœ”οΈ + ``id`` βœ”οΈ + ``gain`` ❌ + ========== ===== = + +Internet radio +^^^^^^^^^^^^^^ + +.. _getInternetRadioStations: + +``getInternetRadioStations`` + ❔ 1.9.0 + + No parameter + +.. _createInternetRadioStation: + +``createInternetRadioStation`` + ❔ 1.16.0 + + .. table:: + :widths: 55 30 15 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _updateInternetRadioStation: + +``updateInternetRadioStation`` + ❔ 1.16.0 + + .. table:: + :widths: 55 30 15 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _deleteInternetRadioStation: + +``deleteInternetRadioStation`` + ❔ 1.16.0 + + .. table:: + :widths: 55 30 15 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + =============== ====== = + +Chat +^^^^ + +.. _getChatMessages: + +``getChatMessages`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``since`` βœ”οΈ + ========= ===== = + +.. _addChatMessage: + +``addChatMessage`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + =========== ===== = + Parameter Vers. + =========== ===== = + ``message`` βœ”οΈ + =========== ===== = + +User management +^^^^^^^^^^^^^^^ + +.. _getUser: + +``getUser`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getUsers: + +``getUsers`` + βœ”οΈ 1.9.0 + + No parameter + +.. _createUser: + +``createUser`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ======================= ====== = + Parameter Vers. + ======================= ====== = + ``username`` βœ”οΈ + ``password`` βœ”οΈ + ``email`` βœ”οΈ + ``ldapAuthenticated`` + ``adminRole`` βœ”οΈ + ``settingsRole`` + ``streamRole`` + ``jukeboxRole`` βœ”οΈ + ``downloadRole`` + ``uploadRole`` + ``playlistRole`` + ``coverArtRole`` + ``commentRole`` + ``podcastRole`` + ``shareRole`` + ``videoConversionRole`` 1.14.0 + ``musicFolderId`` 1.12.0 πŸ“… + ======================= ====== = + +.. _updateUser: + +``updateUser`` + βœ”οΈ 1.10.2 + + .. table:: + :widths: 55 30 15 + + ======================= ====== = + Parameter Vers. + ======================= ====== = + ``username`` 1.10.2 βœ”οΈ + ``password`` 1.10.2 βœ”οΈ + ``email`` 1.10.2 βœ”οΈ + ``ldapAuthenticated`` 1.10.2 + ``adminRole`` 1.10.2 βœ”οΈ + ``settingsRole`` 1.10.2 + ``streamRole`` 1.10.2 + ``jukeboxRole`` 1.10.2 βœ”οΈ + ``downloadRole`` 1.10.2 + ``uploadRole`` 1.10.2 + ``coverArtRole`` 1.10.2 + ``commentRole`` 1.10.2 + ``podcastRole`` 1.10.2 + ``shareRole`` 1.10.2 + ``videoConversionRole`` 1.14.0 + ``musicFolderId`` 1.12.0 πŸ“… + ``maxBitRate`` 1.13.0 πŸ“… + ======================= ====== = + +.. _deleteUser: + +``deleteUser`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _changePassword: + +``changePassword`` + βœ”οΈ + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ``password`` βœ”οΈ + ============ ===== = + +Bookmarks +^^^^^^^^^ + +.. _getBookmarks: + +``getBookmarks`` + ❔ 1.9.0 + + No parameter + +.. _createBookmark: + +``createBookmark`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` 1.9.0 ❔ + ``position`` 1.9.0 ❔ + ``comment`` 1.9.0 ❔ + ============ ===== = + +.. _deleteBookmark: + +``deleteBookmark`` + ❔ 1.9.0 + + .. table:: + :widths: 55 30 15 + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` 1.9.0 ❔ + =============== ===== = + +.. _getPlayQueue: + +``getPlayQueue`` + ❔ 1.12.0 + + No parameter + +.. _savePlayQueue: + +``savePlayQueue`` + ❔ 1.12.0 + + .. table:: + :widths: 55 30 15 + + ============ ====== = + Parameter Vers. + ============ ====== = + ``id`` 1.12.0 ❔ + ``current`` 1.12.0 ❔ + ``position`` 1.12.0 ❔ + ============ ====== = + +Library scanning +^^^^^^^^^^^^^^^^ + +.. _getScanStatus: + +``getScanStatus`` + βœ”οΈ 1.15.0 + + No parameter + +.. _startScan: + +``startScan`` + βœ”οΈ 1.15.0 + + No parameter + +Changes by version +------------------ + +Version 1.9.0 +^^^^^^^^^^^^^ + +Added methods: + +* getGenres_ +* getSongsByGenre_ +* hls_ +* refreshPodcasts_ +* createPodcastChannel_ +* deletePodcastChannel_ +* deletePodcastEpisode_ +* downloadPodcastEpisode_ +* getInternetRadioStations_ +* getUsers_ +* getBookmarks_ +* createBookmark_ +* deleteBookmark_ + +Added method parameters: + +* updatePlaylist_ + + * ``public`` + +* scrobble_ + + * ``time`` + +* getPodcasts_ + + * ``includeEpisodes`` + * ``id`` + +Version 1.10.1 +^^^^^^^^^^^^^^ + +Added method parameters: + +* getAlbumList_ + + * ``fromYear`` + * ``toYear`` + * ``genre`` + +* getAlbumList2_ + + * ``fromYear`` + * ``toYear`` + * ``genre`` + +Version 1.10.2 +^^^^^^^^^^^^^^ + +Added methods: + +* updateUser_ + +Version 1.11.0 +^^^^^^^^^^^^^^ + +Added methods: + +* getArtistInfo_ +* getArtistInfo2_ +* getSimilarSongs_ +* getSimilarSongs2_ + +Version 1.12.0 +^^^^^^^^^^^^^^ + +Added methods: + +* getPlayQueue_ +* savePlayQueue_ + +Added method parameters: + +* getAlbumList_ + + * ``musicFolderId`` + +* getAlbumList2_ + + * ``musicFolderId`` + +* getSongsByGenre_ + + * ``musicFolderId`` + +* getStarred_ + + * ``musicFolderId`` + +* getStarred2_ + + * ``musicFolderId`` + +* search2_ + + * ``musicFolderId`` + +* search3_ + + * ``musicFolderId`` + +* createUser_ + + * ``musicFolderId`` + +* updateUser_ + + * ``musicFolderId`` + +Version 1.13.0 +^^^^^^^^^^^^^^ + +Added global parameters: + +* ``t`` +* ``s`` + +Added methods: + +* getTopSongs_ + +Added method parameters: + +* updateUser_ + + * ``maxBitRate`` + +Version 1.14.0 +^^^^^^^^^^^^^^ + +Added methods: + +* getAlbumInfo_ +* getAlbumInfo2_ +* getNewestPodcasts_ + +Added method parameters: + +* getArtists_ + + * ``musicFolderId`` + +* createUser_ + + * ``videoConversionRole`` + +* updateUser_ + + * ``videoConversionRole`` + +Version 1.15.0 +^^^^^^^^^^^^^^ + +Added error code ``41`` + +Added methods: + +* getVideoInfo_ +* getCaptions_ +* getScanStatus_ +* startScan_ + +Added method parameters: + +* stream_ + + * ``converted`` + +* hls_ + + * ``audioTrack`` + +Version 1.16.0 +^^^^^^^^^^^^^^ + +Added methods: + +* createInternetRadioStation_ +* updateInternetRadioStation_ +* deleteInternetRadioStation_ diff --git a/docs/conf.py b/docs/conf.py index abea604..01a4cd1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,88 +1,88 @@ -# -- Project information ----------------------------------------------------- - -project = "Supysonic" -author = "Alban FΓ©ron" -copyright = "2013-2021, " + author - -version = "0.6.2" -release = "0.6.2" - - -# -- General configuration --------------------------------------------------- - -extensions = [] -templates_path = [] -source_suffix = ".rst" -master_doc = "index" -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -primary_domain = None -highlight_language = "none" - -language = None - - -# -- Options for HTML output ------------------------------------------------- - -html_theme = "alabaster" -html_theme_options = { - "description": "A Python implementation of the Subsonic server API", - "github_user": "spl0k", - "github_repo": "supysonic", -} -html_static_path = ["_static"] - -# Default alabaseter sidebars + localtoc -html_sidebars = { - "**": [ - "about.html", - "localtoc.html", - "navigation.html", - "relations.html", - "searchbox.html", - "donate.html", - ] -} - -html_domain_indices = False - - -# -- Options for manual page output ------------------------------------------ - -_man_authors = ["Louis-Philippe VΓ©ronneau", author] - -# Man pages, they are writter to be generated directly by `rst2man` so using -# Sphinx to build them will give weird sections, but if we ever need it it's -# there - -# (source start file, name, description, authors, manual section). -man_pages = [ - ( - "man/supysonic-cli", - "supysonic-cli", - "Python implementation of the Subsonic server API", - _man_authors, - 1, - ), - ( - "man/supysonic-cli-user", - "supysonic-cli-user", - "Supysonic user management commands", - _man_authors, - 1, - ), - ( - "man/supysonic-cli-folder", - "supysonic-cli-folder", - "Supysonic folder management commands", - _man_authors, - 1, - ), - ( - "man/supysonic-daemon", - "supysonic-daemon", - "Supysonic background daemon", - _man_authors, - 1, - ), -] +# -- Project information ----------------------------------------------------- + +project = "Supysonic" +author = "Alban FΓ©ron" +copyright = "2013-2021, " + author + +version = "0.6.2" +release = "0.6.2" + + +# -- General configuration --------------------------------------------------- + +extensions = [] +templates_path = [] +source_suffix = ".rst" +master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +primary_domain = None +highlight_language = "none" + +language = None + + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "alabaster" +html_theme_options = { + "description": "A Python implementation of the Subsonic server API", + "github_user": "spl0k", + "github_repo": "supysonic", +} +html_static_path = ["_static"] + +# Default alabaseter sidebars + localtoc +html_sidebars = { + "**": [ + "about.html", + "localtoc.html", + "navigation.html", + "relations.html", + "searchbox.html", + "donate.html", + ] +} + +html_domain_indices = False + + +# -- Options for manual page output ------------------------------------------ + +_man_authors = ["Louis-Philippe VΓ©ronneau", author] + +# Man pages, they are writter to be generated directly by `rst2man` so using +# Sphinx to build them will give weird sections, but if we ever need it it's +# there + +# (source start file, name, description, authors, manual section). +man_pages = [ + ( + "man/supysonic-cli", + "supysonic-cli", + "Python implementation of the Subsonic server API", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-user", + "supysonic-cli-user", + "Supysonic user management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-folder", + "supysonic-cli-folder", + "Supysonic folder management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-daemon", + "supysonic-daemon", + "Supysonic background daemon", + _man_authors, + 1, + ), +] diff --git a/docs/index.rst b/docs/index.rst index 7ec46f8..3782e13 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,29 +1,29 @@ -Welcome to Supysonic's documentation! -===================================== - -Supysonic is a Python implementation of the `Subsonic`__ server API. - -Current supported features are: - -* browsing (by folders or tags) -* streaming of various audio file formats -* transcoding -* user or random playlists -* cover arts (as image files in the same folder as music files) -* starred tracks/albums and ratings -* `Last.FM`__ scrobbling -* Jukebox mode - -__ http://www.subsonic.org/ -__ https://www.last.fm/ - -.. rubric:: User's guide - -.. toctree:: - :maxdepth: 2 - - setup/index - transcoding - jukebox - man/index - api +Welcome to Supysonic's documentation! +===================================== + +Supysonic is a Python implementation of the `Subsonic`__ server API. + +Current supported features are: + +* browsing (by folders or tags) +* streaming of various audio file formats +* transcoding +* user or random playlists +* cover arts (as image files in the same folder as music files) +* starred tracks/albums and ratings +* `Last.FM`__ scrobbling +* Jukebox mode + +__ http://www.subsonic.org/ +__ https://www.last.fm/ + +.. rubric:: User's guide + +.. toctree:: + :maxdepth: 2 + + setup/index + transcoding + jukebox + man/index + api diff --git a/docs/jukebox.rst b/docs/jukebox.rst index 30f9bf7..896064b 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -1,45 +1,45 @@ -Jukebox mode -============ - -The jukebox mode allow playing audio files on the hardware of the machine -running Supysonic, using regular clients that support it as a remote control. - -:doc:`setup/daemon` must be running in order to be able to use the jukebox mode. -So be sure to start the :doc:`man/supysonic-daemon` command and keep it running. - -Setting the player program --------------------------- - -Jukebox mode in Supysonic works through the use of third-party command-line -programs. Supysonic isn't bundled with such programs, and you are left to -choose which one you want to use. The chosen program should be able to play a -single audio file from a path specified on its command-line. - -The configuration is done in the :ref:`conf-daemon` of the configuration file, -with the ``jukebox_command`` variable. This variable should include the -following fields: - -``%path`` - absolute path of the file to be played - -``%offset`` - time in seconds where to start playing (used for seeking) - -Here's an example using ``mplayer``:: - - jukebox_command = mplayer -ss %offset %path - -Or using ``mpv``:: - - jukebox_command = mpv --start=%offset %path - -Setting the output volume isn't currently supported. - -Allowing users to act on the jukebox ------------------------------------- - -The jukebox mode is only accessible to chosen users. Granting (or revoking) -jukebox usage rights to a specific user is done with the -:doc:`command line interface `:: - - $ supysonic-cli user setroles --jukebox +Jukebox mode +============ + +The jukebox mode allow playing audio files on the hardware of the machine +running Supysonic, using regular clients that support it as a remote control. + +:doc:`setup/daemon` must be running in order to be able to use the jukebox mode. +So be sure to start the :doc:`man/supysonic-daemon` command and keep it running. + +Setting the player program +-------------------------- + +Jukebox mode in Supysonic works through the use of third-party command-line +programs. Supysonic isn't bundled with such programs, and you are left to +choose which one you want to use. The chosen program should be able to play a +single audio file from a path specified on its command-line. + +The configuration is done in the :ref:`conf-daemon` of the configuration file, +with the ``jukebox_command`` variable. This variable should include the +following fields: + +``%path`` + absolute path of the file to be played + +``%offset`` + time in seconds where to start playing (used for seeking) + +Here's an example using ``mplayer``:: + + jukebox_command = mplayer -ss %offset %path + +Or using ``mpv``:: + + jukebox_command = mpv --start=%offset %path + +Setting the output volume isn't currently supported. + +Allowing users to act on the jukebox +------------------------------------ + +The jukebox mode is only accessible to chosen users. Granting (or revoking) +jukebox usage rights to a specific user is done with the +:doc:`command line interface `:: + + $ supysonic-cli user setroles --jukebox diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst index 8f536ba..0de5c15 100644 --- a/docs/setup/configuration.rst +++ b/docs/setup/configuration.rst @@ -1,308 +1,308 @@ -Configuration -============= - -Supysonic looks for four files for its configuration: :file:`/etc/supysonic`, -:file:`~/.supysonic`, :file:`~/.config/supysonic/supysonic.conf` and -:file:`supysonic.conf` in the current working directory, in this order, merging -values from all files. - -Configuration files must respect a structure similar to Windows INI file, with -``[section]`` headers and using a ``KEY = VALUE`` or ``KEY: VALUE`` syntax. - -If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly -documented configuration sample file at the root of the project, file -conveniently named :file:`config.sample`. More details below. - -__ https://github.com/spl0k/supysonic - -``[base]`` section ------------------- - -This sections defines the database and additional scanning config. - -``database_uri`` - The most important configuration, defines the type and - parameters of the database Supysonic should connect to. It usually includes - username, password, hostname and database name. The typical form of a - database URI is:: - - driver://username:password@host:port/database - - If the connection needs some additional parameters, they can be provided as a - query string, such as:: - - driver://username:password@host:port/database?param1=value1¶m2=value2 - - Supported drivers are ``sqlite``, ``mysql`` and ``postgres`` (or - ``postgresql``). - - As SQLite connects to local files, the format is slightly different. The - "file" portion of the URI is the filename of the database. For a relative - path, it requires three slashes, for absolute paths it's also three slashes - followed by the absolute path, meaning actually four slashes on Unix systems. - - .. highlight:: ini - - :: - - ; Relative path - database_uri = sqlite:///relative-file.db - ; Absolute path on Unix-based systems - database_uri = sqlite:////home/user/supysonic.db - ; Absolute path on Windows - database_uri = sqlite:///C:\Users\user\supysonic.db - - A MySQL-compatible database requires either ``MySQLdb`` or ``pymysql`` to be - installed. PostgreSQL needs ``psycopg2``. - - .. note:: - - For MySQL if no character set is defined on the URI it defaults to - ``utf8mb4`` regardless of what's set on your MySQL installation. - - If ``database_uri`` isn't provided, it defaults to a SQLite database stored - in :file:`/tmp/supysonic/supysonic.db`. - -``scanner_extensions`` - A space separated list of file extensions the scanner is restricted to. - Useful if you have multiple audio formats in your library but only want to - serve some. If left empty, the scanner will try to read every file it finds. - -``follow_symlinks`` - If set to ``yes``, allows the scanner to follow symbolic links. - - Disabled by default, enable it only if you trust your file system as nothing - is done to handle broken links or loops. - -Sample configuration:: - - [base] - ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db - database_uri = sqlite:////var/supysonic/supysonic.db - ;database_uri = mysql://supysonic:supysonic@localhost/supysonic - ;database_uri = postgres://supysonic:supysonic@localhost/supysonic - - ; Optional, restrict scanner to these extensions. Default: none - scanner_extensions = mp3 ogg - - ; Should the scanner follow symbolic links? Default: no - follow_symlinks = no - -``[webapp]`` section --------------------- - -Configuration relative to the HTTP server. - -``cache_dir`` - Directory used to store generated files, such as resized cover art or - transcoded files. Defaults to :file:`/tmp/supysonic`. - -``cache_size`` - Maximum size (in megabytes) of the cache (except for trancodes). - Defaults to 512 MB. - -``transcode_cache_size`` - Maximum size (in megabytes) of the transcode cache. - Defaults to 1024 MB (1 GB). - -``log_file`` - Rotating file where some events generated by the web server are - logged. Leave empty to disable logging. - -``log_level`` - Defines the minimum severity threshold of messages to be added to - ``log_file``. Possible values are: - - * ``DEBUG`` - * ``INFO`` - * ``WARNING`` - * ``ERROR`` - * ``CRITICAL`` - - Defaults to ``WARNING``. - -``mount_api`` (``on`` or ``off``) - Enable or disable the Subsonic REST API. Should be kept on or Supysonic would - be quite useless. Exists mostly for testing purposes. - Defaults to ``on``. - -``mount_webui`` (``on`` or ``off``) - Enable or disable the administrative web interface. - - .. note:: - Setting this off will prevent users from defining a preferred transcoding - format. - - Defaults to ``on``. - -``index_ignored_prefixes`` - Space-separated list of prefixes that should be ignored from artist names - when returning their index. Example: if the word *The* is in this list, - artist *The Rolling Stones* will be listed under the letter *R*. The match is - case insensitive. - Defaults to ``El La Le Las Les Los The``. - -Sample configuration:: - - [webapp] - ; Optional cache directory. Default: /tmp/supysonic - cache_dir = /var/supysonic/cache - - ; Main cache max size in MB. Default: 512 - cache_size = 512 - - ; Transcode cache max size in MB. Default: 1024 (1GB) - transcode_cache_size = 1024 - - ; Optional rotating log file. Default: none - log_file = /var/supysonic/supysonic.log - - ; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. - ; Default: WARNING - log_level = WARNING - - ; Enable the Subsonic REST API. You'll most likely want to keep this on. - ; Here for testing purposes. Default: on - ;mount_api = on - - ; Enable the administrative web interface. Default: on - ;mount_webui = on - - ; Space separated list of prefixes that should be ignored on index endpoints - ; Default: El La Le Las Les Los The - index_ignored_prefixes = El La Le Las Les Los The - -.. _conf-daemon: - -``[daemon]`` section --------------------- - -Configuration for the daemon process that is used to watch for changes in the -library folders and providing the jukebox feature. - -``socket`` - Unix domain socket file (or named pipe on Windows) used to communicate - between the daemon and clients that rely on it (eg. CLI, folder admin web - page, etc.). Note that using an IP address here isn't supported. - Default: :file:`/tmp/supysonic/supysonic.sock` - -``run_watcher`` - Whether or not to start the watcher that will listen for library changes. - Default: yes - -``wait_delay`` - Delay (in seconds) before triggering the scanning operation after a change - have been detected. This prevents running too many scans when multiple - changes are detected for a single file over a short time span. - Default: 5 seconds. - -``jukebox_command`` - Command used by the jukebox mode to play a single file. - See the :doc:`jukebox documentation <../jukebox>` for more details. - -``log_file`` - Rotating file where events generated by the file watcher are logged. - If left empty, any logging will be sent to stderr. - -``log_level`` - Defines the minimum severity threshold of messages to be added to - ``log_file``. Possible values are: - - * ``DEBUG`` - * ``INFO`` - * ``WARNING`` - * ``ERROR`` - * ``CRITICAL`` - - Defaults to ``WARNING``. - -Sample configuration:: - - [daemon] - ; Socket file the daemon will listen on for incoming management commands - ; Default: /tmp/supysonic/supysonic.sock - socket = /var/run/supysonic.sock - - ; Defines if the file watcher should be started. Default: yes - run_watcher = yes - - ; Delay in seconds before triggering scanning operation after a change have been - ; detected. - ; This prevents running too many scans when multiple changes are detected for a - ; single file over a short time span. Default: 5 - wait_delay = 5 - - ; Command used by the jukebox - jukebox_command = mplayer -ss %offset %path - - ; Optional rotating log file for the scanner daemon. Logs to stderr if empty - log_file = /var/supysonic/supysonic-daemon.log - log_level = INFO - -``[lastfm]`` section --------------------- - -This section allow defining API keys to enable Last.FM integration in -Supysonic. Currently it is only used to *scrobble* played tracks and update -the *now playing* information. - -See https://www.last.fm/api to obtain such keys. - -Once keys are set, users have to link their account by visiting their profile -page on Supysonic's administrative UI. - -``api_key`` - Last.FM API key - -``secret`` - secret key associated to the API key - -Sample configuration:: - - [lastfm] - ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts - ; Defaults: none - ;api_key = - ;secret = - -.. _conf-transcoding: - -``[transcoding]`` section -------------------------- - -This section defines command-line programs to be used to convert an audio file -to another format or change its bitrate. All configurations in the sample below -have **not** been thoroughly tested. -For more details, please refer to the -:doc:`transcoding configuration <../transcoding>`. - -:: - - [transcoding] - ; Programs used to convert from one format/bitrate to another. Defaults: none - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - - decoder_mp3 = mpg123 --quiet -w - %srcpath - decoder_ogg = oggdec -o %srcpath - decoder_flac = flac -d -c -s %srcpath - encoder_mp3 = lame --quiet -b %outrate - - - encoder_ogg = oggenc2 -q -M %outrate - - -``[mimetypes]`` section ------------------------ - -Use this section if the system Supysonic is installed on has trouble guessing -the mimetype of some files. This might only be useful in some rare cases. - -See the following links for a list of examples: - -* https://en.wikipedia.org/wiki/Media_type#Common_examples -* https://www.iana.org/assignments/media-types/media-types.xhtml - -:: - - [mimetypes] - ; Extension to mimetype mappings in case your system has some trouble guessing - ; Default: none - ;mp3 = audio/mpeg - ;ogg = audio/vorbis +Configuration +============= + +Supysonic looks for four files for its configuration: :file:`/etc/supysonic`, +:file:`~/.supysonic`, :file:`~/.config/supysonic/supysonic.conf` and +:file:`supysonic.conf` in the current working directory, in this order, merging +values from all files. + +Configuration files must respect a structure similar to Windows INI file, with +``[section]`` headers and using a ``KEY = VALUE`` or ``KEY: VALUE`` syntax. + +If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly +documented configuration sample file at the root of the project, file +conveniently named :file:`config.sample`. More details below. + +__ https://github.com/spl0k/supysonic + +``[base]`` section +------------------ + +This sections defines the database and additional scanning config. + +``database_uri`` + The most important configuration, defines the type and + parameters of the database Supysonic should connect to. It usually includes + username, password, hostname and database name. The typical form of a + database URI is:: + + driver://username:password@host:port/database + + If the connection needs some additional parameters, they can be provided as a + query string, such as:: + + driver://username:password@host:port/database?param1=value1¶m2=value2 + + Supported drivers are ``sqlite``, ``mysql`` and ``postgres`` (or + ``postgresql``). + + As SQLite connects to local files, the format is slightly different. The + "file" portion of the URI is the filename of the database. For a relative + path, it requires three slashes, for absolute paths it's also three slashes + followed by the absolute path, meaning actually four slashes on Unix systems. + + .. highlight:: ini + + :: + + ; Relative path + database_uri = sqlite:///relative-file.db + ; Absolute path on Unix-based systems + database_uri = sqlite:////home/user/supysonic.db + ; Absolute path on Windows + database_uri = sqlite:///C:\Users\user\supysonic.db + + A MySQL-compatible database requires either ``MySQLdb`` or ``pymysql`` to be + installed. PostgreSQL needs ``psycopg2``. + + .. note:: + + For MySQL if no character set is defined on the URI it defaults to + ``utf8mb4`` regardless of what's set on your MySQL installation. + + If ``database_uri`` isn't provided, it defaults to a SQLite database stored + in :file:`/tmp/supysonic/supysonic.db`. + +``scanner_extensions`` + A space separated list of file extensions the scanner is restricted to. + Useful if you have multiple audio formats in your library but only want to + serve some. If left empty, the scanner will try to read every file it finds. + +``follow_symlinks`` + If set to ``yes``, allows the scanner to follow symbolic links. + + Disabled by default, enable it only if you trust your file system as nothing + is done to handle broken links or loops. + +Sample configuration:: + + [base] + ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db + database_uri = sqlite:////var/supysonic/supysonic.db + ;database_uri = mysql://supysonic:supysonic@localhost/supysonic + ;database_uri = postgres://supysonic:supysonic@localhost/supysonic + + ; Optional, restrict scanner to these extensions. Default: none + scanner_extensions = mp3 ogg + + ; Should the scanner follow symbolic links? Default: no + follow_symlinks = no + +``[webapp]`` section +-------------------- + +Configuration relative to the HTTP server. + +``cache_dir`` + Directory used to store generated files, such as resized cover art or + transcoded files. Defaults to :file:`/tmp/supysonic`. + +``cache_size`` + Maximum size (in megabytes) of the cache (except for trancodes). + Defaults to 512 MB. + +``transcode_cache_size`` + Maximum size (in megabytes) of the transcode cache. + Defaults to 1024 MB (1 GB). + +``log_file`` + Rotating file where some events generated by the web server are + logged. Leave empty to disable logging. + +``log_level`` + Defines the minimum severity threshold of messages to be added to + ``log_file``. Possible values are: + + * ``DEBUG`` + * ``INFO`` + * ``WARNING`` + * ``ERROR`` + * ``CRITICAL`` + + Defaults to ``WARNING``. + +``mount_api`` (``on`` or ``off``) + Enable or disable the Subsonic REST API. Should be kept on or Supysonic would + be quite useless. Exists mostly for testing purposes. + Defaults to ``on``. + +``mount_webui`` (``on`` or ``off``) + Enable or disable the administrative web interface. + + .. note:: + Setting this off will prevent users from defining a preferred transcoding + format. + + Defaults to ``on``. + +``index_ignored_prefixes`` + Space-separated list of prefixes that should be ignored from artist names + when returning their index. Example: if the word *The* is in this list, + artist *The Rolling Stones* will be listed under the letter *R*. The match is + case insensitive. + Defaults to ``El La Le Las Les Los The``. + +Sample configuration:: + + [webapp] + ; Optional cache directory. Default: /tmp/supysonic + cache_dir = /var/supysonic/cache + + ; Main cache max size in MB. Default: 512 + cache_size = 512 + + ; Transcode cache max size in MB. Default: 1024 (1GB) + transcode_cache_size = 1024 + + ; Optional rotating log file. Default: none + log_file = /var/supysonic/supysonic.log + + ; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. + ; Default: WARNING + log_level = WARNING + + ; Enable the Subsonic REST API. You'll most likely want to keep this on. + ; Here for testing purposes. Default: on + ;mount_api = on + + ; Enable the administrative web interface. Default: on + ;mount_webui = on + + ; Space separated list of prefixes that should be ignored on index endpoints + ; Default: El La Le Las Les Los The + index_ignored_prefixes = El La Le Las Les Los The + +.. _conf-daemon: + +``[daemon]`` section +-------------------- + +Configuration for the daemon process that is used to watch for changes in the +library folders and providing the jukebox feature. + +``socket`` + Unix domain socket file (or named pipe on Windows) used to communicate + between the daemon and clients that rely on it (eg. CLI, folder admin web + page, etc.). Note that using an IP address here isn't supported. + Default: :file:`/tmp/supysonic/supysonic.sock` + +``run_watcher`` + Whether or not to start the watcher that will listen for library changes. + Default: yes + +``wait_delay`` + Delay (in seconds) before triggering the scanning operation after a change + have been detected. This prevents running too many scans when multiple + changes are detected for a single file over a short time span. + Default: 5 seconds. + +``jukebox_command`` + Command used by the jukebox mode to play a single file. + See the :doc:`jukebox documentation <../jukebox>` for more details. + +``log_file`` + Rotating file where events generated by the file watcher are logged. + If left empty, any logging will be sent to stderr. + +``log_level`` + Defines the minimum severity threshold of messages to be added to + ``log_file``. Possible values are: + + * ``DEBUG`` + * ``INFO`` + * ``WARNING`` + * ``ERROR`` + * ``CRITICAL`` + + Defaults to ``WARNING``. + +Sample configuration:: + + [daemon] + ; Socket file the daemon will listen on for incoming management commands + ; Default: /tmp/supysonic/supysonic.sock + socket = /var/run/supysonic.sock + + ; Defines if the file watcher should be started. Default: yes + run_watcher = yes + + ; Delay in seconds before triggering scanning operation after a change have been + ; detected. + ; This prevents running too many scans when multiple changes are detected for a + ; single file over a short time span. Default: 5 + wait_delay = 5 + + ; Command used by the jukebox + jukebox_command = mplayer -ss %offset %path + + ; Optional rotating log file for the scanner daemon. Logs to stderr if empty + log_file = /var/supysonic/supysonic-daemon.log + log_level = INFO + +``[lastfm]`` section +-------------------- + +This section allow defining API keys to enable Last.FM integration in +Supysonic. Currently it is only used to *scrobble* played tracks and update +the *now playing* information. + +See https://www.last.fm/api to obtain such keys. + +Once keys are set, users have to link their account by visiting their profile +page on Supysonic's administrative UI. + +``api_key`` + Last.FM API key + +``secret`` + secret key associated to the API key + +Sample configuration:: + + [lastfm] + ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts + ; Defaults: none + ;api_key = + ;secret = + +.. _conf-transcoding: + +``[transcoding]`` section +------------------------- + +This section defines command-line programs to be used to convert an audio file +to another format or change its bitrate. All configurations in the sample below +have **not** been thoroughly tested. +For more details, please refer to the +:doc:`transcoding configuration <../transcoding>`. + +:: + + [transcoding] + ; Programs used to convert from one format/bitrate to another. Defaults: none + transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - + transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - + decoder_mp3 = mpg123 --quiet -w - %srcpath + decoder_ogg = oggdec -o %srcpath + decoder_flac = flac -d -c -s %srcpath + encoder_mp3 = lame --quiet -b %outrate - - + encoder_ogg = oggenc2 -q -M %outrate - + +``[mimetypes]`` section +----------------------- + +Use this section if the system Supysonic is installed on has trouble guessing +the mimetype of some files. This might only be useful in some rare cases. + +See the following links for a list of examples: + +* https://en.wikipedia.org/wiki/Media_type#Common_examples +* https://www.iana.org/assignments/media-types/media-types.xhtml + +:: + + [mimetypes] + ; Extension to mimetype mappings in case your system has some trouble guessing + ; Default: none + ;mp3 = audio/mpeg + ;ogg = audio/vorbis diff --git a/docs/transcoding.rst b/docs/transcoding.rst index fe53410..e451d53 100644 --- a/docs/transcoding.rst +++ b/docs/transcoding.rst @@ -1,148 +1,148 @@ -Transcoding -=========== - -Transcoding is the process of converting from one audio format to another. This -allows for streaming of formats that wouldn't be streamable otherwise, or -reducing the quality of an audio file to allow a decent streaming for clients -with limited bandwidth, such as the ones running on a mobile connection. - -Transcoding in Supysonic is achieved through the use of third-party command-line -programs. Supysonic isn't bundled with such programs, and you are left to choose -which one you want to use. - -If you want to use transcoding but your client doesn't allow you to do so, you -can force Supysonic to transcode for that client by going to your profile page -on the web interface. - -Configuration -------------- - -Configuration of transcoders is done on the :ref:`conf-transcoding` of the -configuration file. - -Transcoding can be done by one single program which is able to convert from one -format directly to another one, or by two programs: a decoder and an encoder. -All these are defined by the following variables: - -* ``transcoder_EXT_EXT`` -* ``decoder_EXT`` -* ``encoder_EXT`` -* ``trancoder`` -* ``decoder`` -* ``encoder`` -* ``default_transcode_target`` - -where ``EXT`` is the lowercase file extension of the matching audio format. -``transcoder``\ s variables have two extensions: the first one is the source -extension, and the second one is the extension to convert to. The same way, -``decoder``\ s extension is the source extension, and ``encoder``\ s extension -is the extension to convert to. -The value of ``default_transcode_target`` will be used as output format when a -client requests a bitrate lower than the original file and no specific format. - -Notice that all of them have a version without extension. Those are generic -versions. The programs defined with these variables should be able to -transcode/decode/encode any format. For that reason, we suggest you don't use -these if you want to keep control over the available transcoders. - -Supysonic will take the first available transcoding configuration in the -following order: - -#. specific transcoder -#. specific decoder / specific encoder -#. generic decoder / generic encoder (with the possibility to use a generic - decoder with a specific encoder, and vice-versa) -#. generic transcoder - -All the variables should be set to the command-line used to run the converter -program. The command-lines can include the following fields: - -``%srcpath`` - path to the original file to transcode - -``%srcfmt`` - extension of the original file - -``%outfmt`` - extension of the resulting file - -``%outrate`` - bitrate of the resulting file - -``%title`` - title of the file to transcode - -``%album`` - album name of the file to transcode - -``%artist`` - artist name of the file to transcode - -``%tracknumber`` - track number of the file to transcode - -``%totaltracks`` - number of tracks in the album of the file to transcode - -``%discnumber`` - disc number of the file to transcode - -``%genre`` - genre of the file to transcode (not always available, defaults to "") - -``%year`` - year of the file to transcode (not always available, defaults to "") - -One final note: the original file should be provided as an argument of -transcoders and decoders. All transcoders, decoders and encoders should write -to standard output, and encoders should read from standard input (decoders -output being piped into encoders) - -Suggested configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -Here is an example configuration that you could use. This is provided as-is, -and some configurations haven't been tested. - -.. highlight:: ini - -Basic configuration:: - - [transcoding] - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - - decoder_mp3 = mpg123 --quiet -w - %srcpath - decoder_ogg = oggdec -o %srcpath - decoder_flac = flac -d -c -s %srcpath - encoder_mp3 = lame --quiet -b %outrate - - - encoder_ogg = oggenc2 -Q -M %outrate - - default_transcode_target = mp3 - -To include track metadata in the transcoded stream:: - - [transcoding] - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath - - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -metadata title=%title -metadata album=%album -metadata author=%artist -metadata track=%tracknumber/%totaltracks -metadata disc=%discnumber -metadata genre=%genre -metadata date=%year -f %outfmt - - decoder_mp3 = mpg123 --quiet -w - %srcpath - decoder_ogg = oggdec -o %srcpath - decoder_flac = flac -d -c -s %srcpath - encoder_mp3 = lame --quiet -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 - - - encoder_ogg = oggenc2 -Q -M %outrate -t %title -l %album -a %artist -N %tracknumber -c TOTALTRACKS=%totaltracks -c DISCNUMBER=%discnumber -G %genre -d %year - - default_transcode_target = mp3 - -Enabling transcoding --------------------- - -Once the transcoding configuration has been set, most clients will require the -user to specify that they want to transcode files. This might be done on the -client itself, but most importantly it should be done on Supysonic web -interface. Not doing so might prevent some clients to properly request -transcoding. - -To enable transcoding with the web interface, you should first start using the -client you want to set transcoding for. Only browsing the library should -suffice. Then open your browser of choice and navigate to the URL of your -Supysonic instance. Log in with your credentials and the click on your username -in the top bar. There you should be presented with a list of clients you used to -connect to Supysonic and be able to set your preferred streaming format -and bitrate. +Transcoding +=========== + +Transcoding is the process of converting from one audio format to another. This +allows for streaming of formats that wouldn't be streamable otherwise, or +reducing the quality of an audio file to allow a decent streaming for clients +with limited bandwidth, such as the ones running on a mobile connection. + +Transcoding in Supysonic is achieved through the use of third-party command-line +programs. Supysonic isn't bundled with such programs, and you are left to choose +which one you want to use. + +If you want to use transcoding but your client doesn't allow you to do so, you +can force Supysonic to transcode for that client by going to your profile page +on the web interface. + +Configuration +------------- + +Configuration of transcoders is done on the :ref:`conf-transcoding` of the +configuration file. + +Transcoding can be done by one single program which is able to convert from one +format directly to another one, or by two programs: a decoder and an encoder. +All these are defined by the following variables: + +* ``transcoder_EXT_EXT`` +* ``decoder_EXT`` +* ``encoder_EXT`` +* ``trancoder`` +* ``decoder`` +* ``encoder`` +* ``default_transcode_target`` + +where ``EXT`` is the lowercase file extension of the matching audio format. +``transcoder``\ s variables have two extensions: the first one is the source +extension, and the second one is the extension to convert to. The same way, +``decoder``\ s extension is the source extension, and ``encoder``\ s extension +is the extension to convert to. +The value of ``default_transcode_target`` will be used as output format when a +client requests a bitrate lower than the original file and no specific format. + +Notice that all of them have a version without extension. Those are generic +versions. The programs defined with these variables should be able to +transcode/decode/encode any format. For that reason, we suggest you don't use +these if you want to keep control over the available transcoders. + +Supysonic will take the first available transcoding configuration in the +following order: + +#. specific transcoder +#. specific decoder / specific encoder +#. generic decoder / generic encoder (with the possibility to use a generic + decoder with a specific encoder, and vice-versa) +#. generic transcoder + +All the variables should be set to the command-line used to run the converter +program. The command-lines can include the following fields: + +``%srcpath`` + path to the original file to transcode + +``%srcfmt`` + extension of the original file + +``%outfmt`` + extension of the resulting file + +``%outrate`` + bitrate of the resulting file + +``%title`` + title of the file to transcode + +``%album`` + album name of the file to transcode + +``%artist`` + artist name of the file to transcode + +``%tracknumber`` + track number of the file to transcode + +``%totaltracks`` + number of tracks in the album of the file to transcode + +``%discnumber`` + disc number of the file to transcode + +``%genre`` + genre of the file to transcode (not always available, defaults to "") + +``%year`` + year of the file to transcode (not always available, defaults to "") + +One final note: the original file should be provided as an argument of +transcoders and decoders. All transcoders, decoders and encoders should write +to standard output, and encoders should read from standard input (decoders +output being piped into encoders) + +Suggested configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +Here is an example configuration that you could use. This is provided as-is, +and some configurations haven't been tested. + +.. highlight:: ini + +Basic configuration:: + + [transcoding] + transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - + transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - + decoder_mp3 = mpg123 --quiet -w - %srcpath + decoder_ogg = oggdec -o %srcpath + decoder_flac = flac -d -c -s %srcpath + encoder_mp3 = lame --quiet -b %outrate - - + encoder_ogg = oggenc2 -Q -M %outrate - + default_transcode_target = mp3 + +To include track metadata in the transcoded stream:: + + [transcoding] + transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath - + transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -metadata title=%title -metadata album=%album -metadata author=%artist -metadata track=%tracknumber/%totaltracks -metadata disc=%discnumber -metadata genre=%genre -metadata date=%year -f %outfmt - + decoder_mp3 = mpg123 --quiet -w - %srcpath + decoder_ogg = oggdec -o %srcpath + decoder_flac = flac -d -c -s %srcpath + encoder_mp3 = lame --quiet -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 - - + encoder_ogg = oggenc2 -Q -M %outrate -t %title -l %album -a %artist -N %tracknumber -c TOTALTRACKS=%totaltracks -c DISCNUMBER=%discnumber -G %genre -d %year - + default_transcode_target = mp3 + +Enabling transcoding +-------------------- + +Once the transcoding configuration has been set, most clients will require the +user to specify that they want to transcode files. This might be done on the +client itself, but most importantly it should be done on Supysonic web +interface. Not doing so might prevent some clients to properly request +transcoding. + +To enable transcoding with the web interface, you should first start using the +client you want to set transcoding for. Only browsing the library should +suffice. Then open your browser of choice and navigate to the URL of your +Supysonic instance. Log in with your credentials and the click on your username +in the top bar. There you should be presented with a list of clients you used to +connect to Supysonic and be able to set your preferred streaming format +and bitrate.