tdarr-plugs/PLUGIN_DOCUMENTATION.md

Tdarr Plugin Suite Documentation

Version: 2025-12-16
Plugins: misc_fixes v2.8 | stream_organizer v4.10 | audio_standardizer v1.15 | av1_converter v2.32

---

Recommended Pipeline Order

1. Misc Fixes          → Fix containers, timestamps, clean streams
2. English First       → Organize streams, handle subtitles
3. Audio Standardizer  → Convert audio codecs
4. AV1 Converter       → Convert video codec (most intensive)

Tip

Run plugins in this order to fail fast on cheap operations before expensive video encoding.

---

Plugin 1: Misc Fixes (v2.6)

Purpose: First-in-pipeline cleanup for edge cases and container standardization.

Features & Impact

Feature	Quality	Filesize	Speed	Default	Why
target_container	—	—	Fast	mkv	MKV supports all codecs/subs, best compatibility
force_conform	—	↓ Smaller	Fast	true	Drops incompatible streams to prevent mux errors
remove_image_streams	—	↓ Smaller	Fast	true	Removes cover art spam (MJPEG/PNG/GIF)
ensure_video_first	—	—	Fast	true	Fixes player compatibility issues
fix_ts_timestamps	↑ Better	—	Fast	true	Fixes playback issues in TS/AVI/MPG files

Container Compatibility Rules

MKV Target (drops):

• mov_text (Apple subtitle format)
• eia_608 (closed captions)
• timed_id3 (metadata)
• data streams

MP4 Target (drops):

• hdmv_pgs_subtitle (Blu-ray PGS)
• eia_608 (closed captions)
• subrip (SRT subtitles)
• timed_id3 (metadata)

---

Plugin 2: English First Streams (v4.7)

Purpose: Stream organization and subtitle management.

Features & Impact

Feature	Quality	Filesize	Speed	Default	Why
includeAudio	—	—	Fast	true	English audio first improves player UX
includeSubtitles	—	—	Fast	true	English subs first improves accessibility
standardizeToSRT	↑ Compat	↓ Smaller	Medium	true	SRT is universally supported
extractSubtitles	—	—	Fast	false	External subs optional, not always wanted
removeAfterExtract	—	↓ Smaller	Fast	false	Keep embedded subs by default
skipCommentary	—	—	—	true	Commentary tracks rarely desired
setDefaultFlags	—	—	Fast	false	Let player decide defaults
customLanguageCodes	—	—	—	eng,en,...	Covers all common English variants
useCCExtractor	—	—	Slow	false	CC extraction is optional extra step
embedExtractedCC	—	↑ Larger	Fast	false	Only if you want CC in container

Subtitle Handling

Source Codec	Action	Reason
ASS/SSA	→ SRT	Universal compatibility
WebVTT	→ SRT	Always converted (problematic in containers)
mov_text	→ SRT	Apple format, limited support
PGS/VobSub	Copy	Image-based, cannot convert to SRT
eia_608/cc_dec	Skip	Requires CCExtractor

---

Plugin 3: Combined Audio Standardizer (v1.12)

Purpose: Audio codec and channel standardization.

Features & Impact

Feature	Quality	Filesize	Speed	Default	Why
codec	↑ Opus better	↓ Opus smaller	Medium	opus	Opus is more efficient than AAC
skip_if_compatible	—	—	↑ Faster	true	Don't re-encode if already AAC/Opus
bitrate_per_channel	↕ Varies	↕ Varies	—	auto	Smart: min(64kbps/ch, source)
channel_mode	↓ Stereo loses	↓ Stereo smaller	—	preserve	Keep original channels by default
create_downmix	—	↑ Larger	Slow	true	2ch compatibility track
create_6ch_downmix	—	↑ Larger	Slow	false	5.1 from 7.1, rarely needed
downmix_single_track	—	↓ Smaller	↑ Faster	false	One downmix per language is enough
force_transcode	—	—	↓ Slower	false	Only re-encode if needed
opus_application	↕ Varies	—	—	audio	Best for music/movies
opus_vbr	↑ VBR better	↓ VBR smaller	—	on	VBR = best quality per bit
opus_compression	↑ 10 best	—	↓ 10 slowest	10	Max quality for archival
aac_profile	↕ Varies	↕ Varies	—	aac_low	AAC-LC: best quality/compatibility
target_sample_rate	↓ Lower = worse	↓ Lower = smaller	—	original	Preserve source quality
preserve_metadata	—	—	—	true	Keep language/title tags
quality_preset	↕ Varies	↕ Varies	—	custom	Manual control preferred

Quality Presets

Preset	AAC kbps/ch	Opus kbps/ch	Use Case
high_quality	128	96	Archival, high-end audio
balanced	80	64	General streaming
small_size	64	64	Space-constrained
custom	(manual)	(manual)	Full control

Opus Compatibility Note

Incompatible layouts auto-downmix to stereo:

• 3.0(back/front), 4.0, 5.0(side), 6.0, 6.1, 7.0, 7.0(front)

