Transcoding

Transcoding

Transcoding allows you to convert one type of file to another. Ampache supports on the fly transcoding of all file types based on user, IP address or available bandwidth. In order to transcode Ampache takes advantage of existing binary applications such as ffmpeg, Lame or mp3splt. In order for transcoding to work you must first install the supporting applications and ensure that they are executable by the webserver. If you have any trouble to get transcoding working you can also have a look at the FAQ.

WARNING: Transcoding currently causes several issues documented in #1048 which you should know about before enabling it. For that reason usability is quite limited with transcoding enabled.

Standard Transcoding

You will need to enable and configure transcoding in the config file before it will work.

;######################################################
; These are commands used to transcode non-streaming
; formats to the target file type for streaming.
; This can be useful in re-encoding file types that don't stream
; very well, or if your player doesn't support some file types.
;
; 'Downsampling' will also use these commands.
;
; To state the bleeding obvious, any programs referenced in the downsample
; commands must be installed, in the web server's search path (or referenced
; by their full path), and executable by the web server.

; Input type selection
; TYPE is the extension. 'allowed' certifies that transcoding works properly for
; this input format. 'required' further forbids the direct streaming of a format
; (e.g. if you store everything in FLAC, but don't want to ever stream that.)
; transcode_TYPE         = {allowed|required|false}
; DEFAULT: false
;transcode_m4a      = allowed
;transcode_flac     = required
;transcode_mp3      = allowed

; Default output format
; DEFAULT: none
;encode_target = mp3

; Override the default output format on a per-type basis
; encode_target_TYPE = TYPE
; DEFAULT: none
;encode_target_flac = ogg

Ampache8: encode_target, encode_video_target, encode_player_webplayer_target and encode_player_api_target are now per-user preferences under Streaming -> Transcoding in the web interface, rather than config-only settings. The config values above only seed the default the first time a user's preferences are created (e.g. on upgrade or new account) - after that, change them per user from their Options page, or with bin/cli admin:updateUser. An explicit format= request parameter still always takes priority.

Ampache8 also adds per-user dynamic downsampling and per-player bitrate overrides, both preferences rather than config options: max_bit_rate/min_bit_rate cap and floor a user's own transcode bitrate, and transcode_bitrate_webplayer/transcode_bitrate_api override the site-wide transcode_bitrate per player (0 uses the default).

; Command configuration. Substitutions will be made as follows:
; %FILE% => filename
; %BITRATE% => target bit rate in bits per second (as chosen by the admin or
; users in the preferences, if transcode_player_customize = "true")
; %MAXBITRATE% => ceiling bit rate in bits per second, from the `maxbitrate`
; stream URL argument. Both are plain bps values, so do NOT add a `k` suffix.
; You can do fancy things like VBR, but consider whether the consequences are
; acceptable in your environment.

NOTE the old %SAMPLE% placeholder is long gone; the substitution is %BITRATE%.

The k suffix moved twice

Ampache 7.8.0 asked you to write %BITRATE%k, because the value was inserted in kilobits.

Ampache8 reverses this. The bitrate is expanded to full bits per second before it is inserted, so the shipped defaults are back to a bare %BITRATE%.

A k left over from an Ampache7 config is not an error — the substitution consumes a trailing k or K along with the placeholder, so %BITRATE%k still produces 128000 rather than 128000k. Dropping it is tidier and matches the new defaults, but nothing breaks if you don't.

encode_args_ts uses %MAXBITRATE%, which is expanded the same way from the maxbitrate stream URL argument.

; Master transcode command
; transcode_cmd should be a single command that supports multiple file types,
; such as ffmpeg or avconv. It's still possible to make a configuration that's
; equivalent to the old default, but if you find that necessary you should be
; clever enough to figure out how on your own.
; DEFAULT: none
;transcode_cmd = "ffmpeg"

; Transcode input file argument
transcode_input = "-i %FILE%"

; Specific transcode commands
; It shouldn't be necessary in most cases, but you can override the transcode
; command for specific source formats.  It still needs to accept the
; encoding arguments, so the easiest approach is to use your normal command as
; a clearing-house.
; transcode_cmd_TYPE = TRANSCODE_CMD
;transcode_cmd_mid = "timidity -Or -o – %FILE% | ffmpeg -i pipe:0"

; encode_args_TYPE = TRANSCODE_CMD_ARGS
encode_args_mp3 = "-vn -b:a %BITRATE% -c:a libmp3lame -f mp3 pipe:1"
encode_args_ogg = "-vn -b:a %BITRATE% -c:a libvorbis -f ogg pipe:1"
encode_args_opus = "-vn -b:a %BITRATE% -c:a libopus -compression_level 10 -f ogg pipe:1"
encode_args_m4a = "-vn -b:a %BITRATE% -c:a aac -movflags +frag_keyframe+empty_moov+default_base_moof -f mp4 pipe:1"

The arguments may need to be adjusted depending on the specific external program chosen and its age.

ReplayGain and car profiles (Ampache8)

Ampache8 adds four extra output profiles you can enable in your own config: encode_args_mp3_rg, encode_args_mp3_car, encode_args_opus_rg and encode_args_opus_car.

The _rg variants apply track ReplayGain in the transcode with a 6dB preamp; the _car variants use a 15dB preamp and resample through soxr (heavier CPU) for listening in a noisy environment.

Your source files must already be tagged with ReplayGain (use loudgain or rsgain), or the gain clauses do nothing.

NOTE these formats are never written to the transcode cache, because the normalisation is per-source. Keep cache_target set to a plain format such as mp3 or opus.

opus_rg/opus_car will not play on iOS (Opus-in-Ogg). mp3_rg/mp3_car are cross-platform.

The m4a profile is fragmented MP4, so it can be streamed before the whole file exists.

Network Based Transcoding

You can also force transcoding based on the IP address of the user streaming. This allows you to automatically downsample and transcode music if the user is off of your local network. To enable this you first need to define a Local Network ACL and then enable downsample_remote in the ampache.cfg.php

; Downsample Remote
; If this is set to true and access control is on any users who are not
; coming from a defined 'network' ACL will be automatically downsampled
; regardless of their preferences.
; DEFAULT: false
;downsample_remote = "false"

Transcode Anyone outside 10.x Space

The below example config would cause anyone whos IP is not 10.x.x.x to have their streams transcoded according to the transcode rules in the config file

Config Variables

downsample_remote = "true"
access_control = "true"

ACL Interface Access for Clients

User	Type	Start Address	End Address	Level
All	Interface	0.0.0.0	255.255.255.255	All

This first ACL will let us continue to login after we've enabled the Access Control in the config file, next we need to allow streaming from our clients.

ACL Streaming Access for Clients

User	Type	Start Address	End Address	Level
All	Streaming	0.0.0.0	255.255.255.255	All

Last we'll need to define what is our local network so that Ampache knows when it needs to transcode

ACL Local Network Definition

User	Type	Start Address	End Address	Level
All	Network	10.0.0.0	10.255.255.255	All

This will make is so that a client connecting from 192.168.0.32 would be considered Non-Local and would be forced to use any configured transcoding. A client coming from 10.0.32.12 would be considered local and would not be transcoded. You can have as many network ACL definitions as you want.