mirror of
https://github.com/spl0k/supysonic.git
synced 2024-11-09 19:52:16 +00:00
Merge branch 'docs'
This commit is contained in:
Alban Féron
commit
41f66b5e63
20
docs/Makefile
Normal file
20
docs/Makefile
Normal 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
917
docs/api.md
@ -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
1288
docs/api.rst
Normal file
File diff suppressed because it is too large
Load Diff
74
docs/cli.md
74
docs/cli.md
@ -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
88
docs/conf.py
Normal 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,
|
||||||
|
),
|
||||||
|
]
|
||||||
@ -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
|
|
||||||
```
|
|
||||||
|
|
||||||
29
docs/index.rst
Normal file
29
docs/index.rst
Normal 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
|
||||||
@ -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
45
docs/jukebox.rst
Normal 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
18
docs/man/index.rst
Normal 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
|
||||||
@ -6,50 +6,72 @@ supysonic-cli-folder
|
|||||||
Supysonic folder management commands
|
Supysonic folder management commands
|
||||||
------------------------------------
|
------------------------------------
|
||||||
|
|
||||||
:Author: Louis-Philippe Véronneau
|
:Author: Louis-Philippe Véronneau, Alban Féron
|
||||||
:Date: 2019
|
:Date: 2019, 2021
|
||||||
:Manual section: 1
|
:Manual section: 1
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
========
|
========
|
||||||
|
|
||||||
| supysonic-cli folder **add** <name> <path>
|
| ``supysonic-cli folder list``
|
||||||
| supysonic-cli folder **delete** <name>
|
| ``supysonic-cli folder add`` `name` `path`
|
||||||
| supysonic-cli folder **list**
|
| ``supysonic-cli folder delete`` `name`
|
||||||
| supysonic-cli folder **scan** [-f] [--background | --foreground] [<name>...]
|
| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]...
|
||||||
|
|
||||||
Arguments
|
Description
|
||||||
=========
|
===========
|
||||||
|
|
||||||
| **add** Add a new folder
|
The ``supysonic-cli folder`` subcommand manages your library folders, where the
|
||||||
| **delete** Delete a folder
|
audio files are located. This allows to list, add, delete and scan the folders.
|
||||||
| **list** List all the folders
|
|
||||||
| **scan** Scan all or specified 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
|
Options
|
||||||
=======
|
=======
|
||||||
|
|
||||||
| **-f** | **--force**
|
-f, --force
|
||||||
| Force scan of already known files even if they haven't changed
|
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**
|
--background
|
||||||
| Scan in the background. Requires the daemon to be running
|
Scan in the background. Requires the ``supysonic-daemon`` to be running
|
||||||
|
|
||||||
| **--foreground**
|
--foreground
|
||||||
| Scan in the foreground, blocking the process while the scan is running
|
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
|
Examples
|
||||||
========
|
========
|
||||||
|
|
||||||
To add a new folder to your music library, you can do something like this::
|
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::
|
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
|
See Also
|
||||||
========
|
========
|
||||||
|
|
||||||
supysonic-cli(1), supysonic-cli-user(1)
|
``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1)
|
||||||
|
|||||||
@ -6,58 +6,80 @@ supysonic-cli-user
|
|||||||
Supysonic user management commands
|
Supysonic user management commands
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
:Author: Louis-Philippe Véronneau
|
:Author: Louis-Philippe Véronneau, Alban Féron
|
||||||
:Date: 2019
|
:Date: 2019, 2021
|
||||||
:Manual section: 1
|
:Manual section: 1
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
========
|
========
|
||||||
|
|
||||||
| supysonic-cli user **add** <user> [-p <password>] [-e <email>]
|
| ``supysonic-cli user list``
|
||||||
| supysonic-cli user **delete** <user>
|
| ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`]
|
||||||
| supysonic-cli user **changepass** <user> <password>
|
| ``supysonic-cli user delete`` `user`
|
||||||
| supysonic-cli user **list**
|
| ``supysonic-cli user changepass`` `user` `password`
|
||||||
| supysonic-cli user **setroles** [-a|-A] [-j|-J] <user>
|
| ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user`
|
||||||
|
|
||||||
Arguments
|
Description
|
||||||
=========
|
===========
|
||||||
|
|
||||||
| **add** Add a new user
|
The ``supysonic-cli user`` subcommand manages users, allowing to list them, add
|
||||||
| **delete** Delete the user
|
a new user, delete an existing user, and change their password or roles.
|
||||||
| **changepass** Change the user's password
|
|
||||||
| **list** List all the users
|
``supysonic-cli user list``
|
||||||
| **setroles** Give or remove rights to the user
|
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
|
Options
|
||||||
=======
|
=======
|
||||||
|
|
||||||
| **-p** | **--password** *<password>*
|
-p password, --password password
|
||||||
| Specify the user's password
|
Specify the user's password upon creation.
|
||||||
|
|
||||||
| **-e** | **--email** *<email>*
|
-e email, --email email
|
||||||
| Specify the user's email
|
Specify the user's email.
|
||||||
|
|
||||||
| **-a** | **--noadmin**
|
The next options relate to user roles. They work in pairs, one option granting
|
||||||
| Revoke admin rights
|
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**
|
-A, --admin
|
||||||
| Grant admin rights
|
Grant admin rights.
|
||||||
|
|
||||||
| **-j** | **--nojukebox**
|
-a, --noadmin
|
||||||
| Revoke jukebox rights
|
Revoke admin rights.
|
||||||
|
|
||||||
| **-J** | **--jukebox**
|
-J, --jukebox
|
||||||
| Grant jukebox rights
|
Grant jukebox rights.
|
||||||
|
|
||||||
|
-j, --nojukebox
|
||||||
|
Revoke jukebox rights.
|
||||||
|
|
||||||
Examples
|
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 add MyUserName -p MyAwesomePassword
|
||||||
$ supysonic-cli user setroles -A MyUserName
|
$ supysonic-cli user setroles -A MyUserName
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
========
|
========
|
||||||
|
|
||||||
supysonic-cli(1), supysonic-cli-folder(1)
|
``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1)
|
||||||
|
|||||||
@ -6,25 +6,21 @@ supysonic-cli
|
|||||||
Python implementation of the Subsonic server API
|
Python implementation of the Subsonic server API
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
|
||||||
:Author: Louis-Philippe Véronneau
|
:Author: Louis-Philippe Véronneau, Alban Féron
|
||||||
:Date: 2019
|
:Date: 2019, 2021
|
||||||
:Manual section: 1
|
:Manual section: 1
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
========
|
========
|
||||||
|
|
||||||
| supysonic-cli [**subcommand**]
|
| ``supysonic-cli`` [`subcommand`]
|
||||||
| supysonic-cli **help**
|
| ``supysonic-cli help`` [`subcommand`]
|
||||||
| supysonic-cli **help** *user*
|
|
||||||
| supysonic-cli **help** *folder*
|
|
||||||
|
|
||||||
Description
|
Description
|
||||||
===========
|
===========
|
||||||
|
|
||||||
| supysonic is a Python implementation of the Subsonic server API.
|
Supysonic is a Python implementation of the Subsonic server API.
|
||||||
| Current supported features are:
|
Current supported features are:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
||||||
| * browsing (by folders or tags)
|
| * browsing (by folders or tags)
|
||||||
| * streaming of various audio file formats
|
| * streaming of various audio file formats
|
||||||
@ -33,34 +29,41 @@ Description
|
|||||||
| * cover arts (as image files in the same folder as music files)
|
| * cover arts (as image files in the same folder as music files)
|
||||||
| * starred tracks/albums and ratings
|
| * starred tracks/albums and ratings
|
||||||
| * Last.FM scrobbling
|
| * Last.FM scrobbling
|
||||||
|
| * Jukebox mode
|
||||||
|
|
||||||
| The "Subsonic API" is a set of adhoc standards to browse, stream or
|
The "Subsonic API" is a set of adhoc standards to browse, stream or download a
|
||||||
| download a music collection over HTTP.
|
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
|
Subcommands
|
||||||
===========
|
===========
|
||||||
|
|
||||||
| If ran without arguments, **supysonic-cli** will open an interactive
|
``supysonic-cli`` has three different subcommands:
|
||||||
| prompt.
|
|
||||||
|
|
||||||
**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
|
``folder`` `args` ...
|
||||||
| * user
|
Folder managemnt commands
|
||||||
| * folder
|
|
||||||
|
|
||||||
| For more details on the **user** and **folder** subcommands, see the
|
For more details on the ``user`` and ``folder`` subcommands, see the
|
||||||
| subsonic-cli-user(1), subsonic-cli-folder(1) manual pages.
|
``subsonic-cli-user``\ (1), ``subsonic-cli-folder``\ (1) manual pages.
|
||||||
|
|
||||||
Bugs
|
Bugs
|
||||||
====
|
====
|
||||||
|
|
||||||
| Bugs can be reported to your distribution's bug tracker or upstream
|
Bugs can be reported to your distribution's bug tracker or upstream
|
||||||
| at https://github.com/spl0k/supysonic/issues.
|
at https://github.com/spl0k/supysonic/issues.
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
========
|
========
|
||||||
|
|
||||||
supysonic-cli-user(1), supysonic-cli-folder(1)
|
``supysonic-cli-user``\ (1), ``supysonic-cli-folder``\ (1)
|
||||||
|
|||||||
@ -2,37 +2,41 @@
|
|||||||
supysonic-daemon
|
supysonic-daemon
|
||||||
================
|
================
|
||||||
|
|
||||||
------------------------
|
---------------------------
|
||||||
Supysonic scanner daemon
|
Supysonic background daemon
|
||||||
------------------------
|
---------------------------
|
||||||
|
|
||||||
:Author: Louis-Philippe Véronneau
|
:Author: Louis-Philippe Véronneau, Alban Féron
|
||||||
:Date: 2019
|
:Date: 2019, 2021
|
||||||
:Manual section: 1
|
:Manual section: 1
|
||||||
|
|
||||||
Synopsis
|
Synopsis
|
||||||
========
|
========
|
||||||
|
|
||||||
| supysonic-daemon
|
``supysonic-daemon``
|
||||||
|
|
||||||
Description
|
Description
|
||||||
===========
|
===========
|
||||||
|
|
||||||
| **supysonic-daemon** is an optional non-exiting process made to be ran in the
|
``supysonic-daemon`` is an optional non-exiting process made to be ran in the
|
||||||
| background to manage background scans and library changes detection.
|
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
|
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
|
``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
|
background instead of running in the foreground. This daemon also enables the
|
||||||
| web UI scan feature.
|
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
|
||||||
====
|
====
|
||||||
|
|
||||||
| Bugs can be reported to your distribution's bug tracker or upstream
|
Bugs can be reported to your distribution's bug tracker or upstream
|
||||||
| at https://github.com/spl0k/supysonic/issues.
|
at https://github.com/spl0k/supysonic/issues.
|
||||||
|
|
||||||
See Also
|
See Also
|
||||||
========
|
========
|
||||||
|
|
||||||
supysonic-cli(1)
|
``supysonic-cli``\ (1)
|
||||||
|
|||||||
308
docs/setup/configuration.rst
Normal file
308
docs/setup/configuration.rst
Normal 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¶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
|
||||||
59
docs/setup/daemon.rst
Normal file
59
docs/setup/daemon.rst
Normal 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
39
docs/setup/database.rst
Normal 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
56
docs/setup/deploying/apache.rst
Normal 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
22
docs/setup/deploying/index.rst
Normal 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
102
docs/setup/deploying/other.rst
Normal 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
61
docs/setup/deploying/wsgi-standalone.rst
Normal 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
43
docs/setup/index.rst
Normal 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
94
docs/setup/install.rst
Normal 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
|
||||||
@ -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
148
docs/transcoding.rst
Normal 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.
|
||||||
Loading…
Reference in New Issue
Block a user