gwutilz/MANUAL.md

GWEncoder v3.0 - Complete User Manual

Table of Contents

1. What is GWEncoder?
2. What is it used for?
3. Why these settings?
4. Installation & Setup
5. Basic Usage
6. Encoding Modes Explained
7. Codec Options
8. Audio Options
9. Video Options
10. Advanced Usage
11. Troubleshooting
12. Technical Details

---

What is GWEncoder?

GWEncoder is a unified video encoding tool designed to simplify the complex process of video compression and format conversion. It's a command-line application built in Go that provides multiple encoding modes optimized for different use cases.

Key Features:

• Unified Interface: Single tool with multiple encoding modes
• Multiple Codecs: AV1, H.264/x264, NVIDIA NVENC HEVC support
• Hardware Acceleration: GPU-accelerated encoding when available
• Automatic Optimization: Smart CPU core detection and utilization
• Progress Tracking: Real-time encoding progress with ETA
• Cross-Platform: Works on Linux, macOS, and Windows
• No Dependencies: Single binary with minimal external requirements

---

What is it used for?

GWEncoder is designed for various video encoding scenarios:

Primary Use Cases:

1. Content Creation

   • Converting raw footage to web-ready formats
   • Creating multiple versions for different platforms
   • Optimizing file sizes for storage

2. Web Publishing

   • Preparing videos for YouTube, Vimeo, social media
   • Creating web-optimized formats (WEBM, MP4)
   • Balancing quality vs. file size for web delivery

3. Archival & Storage

   • Compressing large video files for long-term storage
   • Converting between different video formats
   • Creating backup copies with reduced file sizes

4. Streaming Preparation

   • Encoding videos for live streaming platforms
   • Creating adaptive bitrate versions
   • Optimizing for specific bandwidth requirements

5. Professional Workflows

   • Batch processing multiple files
   • Consistent encoding across projects
   • Integration with automated workflows

---

Why these settings?

The encoding settings in GWEncoder are carefully chosen based on extensive testing and industry best practices:

Codec Selection Rationale:

AV1 (Default)

• Why: Next-generation codec with 30-50% better compression than H.264
• Trade-off: Slower encoding but smaller files
• Best for: Future-proofing, maximum compression, web delivery

H.264/x264

• Why: Universal compatibility, hardware acceleration support
• Trade-off: Larger files but faster encoding and broad compatibility
• Best for: Maximum compatibility, older devices, quick encoding

NVIDIA NVENC HEVC

• Why: Hardware acceleration, good compression, reasonable compatibility
• Trade-off: Requires NVIDIA GPU, slightly larger files than software HEVC
• Best for: Fast encoding with good quality, GPU-accelerated workflows

Quality Settings (CRF):

CRF 32 (Fast/Quick modes)

• Why: Good balance of quality and file size
• Visual Impact: Slight quality loss, significant size reduction
• Best for: General purpose, web delivery, storage optimization

CRF 40 (Web mode)

• Why: Optimized for web streaming, smaller files
• Visual Impact: Noticeable quality loss but acceptable for web
• Best for: Social media, web embeds, bandwidth-limited scenarios

CRF 45 (Tiny mode)

• Why: Maximum compression for storage
• Visual Impact: Significant quality loss, very small files
• Best for: Archival, previews, storage-constrained environments

Preset Settings:

Preset 10 (Fast modes)

• Why: Fast encoding with reasonable quality
• Trade-off: Slightly larger files but much faster encoding
• Best for: Quick turnaround, batch processing

Preset 8 (Tiny mode)

• Why: Maximum compression efficiency
• Trade-off: Slower encoding but smallest possible files
• Best for: Storage optimization, archival purposes

Audio Settings:

Opus Codec

• Why: Superior compression and quality compared to AAC
• Best for: WEBM containers, modern web browsers, quality-focused encoding

AAC Codec

• Why: Universal compatibility, hardware support
• Best for: MP4 containers, older devices, maximum compatibility

Bitrate Selection (64-80 kbps per channel)

• Why: Transparent quality for most content at reasonable file sizes
• Calculation: Stereo = 128-160 kbps total, 5.1 = 384-480 kbps total
• Best for: Balancing quality and file size

---

Installation & Setup

Prerequisites:

1. FFmpeg (Required)

   # Ubuntu/Debian:
   sudo apt update
   sudo apt install ffmpeg
   
   # CentOS/RHEL:
   sudo yum install ffmpeg
   
   # macOS:
   brew install ffmpeg
   
   # Windows:
   # Download from https://ffmpeg.org/download.html
   

