Open-Awesome
CategoriesAlternativesStacksSelf-HostedExplore
Open-Awesome

© 2026 Open-Awesome. Curated for the developer elite.

TermsPrivacyAboutGitHubRSS
  1. Home
  2. Game Boy Development
  3. GBVideoPlayer

GBVideoPlayer

MITPythonv1.0

A technical demo showing how to hack the Game Boy Color LCD controller to play full-motion color video with music.

GitHubGitHub
103 stars7 forks0 contributors

What is GBVideoPlayer?

GBVideoPlayer is a technical demo that demonstrates how to hack the Game Boy Color's LCD controller to play full-motion color video with music. It solves the challenge of video playback on severely constrained 8-bit hardware by exploiting hardware quirks and using extreme optimization techniques. The project includes both a custom video encoder and a highly optimized Z80 assembly player that runs on actual Game Boy Color hardware or accurate emulators.

Target Audience

Retro computing enthusiasts, demoscene developers, and embedded systems programmers interested in pushing hardware limits and understanding low-level Game Boy Color programming.

Value Proposition

Developers choose this project to learn about extreme optimization techniques for constrained systems and to see innovative hardware hacking approaches that enable capabilities far beyond the Game Boy Color's intended design.

Overview

GBVideoPlayer is a technical demonstration that pushes the Game Boy Color's hardware to its limits by enabling it to play full-motion color video with synchronized music. It showcases innovative hardware hacking techniques to overcome the console's severe memory and processing constraints, achieving what was previously thought impossible on the 8-bit platform.

Key Features

  • Hardware LCD Controller Hacking — Manipulates the Game Boy Color's LCD controller to bypass its tile-based graphics system and display video frames.
  • Custom Video Encoding Pipeline — Uses a two-stage encoder (Photoshop batch script + Python) to compress video into a format the Game Boy can process.
  • Cycle-Accurate Z80 Assembly — The player core is written in highly optimized Z80 assembly with precise CPU cycle counting for real-time playback.
  • Compact Music Format — Music is stored in a custom binary format converted from an OpenMPT-style textual representation for efficient playback.
  • Frame Repetition Compression — Encoder can skip similar frames by repeating a single frame up to 127 times to save ROM space.

Philosophy

The project embraces extreme optimization and hardware exploitation to achieve seemingly impossible results on constrained retro hardware, following in the spirit of demoscene projects like 8088 Corruption.

Use Cases

Best For

  • Understanding Game Boy Color LCD controller exploitation
  • Learning cycle-accurate Z80 assembly optimization
  • Studying video compression techniques for severely memory-constrained systems
  • Creating technical demos for retro gaming hardware
  • Experimenting with hardware limitations in embedded systems
  • Developing accurate emulator test cases for timing-sensitive code

Not Ideal For

  • Projects requiring real-time video encoding or playback without offline preprocessing.
  • Developers seeking a video solution with broad emulator compatibility across various platforms.
  • Teams wanting a simple, GUI-based tool for video conversion on retro hardware.
  • Applications needing small ROM sizes under typical Game Boy cartridge limits (e.g., under 1MB).

Pros & Cons

Pros

Hardware LCD Hacking

Manipulates the Game Boy Color's LCD controller to bypass its tile-based graphics system, enabling direct frame display as described in the technical specifications.

Cycle-Accurate Assembly

Written in highly optimized Z80 assembly with precise CPU cycle counting, allowing real-time video playback on a 2MHz processor, as noted in the tl;dr.

Custom Compression Techniques

Uses frame repetition up to 127 times and a compact music format to minimize ROM usage, addressing the severe memory constraints highlighted in the README.

Technical Demonstration Value

Showcases extreme optimization on retro hardware, achieving full-motion color video with music, inspired by demoscene projects like 8088 Corruption.

Cons

Complex Encoding Setup

Requires Photoshop for batch processing and Python scripts, making video conversion tool-dependent and cumbersome, as outlined in the compilation section.

Limited Emulator Support

Due to precise timing hacks, it only works on a few accurate emulators like BGB, restricting development and testing, as admitted in the emulator support section.

Buggy and Disabled Features

The encoder has buggy support for row-back-reference compression that is disabled due to CPU cycle constraints, limiting compression efficiency as mentioned in the technical specifications.

Large ROM Requirements

The demo ROM is 7.6MB, which is impractically large for standard Game Boy cartridges, as noted in the technical specifications.

Frequently Asked Questions

Quick Stats

Stars103
Forks7
Contributors0
Open Issues2
Last commit8 years ago
CreatedSince 2015

Tags

#embedded-systems#retro-computing#z80-assembly#hardware-hacking#game-boy-color#emulator-development#demoscene#video-playback

Built With

r
rgbds
P
Python
z
z80-assembly

Included in

Game Boy Development4.4k
Auto-fetched 20 hours ago

Related Projects

GBVideoPlayer2GBVideoPlayer2

A new version of GBVideoPlayer with higher resolution, 3-bit stereo PCM audio and video compression

Stars133
Forks16
Last commit6 years ago
CUTE DEMOCUTE DEMO

A Cute Demo for the GameBoy Color

Stars40
Forks4
Last commit6 years ago
matrix-rain-gbmatrix-rain-gb

Matrix digital rain effect for the Game Boy

Stars32
Forks2
Last commit2 years ago
10 PRINT Game Boy10 PRINT Game Boy

🖨 Port of a famous C64 BASIC one-liner to the Game Boy.

Stars29
Forks2
Last commit8 years ago
Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a projectStar on GitHub