---

Plugin 4: AV1 SVT Converter (v2.22)

Purpose: Video transcoding with modern AV1 codec using SVT-AV1.

Core Settings Impact

Feature	Quality	Filesize	Speed	Default	Why
crf	↓ Higher = worse	↓ Higher = smaller	↑ Higher = faster	26	Sweet spot for 1080p
preset	↓ Higher = worse	—	↑ Higher = faster	6	Best speed/quality balance
tune	0=VQ best	—	0=VQ slowest	0	Visual Quality mode
input_depth	↑ 10-bit better	↓ 10-bit smaller	↓ 10-bit slower	10	Prevents banding, minimal penalty
rate_control_mode	↕ Varies	↕ Varies	↓ VMAF slowest	crf	CRF=quality-based, VBR=bitrate-based, VMAF=quality-targeted
vmaf_target	↑ Higher better	↑ Higher larger	—	95	Target quality score (VMAF mode only)
vmaf_samples	↑ More accurate	—	↓ More slower	4	Sample count for CRF analysis (VMAF mode only)

Advanced Settings Impact

Feature	Quality	Filesize	Speed	Default	Why
scd	↑ On better	—	↓ On 5-10% slower	1	Better keyframe placement
aq_mode	↑ 2 best	—	↓ 2 is 10-20% slower	2	DeltaQ best quality
lookahead	↑ Higher better	—	↓ Higher slower	-1	Auto is good compromise
enable_tf	↑ On better	—	↓ On 15-25% slower	1	Temporal filtering = smoother
film_grain	↑ Natural look	↓ Smaller	↓ Slower	0	Only for grainy sources
fast_decode	—	↑ Larger	↑ Faster decode	0	Off = best compression

Bitrate Control

Strategy	Description	Use Case
static	Use custom_maxrate or unlimited	Manual control
match_source	100% of source bitrate	Matching original quality
75%_source	75% of source bitrate	Good compression
50%_source	50% of source bitrate	Recommended balance
33%_source	33% of source bitrate	Aggressive compression
25%_source	25% of source bitrate	Maximum compression

Rate Control Modes

Mode	Description	File Size	Speed	Use Case
crf	Constant Rate Factor - quality-based encoding	Unpredictable	Fast	General use, quality priority
vbr	Variable Bitrate - target average with peak limits	Predictable	Fast	Bandwidth constraints, streaming
vmaf	Quality-targeted - ab-av1 auto CRF selection	Optimized	Slowest	Consistent quality across content

VMAF Mode Requirements:

• Requires ab-av1 binary installed and accessible
• Set via ABAV1_PATH environment variable or install to /usr/local/bin/ab-av1
• Docker: Volume mount binary with -v /path/to/ab-av1:/usr/local/bin/ab-av1
• Falls back to CRF mode if binary not found

VMAF Mode Settings:

• vmaf_target: Quality target (85-99). 95 = visually transparent, 90 = good quality, 85 = acceptable
• vmaf_samples: Analysis segments (2-8). More = accurate but slower. 4 is recommended balance

Resolution CRF Adjustment

Output Resolution	CRF Adjustment	Reason
4K (≥2160p)	+2 CRF	Less visible artifacts at high res
1080p	Baseline	Reference resolution
720p or lower	-2 CRF	More visible artifacts, needs quality

Container Selection

Container	Pros	Cons
mp4	Universal compatibility	Limited subtitle support
mkv	All features supported	Some devices don't support
webm	Web-native	Audio must be Opus/Vorbis
original	No remux	May have incompatibilities

---

Default Values Rationale

Why These Defaults?

Codec Choices:

• Opus over AAC: 20-30% better compression at same quality
• AV1 over HEVC: 30-50% better compression, royalty-free
• 10-bit over 8-bit: Eliminates banding with minimal speed penalty

Quality Settings:

• CRF 26: Visually transparent for most content at 1080p
• Preset 6: 2-3x faster than preset 3, only ~5% larger files
• Tune 0 (VQ): Optimized for human perception over PSNR metrics

Efficiency Settings:

• SCD On: Better seeking, cleaner scene transitions
• AQ Mode 2: Allocates bits where human eye is most sensitive
• Temporal Filtering On: Reduces noise, improves compression

Safety Settings:

• Skip HEVC enabled: HEVC is already efficient, may not benefit from AV1
• Force transcode disabled: Don't re-encode already-optimal files
• Preserve metadata: Keep language tags and titles

---

Changelog (This Update)

v2.1 - misc_fixes

• Added input validation function
• Standardized boolean inputs to string type with star markers
• Normalized boolean checks to === 'true' pattern

v4.2 - english_first_streams

• Fixed CCExtractor error handling (now continues if CC extraction fails)

v1.11 - combined_audio_standardizer

• Fixed create_downmix_6ch → create_6ch_downmix typo
• Fixed double backslash in log strings

v2.21 - av1_svt_converter

• Version bump for documentation consistency