2. Go (For building from source)

   # Ubuntu/Debian:
   sudo apt install golang-go
   
   # CentOS/RHEL:
   sudo yum install golang
   
   # macOS:
   brew install go
   

Building GWEncoder:

# Clone or download the project
cd /path/to/GWUTILZ

# Build shared utilities
cd gwutils
go build

# Build main application
cd ../gwencoder
go mod tidy
go build -o gwencoder main.go

# Make executable
chmod +x gwencoder

# Test installation
./gwencoder --help

Verification:

# Check FFmpeg installation
ffmpeg -version

# Check FFprobe installation
ffprobe -version

# Test GWEncoder
./gwencoder --info

---

Basic Usage

Command Structure:

./gwencoder [MODE] [OPTIONS] [CODEC] [AUDIO] [VIDEO]

Quick Examples:

# Fast AV1 encoding (most common)
./gwencoder --fast

# Web-optimized encoding for social media
./gwencoder --web

# Quick encoding with H.264 for compatibility
./gwencoder --quick --x264

# Tiny files for storage
./gwencoder --tiny

# Custom bitrate control
./gwencoder --fast --maxrate 5000

# Custom audio bitrate
./gwencoder --web --abr 128

Getting Help:

./gwencoder --help      # Show all options
./gwencoder --info      # System information
./gwencoder --stats     # Encoding statistics

---

Encoding Modes Explained

--fast Mode

Purpose: Quick encoding with good quality Best for: General purpose, quick turnaround, local storage

Settings:

• Codec: AV1 (libsvtav1)
• CRF: 32 (good quality)
• Preset: 10 (fast encoding)
• Container: MKV
• Audio: Opus 64kbps per channel
• Maxrate: 2000 kbps

Use Cases:

• Converting raw footage quickly
• Creating local backups
• General video processing
• When you need good quality fast

Example:

./gwencoder --fast
# Input: video.mp4 → Output: video-AV1-Fast-GWELL.mkv

--web Mode

Purpose: Web-optimized encoding for streaming Best for: YouTube, social media, web embeds

Settings:

• Codec: AV1 (libsvtav1)
• CRF: 40 (web-optimized quality)
• Preset: 10 (balanced encoding)
• Container: WEBM
• Audio: Opus 64kbps per channel
• Maxrate: 2000 kbps

Use Cases:

• YouTube uploads
• Social media posts
• Web page embeds
• Streaming platforms

Example:

./gwencoder --web
# Input: video.mp4 → Output: video-AV1-Web-Optimized-GWELL.webm

--quick Mode

Purpose: Balanced quality and speed Best for: General purpose, good quality, reasonable speed

Settings:

• Codec: AV1 (libsvtav1)
• CRF: 32 (good quality)
• Preset: 10 (balanced encoding)
• Container: MKV
• Audio: Opus 80kbps per channel
• Maxrate: 3000 kbps

Use Cases:

• High-quality local encoding
• Professional workflows
• When you need both speed and quality

Example:

./gwencoder --quick
# Input: video.mp4 → Output: video-AV1-Quick-GWELL.mkv

--tiny Mode

Purpose: Maximum compression for storage Best for: Archival, storage optimization, previews

Settings:

• Codec: AV1 (libsvtav1)
• CRF: 45 (high compression)
• Preset: 8 (quality-focused)
• Container: MP4
• Audio: AAC 64kbps per channel
• Maxrate: 1500 kbps

Use Cases:

• Long-term storage
• Bandwidth-limited scenarios
• Creating previews
• Archival purposes

Example:

./gwencoder --tiny
# Input: video.mp4 → Output: video-AV1-Tiny-GWELL.mp4

--full Mode

Purpose: Full interactive mode with all options Best for: Advanced users, custom configurations

Features:

• All codec options
• Custom quality settings
• Hardware acceleration options
• Advanced audio settings
• Resolution scaling
• Subtitle handling

Example:

./gwencoder --full
# Interactive mode with full control

---

Codec Options

--x264 (H.264/x264)

What it is: Software H.264 encoder Compatibility: Universal (99% of devices) Speed: Fast encoding File Size: Larger than AV1 Quality: Excellent

Best for:

• Maximum compatibility
• Older devices
• Quick encoding
• When file size isn't critical

Example:

