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)

```bash
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

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

### Option 3: Using run.sh

```bash
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`:
```bash
source /home/stu/Projects/VT_Player/scripts/alias.sh
```

Then reload:
```bash
source ~/.bashrc
```

### For Zsh users:
Add this line to `~/.zshrc`:
```bash
source /home/stu/Projects/VT_Player/scripts/alias.sh
```

Then reload:
```bash
source ~/.zshrc
```

### After setting up:
From any directory, you can simply type:
```bash
VTPlayer
```

---

## What Each Script Does

### build.sh
```bash
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
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
```bash
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**
  ```bash
  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)
  ```bash
  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:
```bash
export CGO_ENABLED=0
bash scripts/build.sh
```

### Problem: "Permission denied" on scripts
**Solution:**
```bash
chmod +x scripts/*.sh
bash scripts/build.sh
```

### Problem: Out of disk space
**Solution:** Clean the cache
```bash
bash scripts/build.sh
# Or manually:
go clean -cache -modcache
```

### Problem: Outdated dependencies
**Solution:** Clean and rebuild
```bash
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:
```bash
ls -lh VTPlayer
file VTPlayer
```

If missing, rebuild:
```bash
bash scripts/build.sh
```

---

## Development Workflow

### Making code changes and testing:

```bash
# After editing code, rebuild and run:
VTPlayerRebuild
VTPlayer

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

### Quick test loop:
```bash
# 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**
   ```bash
   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:

```bash
# 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:
```bash
# 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:**
```bash
cd /home/stu/Projects/VT_Player
source scripts/alias.sh
VTPlayer
```

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