mirror of
https://github.com/spl0k/supysonic.git
synced 2024-12-22 08:56:17 +00:00
Docs as reST: transcoding
This commit is contained in:
Alban Féron
parent
cfc324e346
commit
ff75ff1230
@ -90,7 +90,7 @@ Sample configuration:
|
||||
|
||||
Configuration relative to the HTTP server.
|
||||
|
||||
``cache_dir``:
|
||||
``cache_dir``
|
||||
Directory used to store generated files, such as resized cover art or
|
||||
transcoded files. Defaults to ``/tmp/supysonic``.
|
||||
|
||||
@ -266,6 +266,8 @@ Sample configuration:
|
||||
;api_key =
|
||||
;secret =
|
||||
|
||||
.. _conf-transcoding:
|
||||
|
||||
``[transcoding]`` section
|
||||
-------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
```
|
||||
139
docs/transcoding.rst
Normal file
139
docs/transcoding.rst
Normal file
@ -0,0 +1,139 @@
|
||||
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.
|
||||
|
||||
Basic configuration:
|
||||
|
||||
.. code-block:: 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:
|
||||
|
||||
.. code-block:: 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
|
||||
|
||||
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 you preferred streaming
|
||||
format and bitrate.
|
||||
Loading…
Reference in New Issue
Block a user