./gwencoder --fast --x264
# Uses H.264 instead of AV1

--nvhevc (NVIDIA NVENC HEVC)

What it is: Hardware-accelerated HEVC encoder Compatibility: Good (modern devices) Speed: Very fast (GPU-accelerated) File Size: Good compression Quality: Very good

Requirements:

• NVIDIA GPU with NVENC support
• Modern drivers

Best for:

• Fast encoding with good quality
• GPU-accelerated workflows
• When you have NVIDIA hardware

Example:

./gwencoder --fast --nvhevc
# Uses NVIDIA hardware acceleration

Default (AV1)

What it is: Next-generation codec Compatibility: Good (modern browsers/devices) Speed: Slower encoding File Size: Excellent compression Quality: Excellent

Best for:

• Future-proofing
• Maximum compression
• Web delivery
• When encoding time isn't critical

---

Audio Options

--aac

What it is: Forces AAC audio codec Compatibility: Universal Quality: Good File Size: Larger than Opus

Best for:

• Maximum compatibility
• MP4 containers
• Older devices

Example:

./gwencoder --web --aac
# Forces AAC instead of Opus

--opus

What it is: Forces Opus audio codec Compatibility: Good (modern devices) Quality: Excellent File Size: Smaller than AAC

Best for:

• Quality-focused encoding
• WEBM containers
• Modern web delivery

Example:

./gwencoder --fast --opus
# Forces Opus instead of container default

--abr <bitrate>

What it is: Sets custom audio bitrate per channel Default: Mode-specific (64-80 kbps per channel) Range: 32-256 kbps per channel recommended

Calculation:

• Stereo: 2 channels × bitrate = total bitrate
• 5.1: 6 channels × bitrate = total bitrate

Examples:

./gwencoder --fast --abr 128    # 256 kbps total for stereo
./gwencoder --web --abr 64      # 128 kbps total for stereo
./gwencoder --tiny --abr 32     # 64 kbps total for stereo

---

Video Options

--maxrate <bitrate>

What it is: Sets maximum video bitrate in kbps Purpose: Caps video bitrate to control file size Default: Mode-specific (1500-3000 kbps)

Why use it:

• Control file sizes
• Meet platform requirements
• Bandwidth limitations
• Storage constraints

Examples:

./gwencoder --fast --maxrate 5000    # 5 Mbps max
./gwencoder --web --maxrate 2000     # 2 Mbps max
./gwencoder --tiny --maxrate 1000    # 1 Mbps max

Bitrate Guidelines:

• 500-1000 kbps: Very low quality, tiny files
• 1000-2000 kbps: Low quality, small files
• 2000-5000 kbps: Good quality, medium files
• 5000-10000 kbps: High quality, large files
• 10000+ kbps: Very high quality, very large files

---

Advanced Usage

Combining Options

# High-quality H.264 with custom settings
./gwencoder --quick --x264 --maxrate 8000 --abr 128

# Web-optimized with hardware acceleration
./gwencoder --web --nvhevc --maxrate 3000

# Tiny files with maximum compression
./gwencoder --tiny --maxrate 1000 --abr 32

Batch Processing

GWEncoder automatically processes all supported video files in the current directory:

# Process all videos in current directory
./gwencoder --fast

# Process specific files (place in directory with only those files)
mkdir batch_processing
cp video1.mp4 video2.mkv batch_processing/
cd batch_processing
./gwencoder --web

File Naming Convention

Output files follow this pattern:

[original_name]-[CODEC]-[MODE]-GWELL.[extension]

Examples:

• video.mp4 → video-AV1-Fast-GWELL.mkv
• movie.mkv → movie-H264-Web-Optimized-GWELL.mkv
• clip.avi → clip-NVHEVC-Quick-GWELL.mkv

Supported Input Formats

• Video: WMV, AVI, MP4, MKV, MPG, TS, WEBM
• Audio: Any format supported by FFmpeg
• Containers: Any container supported by FFmpeg

Supported Output Formats

• Containers: MKV, MP4, WEBM
• Video Codecs: AV1, H.264, HEVC
• Audio Codecs: Opus, AAC

---

Troubleshooting

Common Issues

"FFmpeg not found"

Problem: GWEncoder can't find FFmpeg Solution:

# Check if FFmpeg is installed
ffmpeg -version

# Install FFmpeg if missing
sudo apt install ffmpeg  # Ubuntu/Debian
brew install ffmpeg      # macOS

"No video files found"

