Transcoding Configuration

Configure media transcoding, codecs, quality settings, and encoding options

Transcoding allows Jellyfin to convert media on-the-fly to formats compatible with client devices. Proper configuration ensures optimal quality, performance, and compatibility.

Encoding Configuration File

Transcoding settings are stored in encoding.xml:

/var/lib/jellyfin/config/encoding.xml

FFmpeg Configuration

FFmpeg Path

Jellyfin requires FFmpeg for transcoding. Configure the path:

<EncoderAppPath>/usr/bin/ffmpeg</EncoderAppPath>
<EncoderAppPathDisplay>/usr/bin/ffmpeg</EncoderAppPathDisplay>

• EncoderAppPath: Path set by user via UI
• EncoderAppPathDisplay: Currently used path displayed on transcode page

Jellyfin automatically detects FFmpeg if installed in standard locations.

FFmpeg Probe Settings

Configure via environment variables:

JELLYFIN_FFmpeg_probesize=1G
JELLYFIN_FFmpeg_analyzeduration=200M

These settings control how FFmpeg analyzes media files:

• probesize: Amount of data to analyze (default: 1G)
• analyzeduration: Duration to analyze (default: 200M)

Increase these values for files with complex or delayed streams.

Video Encoding

H.264 Encoding

CRF (Quality)

Constant Rate Factor controls encoding quality:

<H264Crf>23</H264Crf>

• Lower values = higher quality, larger files
• Higher values = lower quality, smaller files
• Range: 0-51 (default: 23)
• Recommended: 18-28

Software Encoder

Default software encoder: libx264

<EnableHardwareEncoding>false</EnableHardwareEncoding>

Hardware Encoders

Available hardware H.264 encoders:

• h264_nvenc (NVIDIA)
• h264_qsv (Intel Quick Sync)
• h264_amf (AMD)
• h264_vaapi (VA-API)
• h264_videotoolbox (Apple)
• h264_v4l2m2m (Video4Linux)
• h264_rkmpp (Rockchip)

H.265/HEVC Encoding

<H265Crf>28</H265Crf>
<AllowHevcEncoding>false</AllowHevcEncoding>

1. Enable HEVC

   HEVC provides better compression but requires more processing:

   <AllowHevcEncoding>true</AllowHevcEncoding>
   
2. CRF Configuration

   HEVC typically uses higher CRF values than H.264:

   <H265Crf>28</H265Crf>
   

   • Default: 28
   • Recommended: 24-32
   • CRF 28 (HEVC) ≈ CRF 23 (H.264) in quality
3. Hardware Support

   Ensure client devices support HEVC decoding before enabling.

AV1 Encoding

<AllowAv1Encoding>false</AllowAv1Encoding>

AV1 provides excellent compression but is computationally intensive:

<AllowAv1Encoding>true</AllowAv1Encoding>

AV1 encoding requires significant CPU/GPU resources and is slower than H.264/HEVC.

Encoder Presets

<EncoderPreset>veryfast</EncoderPreset>

Available presets (from fastest to slowest):

• ultrafast - Fastest, lowest quality
• superfast
• veryfast - Good balance for real-time transcoding
• faster
• fast
• medium - Default, balanced quality/speed
• slow
• slower
• veryslow - Best quality, very slow

For real-time transcoding, use veryfast or faster. For offline encoding, use slow or slower.

Audio Encoding

Audio VBR

<EnableAudioVbr>false</EnableAudioVbr>

Variable Bit Rate for audio encoding provides better quality at lower bitrates.

Downmixing Configuration

<DownMixAudioBoost>2</DownMixAudioBoost>
<DownMixStereoAlgorithm>None</DownMixStereoAlgorithm>

Audio Boost

Apply volume boost when downmixing surround to stereo:

<DownMixAudioBoost>2</DownMixAudioBoost>

• Range: 0-10
• Default: 2

Downmix Algorithm

Choose stereo downmix algorithm:

<DownMixStereoAlgorithm>None</DownMixStereoAlgorithm>

Options:

• None - FFmpeg default
• Dave750 - Dave750 algorithm
• NightMode - Night mode compression

Audio Codec Limitations

Jellyfin enforces channel limits for certain encoders:

Codec	Max Channels
libmp3lame	2 (stereo)
libfdk_aac	6 (5.1)
ac3	6 (5.1)
eac3	6 (5.1)
AAC	8
FLAC	8
ALAC	8
Opus	8
Vorbis	8

