MPV-GeomUX

A portable mpv enhancement suite focused on geometry control (pan/zoom/rotate/flip/crop), AB loop, speed control, color/filters adjustment, named presets, and clean OSD user experience. Built with modular Lua scripts, configurable options, automated packaging tools, and comprehensive documentation for Windows portable deployment.

Overview

MPV-GeomUX is a comprehensive portable video player solution built on mpv, designed for advanced visual adjustment workflows. It specializes in real-time geometry transformations, instant color/filter adjustments, AB loop controls, preset management, and seamless Windows 11 portable deployment.

The project implements a unified high-efficiency workflow through mpv's portable_config architecture, modular Lua scripting system, and optional companion frontend via IPC control, delivering consistent performance and excellent user experience.

Features

• One-Click Portable: Deploy portable_config alongside mpv.exe for installation-free startup
• High Interactivity: Complete control via keyboard shortcuts, mouse actions, and OSD/menu interfaces
• Advanced Customization: Save/load personal presets, per-file state memory, automatic profile application
• Modular Extension: Lua script modules with toggle/extend capabilities without conflicts

Quick Start

1. Download and extract mpv Windows version zip package
2. Run ./tools/build_portable.sh to build portable configuration
3. Launch with MPV-GeomUX.bat or MPV-GeomUX-Silent.vbs
4. Drag video files into the window and use the keyboard shortcuts below

Requirements

• Operating System: Windows 11 (primary), Windows 10 (compatible)
• mpv Player: Latest stable version (auto-downloaded by build tools)
• Development Environment: WSL2 with Ubuntu (for build scripts)
• Dependencies: Lua 5.1/5.2/LuaJIT (auto-installed)

Implemented Features (Stories 1.1 & 1.2: Transform Control)

🎮 Available Keyboard Shortcuts

Transform Control ⚡:

• r key: Rotate clockwise 90° (0° → 90° → 180° → 270° → 0°)
• Shift+r key: Rotate counterclockwise 90° (0° → 270° → 180° → 90° → 0°)
• m key: Toggle horizontal flip (mirror effect)
• Shift+m key: Toggle vertical flip (upside-down effect)
• Alt+0 key: Reset all transformations to default state

Mouse Control:

• Single click on video: Toggle pause/play
• Double click on video: Toggle fullscreen mode

🔥 Advanced Transform Combinations

Mix and match for creative effects:

• Rotation + Flip: Perfect for mobile videos and mirrored content
• Four flip modes: None, Horizontal (H), Vertical (V), Both (HV)
• Instant reset: One key to restore original orientation
• Smart persistence: Settings remembered per video file

⚡ Why MPV-GeomUX Rocks

• Zero Installation: Drop portable_config folder and run!
• Lightning Fast: < 50ms response time for all transforms
• Smart Debug: Cycle through ALL combinations with Ctrl+Shift+D
• Clean Architecture: Zero root directory pollution principle

🧪 Testing Shortcuts (Debug Only)

• Ctrl+Shift+I: Show complete transform status (rotation + flip + all)
• Ctrl+Shift+T: Test MPV-GeomUX loading status
• Ctrl+Shift+D: Cycle through all transform combinations for testing

Planned Features (Coming Soon)

• Advanced Geometry (Stories 1.3-1.4): Pan (fine adjustment + mouse drag), zoom and fit modes
• Color & Filters (Epic 2): Brightness/contrast/saturation/hue, curves, GLSL shaders, 3D LUT, filter stacking and preset management
• AB Loop & Speed (Epic 3): A/B markers, looping, speed fine-tuning with pitch correction
• Presets & Automation (Epic 4): Named presets, multi-preset management, per-file memory, auto-profile by video properties or filename patterns
• UI/UX (Epic 5): Navigable OSD menus, status overlays, shortcut display, optional desktop companion GUI (IPC control)
• Portable & Packaging (Epic 6): Windows 11 portable deployment, zip packaging and versioned releases

Installation

Automated Installation (Recommended)

