gwutilz/gwencoder/docs/phases/PHASE2_IMPLEMENTATION.md

Phase 2 Implementation Summary

Overview

Phase 2 implements missing Tdarr plugin capabilities with detailed impact analysis and defaults documentation.

✅ Implemented Features

1. Audio Quality Presets ✅

Status: Fully implemented Location: encoding/audio.go

Presets Available:

• high_quality: AAC 128k/ch, Opus 96k/ch, Stereo 256k
• balanced: AAC 80k/ch, Opus 64k/ch, Stereo 160k (default)
• small_size: AAC 64k/ch, Opus 48k/ch, Stereo 128k
• custom: Uses manual settings

Impact:

• Time: No impact
• Compression: Variable (high_quality = best, small_size = fastest)
• File Size: ±20-50% depending on preset
• Quality: Variable (high_quality = highest, small_size = acceptable)

Implementation:

• ApplyQualityPreset() function applies preset settings
• Automatically overrides manual bitrate when preset selected
• Logs preset application with description

2. Stream Reordering Integration ✅

Status: Fully implemented Location: encoding/streams.go, integrated into main.go

Features:

• Reorders English audio/subtitle streams first
• Preserves relative order of non-English streams
• Custom language codes supported
• Optional (can be disabled)

Impact:

• Time: +0.1-0.5s (one-time stream analysis)
• Compression: No impact
• File Size: No impact
• Quality: No impact
• Functionality: Better player compatibility

Implementation:

• ReorderStreams() function reorders streams
• BuildStreamMappingArgs() builds FFmpeg mapping
• Integrated into encoding pipeline
• Logs when reordering occurs

3. Subtitle Conversion to SRT ✅

Status: Fully implemented Location: encoding/streams.go, integrated into main.go

Features:

• Converts ASS, SSA, WebVTT, MOV_TEXT → SRT
• Copies image subtitles (PGS, VobSub)
• WebVTT always converted (compatibility)
• Mixed subtitle handling (only converts if all text-based)

Impact:

• Time: +5-15% (conversion overhead)
• Compression: No impact
• File Size: Slightly smaller (SRT is text-based)
• Quality: No visual impact
• Functionality: Better compatibility

Implementation:

• BuildSubtitleCodecArgs() determines codec handling
• NeedsSRTConversion() checks if conversion needed
• Integrated into encoding pipeline
• Logs conversion count

4. Smart Container Selection ✅

Status: Fully implemented Location: encoding/streams.go, integrated into main.go

Features:

• Detects Apple/broadcast streams (MP4/MOV family)
• Auto-switches to MP4 when unsupported streams detected
• Excludes EIA-608, CC_DEC, tx3g from MKV
• Prevents muxing errors

Impact:

• Time: No impact
• Compression: No impact
• File Size: No impact
• Quality: No impact
• Functionality: Prevents errors

Implementation:

• GetContainerFormat() detects input format
• DetectUnsupportedStreams() finds incompatible streams
• ShouldUseMP4Container() determines if MP4 needed
• Integrated into encoding pipeline
• Logs container switch

5. Unsupported Stream Exclusion ✅

Status: Fully implemented Location: encoding/streams.go, integrated into main.go

Features:

• Excludes EIA-608, CC_DEC, tx3g, bin_data
• Only applies when outputting to MKV
• MP4 can handle these streams

Impact:

• Time: Minimal (one-time detection)
• Compression: No impact
• File Size: Slightly smaller (removed streams)
• Quality: No impact
• Functionality: Prevents muxing errors

Implementation:

• DetectUnsupportedStreams() finds incompatible streams
• Excludes via -map -0:idx in FFmpeg
• Logs exclusion count

6. Downmix Track Creation (Structure Ready) ⏳

Status: Functions implemented, not yet integrated Location: encoding/audio.go

Features:

• Creates stereo (2ch) downmix from 5.1/7.1
• Only creates if track doesn't exist
• Uses stereo_bitrate setting
• downmix_single_track option

Impact:

• Time: +10-20% per downmix track
• Compression: No impact
• File Size: +2-5MB per stereo downmix
• Quality: No impact (downmix quality)

Implementation:

• BuildDownmixArgs() function ready
• Needs integration into audio processing loop
• Will be added in next phase

7. "Original" Bitrate Option ✅

Status: Fully implemented Location: encoding/audio.go

Features:

• When bitrate_per_channel = 0, uses source bitrate
• Preserves high-quality audio
• No bitrate specified in FFmpeg

Impact:

• Time: No impact
• Compression: Preserves source quality
• File Size: Variable (depends on source)
• Quality: Preserves source quality

Implementation:

• CalculateBitrate() returns 0 for "original"
• FFmpeg uses source bitrate automatically

Defaults Summary

Audio Quality Presets

Preset	AAC kbps/ch	Opus kbps/ch	Stereo kbps	Default
high_quality	128	96	256	No
balanced	80	64	160	No
small_size	64	48	128	No
custom	Manual	Manual	Manual	Yes

Stream Reordering

• Include Audio: true (default)
• Include Subtitles: true (default)
• Standardize to SRT: true (default)
• Extract Subtitles: false (default)
• Remove After Extract: false (default)
• Skip Commentary: true (default)

Container Selection

• Smart Selection: Enabled (default)
• Auto-switch to MP4: When needed (default)

Impact Summary

Feature	Time	Compression	File Size	Quality	Status
Quality Presets	None	Variable	±20-50%	Variable	✅
Stream Reordering	+0.1-0.5s	None	None	None	✅
Subtitle → SRT	+5-15%	None	-5-10%	None	✅
Container Selection	None	None	None	None	✅
Stream Exclusion	+0.1s	None	-0.1-0.5MB	None	✅
Original Bitrate	None	Preserves	Variable	Preserves	✅
Downmix Creation	+10-20%	None	+2-5MB	None	⏳

Files Modified

• ✅ encoding/audio.go - Quality presets, downmix functions
• ✅ encoding/streams.go - Stream reordering, subtitle handling, container selection
• ✅ main.go - Integrated all features into encoding pipeline

Testing Status

• ✅ Code compiles successfully
• ⏳ Runtime testing needed
• ⏳ Test with various video files
• ⏳ Test with different subtitle types
• ⏳ Test with Apple/broadcast streams

Next Steps

1. ⏳ Integrate downmix track creation
2. ⏳ Implement subtitle extraction
3. ⏳ Add CLI flags for new options
4. ⏳ Test with real video files
5. ⏳ Performance benchmarking

Usage Examples

Quality Presets

audioStandardizer.QualityPreset = "balanced"
audioStandardizer = encoding.ApplyQualityPreset(audioStandardizer)

Stream Reordering

streamReorderer := encoding.DefaultStreamReorderer()
reorderedStreams := encoding.ReorderStreams(allStreams, streamReorderer)

Subtitle Conversion

subtitleCodec := encoding.BuildSubtitleCodecArgs(subtitleStreams, true)

Notes

• All features maintain backward compatibility
• Defaults match Tdarr plugin defaults
• Impact analysis based on Tdarr plugin documentation
• Features are opt-in via configuration (not CLI flags yet)