VT_Player/WINDOWS_COMPATIBILITY.md

# VT_Player Windows Compatibility Guide

This document explains how VT_Player has been made compatible with Windows 11 and how it shares dependencies with VideoTools.

---

## Quick Start (Windows 11)

If you already have VideoTools installed and working on Windows 11, VT_Player should work immediately with the same dependencies:

```bash
# In Git Bash
cd /path/to/VT_Player
./scripts/build.sh
```

The build will:
1. Detect Windows platform automatically
2. Build `vt_player.exe` with Windows GUI flags
3. Check for FFmpeg on PATH (should already be there from VideoTools)

---

## What Was Changed for Windows Compatibility

### 1. **Universal Build Script** (`scripts/build.sh`)
- Auto-detects platform (Linux/macOS/Windows)
- Uses appropriate build flags for each platform
- Windows-specific: `-ldflags="-H windowsgui -s -w"`
  - `-H windowsgui`: Hide console window for GUI app
  - `-s -w`: Strip debug symbols for smaller binary

### 2. **Console Window Hiding** (`internal/utils/`)

Added platform-specific utilities to hide FFmpeg/FFprobe console windows on Windows:

**`internal/utils/proc_windows.go`:**
```go
//go:build windows

package utils

import (
	"os/exec"
	"syscall"
)

// ApplyNoWindow hides the console window for spawned processes on Windows.
func ApplyNoWindow(cmd *exec.Cmd) {
	if cmd == nil {
		return
	}
	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
}
```

**`internal/utils/proc_other.go`:**
```go
//go:build !windows

package utils

import "os/exec"

// ApplyNoWindow is a no-op on non-Windows platforms.
func ApplyNoWindow(cmd *exec.Cmd) {
	_ = cmd
}
```

### 3. **FFmpeg Integration**

VT_Player shares FFmpeg with VideoTools on Windows. If you've already installed VideoTools on Windows 11:
- FFmpeg and ffprobe are already on your PATH
- VT_Player will use the same binaries
- No additional FFmpeg installation needed

---

## Building on Windows 11

### Prerequisites

From your VideoTools setup, you should already have:
- ✅ Go 1.21+ (`go version` to check)
- ✅ MinGW-w64 (for CGO compilation)
- ✅ FFmpeg on PATH
- ✅ Git Bash or MSYS2

### Build Process

1. **Open Git Bash** (or MSYS2)

2. **Navigate to VT_Player:**
   ```bash
   cd /path/to/VT_Player
   ```

3. **Run the build script:**
   ```bash
   ./scripts/build.sh
   ```

4. **Expected output:**
   ```
   ════════════════════════════════════════════════════════════════
     VT_Player Universal Build Script
   ════════════════════════════════════════════════════════════════

   🔍 Detected platform: Windows

   📦 Go version:
   go version go1.21.x windows/amd64

   🧹 Cleaning previous builds...
   ✓ Cache cleaned

   ⬇️  Downloading dependencies...
   ✓ Dependencies downloaded

   🔨 Building VT_Player for Windows...
   ✓ Build successful!

   ════════════════════════════════════════════════════════════════
   ✅ BUILD COMPLETE
   ════════════════════════════════════════════════════════════════

   Output: vt_player.exe
   Size: ~45M

   ✓ FFmpeg detected on PATH

   Ready to run:
     .\vt_player.exe
   ```

5. **Run VT_Player:**
   ```bash
   ./vt_player.exe
   ```

---

## Shared Dependencies with VideoTools

VT_Player and VideoTools share the same dependencies on Windows:

| Dependency | Purpose | Shared? |
|------------|---------|---------|
| **Go 1.21+** | Compilation | ✅ Yes |
| **MinGW-w64** | CGO for Fyne | ✅ Yes |
| **FFmpeg** | Video processing | ✅ Yes (same PATH) |
| **FFprobe** | Metadata extraction | ✅ Yes (same PATH) |

### Why This Works