Transcoding Behavior

Threading

<EncodingThreadCount>-1</EncodingThreadCount>

• -1: Auto (uses all available CPU cores)
• 0: FFmpeg default
• 1-N: Specific thread count

Setting to -1 allows FFmpeg to utilize all CPU resources for faster transcoding.

Throttling

<EnableThrottling>false</EnableThrottling>
<ThrottleDelaySeconds>180</ThrottleDelaySeconds>

Throttling is deprecated and disabled by default. Modern clients handle buffering automatically.

Segment Management

<EnableSegmentDeletion>false</EnableSegmentDeletion>
<SegmentKeepSeconds>720</SegmentKeepSeconds>

For HLS streaming, configure segment retention:

• EnableSegmentDeletion: Auto-delete old segments
• SegmentKeepSeconds: How long to keep segments (default: 720)

Muxing Queue

<MaxMuxingQueueSize>2048</MaxMuxingQueueSize>

Buffer size for muxing operations (default: 2048).

Temporary Transcoding Path

<TranscodingTempPath>/var/lib/jellyfin/transcodes</TranscodingTempPath>

Specify where temporary transcode files are stored:

1. Default Location

   If not specified, uses system temp directory.

2. Fast Storage

   Use SSD or RAM disk for better performance:

   <TranscodingTempPath>/mnt/ramdisk/jellyfin-transcodes</TranscodingTempPath>
   
3. Disk Space

   Ensure adequate space (4K transcoding can use 10-20 GB temporarily).

Using a RAM disk for transcoding significantly improves performance and reduces SSD wear.

Subtitle Configuration

Subtitle Extraction

<EnableSubtitleExtraction>true</EnableSubtitleExtraction>
<SubtitleExtractionTimeoutMinutes>30</SubtitleExtractionTimeoutMinutes>

Configure how subtitles are extracted from media:

• EnableSubtitleExtraction: Allow extracting embedded subtitles
• SubtitleExtractionTimeoutMinutes: Maximum time to spend extracting

Fallback Fonts

<EnableFallbackFont>false</EnableFallbackFont>
<FallbackFontPath>/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf</FallbackFontPath>

Specify fallback font for subtitle rendering.

Hardware Decoding

Codec Selection

<HardwareDecodingCodecs>
  <string>h264</string>
  <string>vc1</string>
</HardwareDecodingCodecs>

Specify which codecs use hardware decoding:

• h264 - H.264/AVC
• hevc - H.265/HEVC
• vc1 - VC-1
• mpeg2video - MPEG-2
• vp8 - VP8
• vp9 - VP9
• av1 - AV1

Advanced Decoding Options

<EnableDecodingColorDepth10Hevc>true</EnableDecodingColorDepth10Hevc>
<EnableDecodingColorDepth10Vp9>true</EnableDecodingColorDepth10Vp9>
<EnableDecodingColorDepth10HevcRext>false</EnableDecodingColorDepth10HevcRext>
<EnableDecodingColorDepth12HevcRext>false</EnableDecodingColorDepth12HevcRext>

10-bit HEVC

Enable hardware decoding for 10-bit HEVC:

<EnableDecodingColorDepth10Hevc>true</EnableDecodingColorDepth10Hevc>

10-bit VP9

Enable hardware decoding for 10-bit VP9:

<EnableDecodingColorDepth10Vp9>true</EnableDecodingColorDepth10Vp9>

HEVC RExt

Advanced HEVC profiles (Range Extensions):

<EnableDecodingColorDepth10HevcRext>false</EnableDecodingColorDepth10HevcRext>
<EnableDecodingColorDepth12HevcRext>false</EnableDecodingColorDepth12HevcRext>

NVIDIA Enhanced Decoder

<EnableEnhancedNvdecDecoder>true</EnableEnhancedNvdecDecoder>

Enables enhanced NVDEC for Dolby Vision to SDR tone mapping.

System Native Decoder

<PreferSystemNativeHwDecoder>true</PreferSystemNativeHwDecoder>

Prefer OS-native hardware decoder (e.g., VideoToolbox on macOS).

Deinterlacing

<DeinterlaceDoubleRate>false</DeinterlaceDoubleRate>
<DeinterlaceMethod>yadif</DeinterlaceMethod>

Method

Available deinterlacing algorithms:

• yadif - Yet Another Deinterlacing Filter (recommended)
• bwdif - Bob Weaver Deinterlacing Filter

<DeinterlaceMethod>yadif</DeinterlaceMethod>