Problem: No supported video files in directory Solution:

# Check current directory
ls -la *.mp4 *.mkv *.avi *.webm

# Move to directory with video files
cd /path/to/video/files
./gwencoder --fast

"Permission denied"

Problem: Can't execute gwencoder Solution:

chmod +x gwencoder

"Out of memory" or "Encoding too slow"

Problem: System resources insufficient Solutions:

• Use --tiny mode for smaller files
• Use --x264 for faster encoding
• Use --nvhevc if you have NVIDIA GPU
• Close other applications
• Process files one at a time

"NVIDIA NVENC not available"

Problem: --nvhevc fails Solutions:

• Check if you have NVIDIA GPU
• Update NVIDIA drivers
• Use --x264 instead
• Use default AV1 encoding

Performance Optimization

For Speed:

# Use H.264 for fastest encoding
./gwencoder --fast --x264

# Use hardware acceleration if available
./gwencoder --fast --nvhevc

# Use tiny mode for smallest files
./gwencoder --tiny

For Quality:

# Use higher bitrates
./gwencoder --quick --maxrate 8000

# Use higher audio bitrates
./gwencoder --fast --abr 128

# Use AV1 for best compression
./gwencoder --quick  # (default AV1)

For Compatibility:

# Use H.264 with MP4
./gwencoder --web --x264

# Use AAC audio
./gwencoder --fast --aac

Log Files

GWEncoder creates several log files for troubleshooting:

• gwencoder_log.txt: Successful encoding history
• gwencoder_errors.txt: Error details and FFmpeg output
• gwencoder_stats.json: Encoding statistics and performance data

Check these files if you encounter issues:

# View recent errors
tail -20 gwencoder_errors.txt

# View encoding history
tail -20 gwencoder_log.txt

# View statistics
cat gwencoder_stats.json

---

Technical Details

Architecture

GWEncoder is built with a modular architecture:

gwencoder/
├── main.go           # Main application logic
└── gwutils/          # Shared utilities package
    ├── common.go     # Common functions
    └── config.go     # Configuration structures

FFmpeg Integration

GWEncoder uses FFmpeg for all video processing:

• Video Encoding: libsvtav1, libx264, hevc_nvenc
• Audio Encoding: libopus, aac
• Container Support: MKV, MP4, WEBM
• Progress Parsing: Real-time FFmpeg output analysis

Performance Characteristics

Encoding Speed (relative):

1. NVIDIA NVENC HEVC: Fastest (hardware accelerated)
2. H.264/x264: Fast (software, optimized)
3. AV1: Slower (software, high compression)

File Size (relative):

1. AV1: Smallest files
2. HEVC: Medium files
3. H.264: Largest files

Quality (at same bitrate):

1. AV1: Best quality
2. HEVC: Good quality
3. H.264: Good quality

Memory Usage

• Typical: 200-500 MB RAM
• Peak: 1-2 GB RAM (depending on video resolution)
• Recommendation: 4+ GB RAM for 1080p, 8+ GB for 4K

CPU Usage

• AV1: High CPU usage, benefits from many cores
• H.264: Medium CPU usage, good single-core performance
• NVENC: Low CPU usage (GPU does the work)

Storage Requirements

• Temporary: ~2x input file size during encoding
• Output: Varies by settings (typically 10-50% of input size)
• Logs: Minimal (few MB per encoding session)

---

Best Practices

Choosing the Right Mode

1. For Web Uploads: Use --web mode
2. For Local Storage: Use --fast or --quick mode
3. For Archival: Use --tiny mode
4. For Compatibility: Use --x264 codec
5. For Speed: Use --nvhevc if available

File Size Management

1. Large Files: Use --tiny mode or lower --maxrate
2. Quality Priority: Use --quick mode with higher --maxrate
3. Storage Optimization: Use AV1 codec with appropriate CRF

Batch Processing

1. Organize Files: Group similar content together
2. Test First: Try one file before batch processing
3. Monitor Resources: Watch CPU/memory usage
4. Backup Originals: Keep source files safe

Quality vs. Speed Trade-offs

1. Speed Priority: H.264 + fast preset
2. Quality Priority: AV1 + quality preset
3. Balanced: AV1 + balanced preset
4. Storage Priority: AV1 + high CRF + low maxrate

---

This manual provides comprehensive guidance for using GWEncoder effectively. For additional support or feature requests, please refer to the project documentation or create an issue in the project repository.