gwutilz/gwencoder/docs/phases/PHASE_OVERVIEW.md

Phase Implementation Overview

✅ Completed Phases

Phase 1: Core Implementation ✅

Status: Complete

• ✅ AV1 advanced parameters (preset, CRF, tune, SCD, AQ, TF, lookahead, etc.)
• ✅ Resolution-aware CRF adjustment
• ✅ Maxrate cap for AV1
• ✅ Audio codec conversion (AAC/Opus)
• ✅ Audio channel handling (preserve/stereo/mono)
• ✅ Audio bitrate configuration
• ✅ Stream reordering (English first)
• ✅ Subtitle conversion to SRT
• ✅ Quality presets for audio
• ✅ Opus incompatible layout detection
• ✅ Force transcode flag

Phase 2: CLI Flags ✅

Status: Complete

• ✅ All AV1 advanced flags (10 flags)
• ✅ All audio standardization flags (8 flags)
• ✅ All stream operation flags (7 flags)
• ✅ EncodingOptions struct for structured configuration
• ✅ Flag parsing system
• ✅ Help text updates

Phase 3: Remaining Features ✅

Status: Complete

• ✅ Downmix track creation
• ✅ Subtitle extraction to external files
• ✅ Remove subtitles after extraction
• ✅ Container smart selection (detection and switching)
• ✅ Unsupported stream detection

---

⏳ Remaining Work

Phase 4: Missing Features

4.1 CC Extraction (ccextractor) ⏳

Status: NOT Implemented Priority: Low Impact:

• Time: +5-10s per file with CC streams
• Compression: None
• File Size: +50-200KB (external SRT file)
• Quality: None
• Functionality: Extracts EIA-608/teletext captions to external SRT

Details:

• Requires ccextractor binary (optional dependency)
• Extracts closed captions from video streams
• Creates external .cc.srt file
• Optional: Embed extracted CC back into container

Implementation Needed:

• Add --use-cc-extractor flag
• Add --embed-extracted-cc flag
• Implement ExtractCC() function in encoding/streams.go
• Check for ccextractor availability
• Run ccextractor before FFmpeg encoding
• Optionally embed extracted SRT back into output

Files to Modify:

• main.go - Add CLI flags
• encoding/streams.go - Add CC extraction functions
• EncodingOptions struct - Add UseCCExtractor, EmbedExtractedCC fields

---

4.2 Unsupported Stream Exclusion ⏳

Status: Partially Implemented (Detection exists, exclusion logic incomplete) Priority: Medium Impact:

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

Details:

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

Current Status:

• ✅ DetectUnsupportedStreams() exists in encoding/streams.go
• ✅ IsUnsupportedSubtitle() exists
• ⏳ Exclusion logic in FFmpeg command building needs verification
• ⏳ Stream mapping needs to skip unsupported streams when outputting to MKV

Implementation Needed:

• Verify unsupported streams are excluded from -map arguments when outputting to MKV
• Add logging when streams are excluded
• Test with files containing unsupported streams

Files to Check/Modify:

• main.go - Verify stream mapping excludes unsupported streams for MKV output
• encoding/streams.go - May need helper function to filter streams

---

4.3 Container Smart Selection Verification ⏳

Status: Implemented, needs testing Priority: Medium Impact:

• Time: None
• Compression: None
• File Size: None
• Quality: None
• Functionality: Prevents errors with Apple/broadcast streams in MKV

Details:

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

Current Status:

• ✅ GetContainerFormat() exists
• ✅ ShouldUseMP4Container() exists
• ✅ Logic integrated in main.go (lines 642-650)
• ⏳ Needs testing with Apple/broadcast format files

Implementation Needed:

• Test with MP4/MOV input files
• Test with files containing unsupported streams
• Verify container switching works correctly
• Add user notification when container is switched

---

Phase 5: Testing & Validation ⏳

5.1 Comprehensive Testing ⏳

Status: Not Started Priority: High

Test Cases Needed:

