diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 6412730..0000000 --- a/docs/api.md +++ /dev/null @@ -1,917 +0,0 @@ -# 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](#methods-and-parameters-listing) -- [Changes by version](#changes-by-version) - -## 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 - -| Method | Vers. | | -|-------------------------------------------------------------|--------|---| -| [`ping`](#ping) | | βœ”οΈ | -| [`getLicense`](#getlicense) | | βœ”οΈ | -| [`getMusicFolders`](#getmusicfolders) | | βœ”οΈ | -| [`getIndexes`](#getindexes) | | βœ”οΈ | -| [`getMusicDirectory`](#getmusicdirectory) | | βœ”οΈ | -| [`getGenres`](#getgenres) | 1.9.0 | βœ”οΈ | -| [`getArtists`](#getartists) | | βœ”οΈ | -| [`getArtist`](#getartist) | | βœ”οΈ | -| [`getAlbum`](#getalbum) | | βœ”οΈ | -| [`getSong`](#getsong) | | βœ”οΈ | -| [`getVideos`](#getvideos) | | ❌ | -| [`getVideoInfo`](#getvideoinfo) | 1.15.0 | πŸ”΄ | -| [`getArtistInfo`](#getartistinfo) | 1.11.0 | πŸ“… | -| [`getArtistInfo2`](#getartistinfo2) | 1.11.0 | πŸ“… | -| [`getAlbumInfo`](#getalbuminfo) | 1.14.0 | πŸ“… | -| [`getAlbumInfo2`](#getalbuminfo2) | 1.14.0 | πŸ“… | -| [`getSimilarSongs`](#getsimilarsongs) | 1.11.0 | ❔ | -| [`getSimilarSongs2`](#getsimilarsongs2) | 1.11.0 | ❔ | -| [`getTopSongs`](#gettopsongs) | 1.13.0 | ❔ | -| [`getAlbumList`](#getalbumlist) | | βœ”οΈ | -| [`getAlbumList2`](#getalbumlist2) | | βœ”οΈ | -| [`getRandomSongs`](#getrandomsongs) | | βœ”οΈ | -| [`getSongsByGenre`](#getsongsbygenre) | 1.9.0 | βœ”οΈ | -| [`getNowPlaying`](#getnowplaying) | | βœ”οΈ | -| [`getStarred`](#getstarred) | | βœ”οΈ | -| [`getStarred2`](#getstarred2) | | βœ”οΈ | -| [`search`](#search) | | βœ”οΈ | -| [`search2`](#search2) | | βœ”οΈ | -| [`search3`](#search3) | | βœ”οΈ | -| [`getPlaylists`](#getplaylists) | | βœ”οΈ | -| [`getPlaylist`](#getplaylist) | | βœ”οΈ | -| [`createPlaylist`](#createplaylist) | | βœ”οΈ | -| [`updatePlaylist`](#updateplaylist) | | βœ”οΈ | -| [`deletePlaylist`](#deleteplaylist) | | βœ”οΈ | -| [`stream`](#stream) | | βœ”οΈ | -| [`download`](#download) | | βœ”οΈ | -| [`hls`](#hls) | 1.9.0 | πŸ”΄ | -| [`getCaptions`](#getcaptions) | 1.15.0 | πŸ”΄ | -| [`getCoverArt`](#getcoverart) | | βœ”οΈ | -| [`getLyrics`](#getlyrics) | | βœ”οΈ | -| [`getAvatar`](#getavatar) | | ❌ | -| [`star`](#star) | | βœ”οΈ | -| [`unstar`](#unstar) | | βœ”οΈ | -| [`setRating`](#setrating) | | βœ”οΈ | -| [`scrobble`](#scrobble) | | βœ”οΈ | -| [`getShares`](#getshares) | | ❌ | -| [`createShare`](#createshare) | | ❌ | -| [`updateShare`](#updateshare) | | ❌ | -| [`deleteShare`](#deleteshare) | | ❌ | -| [`getPodcasts`](#getpodcasts) | | ❔ | -| [`getNewestPodcasts`](#getnewestpodcasts) | 1.14.0 | ❔ | -| [`refreshPodcasts`](#refreshpodcasts) | 1.9.0 | ❔ | -| [`createPodcastChannel`](#createpodcastchannel) | 1.9.0 | ❔ | -| [`deletePodcastChannel`](#deletepodcastchannel) | 1.9.0 | ❔ | -| [`deletePodcastEpisode`](#deletepodcastepisode) | 1.9.0 | ❔ | -| [`downloadPodcastEpisode`](#downloadpodcastepisode) | 1.9.0 | ❔ | -| [`jukeboxControl`](#jukeboxcontrol) | | βœ”οΈ | -| [`getInternetRadioStations`](#getinternetradiostations) | 1.9.0 | βœ”οΈ | -| [`createInternetRadioStation`](#createinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`updateInternetRadioStation`](#updateinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`deleteInternetRadioStation`](#deleteinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`getChatMessages`](#getchatmessages) | | βœ”οΈ | -| [`addChatMessage`](#addchatmessage) | | βœ”οΈ | -| [`getUser`](#getuser) | | βœ”οΈ | -| [`getUsers`](#getusers) | 1.9.0 | βœ”οΈ | -| [`createUser`](#createuser) | | βœ”οΈ | -| [`updateUser`](#updateuser) | 1.10.2 | βœ”οΈ | -| [`deleteUser`](#deleteuser) | | βœ”οΈ | -| [`changePassword`](#changepassword) | | βœ”οΈ | -| [`getBookmarks`](#getbookmarks) | 1.9.0 | ❔ | -| [`createBookmark`](#createbookmark) | 1.9.0 | ❔ | -| [`deleteBookmark`](#deletebookmark) | 1.9.0 | ❔ | -| [`getPlayQueue`](#getplayqueue) | 1.12.0 | ❔ | -| [`savePlayQueue`](#saveplayqueue) | 1.12.0 | ❔ | -| [`getScanStatus`](#getscanstatus) | 1.15.0 | βœ”οΈ | -| [`startScan`](#startscan) | 1.15.0 | βœ”οΈ | - -### Global - -Parameters used for any request - -| P. | Vers. | | -|-----|--------|---| -| `u` | | βœ”οΈ | -| `p` | | βœ”οΈ | -| `t` | 1.13.0 | πŸ”΄ | -| `s` | 1.13.0 | πŸ”΄ | -| `v` | | βœ”οΈ | -| `c` | | βœ”οΈ | -| `f` | | βœ”οΈ | - -Error codes - -| # | Vers. | | -|----|--------|---| -| 0 | | βœ”οΈ | -| 10 | | βœ”οΈ | -| 20 | | βœ”οΈ | -| 30 | | βœ”οΈ | -| 40 | | βœ”οΈ | -| 41 | 1.15.0 | πŸ“… | -| 50 | | βœ”οΈ | -| 60 | | βœ”οΈ | -| 70 | | βœ”οΈ | - -### System - -#### `ping` -βœ”οΈ -No parameter - -#### `getLicense` -βœ”οΈ -No parameter - -### Browsing - -#### `getMusicFolders` -βœ”οΈ -No parameter - -#### `getIndexes` -βœ”οΈ - -| Parameter | Vers. | | -|-------------------|-------|---| -| `musicFolderId` | | βœ”οΈ | -| `ifModifiedSince` | | βœ”οΈ | - -#### `getMusicDirectory` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getGenres` -βœ”οΈ 1.9.0 -No parameter - -#### `getArtists` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.14.0 | πŸ“… | - -#### `getArtist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getAlbum` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getSong` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getVideos` -❌ -No parameter - -#### `getVideoInfo` -πŸ”΄ 1.15.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.15.0 | πŸ”΄ | - -#### `getArtistInfo` -πŸ“… 1.11.0 - -| Parameter | Vers. | | -|---------------------|--------|---| -| `id` | 1.11.0 | πŸ“… | -| `count` | 1.11.0 | πŸ“… | -| `includeNotPresent` | 1.11.0 | πŸ“… | - -#### `getArtistInfo2` -πŸ“… 1.11.0 - -| Parameter | Vers. | | -|---------------------|--------|---| -| `id` | 1.11.0 | πŸ“… | -| `count` | 1.11.0 | πŸ“… | -| `includeNotPresent` | 1.11.0 | πŸ“… | - -#### `getAlbumInfo` -πŸ“… 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.14.0 | πŸ“… | - -#### `getAlbumInfo2` -πŸ“… 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.14.0 | πŸ“… | - -#### `getSimilarSongs` -❔ 1.11.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.11.0 | ❔ | -| `count` | 1.11.0 | ❔ | - -#### `getSimilarSongs2` -❔ 1.11.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.11.0 | ❔ | -| `count` | 1.11.0 | ❔ | - -#### `getTopSongs` -❔ 1.13.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `artist` | 1.13.0 | ❔ | -| `count` | 1.13.0 | ❔ | - -### Album/song lists - -#### `getAlbumList` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `type` | | βœ”οΈ | -| `size` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -On 1.10.1, `byYear` and `byGenre` were added to `type` - -#### `getAlbumList2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `type` | | βœ”οΈ | -| `size` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -On 1.10.1, `byYear` and `byGenre` were added to `type` - -#### `getRandomSongs` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|-------|---| -| `size` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `musicFolderId` | | βœ”οΈ | - -#### `getSongsByGenre` -βœ”οΈ 1.9.0 - -| Parameter | Vers. | | -|-----------------|--------|---| -| `genre` | 1.9.0 | βœ”οΈ | -| `count` | 1.9.0 | βœ”οΈ | -| `offset` | 1.9.0 | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `getNowPlaying` -βœ”οΈ -No parameter - -#### `getStarred` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `getStarred2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.12.0 | πŸ“… | - -### Searching - -#### `search` -βœ”οΈ - -| Parameter | Vers. | | -|-------------|-------|---| -| `artist` | | βœ”οΈ | -| `album` | | βœ”οΈ | -| `title` | | βœ”οΈ | -| `any` | | βœ”οΈ | -| `count` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `newerThan` | | βœ”οΈ | - -#### `search2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `query` | | βœ”οΈ | -| `artistCount` | | βœ”οΈ | -| `artistOffset` | | βœ”οΈ | -| `albumCount` | | βœ”οΈ | -| `albumOffset` | | βœ”οΈ | -| `songCount` | | βœ”οΈ | -| `songOffset` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `search3` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `query` | | βœ”οΈ | -| `artistCount` | | βœ”οΈ | -| `artistOffset` | | βœ”οΈ | -| `albumCount` | | βœ”οΈ | -| `albumOffset` | | βœ”οΈ | -| `songCount` | | βœ”οΈ | -| `songOffset` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -### Playlists - -#### `getPlaylists` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | βœ”οΈ | - -#### `getPlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `createPlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|--------------|-------|---| -| `playlistId` | | βœ”οΈ | -| `name` | | βœ”οΈ | -| `songId` | | βœ”οΈ | - -#### `updatePlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|---------------------|-------|---| -| `playlistId` | | βœ”οΈ | -| `name` | | βœ”οΈ | -| `comment` | | βœ”οΈ | -| `public` | 1.9.0 | βœ”οΈ | -| `songIdToAdd` | | βœ”οΈ | -| `songIndexToRemove` | | βœ”οΈ | - -#### `deletePlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -### Media retrieval - -#### `stream` -βœ”οΈ - -| Parameter | Vers. | | -|-------------------------|--------|---| -| `id` | | βœ”οΈ | -| `maxBitRate` | | βœ”οΈ | -| `format` | | βœ”οΈ | -| `timeOffset` | | ❌ | -| `size` | | ❌ | -| `estimateContentLength` | | βœ”οΈ | -| `converted` | 1.15.0 | πŸ”΄ | - -#### `download` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `hls` -πŸ”΄ 1.9.0 - -| Parameter | Vers. | | -|--------------|--------|---| -| `id` | 1.9.0 | πŸ”΄ | -| `bitRate` | 1.9.0 | πŸ”΄ | -| `audioTrack` | 1.15.0 | πŸ”΄ | - -#### `getCaptions` -πŸ”΄ 1.15.0 - -| Parameter | Vers. | | -|-------------|--------|---| -| `id` | 1.15.0 | πŸ”΄ | -| `format` | 1.15.0 | πŸ”΄ | - -#### `getCoverArt` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | -| `size` | | βœ”οΈ | - -#### `getLyrics` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `artist` | | βœ”οΈ | -| `title` | | βœ”οΈ | - -#### `getAvatar` -❌ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | ❌ | - -### Media annotation - -#### `star` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | | βœ”οΈ | -| `albumId` | | βœ”οΈ | -| `artistId` | | βœ”οΈ | - -#### `unstar` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | | βœ”οΈ | -| `albumId` | | βœ”οΈ | -| `artistId` | | βœ”οΈ | - -#### `setRating` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | -| `rating` | | βœ”οΈ | - -#### `scrobble` -βœ”οΈ - -| Parameter | Vers. | | -|--------------|-------|---| -| `id` | | βœ”οΈ | -| `time` | 1.9.0 | βœ”οΈ | -| `submission` | | βœ”οΈ | - -### Sharing - -#### `getShares` -❌ -No parameter - -#### `createShare` -❌ - -| Parameter | Vers. | | -|---------------|-------|---| -| `id` | | ❌ | -| `description` | | ❌ | -| `expires` | | ❌ | - -#### `updateShare` -❌ - -| Parameter | Vers. | | -|---------------|-------|---| -| `id` | | ❌ | -| `description` | | ❌ | -| `expires` | | ❌ | - -#### `deleteShare` -❌ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | ❌ | - -### Podcast - -#### `getPodcasts` -❔ - -| Parameter | Vers. | | -|-------------------|-------|---| -| `includeEpisodes` | 1.9.0 | ❔ | -| `id` | 1.9.0 | ❔ | - -#### `getNewestPodcasts` -❔ 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `count` | 1.14.0 | ❔ | - -#### `refreshPodcasts` -❔ 1.9.0 - -No parameter - -#### `createPodcastChannel` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `url` | 1.9.0 | ❔ | - -#### `deletePodcastChannel` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -#### `deletePodcastEpisode` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - - -#### `downloadPodcastEpisode` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -### Jukebox - -#### `jukeboxControl` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `action` | | βœ”οΈ | -| `index` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `id` | | βœ”οΈ | -| `gain` | | ❌ | - -### Internet radio - -#### `getInternetRadioStations` -❔ 1.9.0 - -No parameter - -#### `createInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|---------------|--------|---| -| `streamUrl` | 1.16.0 | ❔ | -| `name` | 1.16.0 | ❔ | -| `homepageUrl` | 1.16.0 | ❔ | - -#### `updateInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|---------------|--------|---| -| `id` | 1.16.0 | ❔ | -| `streamUrl` | 1.16.0 | ❔ | -| `name` | 1.16.0 | ❔ | -| `homepageUrl` | 1.16.0 | ❔ | - -#### `deleteInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.16.0 | ❔ | - -### Chat - -#### `getChatMessages` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `since` | | βœ”οΈ | - -#### `addChatMessage` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `message` | | βœ”οΈ | - -### User management - -#### `getUser` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | βœ”οΈ | - -#### `getUsers` -βœ”οΈ 1.9.0 - -No parameter - -#### `createUser` -βœ”οΈ - -| 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` -βœ”οΈ 1.10.2 - -| 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` -βœ”οΈ - -| Parameter | Vers. | | -|------------|--------|---| -| `username` | | βœ”οΈ | - -#### `changePassword` -βœ”οΈ - -| Parameter | Vers. | | -|------------|--------|---| -| `username` | | βœ”οΈ | -| `password` | | βœ”οΈ | - -### Bookmarks - -#### `getBookmarks` -❔ 1.9.0 -No parameter - -#### `createBookmark` -❔ 1.9.0 - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | 1.9.0 | ❔ | -| `position` | 1.9.0 | ❔ | -| `comment` | 1.9.0 | ❔ | - -#### `deleteBookmark` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -#### `getPlayQueue` -❔ 1.12.0 -No parameter - -#### `savePlayQueue` -❔ 1.12.0 - -| Parameter | Vers. | | -|------------|--------|---| -| `id` | 1.12.0 | ❔ | -| `current` | 1.12.0 | ❔ | -| `position` | 1.12.0 | ❔ | - -### Library scanning - -#### `getScanStatus` -βœ”οΈ 1.15.0 -No parameter - -#### `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/api.rst b/docs/api.rst new file mode 100644 index 0000000..0ac0598 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,1288 @@ +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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +=========================== ====== = +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 + +===== ====== = +P. Vers. +===== ====== = +``u`` βœ”οΈ +``p`` βœ”οΈ +``t`` 1.13.0 πŸ”΄ +``s`` 1.13.0 πŸ”΄ +``v`` βœ”οΈ +``c`` βœ”οΈ +``f`` βœ”οΈ +===== ====== = + +Error codes + +== ====== = +# 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`` + βœ”οΈ + + =================== ===== = + Parameter Vers. + =================== ===== = + ``musicFolderId`` βœ”οΈ + ``ifModifiedSince`` βœ”οΈ + =================== ===== = + +.. _getMusicDirectory: + +``getMusicDirectory`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getGenres: + +``getGenres`` + βœ”οΈ 1.9.0 + + No parameter + +.. _getArtists: + +``getArtists`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.14.0 πŸ“… + ================= ====== = + +.. _getArtist: + +``getArtist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getAlbum: + +``getAlbum`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getSong: + +``getSong`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getVideos: + +``getVideos`` + ❌ + + No parameter + +.. _getVideoInfo: + +``getVideoInfo`` + πŸ”΄ 1.15.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.15.0 πŸ”΄ + ========= ====== = + +.. _getArtistInfo: + +``getArtistInfo`` + πŸ“… 1.11.0 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getArtistInfo2: + +``getArtistInfo2`` + πŸ“… 1.11.0 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getAlbumInfo: + +``getAlbumInfo`` + πŸ“… 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getAlbumInfo2: + +``getAlbumInfo2`` + πŸ“… 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getSimilarSongs: + +``getSimilarSongs`` + ❔ 1.11.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getSimilarSongs2: + +``getSimilarSongs2`` + ❔ 1.11.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getTopSongs: + +``getTopSongs`` + ❔ 1.13.0 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``artist`` 1.13.0 ❔ + ``count`` 1.13.0 ❔ + ========== ====== = + +Album/song lists +^^^^^^^^^^^^^^^^ + +.. _getAlbumList: + +``getAlbumList`` + βœ”οΈ + + ================= ====== = + 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`` + βœ”οΈ + + ================= ====== = + 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`` + βœ”οΈ + + ================= ===== = + Parameter Vers. + ================= ===== = + ``size`` βœ”οΈ + ``genre`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``musicFolderId`` βœ”οΈ + ================= ===== = + +.. _getSongsByGenre: + +``getSongsByGenre`` + βœ”οΈ 1.9.0 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``genre`` 1.9.0 βœ”οΈ + ``count`` 1.9.0 βœ”οΈ + ``offset`` 1.9.0 βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getNowPlaying: + +``getNowPlaying`` + βœ”οΈ + + No parameter + +.. _getStarred: + +``getStarred`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getStarred2: + +``getStarred2`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Searching +^^^^^^^^^ + +.. _search-: + +``search`` + βœ”οΈ + + ============= ===== = + Parameter Vers. + ============= ===== = + ``artist`` βœ”οΈ + ``album`` βœ”οΈ + ``title`` βœ”οΈ + ``any`` βœ”οΈ + ``count`` βœ”οΈ + ``offset`` βœ”οΈ + ``newerThan`` βœ”οΈ + ============= ===== = + +.. _search2: + +``search2`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _search3: + +``search3`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Playlists +^^^^^^^^^ + +.. _getPlaylists: + +``getPlaylists`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getPlaylist: + +``getPlaylist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _createPlaylist: + +``createPlaylist`` + βœ”οΈ + + ============== ===== = + Parameter Vers. + ============== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``songId`` βœ”οΈ + ============== ===== = + +.. _updatePlaylist: + +``updatePlaylist`` + βœ”οΈ + + ===================== ===== = + Parameter Vers. + ===================== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``comment`` βœ”οΈ + ``public`` 1.9.0 βœ”οΈ + ``songIdToAdd`` βœ”οΈ + ``songIndexToRemove`` βœ”οΈ + ===================== ===== = + +.. _deletePlaylist: + +``deletePlaylist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +Media retrieval +^^^^^^^^^^^^^^^ + +.. _stream: + +``stream`` + βœ”οΈ + + ========================= ====== = + Parameter Vers. + ========================= ====== = + ``id`` βœ”οΈ + ``maxBitRate`` βœ”οΈ + ``format`` βœ”οΈ + ``timeOffset`` ❌ + ``size`` ❌ + ``estimateContentLength`` βœ”οΈ + ``converted`` 1.15.0 πŸ”΄ + ========================= ====== = + +.. _download: + +``download`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _hls: + +``hls`` + πŸ”΄ 1.9.0 + + ============== ====== = + Parameter Vers. + ============== ====== = + ``id`` 1.9.0 πŸ”΄ + ``bitRate`` 1.9.0 πŸ”΄ + ``audioTrack`` 1.15.0 πŸ”΄ + ============== ====== = + +.. _getCaptions: + +``getCaptions`` + πŸ”΄ 1.15.0 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``id`` 1.15.0 πŸ”΄ + ``format`` 1.15.0 πŸ”΄ + ========== ====== = + +.. _getCoverArt: + +``getCoverArt`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ``size`` βœ”οΈ + ========= ===== = + +.. _getLyrics: + +``getLyrics`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``artist`` βœ”οΈ + ``title`` βœ”οΈ + ========== ===== = + +.. _getAvatar: + +``getAvatar`` + ❌ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` ❌ + ============ ===== = + +Media annotation +^^^^^^^^^^^^^^^^ + +.. _star: + +``star`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _unstar: + +``unstar`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _setRating: + +``setRating`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``id`` βœ”οΈ + ``rating`` βœ”οΈ + ========== ===== = + +.. _scrobble: + +``scrobble`` + βœ”οΈ + + ============== ===== = + Parameter Vers. + ============== ===== = + ``id`` βœ”οΈ + ``time`` 1.9.0 βœ”οΈ + ``submission`` βœ”οΈ + ============== ===== = + +Sharing +^^^^^^^ + +.. _getShares: + +``getShares`` + ❌ + + No parameter + +.. _createShare: + +``createShare`` + ❌ + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _updateShare: + +``updateShare`` + ❌ + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _deleteShare: + +``deleteShare`` + ❌ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` ❌ + ========= ===== = + +Podcast +^^^^^^^ + +.. _getPodcasts: + +``getPodcasts`` + ❔ + + =================== ===== = + Parameter Vers. + =================== ===== = + ``includeEpisodes`` 1.9.0 ❔ + ``id`` 1.9.0 ❔ + =================== ===== = + +.. _getNewestPodcasts: + +``getNewestPodcasts`` + ❔ 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``count`` 1.14.0 ❔ + ========= ====== = + +.. _refreshPodcasts: + +``refreshPodcasts`` + ❔ 1.9.0 + + No parameter + +.. _createPodcastChannel: + +``createPodcastChannel`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``url`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastChannel: + +``deletePodcastChannel`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastEpisode: + +``deletePodcastEpisode`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _downloadPodcastEpisode: + +``downloadPodcastEpisode`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +Jukebox +^^^^^^^ + +.. _jukeboxControl: + +``jukeboxControl`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``action`` βœ”οΈ + ``index`` βœ”οΈ + ``offset`` βœ”οΈ + ``id`` βœ”οΈ + ``gain`` ❌ + ========== ===== = + +Internet radio +^^^^^^^^^^^^^^ + +.. _getInternetRadioStations: + +``getInternetRadioStations`` + ❔ 1.9.0 + + No parameter + +.. _createInternetRadioStation: + +``createInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _updateInternetRadioStation: + +``updateInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _deleteInternetRadioStation: + +``deleteInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + =============== ====== = + +Chat +^^^^ + +.. _getChatMessages: + +``getChatMessages`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``since`` βœ”οΈ + ========= ===== = + +.. _addChatMessage: + +``addChatMessage`` + βœ”οΈ + + =========== ===== = + Parameter Vers. + =========== ===== = + ``message`` βœ”οΈ + =========== ===== = + +User management +^^^^^^^^^^^^^^^ + +.. _getUser: + +``getUser`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getUsers: + +``getUsers`` + βœ”οΈ 1.9.0 + + No parameter + +.. _createUser: + +``createUser`` + βœ”οΈ + + ======================= ====== = + 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 + + ======================= ====== = + 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`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _changePassword: + +``changePassword`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ``password`` βœ”οΈ + ============ ===== = + +Bookmarks +^^^^^^^^^ + +.. _getBookmarks: + +``getBookmarks`` + ❔ 1.9.0 + + No parameter + +.. _createBookmark: + +``createBookmark`` + ❔ 1.9.0 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` 1.9.0 ❔ + ``position`` 1.9.0 ❔ + ``comment`` 1.9.0 ❔ + ============ ===== = + +.. _deleteBookmark: + +``deleteBookmark`` + ❔ 1.9.0 + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` 1.9.0 ❔ + =============== ===== = + +.. _getPlayQueue: + +``getPlayQueue`` + ❔ 1.12.0 + + No parameter + +.. _savePlayQueue: + +``savePlayQueue`` + ❔ 1.12.0 + + ============ ====== = + 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/cli.md b/docs/cli.md deleted file mode 100644 index 7e5ee36..0000000 --- a/docs/cli.md +++ /dev/null @@ -1,74 +0,0 @@ -# Command line interface - -The command-line interface (often abbreviated CLI) is an interface allowing -administration operations without the use of the web interface. It can either -be run in interactive mode (`supysonic-cli`) or to issue a single command -(`supysonic-cli `). - -If ran without arguments, `supysonic-cli` will open an interactive prompt. You -can use the command line tool to do a few things: - -## Help commands - -Whenever you are lost - -``` -Usage: - supysonic-cli help - supysonic-cli help user - supysonic-cli help folder - -Arguments: - user Display the help message for the user command - folder Display the help message for the folder command -``` - -## User management commands - -``` -Usage: - supysonic-cli user add [-p ] [-e ] - supysonic-cli user delete - supysonic-cli user changepass - supysonic-cli user list - supysonic-cli user setroles [-a|-A] [-j|-J] - -Arguments: - add Add a new user - delete Delete the user - changepass Change the user's password - list List all the users - setroles Give or remove rights to the user - -Options: - -p --password Specify the user's password - -e --email Specify the user's email - -a --noadmin Revoke admin rights - -A --admin Grant admin rights - -j --nojukebox Revoke jukebox rights - -J --jukebox Grant jukebox rights -``` - -## Folder management commands - -``` -Usage: - supysonic-cli folder add - supysonic-cli folder delete - supysonic-cli folder list - supysonic-cli folder scan [-f] [--background | --foreground] [...] - -Arguments: - add Add a new folder - delete Delete a folder - list List all the folders - scan Scan all or specified folders - -Options: - -f --force Force scan of already known files even if they - haven't changed - --background Scan in the background. Requires the daemon to - be running. - --foreground Scan in the foreground, blocking the process - while the scan is running -``` diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..fd69c42 --- /dev/null +++ b/docs/conf.py @@ -0,0 +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 = [] + +# 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/configuration.md b/docs/configuration.md deleted file mode 100644 index ecdbe60..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,250 +0,0 @@ -# Configuration - -_Supysonic_ looks for four files for its configuration: `/etc/supysonic`, -`~/.supysonic`, `~/.config/supysonic/supysonic.conf` and `supysonic.conf` in -the current folder, 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. - -You'll find a roughly documented configuration sample file at the root of the -project, file conveniently named `config.sample`. More details below. - -There are six sections in the configuration: -- [base](#base-section): defines the database and additional scanning config -- [webapp](#webapp-section): configuration relative to the HTTP server -- [daemon](#daemon-section): configuration for the scanning file watcher -- [lastfm](#lastfm-section): keys to enable Last.FM scrobbling -- [transcoding](#transcoding-section): defines transcoding programs -- [mimetypes](#mimetypes-section): some file extension to mimetype mappings - -## `[base]` section - -`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. - -```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 that 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 -`/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. - -```ini -[base] -; A database URI. See the 'schema' folder for schema creation scripts -; 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 - -`cache_dir`: directory used to store generated files, such as resized cover -art or transcoded files. Defaults to `/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` and -`CRITICAL`. Defaults to `WARNING`. - -`mount_api`: [`on`/`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`/`off`] enable or disable the administrative web interface. -Note that 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`. - -```ini -[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]` section - -`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: /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 [jukebox documentation](jukebox.md) 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` and -`CRITICAL`. Defaults to `WARNING`. - -```ini -[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 - -```ini -[lastfm] -; API and secret key to enable scrobbling. http://www.last.fm/api/accounts -; Defaults: none -;api_key = -;secret = -``` - -## `[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 -[transcoding configuration](transcoding.md). - -```ini -[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 - -```ini -[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/index.rst b/docs/index.rst new file mode 100644 index 0000000..7ec46f8 --- /dev/null +++ b/docs/index.rst @@ -0,0 +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 diff --git a/docs/jukebox.md b/docs/jukebox.md deleted file mode 100644 index 5d3a0b8..0000000 --- a/docs/jukebox.md +++ /dev/null @@ -1,43 +0,0 @@ -# Jukebox - -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. - -The daemon must be running in order to be able to use the jukebox mode. So be -sure to start the `supysonic-daemon` command and keep it running. A basic -_systemd_ service file can be found at the root of the project folder. - -## 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 `[daemon]` section of the -[configuration file](configuration.md), 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 [CLI](cli.md): - -``` -$ supysonic-cli user setroles --jukebox -``` diff --git a/docs/jukebox.rst b/docs/jukebox.rst new file mode 100644 index 0000000..30f9bf7 --- /dev/null +++ b/docs/jukebox.rst @@ -0,0 +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 diff --git a/docs/man/index.rst b/docs/man/index.rst new file mode 100644 index 0000000..a5d55bc --- /dev/null +++ b/docs/man/index.rst @@ -0,0 +1,18 @@ +Man pages +========= + +.. rubric:: Command-line interface + +.. toctree:: + :maxdepth: 2 + + supysonic-cli + supysonic-cli-user + supysonic-cli-folder + +.. rubric:: Daemon + +.. toctree:: + :maxdepth: 2 + + supysonic-daemon diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 9d0dee5..d41dca0 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -6,50 +6,72 @@ supysonic-cli-folder Supysonic folder management commands ------------------------------------ -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli folder **add** -| supysonic-cli folder **delete** -| supysonic-cli folder **list** -| supysonic-cli folder **scan** [-f] [--background | --foreground] [...] +| ``supysonic-cli folder list`` +| ``supysonic-cli folder add`` `name` `path` +| ``supysonic-cli folder delete`` `name` +| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... -Arguments -========= +Description +=========== -| **add** Add a new folder -| **delete** Delete a folder -| **list** List all the folders -| **scan** Scan all or specified folders +The ``supysonic-cli folder`` subcommand manages your library folders, where the +audio files are located. This allows to list, add, delete and scan the folders. + +``supysonic-cli folder list`` + List all the folders. + +``supysonic-cli folder add`` `name` `path` + Add a new library folder called `name` and located at `path`. `name` must be + unique and `path` pointing to an existing directory. If ``supysonic-daemon`` + is running it will start to listen for changes in this folder but will not + scan files already present in the folder. + +``supysonic-cli folder delete`` `name` + Delete the folder called `name`. + +``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... + Scan the specified folders. If none is given, all the registered folders are + scanned. Options ======= -| **-f** | **--force** -|     Force scan of already known files even if they haven't changed +-f, --force + Force scan of already known files even if they haven't changed. Might be + useful if an update to Supysonic adds new metadata to audio files. -| **--background** -|     Scan in the background. Requires the daemon to be running +--background + Scan in the background. Requires the ``supysonic-daemon`` to be running -| **--foreground** -|     Scan in the foreground, blocking the process while the scan is running +--foreground + Scan in the foreground, blocking the process while the scan is running + +If neither ``--background`` nor ``--foreground`` is provided, ``supysonic-cli`` +will try to connect to the daemon to initiate a background scan, falling back to +a foreground scan if it isn't available. Examples ======== To add a new folder to your music library, you can do something like this:: - $ supysonic-cli folder add MyLibrary /home/username/Music + $ supysonic-cli folder add MyLibrary /home/username/Music Once you've added a folder, you will need to scan it:: - $ supysonic-cli folder scan MyLibrary + $ supysonic-cli folder scan MyLibrary + +The audio files residing in `/home/username/Music` will now appear under the +`MyLibrary` folder on the clients. See Also ======== -supysonic-cli(1), supysonic-cli-user(1) +``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1) diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index 33096cc..b4f51d5 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -6,58 +6,80 @@ supysonic-cli-user Supysonic user management commands ---------------------------------- -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli user **add** [-p ] [-e ] -| supysonic-cli user **delete** -| supysonic-cli user **changepass** -| supysonic-cli user **list** -| supysonic-cli user **setroles** [-a|-A] [-j|-J] +| ``supysonic-cli user list`` +| ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] +| ``supysonic-cli user delete`` `user` +| ``supysonic-cli user changepass`` `user` `password` +| ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` -Arguments -========= +Description +=========== -| **add** Add a new user -| **delete** Delete the user -| **changepass** Change the user's password -| **list** List all the users -| **setroles** Give or remove rights to the user +The ``supysonic-cli user`` subcommand manages users, allowing to list them, add +a new user, delete an existing user, and change their password or roles. + +``supysonic-cli user list`` + List all the users. + +``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] + Add a new user named `user`. Will prompt for a password if it isn't given + with the ``--password`` option. + +``supysonic-cli user delete`` `user` + Delete the user `user`. + +``supysonic-cli user changepass`` `user` [`password`] + Change the password of user `user`. Will prompt for the new password if not + provided. + +``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` + Give or remove rights to user `user`. Options ======= -| **-p** | **--password** ** -|     Specify the user's password +-p password, --password password + Specify the user's password upon creation. -| **-e** | **--email** ** -|     Specify the user's email +-e email, --email email + Specify the user's email. -| **-a** | **--noadmin** -|     Revoke admin rights +The next options relate to user roles. They work in pairs, one option granting +a right while the other revokes it; obviously options of the same pair are +mutually exclusive. The long options are named with the matching right, prefix +it with a ``no`` to revoke the right. For short options, the upper case letter +grants the right while the lower case letter revokes it. Short options might be +combined into a single one such as ``-aJ`` to both revoke the admin right and +grant the jukebox one. -| **-A** | **--admin** -|     Grant admin rights +-A, --admin + Grant admin rights. -| **-j** | **--nojukebox** -|     Revoke jukebox rights +-a, --noadmin + Revoke admin rights. -| **-J** | **--jukebox** -|     Grant jukebox rights +-J, --jukebox + Grant jukebox rights. + +-j, --nojukebox + Revoke jukebox rights. Examples ======== -To add a new admin user:: +To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: - $ supysonic-cli user add MyUserName -p MyAwesomePassword - $ supysonic-cli user setroles -A MyUserName + $ supysonic-cli user add MyUserName -p MyAwesomePassword + $ supysonic-cli user setroles -A MyUserName See Also ======== -supysonic-cli(1), supysonic-cli-folder(1) +``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/man/supysonic-cli.rst b/docs/man/supysonic-cli.rst index d9d71b3..a19de78 100644 --- a/docs/man/supysonic-cli.rst +++ b/docs/man/supysonic-cli.rst @@ -6,25 +6,21 @@ supysonic-cli Python implementation of the Subsonic server API ------------------------------------------------ -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli [**subcommand**] -| supysonic-cli **help** -| supysonic-cli **help** *user* -| supysonic-cli **help** *folder* +| ``supysonic-cli`` [`subcommand`] +| ``supysonic-cli help`` [`subcommand`] Description =========== -| supysonic is a Python implementation of the Subsonic server API. -| Current supported features are: - -| +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 @@ -33,34 +29,41 @@ Description | * cover arts (as image files in the same folder as music files) | * starred tracks/albums and ratings | * Last.FM scrobbling +| * Jukebox mode -| The "Subsonic API" is a set of adhoc standards to browse, stream or -| download a music collection over HTTP. +The "Subsonic API" is a set of adhoc standards to browse, stream or download a +music collection over HTTP. + +The command-line interface is an interface allowing administration operations +without the use of the web interface. If ran without arguments, +``supysonic-cli`` will open an interactive prompt, with arguments it will run +a single command and exit. Subcommands =========== -| If ran without arguments, **supysonic-cli** will open an interactive -| prompt. +``supysonic-cli`` has three different subcommands: -**supysonic-cli** has three different subcommands: +``help`` [`subcommand`] + When used without argument, displays the list of available subcommands. With + an argument, shows the help and arguments for the given subcommand. -| +``user`` `args` ... + User management commands -| * help -| * user -| * folder +``folder`` `args` ... + Folder managemnt commands -| For more details on the **user** and **folder** subcommands, see the -| subsonic-cli-user(1), subsonic-cli-folder(1) manual pages. +For more details on the ``user`` and ``folder`` subcommands, see the +``subsonic-cli-user``\ (1), ``subsonic-cli-folder``\ (1) manual pages. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli-user(1), supysonic-cli-folder(1) +``supysonic-cli-user``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/man/supysonic-daemon.rst b/docs/man/supysonic-daemon.rst index d343e29..39acd79 100644 --- a/docs/man/supysonic-daemon.rst +++ b/docs/man/supysonic-daemon.rst @@ -2,37 +2,41 @@ supysonic-daemon ================ ------------------------- -Supysonic scanner daemon ------------------------- +--------------------------- +Supysonic background daemon +--------------------------- -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-daemon +``supysonic-daemon`` Description =========== -| **supysonic-daemon** is an optional non-exiting process made to be ran in the -| background to manage background scans and library changes detection. +``supysonic-daemon`` is an optional non-exiting process made to be ran in the +background to manage background scans, library changes detection and the jukebox +mode (audio played on the server hardware). -| If **supysonic-daemon** is running when you start a manual scan using -| **supysonic-cli(1)**, the scan will be run by the daemon process in the -| background instead of running in the foreground. This daemon also enables the -| web UI scan feature. +If ``supysonic-daemon`` is running when you start a manual scan using +``supysonic-cli``\ (1), the scan will be run by the daemon process in the +background instead of running in the foreground. This daemon also enables the +web UI scan feature. + +With proper configuration, ``supysonic-daemon`` also allows authorized users to +play audio on the machine's hardware, using their client as a remote control. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli(1) +``supysonic-cli``\ (1) diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst new file mode 100644 index 0000000..8f536ba --- /dev/null +++ b/docs/setup/configuration.rst @@ -0,0 +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 diff --git a/docs/setup/daemon.rst b/docs/setup/daemon.rst new file mode 100644 index 0000000..30d6003 --- /dev/null +++ b/docs/setup/daemon.rst @@ -0,0 +1,59 @@ +The daemon +========== + +Supysonic comes with an optional daemon service that currently provides the +following features: + +- background scans +- library changes detection +- jukebox mode + +Background scans +---------------- + +First of all, the daemon allows running backgrounds scans, meaning you can start +scans from the :doc:`command-line interface <../man/supysonic-cli>` and do +something else while it's scanning (otherwise the scan will block the CLI until +it's done). Background scans also enable the web UI to run scans, while you have +to use the CLI to do so if you don't run the daemon. + +Library watching +---------------- + +Instead of manually running a scan every time your library changes, the daemon +can listen to any library change and update the database accordingly. This +watcher is started along with the daemon but can be disabled to only keep +background scans. Please refer to :ref:`conf-daemon` of the configuration to +enable or disable it. + +Jukebox +------- + +Finally, the daemon acts as a backend for the jukebox mode, allowing to play +audio on the machine running Supysonic. More details on the :doc:`../jukebox` +page. + +Running it +---------- + +The daemon is :doc:`../man/supysonic-daemon`, it is a non-exiting process. +If you want to keep it running in background, either use the old +:command:`nohup` or :command:`screen` methods, or start it as a systemd unit. + +Below is a basic service file to load it through systemd. Modify it to match +your installation and save it as +:file:`/etc/systemd/system/supysonic-daemon.service`. + +.. code-block:: ini + + [Unit] + Description=Supysonic Daemon + + [Service] + User=someuser + Group=somegroup + WorkingDirectory=/home/supysonic + ExecStart=/usr/bin/python3 -m supysonic.daemon + + [Install] + WantedBy=multi-user.target diff --git a/docs/setup/database.rst b/docs/setup/database.rst new file mode 100644 index 0000000..71dc9e9 --- /dev/null +++ b/docs/setup/database.rst @@ -0,0 +1,39 @@ +Database setup +============== + +Supysonic needs a database to run. It can either be a SQLite, MySQL-compatible +or PostgreSQL database. + +If you absolutely have no clue about databases, you can go with SQLite as it +doesn't need any setup other than specifying a path for the database in the +:doc:`configuration `. + +.. note:: + + SQLite, while being a viable option, isn't recommended for large + installations. First of all its performance *might* start to decrease as the + size of your library grows. But most importantly if you have a lot of users + reaching the instance at the same time you will start to see the performance + drop, or even errors. + +Please refer to the documentation of the DBMS you've chosen on how to create a +database. Once it has a database, Supysonic will automatically create the +tables it needs and keep the schema up-to-date. + +The PostgreSQL case +------------------- + +If you want to use PostgreSQL you'll have to add the ``citext`` extension to the +database once created. This can be done when connected to the database as the +superuser. How to connect as a superuser might change depending on your +PostgreSQL installation (this is **not** the same thing as the OS superuser +known as *root* on Linux systems). + +On a Debian-based system you can connect as a superuser by invoking +:command:`psql` while being logged in as the *postgres* user. The following +commands will install the ``citext`` extension on the database named *supysonic* +assuming you are currently logged as *root*. :: + + # su - postgres + $ psql supysonic + supysonic=# CREATE EXTENSION citext; diff --git a/docs/setup/deploying/apache.rst b/docs/setup/deploying/apache.rst new file mode 100644 index 0000000..2f8eebb --- /dev/null +++ b/docs/setup/deploying/apache.rst @@ -0,0 +1,56 @@ +Apache and mod_wsgi +=================== + +If you are using the `Apache`__ webserver, you can use it to run Supysonic with +the help of `mod_wsgi`__. + +__ https://httpd.apache.org/ +__ https://github.com/GrahamDumpleton/mod_wsgi + +Installing `mod_wsgi` +--------------------- + +If you don't have `mod_wsgi` installed yet you have to install it and enable it +first as follows:: + + # apt install libapache2-mod-wsgi-py3 + # a2enmod wsgi + +Creating a `.wsgi` file +----------------------- + +To run Supysonic within Apache you need a :file:`supysonic.wsgi` file. Create +one somewhere and fill it with the following content: + +.. code-block:: python3 + + from supysonic.web import create_application + application = create_application() + +Store that file somewhere that you will find it again (e.g.: +:file:`/var/www/supysonic/supysonic.wsgi`). + +Configuring Apache +------------------ + +The last thing you have to do is to edit the Apache configuration to tell it to +load the application. Here's a basic example of what it looks like: + +.. code-block:: apache + + WSGIScriptAlias /supysonic /var/www/supysonic/supysonic.wsgi + + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + Require all granted + + +With that kind of configuration, the server address will look like +`http://server/supysonic/`. + +For more information consult the `mod_wsgi documentation`__. Note that the +``WSGIPassAuthorization`` directive is required for some clients as they provide +their credentials using the *basic access authentification* mechanism rather +than as URL query parameters. + +__ https://modwsgi.readthedocs.io/en/latest/ diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst new file mode 100644 index 0000000..79b4502 --- /dev/null +++ b/docs/setup/deploying/index.rst @@ -0,0 +1,22 @@ +Running the web server +====================== + +Once Supysonic is installed and configured, you'll have to start its web server +for the clients to be able to access the music. Here you have several options, +whether you want to run it as independant process(es), then possibly putting it +behind a reverse proxy, or running it as a WSGI application within Apache. + +You'll find some common (and less common) deployment option below: + +.. toctree:: + :maxdepth: 2 + + wsgi-standalone + apache + other + +As Supysonic is a WSGI application, you have numerous deployment options +available to you. If you want to deploy it to a WSGI server not listed here, +look up the server documentation about how to use a WSGI app with it. When +setting one of those, you'll want to call the :py:func:`create_application` +factory function from module :py:mod:`supysonic.web`. diff --git a/docs/setup/deploying/other.rst b/docs/setup/deploying/other.rst new file mode 100644 index 0000000..90fa449 --- /dev/null +++ b/docs/setup/deploying/other.rst @@ -0,0 +1,102 @@ +Other options +============= + +FastCGI +------- + +FastCGI is a deployment option on servers like `nginx`__ or `lighttpd`__; see +:doc:`wsgi-standalone` for other options. +To use Supysonic with any of them you will need a FastCGI server first. The most +popular one is `flup`__ which we will use for this guide. Make sure to have it +installed (with eith :command:`pip` or :command:`apt`) to follow along. + +__ https://nginx.org/ +__ https://www.lighttpd.net/ +__ https://pypi.org/project/flup/ + +Creating a `.fcgi` file +^^^^^^^^^^^^^^^^^^^^^^^ + +First you need to create the FastCGI server file. Let's call it +:file:`supysonic.fcgi`: + +.. code-block:: python3 + + #!/usr/bin/python3 + + from flup.server.fcgi import WSGIServer + from supysonic.web import create_application + + if __name__ == "__main__": + app = create_application() + WSGIServer(app).run() + +This should be enough for Apache to work, however nginx and older versions of +lighttpd need a socket to be explicitly passed to communicate with the +FastCGI server. For that to work you need to pass the path to the socket +to the :py:class:`~flup.server.fcgi.WSGIServer`: + +.. code-block:: python3 + + WSGIServer(app, bindAddress="/path/to/fcgi.sock").run() + +The path has to be the exact same path you define in the server +config. + +Save the :file:`supysonic.fcgi` file somewhere you will find it again. +It makes sense to have that in :file:`/var/www/supysonic` or something +similar. + +Make sure to set the executable bit on that file so that the servers +can execute it:: + + $ chmod +x /var/www/supysonic/supysonic.fcgi + +Configuring the web server +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The example above is good enough for a basic Apache deployment but your +`.fcgi` file will appear in your application URL e.g. +``example.com/supysonic.fcgi/``. If that bothers you or you wish to load it in +another web server, Flask's documentation details how to do it for `Apache`__, +`lighttpd`__ or `nginx`__. + +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-apache +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-lighttpd +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-nginx + +CGI +--- + +If all other deployment methods do not work, CGI will work for sure. +CGI is supported by all major servers but usually has a sub-optimal +performance. + +Creating a `.cgi` file +^^^^^^^^^^^^^^^^^^^^^^ + +First you need to create the CGI application file. Let's call it +:file:`supysonic.cgi`: + +.. code-block:: python3 + + #!/usr/bin/python3 + + from wsgiref.handlers import CGIHandler + from supysonic.web import create_application + + app = create_application() + CGIHandler().run(app) + +Server Setup +^^^^^^^^^^^^ + +Usually there are two ways to configure the server. Either just copy the +``.cgi`` into a :file:`cgi-bin` (and use `mod_rewrite` or something similar to +rewrite the URL) or let the server point to the file directly. + +In Apache for example you can put something like this into the config: + +.. code-block:: apache + + ScriptAlias /supysonic /path/to/the/supysonic.cgi diff --git a/docs/setup/deploying/wsgi-standalone.rst b/docs/setup/deploying/wsgi-standalone.rst new file mode 100644 index 0000000..d7fab3d --- /dev/null +++ b/docs/setup/deploying/wsgi-standalone.rst @@ -0,0 +1,61 @@ +Standalone WSGI Containers +========================== + +There are popular servers written in Python that contain WSGI applications and +serve HTTP. These servers stand alone when they run; you can let your clients +access them directly or proxy to them from your web server such as Apache +or nginx. + +Gunicorn +-------- + +`Gunicorn`__ "Green Unicorn" is a WSGI HTTP Server for UNIX. It's a pre-fork +worker model. Running Supysonic on this server is quite simple. First install +Gunicorn with either :command:`pip install gunicorn` or +:command:`apt install gunicorn3` (the ``gunicorn`` package in this case is +for Python 2 which isn't supported anymore). Then:: + + $ gunicorn "supysonic.web:create_application()" + +But this will only listen on the loopback interface, which isn't really useful. + +Gunicorn provides many command-line options -- see :command:`gunicorn -h`. +For example, to run Supysonic with 4 worker processes (``-w 4``) binding to all +IPv4 interfaces on port 5000 (``-b 0.0.0.0:5000``):: + + $ gunicorn -w 4 -b 0.0.0.0:5000 "supysonic.web:create_application()" + +__ https://gunicorn.org/ + +uWSGI +----- + +`uWSGI`__ is a fast application server written in C. It is very configurable +which makes it more complicated to setup than gunicorn. + +To use it, install the package ``uwsgi`` with either :command:`pip` or +:command:`apt`. Using the later, wou might also need the additional package +``uwsgi-plugin-python3``. + +Then to run Supysonic in uWSGI:: + + $ uwsgi --http-socket 0.0.0.0:5000 --module "supysonic.web:create_application()" + +If it complains about an unknown ``--module`` option, try adding +``--plugin python3``:: + + $ uwsgi --http-socket 0.0.0.0:5000 --plugin python3 --module "supysonic.web:create_application()" + +As uWSGI is highly configurable there are several options you could use to tweak +it to your liking. Detailing all it can do is way beyond the scope of this +documentation, if you're interested please refer to its documentation. + +If you plan on using uWSGI behind a nginx reverse proxy, note that nginx +provides options to integrate directly with uWSGI. You'll find an example +configuration in `Flask's documentation`__ (the framework Supysonic is built +upon). Replace the ``myapp:app`` in their example by +``supysonic.web:create_application()`` (you might need to enclose it in +double-quotes). + +__ https://uwsgi-docs.readthedocs.io/en/latest/ +__ https://flask.palletsprojects.com/en/1.1.x/deploying/uwsgi/ diff --git a/docs/setup/index.rst b/docs/setup/index.rst new file mode 100644 index 0000000..610c25f --- /dev/null +++ b/docs/setup/index.rst @@ -0,0 +1,43 @@ +Supysonic setup +=============== + +This guide details the required steps to get a Supysonic instance ready to +start serving your music. + +.. rubric:: TL;DR + +For the impatient, here's a quick summary to get Supysonic installed and ready +to start serving (but this doesn't create any user nor specifies where your +music is located 😏). This uses `gunicorn`__, but there are +:doc:`other options `. + +:: + + pip install git+https://github.com/spl0k/supysonic.git + pip install gunicorn + gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" + +__ https://gunicorn.org/ + +.. rubric:: Table of contents + +.. toctree:: + :maxdepth: 2 + + install + database + configuration + deploying/index + daemon + +.. _docker: + +.. rubric:: Docker + +Another solution rather than going through the whole setup process yourself is +to use a ready-to-use Docker image. While we don't provide images for Supysonic, +that didn't keep the community from creating some. Take a look on the +`Docker Hub`__ and pick one you like. For more details on their usage, please +refer to the readme of said images. + +__ https://hub.docker.com/search?q=supysonic&type=image diff --git a/docs/setup/install.rst b/docs/setup/install.rst new file mode 100644 index 0000000..9482c9e --- /dev/null +++ b/docs/setup/install.rst @@ -0,0 +1,94 @@ +Installing Supysonic +==================== + +Supysonic is written in Python and supports Python 3.5+. + +Linux +----- + +Currently, only Debian-based distributions might provide Supysonic in their +package repositories. Install the package ``supysonic`` using :command:`apt`:: + + $ apt install supysonic + +This will install Supysonic along with the minimal dependencies it needs to +run. + +.. note:: + + As of January 2021, Supysonic only reached Debian's *testing* release. If + you're using the *stable* release it might not be available in the packages + yet. + +If you plan on using it with a MySQL or PostgreSQL database you also need the +corresponding Python package, ``python-pymysql`` for MySQL or +``python-psycopg2`` for PostgreSQL. + +:: + + $ apt install python-pymysql + +:: + + $ apt install python-psycopg2 + +For other distributions, you might consider installing from :ref:`docker` images +or from `source`_. + +Windows +------- + +.. note:: + While Supysonic hasn't been thoroughly tested on Windows, it *should* work. + If something is broken, we're really sorry. Don't hesitate to `open an + issue`__ on GitHub. + + __ https://github.com/spl0k/supysonic/issues + +Most Windows users do not have Python installed by default, so we begin with +the installation of Python itself. To check if you already have Python +installed, open the *Command Prompt* (:kbd:`Win-R` and type :command:`cmd`). +Once the command prompt is open, type :command:`python --version` and press +Enter. If Python is installed, you will see the version of Python printed to +the screen. If you do not have Python installed, refer to the `Hitchhikers +Guide to Python's`__ Python on Windows installation guides. You must install +`Python 3`__. + +Once Python is installed, you can install Supysonic using :command:`pip`. Refer +to the `source installation instructions `_ below for more information. + +__ https://docs.python-guide.org/ +__ https://docs.python-guide.org/starting/install3/win/ + +.. _source: + +Source +------ + +You can install Supysonic directly from a clone of the `Git repository`__. This +can be done either by cloning the repo and installing from the local clone:: + + $ git clone https://github.com/spl0k/supysonic.git + $ cd supysonic + $ pip install . + +or simply installing directly via :command:`pip`:: + + $ pip install git+https://github.com/spl0k/supysonic.git + +This will install Supysonic along with the minimal dependencies it needs to +run. + +If you plan on using it with a MySQL or PostgreSQL database you also need the +corresponding package, ``pymysql`` for MySQL or ``psycopg2-binary`` for +PostgreSQL. + +:: + + $ pip install pymysql + +:: + + $ pip install psycopg2-binary + +__ https://github.com/spl0k/supysonic diff --git a/docs/transcoding.md b/docs/transcoding.md deleted file mode 100644 index 9b9fa28..0000000 --- a/docs/transcoding.md +++ /dev/null @@ -1,105 +0,0 @@ -# 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 `[transcoding]` section of the -[configuration file](configuration.md). - -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. - -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: - -1. specific transcoder -2. specific decoder / specific encoder -3. generic decoder / generic encoder (with the possibility to use a generic - decoder with a specific encoder, and vice-versa) -4. 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. - -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. - -## Suggested configuration - -Here is an example configuration that you could use. This is provided as-is, -and some configurations haven't been tested. - -Basic configuration: -```ini -[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: -```ini -[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 -``` diff --git a/docs/transcoding.rst b/docs/transcoding.rst new file mode 100644 index 0000000..fe53410 --- /dev/null +++ b/docs/transcoding.rst @@ -0,0 +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.