Both projects:
- Use the same Fyne GUI framework
- Use the same video processing tools (FFmpeg)
- Use the same build toolchain (Go + MinGW)
- Are designed to be portable on Windows

The only difference is the executable name and specific features.

---

## Differences from VideoTools

### What VT_Player Does NOT Include:
- ❌ Conversion queue system
- ❌ Format conversion UI
- ❌ Batch processing
- ❌ DVD authoring

### What VT_Player DOES Include:
- ✅ Frame-accurate playback
- ✅ Keyframe detection and navigation
- ✅ Timeline widget with visual keyframe markers
- ✅ Frame-by-frame stepping
- ✅ Keyframe jumping
- ✅ Lossless cutting (upcoming)

VT_Player is focused exclusively on video playback and frame-accurate editing.

---

## Troubleshooting

### "FFmpeg not found on PATH"

If the build completes but shows FFmpeg warning:
1. Check if VideoTools FFmpeg is on PATH:
   ```bash
   where ffmpeg
   where ffprobe
   ```

2. If not found, add VideoTools FFmpeg to PATH:
   ```powershell
   # In PowerShell as Administrator
   $env:Path += ";C:\path\to\VideoTools\dist\windows"
   ```

3. Or copy FFmpeg from VideoTools:
   ```bash
   cp /c/path/to/VideoTools/dist/windows/ffmpeg.exe .
   cp /c/path/to/VideoTools/dist/windows/ffprobe.exe .
   ```

### "go.exe not found"

Ensure Go is installed and on PATH:
```bash
go version
```

If not found, reinstall Go from https://go.dev/dl/

### "x86_64-w64-mingw32-gcc not found"

MinGW-w64 is required for CGO. If VideoTools builds successfully, MinGW is already installed.

Check with:
```bash
x86_64-w64-mingw32-gcc --version
```

### Build Succeeds but App Crashes

1. Check FFmpeg availability:
   ```bash
   ffmpeg -version
   ffprobe -version
   ```

2. Run with debug output:
   ```bash
   # Set debug environment variable
   export VIDEOTOOLS_DEBUG=1
   ./vt_player.exe
   ```

3. Check logs in current directory for errors

---

## Platform-Specific Build Flags

### Windows (`-ldflags="-H windowsgui -s -w"`)
- `-H windowsgui`: Create GUI app (no console window)
- `-s`: Strip symbol table
- `-w`: Strip DWARF debugging info
- Result: Smaller binary, cleaner UX

### Linux/macOS
- Standard build flags
- Console output available for debugging
- No special GUI flags needed

---

## File Structure After Build

```
VT_Player/
├── vt_player.exe          # Windows executable (~45MB)
├── scripts/
│   └── build.sh           # Universal build script
├── internal/
│   └── utils/
│       ├── proc_windows.go    # Windows console hiding
│       └── proc_other.go      # Linux/macOS no-op
└── ... (source files)
```

---

## Next Steps After Successful Build

1. **Test basic playback:**
   - Drag and drop a video file onto VT_Player
   - Verify it loads and plays

2. **Enable Frame-Accurate Mode:**
   - Tools → Frame-Accurate Mode
   - Load a video
   - Verify keyframes are detected and shown on timeline

3. **Test frame navigation:**
   - Left/Right arrows: Step by frame
   - Up/Down arrows: Jump between keyframes
   - Space: Play/pause

---

## Reporting Issues

If you encounter Windows-specific issues:

1. Check if the same issue occurs in VideoTools
2. Verify FFmpeg is on PATH and working
3. Run with `VIDEOTOOLS_DEBUG=1` for detailed logs
4. Report with:
   - Windows version (should be Windows 11)
   - Go version
   - FFmpeg version
   - Error messages
   - Build log

---

## Summary

VT_Player on Windows 11 should "just work" if VideoTools is already working:
- ✅ Same build environment
- ✅ Same dependencies
- ✅ Same FFmpeg installation
- ✅ Auto-detecting build script
- ✅ Console windows hidden for clean UX

The universal build script handles all platform differences automatically.