GBA Video Studio is a desktop application for converting and playing video on the Game Boy Advance. It converts any video file into a .gba ROM that plays directly on hardware or emulator, with a full visual editor for trimming, previewing, and configuring every encoding parameter.

⚠️ Designed for GBA developers and ROM hackers who need precise control over video encoding for the GBA hardware.

This README is available in the following languages:

English | Español | Português (BR) | Français | Deutsch | Italiano | Português | Nederlands | Polski
Türkçe | Tiếng Việt | Bahasa Indonesia | हिन्दी | Русский | 日本語 | 简体中文 | 繁體中文 | 한국어

• Video to GBA conversion

  • Converts any video file into a playable GBA ROM.
  • YUV444 color space with VQ codebook compression per GOP.
  • Optional Floyd-Steinberg dithering for reduced banding.
  • Letterbox, stretch, or custom crop before encoding.

• Visual editor

  • Load and preview any video file with full playback controls.
  • Set start/end markers to encode only a selected range.
  • Real-time GBA output preview (240×160) with letterbox and crop applied.

• Encoding profiles (presets)

  • Six built-in presets: Default, Balanced, High Quality, Low FPS, Fast Encode, No Audio.
  • Save, reload, and manage custom user presets.
  • Full parameter control: FPS, codebook size, K-means iterations, I-frame interval, motion compensation, and more.

• Audio support

  • PCM: 8-bit signed mono, any sample rate 6500–44100 Hz. Full seeking support.
  • ADPCM: IMA ADPCM 4-bit (~50% smaller), snapped to GBA nice rates. Seeking disabled.
  • Volume adjustment and no-audio mode.

• Decompilation project integration

  • Outputs ready-to-use video.c, video.h, and binary assets for pret projects (pokefirered, pokeemerald, etc.).
  • Configurable skip key (VIDEO_SKIP_KEY).
  • See INTEGRATION.md for integration steps.

• Multi-language UI

  • 18 languages supported. Language can be changed at runtime without restarting.

• Post-export actions

  • Optionally shut down, sleep, hibernate, lock, log off, or quit after encoding completes.

The conversion pipeline is optimized for high-performance video encoding, leveraging parallel processing and memory mapping (memmap) to handle heavy video files without RAM accumulation.

flowchart TD
    A([input.mp4]) --> B[1. FFmpeg Pre-Transcode]
    B --> C[2. Frame Extraction]
    C --> D[3. GOP Processing Parallel]
    D --> E[4. Frame Encoding Parallel]
    E --> F[5. Audio Extraction & Adapt]
    F --> G[6. devkitPro Build]
    G --> H([GBA_Video.gba])

    style A fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style H fill:#2b6cb0,stroke:#3182ce,stroke-width:2px,color:#fff
    classDef steps fill:#1a202c,stroke:#2d3748,stroke-width:1px,color:#e2e8f0;
    class B,C,D,E,F,G steps;

• Geometry: Optional cropping $\rightarrow$ hard resize to 240×160 (supports letterboxing or stretching).
• Timing: Frame rate conversion to exact GBA-native FPS targets.
• Trimming: Precise timeline seeking via optional start-time parameters.

• Color Space: Extracted directly into YUV444 color space.
• Dithering: Optional Floyd-Steinberg spatial error diffusion for optimal 15-bit color representation.
• Memory Footprint: Frames are streamed directly into a disk-backed memmap matrix, ensuring 0% RAM accumulation even on hour-long videos.

• Segmentation: Video is sliced into independent GOPs consisting of one I-frame followed by multiple P-frames.
• Quantization: Trains a localized Vector Quantization (VQ) codebook per GOP using the K-means clustering algorithm.
• Optimization: Codebooks are automatically sorted by structural usage frequency to minimize indexing overhead.

• I-Frames: Encoded using full-frame spatial data combined with the local VQ codebook.
• P-Frames: Temporal compression that only stores delta blocks (changed areas) and motion vectors relative to the previous frame.

