VideoTools/docs/BUILD_AND_RUN.md

VideoTools - Build and Run Guide

Quick Start (2 minutes)

Option 1: Using the Convenience Script (Recommended)

cd /home/stu/Projects/VideoTools
source scripts/alias.sh
VideoTools

This will:

1. Load the convenience commands
2. Build the application (if needed)
3. Run VideoTools GUI

Available commands after sourcing alias.sh:

• VideoTools - Run the application
• VideoToolsRebuild - Force a clean rebuild
• VideoToolsClean - Clean all build artifacts

Option 2: Using build.sh Directly

cd /home/stu/Projects/VideoTools
bash scripts/build.sh
./VideoTools

Option 3: Using run.sh

cd /home/stu/Projects/VideoTools
bash scripts/run.sh

Option 4: Windows Cross-Compilation

cd /home/stu/Projects/VideoTools
bash scripts/build-windows.sh
# Output: dist/windows/VideoTools.exe

Requirements for Windows build:

• Fedora/RHEL: sudo dnf install mingw64-gcc mingw64-winpthreads-static
• Debian/Ubuntu: sudo apt-get install gcc-mingw-w64

---

Making VideoTools Permanent (Optional)

To use VideoTools command from anywhere in your terminal:

For Bash users:

Add this line to ~/.bashrc:

source /home/stu/Projects/VideoTools/scripts/alias.sh

Then reload:

source ~/.bashrc

For Zsh users:

Add this line to ~/.zshrc:

source /home/stu/Projects/VideoTools/scripts/alias.sh

Then reload:

source ~/.zshrc

After setting up:

From any directory, you can simply type:

VideoTools

---

What Each Script Does

build.sh

bash scripts/build.sh

Purpose: Builds VideoTools from source with full dependency management

What it does:

1. Checks if Go is installed
2. Displays Go version
3. Cleans previous builds and cache
4. Downloads and verifies all dependencies
5. Builds the application
6. Shows output file location and size

When to use:

• First time building
• After major code changes
• When you want a clean rebuild
• When dependencies are out of sync

Exit codes:

• 0 = Success
• 1 = Build failed (check errors above)

run.sh

bash scripts/run.sh

Purpose: Runs VideoTools, building first if needed

What it does:

1. Checks if binary exists
2. If binary missing, runs build.sh
3. Verifies binary was created
4. Launches the application

When to use:

• Every time you want to run VideoTools
• When you're not sure if it's built
• After code changes (will rebuild if needed)

Advantages:

• Automatic build detection
• No manual steps needed
• Always runs the latest code

alias.sh

source scripts/alias.sh

Purpose: Creates convenient shell commands

What it does:

1. Adds VideoTools command (alias for scripts/run.sh)
2. Adds VideoToolsRebuild function
3. Adds VideoToolsClean function
4. Prints help text

When to use:

• Once per shell session
• Add to ~/.bashrc or ~/.zshrc for permanent access

Commands created:

VideoTools              # Run the app
VideoToolsRebuild       # Force rebuild
VideoToolsClean         # Remove build artifacts

---

Build Requirements

Required:

• Go 1.21 or later

  go version
  

  If not installed: https://golang.org/dl

Recommended:

• At least 2 GB free disk space (for dependencies)
• Stable internet connection (for downloading dependencies)

Optional:

• FFmpeg (for actual video encoding)

  ffmpeg -version
  

Platform Support

Linux ✅ (Primary Platform)

• Full support with native build scripts
• Hardware acceleration (VAAPI, NVENC, QSV)
• X11 and Wayland display server support

Windows ✅ (New in dev14)

• Cross-compilation from Linux: bash scripts/build-windows.sh
• Requires MinGW-w64 toolchain for cross-compilation
• Native Windows builds planned for future release
• Hardware acceleration (NVENC, QSV, AMF)

For detailed Windows setup, see: Windows Compatibility Guide

---

Troubleshooting

Problem: "Go is not installed"

Solution:

1. Install Go from https://golang.org/dl
2. Add Go to PATH: Add /usr/local/go/bin to your $PATH
3. Verify: go version

Problem: Build fails with "CGO_ENABLED" error

Solution: The script already handles this with CGO_ENABLED=0. If you still get errors:

export CGO_ENABLED=0
bash scripts/build.sh

