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:

# 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: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: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:

   cd /path/to/VT_Player
   

3. Run the build script:

   ./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:

   ./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:

   where ffmpeg
   where ffprobe
   

2. If not found, add VideoTools FFmpeg to PATH:

   # In PowerShell as Administrator
   $env:Path += ";C:\path\to\VideoTools\dist\windows"
   

3. Or copy FFmpeg from VideoTools:

   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:

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:

x86_64-w64-mingw32-gcc --version

Build Succeeds but App Crashes

1. Check FFmpeg availability:

   ffmpeg -version
   ffprobe -version
   

2. Run with debug output:

   # 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.