Double Rate

Output at double framerate:

<DeinterlaceDoubleRate>true</DeinterlaceDoubleRate>

• false: 60i → 30p
• true: 60i → 60p

Tone Mapping

Basic Tone Mapping

<EnableTonemapping>false</EnableTonemapping>
<TonemappingAlgorithm>bt2390</TonemappingAlgorithm>
<TonemappingMode>auto</TonemappingMode>
<TonemappingRange>auto</TonemappingRange>

1. Enable Tone Mapping

   Convert HDR content to SDR:

   <EnableTonemapping>true</EnableTonemapping>
   
2. Algorithm Selection

   Choose tone mapping algorithm:

   <TonemappingAlgorithm>bt2390</TonemappingAlgorithm>
   

   Options:

   • bt2390 - ITU-R BT.2390 (recommended)
   • hable - Hable/Uncharted
   • mobius - Mobius
   • reinhard - Reinhard
3. Mode Configuration

   <TonemappingMode>auto</TonemappingMode>
   <TonemappingRange>auto</TonemappingRange>
   

   Both default to auto for automatic detection.

Tone Mapping Parameters

<TonemappingDesat>0</TonemappingDesat>
<TonemappingPeak>100</TonemappingPeak>
<TonemappingParam>0</TonemappingParam>

• TonemappingDesat: Desaturation strength (default: 0)
• TonemappingPeak: Peak luminance in nits (default: 100)
• TonemappingParam: Algorithm-specific parameter (default: 0)

Hardware-Specific Tone Mapping

Intel VPP

<EnableVppTonemapping>false</EnableVppTonemapping>
<VppTonemappingBrightness>16</VppTonemappingBrightness>
<VppTonemappingContrast>1</VppTonemappingContrast>

Intel Video Post Processing tone mapping.

Apple VideoToolbox

<EnableVideoToolboxTonemapping>false</EnableVideoToolboxTonemapping>

macOS/iOS hardware tone mapping.

Intel Quick Sync Configuration

<QsvDevice></QsvDevice>
<EnableIntelLowPowerH264HwEncoder>false</EnableIntelLowPowerH264HwEncoder>
<EnableIntelLowPowerHevcHwEncoder>false</EnableIntelLowPowerHevcHwEncoder>

1. QSV Device

   Specify QSV device (usually auto-detected):

   <QsvDevice></QsvDevice>
   
2. Low Power Mode

   Enable low power encoding (Xe+ architecture):

   <EnableIntelLowPowerH264HwEncoder>true</EnableIntelLowPowerH264HwEncoder>
   <EnableIntelLowPowerHevcHwEncoder>true</EnableIntelLowPowerHevcHwEncoder>
   

HLS Audio Seeking

<HlsAudioSeekStrategy>DisableAccurateSeek</HlsAudioSeekStrategy>

Configure HLS audio seeking behavior:

• DisableAccurateSeek - Faster seeking, less accurate (default)
• EnableAccurateSeek - Slower seeking, more accurate

Keyframe Extraction

<AllowOnDemandMetadataBasedKeyframeExtractionForExtensions>
  <string>mkv</string>
</AllowOnDemandMetadataBasedKeyframeExtractionForExtensions>

Enable on-demand keyframe extraction for trickplay thumbnails in specific formats.

Performance Optimization

Use Hardware Encoding

Enable hardware acceleration for 10-20x faster transcoding with lower CPU usage.

RAM Disk for Transcodes

Store temporary transcodes in RAM disk for faster I/O and reduced disk wear.

Optimize Thread Count

Set EncodingThreadCount to -1 to use all CPU cores efficiently.

Adjust CRF Values

Balance quality and performance by tuning CRF settings for your use case.

Troubleshooting

1. Transcoding Fails

   Check:

   • FFmpeg is installed and path is correct
   • Sufficient disk space in transcode directory
   • Encoding settings are compatible with source media
2. Poor Quality Output

   Adjust:

   • Lower CRF values for better quality
   • Use slower encoder preset
   • Increase bitrate limits
3. Slow Transcoding

   Optimize:

   • Enable hardware encoding
   • Use faster encoder preset
   • Reduce thread count if CPU is overloaded
4. Audio Out of Sync

   Verify:

   • Source file is not corrupted
   • Audio downmix settings are appropriate
   • HLS audio seek strategy is suitable

Next Steps

Hardware Acceleration

Set up GPU acceleration for optimal performance

Configuration

Review general server configuration options