Problem: "Permission denied" on scripts

Solution:

chmod +x scripts/*.sh
bash scripts/build.sh

Problem: Out of disk space

Solution: Clean the cache

bash scripts/build.sh
# Or manually:
go clean -cache -modcache

Problem: Outdated dependencies

Solution: Clean and rebuild

rm -rf go.mod go.sum
go mod init git.leaktechnologies.dev/stu/VideoTools
bash scripts/build.sh

Problem: Binary won't run

Solution: Check if it was built:

ls -lh VideoTools
file VideoTools

If missing, rebuild:

bash scripts/build.sh

---

Development Workflow

Making code changes and testing:

# After editing code, rebuild and run:
VideoToolsRebuild
VideoTools

# Or in one command:
bash scripts/build.sh && ./VideoTools

Quick test loop:

# Terminal 1: Watch for changes and rebuild
while true; do bash scripts/build.sh; sleep 2; done

# Terminal 2: Test the app
VideoTools

---

DVD Encoding Workflow

To create a professional DVD video:

1. Start the application

   VideoTools
   

2. Go to Convert module

   • Click the Convert tile from main menu

3. Load a video

   • Drag and drop, or use file browser

4. Select DVD format

   • Choose "DVD-NTSC (MPEG-2)" or "DVD-PAL (MPEG-2)"
   • DVD options appear automatically

5. Choose aspect ratio

   • Select 4:3 or 16:9

6. Name output

   • Enter filename (without .mpg extension)

7. Add to queue

   • Click "Add to Queue"

8. Start encoding

   • Click "View Queue" → "Start Queue"

9. Use output file

   • Output: filename.mpg
   • Import into DVDStyler
   • Author and burn to disc

Output specifications:

NTSC:

• 720×480 @ 29.97fps
• MPEG-2 video
• AC-3 stereo audio @ 48 kHz
• Perfect for USA, Canada, Japan, Australia

PAL:

• 720×576 @ 25 fps
• MPEG-2 video
• AC-3 stereo audio @ 48 kHz
• Perfect for Europe, Africa, Asia

Both output region-free, DVDStyler-compatible, PS2-compatible video.

---

Performance Notes

Build time:

• First build: 30-60 seconds (downloads dependencies)
• Subsequent builds: 5-15 seconds (uses cached dependencies)
• Rebuild with changes: 10-20 seconds

File sizes:

• Binary: ~35 MB (optimized)
• With dependencies in cache: ~1 GB total

Runtime:

• Startup: 1-3 seconds
• Memory usage: 50-150 MB depending on video complexity
• Encoding speed: Depends on CPU and video complexity

---

Cross-Platform Building

Linux to Windows Cross-Compilation

# Install MinGW-w64 toolchain
# Fedora/RHEL:
sudo dnf install mingw64-gcc mingw64-winpthreads-static

# Debian/Ubuntu:
sudo apt-get install gcc-mingw-w64

# Cross-compile for Windows
bash scripts/build-windows.sh

# Output: dist/windows/VideoTools.exe

Multi-Platform Build Script

Multi-Platform Build Script

#!/bin/bash
# Build for all platforms

echo "Building for Linux..."
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o VideoTools-linux

echo "Building for Windows..."
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o VideoTools-windows.exe

echo "Building for macOS..."
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o VideoTools-mac

echo "Building for macOS ARM64..."
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o VideoTools-mac-arm64

echo "All builds complete!"
ls -lh VideoTools-*

Production Use

For production deployment:

# Create optimized binary
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o VideoTools

# Verify it works
./VideoTools

# File size will be smaller with -ldflags
ls -lh VideoTools

---

Getting Help

Check the documentation:

• DVD_USER_GUIDE.md - How to use DVD encoding
• DVD_IMPLEMENTATION_SUMMARY.md - Technical details
• README.md - Project overview

Debug a build:

# Verbose output
bash scripts/build.sh 2>&1 | tee build.log

# Check go environment
go env

# Verify dependencies
go mod graph

Report issues:

Include:

1. Output from go version
2. OS and architecture (uname -a)
3. Exact error message
4. Steps to reproduce

---

Summary

Easiest way:

cd /home/stu/Projects/VideoTools
source scripts/alias.sh
VideoTools

That's it! The scripts handle everything else automatically.