gwutilz/gwencoder/README.md

GWEncoder v3.0

A unified video encoding tool with advanced AV1, audio standardization, and stream management features. GWEncoder provides multiple encoding modes and extensive customization options for video processing.

📁 Project Structure

gwencoder/
├── cmd/
│   └── gwencoder/          # Main application entry point
│       └── main.go
├── pkg/
│   └── encoding/           # Encoding logic package
│       ├── audio.go        # Audio processing functions
│       ├── av1.go          # AV1 codec handling
│       └── streams.go      # Stream management
├── docs/
│   ├── phases/             # Development phase documentation
│   ├── reference/          # Technical reference docs
│   └── guides/             # User guides and tutorials
├── scripts/                # Helper and test scripts
│   ├── run_tests.sh
│   ├── phase5_test.sh
│   └── ...
├── tests/
│   ├── artifacts/          # Test media files
│   ├── logs/               # Test output logs
│   └── outputs/            # Test encoding outputs
├── integrations/
│   └── tdarr/              # Tdarr plugin integration
├── logs/                   # Runtime logs (git-ignored)
├── build/                  # Compiled binaries (git-ignored)
├── .archive/               # Archived old binaries
├── Makefile               # Build automation
├── go.mod                 # Go module definition
└── README.md              # This file

Features

• Multiple Codecs: AV1 (default), H.264/x264, NVIDIA NVENC HEVC
• Hardware Acceleration: NVIDIA NVENC support for faster encoding
• Advanced AV1 Options: Preset, CRF, tune modes, temporal filtering, scene change detection
• Audio Standardization: AAC/Opus conversion, channel handling, quality presets
• Stream Management: English-first reordering, subtitle conversion/extraction, CC extraction
• Smart Container Selection: Automatic format switching for compatibility
• Progress Tracking: Real-time encoding progress with ETA
• Resolution-Aware: Automatic CRF adjustment based on video resolution

Quick Start

Building from Source

# Using make (recommended)
make build

# Or using go directly
go build -o build/gwencoder ./cmd/gwencoder

Basic Usage

# Fast encoding (daily driver)
./build/gwencoder --fast

# Web-optimized (streaming, Discord)
./build/gwencoder --web

# Maximum compression
./build/gwencoder --tiny

# High quality archival
./build/gwencoder --hq

# Best possible quality
./build/gwencoder --slow

With Options

# Fast encoding with custom AV1 settings
./build/gwencoder --fast --av1-preset 8 --av1-crf 30

# Web mode with bitrate cap
./build/gwencoder --web --av1-maxrate 5000

# High quality with audio options
./build/gwencoder --hq --audio-quality high --audio-create-downmix

Installation

Requirements

• FFmpeg: Required for encoding
• FFprobe: Required for stream analysis
• ccextractor: Optional, for closed caption extraction
• Go 1.24+: Required for building from source

Building

# Clone the repository
git clone <repository-url>
cd gwencoder

# Build with make
make build

# Or install to GOPATH/bin
make install

Development

# Download dependencies
make deps

# Run tests
make test

# Clean build artifacts
make clean

# Tidy go.mod
make tidy

Encoding Modes

--fast

Best for: Daily driver, quick turnaround

• Container: MKV
• CRF: 28 (auto-adjusted for resolution)
• Preset: 10 (speed optimized)
• Audio: Opus 64kbps per channel
• Use case: General purpose encoding with good quality/speed balance

--web

Best for: Streaming, Discord, web upload

• Container: WEBM
• CRF: 35 (higher compression)
• Preset: 10
• Audio: Opus 64kbps per channel
• Use case: Web distribution, smaller file sizes

--tiny

Best for: Maximum compression

• Container: MP4
• CRF: 42 (very high compression)
• Preset: 8
• Audio: Opus 48kbps per channel
• Use case: Storage-constrained scenarios

--hq

Best for: High quality archival

• Container: MKV
• CRF: 22 (high quality)
• Preset: 6 (slower, better quality)
• Audio: Opus 96kbps per channel
• Use case: Long-term storage, quality preservation

--slow

Best for: Best possible quality

• Container: MKV
• CRF: 18 (very high quality)
• Preset: 4 (slowest, best quality)
• Audio: Opus 128kbps per channel
• Use case: Master copies, archival

Codec Options

AV1 (Default)

Modern, efficient codec with excellent compression:

./build/gwencoder --fast

H.264/x264

Widely compatible, good for older devices:

./build/gwencoder --fast --x264

NVIDIA NVENC HEVC

Hardware-accelerated encoding (requires NVIDIA GPU):

./build/gwencoder --fast --nvhevc

AV1 Advanced Options

Preset and CRF

# Custom preset (0-12, higher = faster)
./build/gwencoder --fast --av1-preset 8

# Custom CRF (lower = higher quality, typically 18-50)
./build/gwencoder --fast --av1-crf 30

# Combined
./build/gwencoder --fast --av1-preset 8 --av1-crf 30

Preset Guide:

• 0-2: Slowest, best quality (archival)
• 4-6: Slow, high quality (HQ mode)
• 8-10: Balanced (fast mode)
• 10-12: Fastest, lower quality (quick encoding)

CRF Guide:

• 18-22: Very high quality (archival)
• 24-28: High quality (general use)
• 30-35: Good quality (web distribution)
• 38-42: Lower quality (maximum compression)