# Clone the repository
git clone https://github.com/user/MPV-GeomUX.git
cd MPV-GeomUX

# Copy environment template
cp .env.example .env

# Edit .env to set your mpv installation path
# MPV_INSTALL_PATH=/path/to/your/mpv

# Build portable configuration
./tools/build_portable.sh

Manual Installation

1. Download mpv Windows portable version
2. Extract to your preferred location
3. Copy config/ and scripts/ directories to mpv/portable_config/
4. Launch mpv with enhanced configuration

Configuration

Environment Variables

Create .env file with your settings:

MPV_INSTALL_PATH=/mnt/c/Users/user/Documents/Yippine/Software/mpv
MPV_DEV_PATH=/mnt/c/Users/user/Documents/Yippine/Program/MPV-GeomUX
USER_PASSWORD=your_wsl_password

Script Options

Customize behavior via config/script-opts/transform_manager.conf:

# OSD display settings
osd_duration=1.5
osd_enabled=yes
debug_mode=no

# Feature toggles
enable_rotation=yes
enable_state_persistence=yes

Usage

Basic Operations

1. Launch Player: Run MPV-GeomUX.bat or MPV-GeomUX-Silent.vbs
2. Load Video: Drag and drop video file onto player window
3. Control Playback: Use mouse clicks or keyboard shortcuts
4. Transform Video: Use rotation keys to adjust video orientation

Advanced Features

• State Persistence: Your rotation settings are automatically saved per video
• Reset Function: Use Alt+0 to quickly reset all transformations
• Debug Mode: Enable debug logging in configuration for troubleshooting

Development

Project Structure

MPV-GeomUX/
├── scripts/core/           # Core Lua modules
├── config/                 # mpv configuration files
├── tools/                  # Build and deployment scripts
├── docs/                   # Documentation
└── tests/                  # Testing utilities

Building from Source

# Install dependencies (WSL/Ubuntu)
sudo apt update
sudo apt install lua5.1 lua5.2 luajit mpv

# Build portable configuration
./tools/build_portable.sh

# Run syntax checks
lua tests/syntax_check.lua

Testing

# Manual testing
lua scripts/test_rotation.lua

# Integration testing
./tools/test_integration.sh

Troubleshooting

Common Issues

Issue: Rotation not working

• Solution: Check if transform_manager.lua is loaded properly
• Command: Press Ctrl+Shift+T to test loading status

Issue: OSD not displaying

• Solution: Enable OSD in script options
• File: config/script-opts/transform_manager.conf

Issue: Key bindings not responding

• Solution: Check for conflicts in config/input.conf

Debug Mode

Enable debug logging:

# In transform_manager.conf
debug_mode=yes
log_level=debug

Performance Issues

For 4K videos or older hardware:

• Disable hardware decoding: hwdec=no in mpv.conf
• Reduce OSD update frequency
• Use software rendering mode

Contributing

Development Workflow

This project follows the BMad Method development cycle:

1. Product Management → Requirements analysis
2. Architecture → Technical design
3. Document Sharding → Task breakdown
4. Scrum Management → Sprint planning
5. Development → Implementation

Submission Guidelines

1. Code Standards: All code comments and variables in English
2. Documentation: Traditional Chinese for docs, English for code
3. Testing: Include test cases for new features
4. Commit Messages: Follow conventional commit format

Git Workflow

Use specialized commands for version control:

• /commit - WIP staging commits
• /push - Code push operations
• /version - Version tag management
• /release - GitHub release creation
• /publish - Complete publishing pipeline

License

[License information to be added]

Acknowledgments

• mpv: The powerful media player foundation
• Lua Community: For excellent scripting support
• Contributors: All developers and testers who make this project possible

Support

• Issues: Report bugs on GitHub Issues
• Documentation: Check docs/ directory for detailed guides
• Community: Join discussions in project forums

---

Version: v0.1.2 (Stories 1.1 & 1.2 Complete)
Last Updated: August 17, 2025
Status: ✅ Rotation & Flip Control Fully Implemented | 🎯 Epic 1 Progress: 50% Complete