1. AV1 Advanced Options

   • Test all preset/CRF combinations
   • Test maxrate caps
   • Test resolution adjustments
   • Test disable flags (TF, SCD, AQ)
   • Test 10-bit encoding
   • Test film grain synthesis

2. Audio Standardization

   • Test codec conversion (AAC/Opus)
   • Test channel downmix (preserve/stereo/mono)
   • Test downmix creation
   • Test quality presets
   • Test bitrate configurations
   • Test Opus incompatible layouts

3. Stream Operations

   • Test stream reordering
   • Test subtitle conversion to SRT
   • Test subtitle extraction
   • Test remove subtitles after extract
   • Test with files containing multiple languages
   • Test with files containing unsupported streams

4. Container Selection

   • Test with MP4/MOV input files
   • Test with files containing unsupported streams
   • Test container switching logic

5. Integration Tests

   • Test with testvid.webm (default settings)
   • Test with various flag combinations
   • Test with files containing subtitles
   • Test with multichannel audio
   • Test with files already in target codec

Test Scripts:

• test_combinations.sh - Created but needs execution
• run_tests.sh - Created but needs execution

Expected Output:

• Test results table with:
  • Time taken
  • File size (before/after)
  • Encoding speed
  • Quality metrics (if available)
  • Flag combinations tested

---

5.2 Performance Benchmarks ⏳

Status: Not Started Priority: Medium

Benchmarks Needed:

• Compare encoding times with/without advanced features
• Measure file size differences
• Test compatibility across players
• Compare quality vs file size tradeoffs
• Test with different video resolutions

---

Phase 6: Documentation & Polish ⏳

6.1 Documentation Updates ⏳

Status: Partial Priority: Medium

Needed:

• ✅ Help text updated (Phase 3)
• ⏳ Usage examples in README
• ⏳ Flag reference guide
• ⏳ Quality/speed tradeoff explanations
• ⏳ Troubleshooting guide

6.2 Logging Enhancements ⏳

Status: Partial Priority: Low

Needed:

• ✅ Stream analysis logging (basic)
• ⏳ Detailed processing summary
• ⏳ Applied adjustments logging (CRF, bitrate, etc.)
• ⏳ Transcoded vs copied streams summary
• ⏳ Container switch notifications

6.3 Error Handling ⏳

Status: Partial Priority: Medium

Needed:

• ⏳ Better error messages for missing dependencies
• ⏳ Validation of flag combinations
• ⏳ Graceful handling of ccextractor unavailability
• ⏳ Better error messages for unsupported streams

---

Summary

✅ Fully Complete

• Phase 1: Core Implementation
• Phase 2: CLI Flags
• Phase 3: Remaining Features (downmix, extraction, container selection)

⏳ Partially Complete / Needs Work

• CC Extraction: NOT implemented (low priority)
• Unsupported Stream Exclusion: Detection exists, exclusion logic needs verification
• Container Smart Selection: Implemented, needs testing
• Testing: Scripts created, execution needed
• Documentation: Help text done, other docs needed
• Logging: Basic logging done, enhancements needed

📊 Priority Ranking

High Priority (Do Next):

1. Comprehensive testing with various flag combinations
2. Verify unsupported stream exclusion works correctly
3. Test container smart selection with real files

Medium Priority: 4. Performance benchmarking 5. Documentation updates 6. Logging enhancements 7. Error handling improvements

Low Priority: 8. CC extraction (ccextractor) implementation 9. Advanced logging features

---

Next Steps

1. Immediate: Run comprehensive tests with testvid.webm and various flag combinations
2. Short-term: Verify unsupported stream exclusion and container selection
3. Medium-term: Performance benchmarking and documentation
4. Long-term: CC extraction (if needed)

---

Files Status

✅ Complete Files

• main.go - Full integration with all features
• encoding/av1.go - All AV1 features
• encoding/audio.go - All audio features
• encoding/streams.go - Stream operations (except CC extraction)

⏳ Files Needing Work

• encoding/streams.go - Add CC extraction functions
• main.go - Verify unsupported stream exclusion
• Test scripts - Execute and document results
• Documentation files - Update with usage examples