VT_Player/docs/BUILD_AND_RUN.md

VT Player - Build and Run Guide

Forked from VideoTools. Some docs still mention "VideoTools"; use the new VTPlayer commands and paths shown below for this project.

Quick Start (2 minutes)

Option 1: Using the Convenience Script (Recommended)

cd /home/stu/Projects/VT_Player
source scripts/alias.sh
VTPlayer

This will:

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

Available commands after sourcing alias.sh:

• VTPlayer - Run the application
• VTPlayerRebuild - Force a clean rebuild
• VTPlayerClean - Clean all build artifacts

Option 2: Using build.sh Directly

cd /home/stu/Projects/VT_Player
bash scripts/build.sh
./VTPlayer

Option 3: Using run.sh

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

---

Making VT Player Permanent (Optional)

To use VTPlayer command from anywhere in your terminal:

For Bash users:

Add this line to ~/.bashrc:

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

Then reload:

source ~/.bashrc

For Zsh users:

Add this line to ~/.zshrc:

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

Then reload:

source ~/.zshrc

After setting up:

From any directory, you can simply type:

VTPlayer

---

What Each Script Does

build.sh

bash scripts/build.sh

Purpose: Builds VT Player 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 VT Player, 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 VT Player
• 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 VTPlayer command (alias for scripts/run.sh)
2. Adds VTPlayerRebuild function
3. Adds VTPlayerClean function
4. Prints help text

When to use:

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

Commands created:

VTPlayer                # Run the app
VTPlayerRebuild         # Force rebuild
VTPlayerClean           # 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
  

---

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/VT_Player
bash scripts/build.sh

Problem: Binary won't run

Solution: Check if it was built:

ls -lh VTPlayer
file VTPlayer

If missing, rebuild:

bash scripts/build.sh

---

Development Workflow

Making code changes and testing:

# After editing code, rebuild and run:
VTPlayerRebuild
VTPlayer

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

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
VTPlayer

---

DVD Encoding Workflow

To create a professional DVD video:

1. Start the application

   VTPlayer
   

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

---

Production Use

For production deployment:

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

# Verify it works
./VTPlayer

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

---

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/VT_Player
source scripts/alias.sh
VTPlayer

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