• PCM Mode: Crisp, uncompressed mono signed 8-bit audio at your chosen sample rate.
• ADPCM Mode: Compressed 4-bit IMA ADPCM, mathematically snapped to the nearest GBA-friendly playback rate to avoid resampling stutter.

• The asset compiler bundles the encoded video, audio binary, and playback engine components.
• Automatically invokes devkitPro / make to link everything into a bare-metal, hardware-compliant GBA_Video.gba ROM.

32 MB cartridge capacity (approx.):

Seek (LEFT/RIGHT) is not available in ADPCM because the IMA ADPCM predictor is cumulative — jumping to an arbitrary byte offset without warm-up would produce corrupted audio.

Built with Python and PySide6 / PySide2 (auto-detected by Python version):

• VideoEditor — main window, manages video loading, preview, and export.
• VideoController — OpenCV-based playback with frame-accurate seeking.
• PresetManager — built-in and user-defined encoding presets.
• VideoEncoderCore — GOP-parallel VQ encoder (K-means + motion compensation).
• AudioEncoder — PCM / IMA ADPCM extractor via bundled ffmpeg (imageio-ffmpeg).
• Translator / ConfigManager — runtime language switching and persistent config.

Download from GitHub Releases:

Download GBAVideoStudio_Portable.7z from GitHub Releases, extract anywhere and run GBAVideoStudio.exe. No installation required.

The portable build registers its location in the Windows registry on first launch so the built-in updater can locate it regardless of where it is extracted.

• devkitPro — install gba-dev group from devkitpro.org (required only for ROM compilation — video conversion works without it)

ffmpeg is bundled automatically via imageio-ffmpeg — no separate installation required.

git clone https://github.com/CompuMaxx/GBA-Video-Studio.git
cd GBA-Video-Studio
python -m venv .venv
# Windows:
.venv\Scripts\activate
pip install -r requirements.txt
python main.py

1. Open a video — File → Open Video or Ctrl+O.
2. Set range (optional) — navigate to start frame, press Ctrl+PageUp; navigate to end frame, press Ctrl+PageDown.
3. Configure output filters — enable/disable Letterbox, set Crop (x,y,w,h), click Apply Filters to preview.
4. Choose a preset — pick from the Preset dropdown (Default, Balanced, High Quality, Low FPS, Fast Encode, No Audio) or tune individual parameters.
5. Select output folder — click Browse.
6. Build ROM — click Build ROM. Progress and elapsed time are shown in the status bar.
7. Done — a popup shows memory usage (ROM / EWRAM / IWRAM). The .gba file is in your output folder.

After encoding, the output/ folder contains everything needed to embed the video in a pret decomp project:

output/
  graphics/video/     → copy to <project>/graphics/video/  (regenerated each encode)
  include/video.h     → copy to <project>/include/video.h  (regenerated each encode)
  src/video.c         → copy to <project>/src/video.c      (copy once)
  INTEGRATION.md

See INTEGRATION.md for the full integration guide, Task API reference, and skip key configuration.

• Settings are stored in config.ini and persist across sessions (language, output folder, preview mode, max workers, default preset, etc.).
• Language can be changed at runtime via Settings → Language — all UI strings update immediately including video info, preset names, and memory table headers.

1. Fork this repository.
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am "Add my feature"
4. Push: git push origin feature/my-feature
5. Open a Pull Request.

• Ausar's GBA Video Player by ArcheyChen — Architectural inspiration for the video playback. The engine used here features custom bug fixes and critical IWRAM/EWRAM optimizations.
• 8ad ADPCM codec by Damian Yerrick ("PinoBatch") — Conceptual basis for the IMA ADPCM audio support, optimized for better memory performance.

Licensed under the GNU General Public License v3.0 (GPL-3.0). Derivative projects must be open source. See LICENSE for details.

If you find this tool useful, consider supporting its development: