✨ Pixel Shell

High-Performance Desktop Overlay Engine & Asset Factory

Pixel Shell is a specialized engine designed to render high-framerate, transparent video overlays on Windows with minimal resource usage. It utilizes a custom "Snowplow" RLE compression algorithm to render uncompressed video frames directly via GDI, bypassing standard video players for absolute background transparency.

The project features a unique Binary Patching Architecture: instead of compiling code for every video, the CLI injects compressed asset data directly into a pre-compiled generic Runner executable, creating standalone, portable .exe files instantly.

Don’t want to build from source?

You can download the latest ready-to-use versions of the tools directly from GitHub Releases.

• ps-gui.exe — The Visual Interface
• ps-cli.exe — The Command Line Builder
• ps-runner.exe — The Template Engine

Place them in the same folder, and you are ready to go.

• ⚡ Zero-Copy Rendering — Custom .bin format optimized for CPU-based sparse rendering
• 🔊 Audio Sync — High-priority audio thread using kira for precise A/V synchronization
• 📦 Standalone Output — Generates single-file .exe overlays with no external dependencies
• 🖥️ Visual Interface — User-friendly GUI for managing projects, downloads, and builds without using the terminal
• 🛠️ All-in-One CLI — Advanced Download, Convert, Debug, and Build tools for automation
• 🛡️ Watchdog Mode — Automatically restarts overlays if they crash or are closed

This is a Cargo workspace organized into applications and shared libraries.

pixel-shell/
├── apps/
│   ├── ps-cli/          # Command Line Interface (backend logic)
│   ├── ps-gui/          # GUI frontend (egui-based visual tool)
│   └── ps-runner/       # Template EXE (player engine)
├── crates/
│   ├── ps-core/         # Shared data structures (PixelRect, headers)
│   └── ps-factory/      # Binary building & patching logic
├── target/              # Build artifacts
├── pixel-shell.ico      # Application icon
└── Cargo.toml           # Workspace configuration

If you want to contribute or modify the engine, follow these steps.

• Rust (via Rustup)
• FFmpeg & FFprobe (required for asset conversion)
• yt-dlp (required for downloading source material)

You must build the entire workspace to generate the GUI, CLI, and Runner template.

git clone https://github.com/Khoa-Trinh/PixelShell.git
cd PixelShell
cargo build --release

Create a working folder (e.g., PixelShellTool) and copy the artifacts:

target/release/ps-gui.exe    -> PixelShellTool/ps-gui.exe
target/release/ps-cli.exe    -> PixelShellTool/ps-cli.exe
target/release/ps-runner.exe -> PixelShellTool/ps-runner.exe

For the easiest experience, use the graphical interface.

1. Launch ps-gui.exe.

2. Configuration: On first run, go to the Settings tab and ensure the paths to ffmpeg, yt-dlp, and the ps-runner.exe template are correct.

3. Workflow:

   • Download: Paste a YouTube URL, select a resolution (1080p / 720p / etc.), and name your project.
   • Output Settings: Select the desired framerate (30 / 60 FPS) and resolution.
   • Process: Click Run All Tasks to automatically download, convert, and build the standalone executable.
   • Manage: Use the Runner tab to launch and monitor your generated overlays with the built-in Watchdog.

For automation or advanced usage, open a terminal in the folder containing the executables.

Downloads a video, extracts audio, and prepares it for processing.

ps-cli.exe download --url "https://youtu.be/..." --resolution 1080p --project "my_overlay"

Transcodes video frames into the optimized .bin format using the Snowplow algorithm.

ps-cli.exe convert --project "my_overlay" --resolutions "1080p,720p" --use-gpu

Injects converted assets into the runner template.

ps-cli.exe build --project "my_overlay" --resolutions "1080p,720p"
# Output will be placed in the /dist folder

Running via command line instead of double-clicking enables Watchdog mode.

ps-cli.exe run --target "my_overlay_1080p.exe"

• Template not found — Ensure ps-runner.exe is in the same folder as the CLI / GUI executable.
• FFmpeg not found — Ensure FFmpeg is installed and added to your system PATH, or configure the absolute path in the GUI settings.
• Black Background — Ensure your source video has a solid black background (#000000) for the transparency engine to work correctly.

This project is licensed under the MIT License.