github/supysonic
1
0
Fork 0
mirror of https://github.com/spl0k/supysonic.git synced 2024-09-19 19:01:03 +00:00
Code Issues Releases Wiki Activity

Merge branch 'docs'

Browse Source
This commit is contained in:
Alban Féron 2021-01-17 19:29:53 +01:00
commit 41f66b5e63
No known key found for this signature in database
GPG Key ID: 8CE0313646D16165
25 changed files with 2561 additions and 1479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Makefile Normal file
View File

@ -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)

917
docs/api.md
View File

@ -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`

1288
docs/api.rst Normal file
View File

File diff suppressed because it is too large Load Diff

74
docs/cli.md
View File

@ -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 <arguments>`).
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 <user> [-p <password>] [-e <email>]
supysonic-cli user delete <user>
supysonic-cli user changepass <user> <password>
supysonic-cli user list
supysonic-cli user setroles [-a|-A] [-j|-J] <user>
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 <password> Specify the user's password
-e --email <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 <name> <path>
supysonic-cli folder delete <name>
supysonic-cli folder list
supysonic-cli folder scan [-f] [--background | --foreground] [<name>...]
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
```

88
docs/conf.py Normal file
View File

@ -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,
),
]

250
docs/configuration.md
View File

@ -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&param2=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
```

29
docs/index.rst Normal file
View File

@ -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

43
docs/jukebox.md
View File

@ -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 <username>
```

45
docs/jukebox.rst Normal file
View File

@ -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 <man/supysonic-cli-user>`::
$ supysonic-cli user setroles --jukebox <username>

18
docs/man/index.rst Normal file
View File

@ -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

60
docs/man/supysonic-cli-folder.rst
View File

@ -6,37 +6,56 @@ 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** <name> <path>
| supysonic-cli folder **delete** <name>
| supysonic-cli folder **list**
| supysonic-cli folder **scan** [-f] [--background | --foreground] [<name>...]
| ``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
========
@ -49,7 +68,10 @@ Once you've added a folder, you will need to scan it::
$ 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)

78
docs/man/supysonic-cli-user.rst
View File

@ -6,53 +6,75 @@ 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** <user> [-p <password>] [-e <email>]
| supysonic-cli user **delete** <user>
| supysonic-cli user **changepass** <user> <password>
| supysonic-cli user **list**
| supysonic-cli user **setroles** [-a|-A] [-j|-J] <user>
| ``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** *<password>*
|     Specify the user's password
-p password, --password password
Specify the user's password upon creation.
| **-e** | **--email** *<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
@ -60,4 +82,4 @@ To add a new admin user::
See Also
========
supysonic-cli(1), supysonic-cli-folder(1)
``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1)

51
docs/man/supysonic-cli.rst
View File

@ -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)

34
docs/man/supysonic-daemon.rst
View File

@ -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)

308
docs/setup/configuration.rst Normal file
View File

@ -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&param2=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

59
docs/setup/daemon.rst Normal file
View File

@ -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

39
docs/setup/database.rst Normal file
View File

@ -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 <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;

56
docs/setup/deploying/apache.rst Normal file
View File

@ -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
<Directory /var/www/supysonic>
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On
Require all granted
</Directory>
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/

22
docs/setup/deploying/index.rst Normal file
View File

@ -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`.

102
docs/setup/deploying/other.rst Normal file
View File

@ -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

61
docs/setup/deploying/wsgi-standalone.rst Normal file
View File

@ -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/

43
docs/setup/index.rst Normal file
View File

@ -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 <deploying/index>`.
::
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

94
docs/setup/install.rst Normal file
View File

@ -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 <source_>`_ 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

105
docs/transcoding.md
View File

@ -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
```

148
docs/transcoding.rst Normal file
View File

@ -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.