Tune Modes

# Visual Quality (default)
./build/gwencoder --fast --av1-tune 0

# PSNR optimization
./build/gwencoder --fast --av1-tune 1

# SSIM optimization
./build/gwencoder --fast --av1-tune 2

Bitrate Control

# Set maximum bitrate cap (kbps)
./build/gwencoder --fast --av1-maxrate 5000

Advanced Features

# Disable temporal filtering (faster, slightly lower quality)
./build/gwencoder --fast --av1-disable-tf

# Disable scene change detection (faster encoding)
./build/gwencoder --fast --av1-disable-scd

# Disable adaptive quantization (faster encoding)
./build/gwencoder --fast --av1-disable-aq

# Use 10-bit encoding (better quality, larger files)
./build/gwencoder --fast --av1-10bit

# Film grain synthesis (0-50)
./build/gwencoder --fast --av1-film-grain 10

Audio Options

Codec Selection

# Force AAC (better MP4 compatibility)
./build/gwencoder --fast --aac

# Force Opus (better compression, MKV/WEBM)
./build/gwencoder --fast --opus

# Explicit codec selection
./build/gwencoder --fast --audio-codec aac
./build/gwencoder --fast --audio-codec opus

Quality Presets

# High quality (128kbps/ch AAC, 96kbps/ch Opus)
./build/gwencoder --fast --audio-quality high

# Balanced (80kbps/ch AAC, 64kbps/ch Opus)
./build/gwencoder --fast --audio-quality balanced

# Small size (64kbps/ch AAC, 48kbps/ch Opus)
./build/gwencoder --fast --audio-quality small

Channel Handling

# Preserve original channels
./build/gwencoder --fast --audio-preserve

# Downmix to stereo
./build/gwencoder --fast --audio-stereo

# Downmix to mono
./build/gwencoder --fast --audio-mono

Custom Bitrates

# Per-channel bitrate
./build/gwencoder --fast --audio-bitrate-per-ch 96

# Stereo downmix bitrate
./build/gwencoder --fast --audio-stereo-bitrate 160

Downmix Creation

# Create additional stereo downmix from 5.1/7.1
./build/gwencoder --fast --audio-create-downmix

Stream Operations

Stream Reordering

# Reorder English streams first (default: enabled)
./build/gwencoder --fast --reorder-streams

# Disable reordering
./build/gwencoder --fast --no-reorder-streams

# Custom language codes
./build/gwencoder --fast --lang-codes "eng,en,de,fr"

Subtitle Handling

# Convert subtitles to SRT (default: enabled)
./build/gwencoder --fast --convert-subs-srt

# Disable subtitle conversion
./build/gwencoder --fast --no-convert-subs-srt

# Extract subtitles to external files
./build/gwencoder --fast --extract-subs

# Remove embedded subs after extraction
./build/gwencoder --fast --extract-subs --remove-subs-after-extract

Closed Caption Extraction

# Extract closed captions using ccextractor
./build/gwencoder --fast --use-cc-extractor

# Extract and embed CC as subtitle track
./build/gwencoder --fast --use-cc-extractor --embed-extracted-cc

Note: Requires ccextractor in PATH. If unavailable, extraction is skipped with a warning.

Video Options

Bitrate Control

# Set maximum video bitrate (kbps)
./build/gwencoder --fast --maxrate 8000

Force Transcoding

# Force transcoding even if already in target codec
./build/gwencoder --fast --force-transcode

Testing

Run the test suite:

# Run all tests from scripts directory
cd scripts
./run_tests.sh

# Run phase 5 tests
./phase5_test.sh

Test outputs are saved to tests/logs/ and tests/outputs/.

Documentation

• Development Phases: Historical development documentation
• Reference Documentation: Technical specifications and codec details
• User Guides: Troubleshooting and advanced usage
• Tdarr Integration: Tdarr plugin documentation

Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

Quick Fixes

FFmpeg not found

Error: FFmpeg not available

Solution: Install FFmpeg and ensure it's in your PATH

ccextractor not found

⚠️  ccextractor not available in PATH, skipping CC extraction

Solution: Install ccextractor or disable CC extraction

Supported Formats

Input Formats

• WMV, AVI, MP4, MKV, MPG, TS, WEBM

Output Formats

• MKV (default for most modes)
• MP4 (for compatibility)
• WEBM (for web distribution)

Advanced Features

Resolution-Aware CRF Adjustment

GWEncoder automatically adjusts CRF based on video resolution:

• 4K (2160p): CRF +2 (higher quality needed)
• 1080p: No adjustment
• 720p: CRF -2 (lower quality acceptable)

Smart Container Selection

Automatically switches to MP4 when:

• Input is Apple/broadcast format (MP4/MOV)
• Unsupported subtitle streams detected (EIA-608, CC_DEC, tx3g)

Stream Filtering

Unsupported streams are automatically filtered for MKV output:

• EIA-608 closed captions
• CC_DEC streams
• tx3g subtitles

Command Reference

See ./build/gwencoder --help for complete command reference.

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Changelog

v3.0

• Reorganized project structure for better maintainability
• Added Makefile for easy building
• Added comprehensive .gitignore
• Added AV1 advanced options
• Added audio standardization
• Added stream reordering and subtitle handling
• Added CC extraction support
• Added smart container selection
• Enhanced logging and error handling