Skip to content

README.nld.md

Latest commit

 

History

History
336 lines (234 loc) · 14.6 KB

README.nld.md

File metadata and controls

336 lines (234 loc) · 14.6 KB
Raw

GBA Video Studio

Discord Platform Python Licentie

GBA Video Studio

GBA Video Studio is een desktopapplicatie voor het converteren en afspelen van video op de Game Boy Advance. Het converteert elk videobestand naar een .gba ROM die direct op hardware of emulator wordt afgespeeld, met een volledige visuele editor voor het trimmen, voorvertonen en configureren van elke encoderingsparameter.

⚠️ Ontworpen voor GBA-ontwikkelaars en ROM-hackers die nauwkeurige controle nodig hebben over video-encoding voor de GBA-hardware.

🌐 Vertalingen

Deze README is beschikbaar in de volgende talen:

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

✨ Functies

  • Video naar GBA-conversie

    • Converteert elk videobestand naar een afspeelbare GBA ROM.
    • YUV444-kleurruimte met VQ-codeboekcompressie per GOP.
    • Optionele Floyd-Steinberg-dithering om banding te verminderen.
    • Letterbox, uitrekken of aangepast bijsnijden vóór de codering.

  • Visuele editor

    • Laadt en bekijkt elk videobestand met volledige afspeelbediening.
    • Stelt start-/eindmarkeringen in om alleen een geselecteerd bereik te coderen.
    • Realtime GBA-uitvoervoorbeeld (240×160) met toegepaste letterbox en bijsnijden.

  • Encoderingsprofielen (presets)

    • Zes ingebouwde presets: Standaard, Evenwichtig, Hoge Kwaliteit, Lage FPS, Snelle Codering, Geen Audio.
    • Opslaan, herladen en beheren van aangepaste gebruikerspresets.
    • Volledige parametercontrole: FPS, codeboekgrootte, K-means-iteraties, I-frame-interval, bewegingscompensatie en meer.

  • Audio-ondersteuning

    • PCM: 8-bits getekende mono, elke samplefrequentie 6500–44100 Hz. Volledige zoekondersteuning.
    • ADPCM: IMA ADPCM 4-bits (~50% kleiner), aangepast aan GBA-vriendelijke snelheden. Zoeken uitgeschakeld.
    • Volumeaanpassing en modus zonder audio.

  • Integratie met decompilatieprojecten

    • Genereert kant-en-klare video.c, video.h en binaire assets voor pret-projecten (pokefirered, pokeemerald, etc.).
    • Configureerbare skip-toets (VIDEO_SKIP_KEY).
    • Zie INTEGRATION.nld.md voor integratiestappen.

  • Meertalige gebruikersinterface

    • Ondersteunt 18 talen. De taal kan tijdens runtime worden gewijzigd zonder herstart.

  • Acties na export

    • Optioneel uitschakelen, slaapstand, sluimerstand, vergrendelen, afmelden of afsluiten na voltooiing van de codering.

🖼️ Schermafbeeldingen

Afbeelding

Afbeelding

🔄 Hoe Het Werkt

De conversiepijplijn is geoptimaliseerd voor hoogwaardige video-encoding, met behulp van parallelle verwerking en geheugenmapping (memmap) om zware videobestanden te verwerken zonder RAM-accumulatie.

flowchart TD
    A([input.mp4]) --> B[1. FFmpeg Voor-transcodering]
    B --> C[2. Frame-extractie]
    C --> D[3. GOP Parallelle Verwerking]
    D --> E[4. Frame Parallelle Codering]
    E --> F[5. Audio-extractie & -aanpassing]
    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;
Loading

🛠️ Pijplijn Uitsplitsing

1. FFmpeg Voor-transcodering

  • Geometrie: Optioneel bijsnijden $\rightarrow$ geforceerd formaat wijzigen naar 240×160 (ondersteunt letterbox of uitrekken).
  • Timing: Framerate-conversie naar exacte GBA-native FPS-doelen.
  • Trimmen: Nauwkeurige tijdlijnzoekopdracht via optionele starttijdparameters.

2. Frame-extractie & Kleurbeheer

  • Kleurruimte: Direct geëxtraheerd naar YUV444-kleurruimte.
  • Dithering: Optionele Floyd-Steinberg ruimtelijke foutdiffusie voor optimale 15-bits kleurweergave.
  • Geheugenvoetafdruk: Frames worden direct naar een schijfondersteunde memmap-matrix gestreamd, wat 0% RAM-accumulatie garandeert, zelfs op urenlange video's.

3. GOP (Groep van Beelden) Verwerking Parallel

  • Segmentatie: De video wordt opgedeeld in onafhankelijke GOP's bestaande uit één I-frame gevolgd door meerdere P-frames.
  • Kwantificering: Traint een gelokaliseerd VQ (Vector Kwantificering) codeboek per GOP met behulp van het K-means clusteringalgoritme.
  • Optimalisatie: Codeboeken worden automatisch gesorteerd op structurele gebruiksfrequentie om indexeringsoverhead te minimaliseren.

4. Frame Codering Parallel

  • I-frames: Gecodeerd met behulp van volledige frame-ruimtelijke gegevens gecombineerd met het lokale VQ-codeboek.
  • P-frames: Temporele compressie die alleen deltabloks (gewijzigde gebieden) en bewegingsvectoren opslaat ten opzichte van het vorige frame.

5. Audio-extractie & Aanpasbaarheid

  • PCM-modus: Heldere, ongecomprimeerde mono getekende 8-bits audio op de door u gekozen samplefrequentie.
  • ADPCM-modus: Gecomprimeerde 4-bits IMA ADPCM, wiskundig aangepast aan de dichtstbijzijnde GBA-vriendelijke afspeelsnelheid om hakkel door hersampling te voorkomen.

6. Compilatie

  • De asset-compiler bundelt de gecodeerde video, audiobinaire bestanden en afspeelmotorcomponenten.
  • Roept automatisch devkitPro / make aan om alles te koppelen in een zelfstandige, hardware-compatibele GBA_Video.gba ROM.

📊 Encoderingsparameters

Video

Parameter Standaard Bereik Effect
Doel FPS 9.9546 5.97 – 14.93 Hoger = vloeiender, groter bestand
I-frame-interval 60 1–999 Korter = betere zoekopdracht, groter bestand
Verschil Drempel 2.5 0.0–50.0 Lager = scherper, groter bestand
Variantie Drempel 10.0 0.0–100.0 Scheidt vlakke vs. getextureerde blokken
Kleur Fallback 10.0 0.0–100.0 Fallback-afstand voor vlakke blokken
Forceer I Drempel 0.7 0.0–1.0 Scèneverandering I-frame gevoeligheid
Codeboekgrootte 256 2–256 Groter = betere kwaliteit
K-means Iteraties 200 1–2000 Meer = betere kwaliteit, langzamer
I-frame Gewicht 3 1–10 I-frame blokgewicht in clustering
Beweging Drempel 6 0–16 Max 2×2 subblokken bijgewerkt per 8×8 MC-blok
Dithering aan aan/uit Floyd-Steinberg, verwaarloosbaar grootteverschil
Bewegingscompensatie aan aan/uit Uitschakelen voor snellere codering, grotere P-frames

Audio

Parameter Standaard Bereik
Formaat PCM PCM / ADPCM
Samplefrequentie 18157 Hz 6500–44100 Hz
Volume 100% 0–200%

GBA-native FPS-waarden

FPS Gebruiksvoorbeeld
5.9727 Minimale grootte
6.6364 Zeer compact
7.4659 Compact
8.5325 Gemiddeld
9.9546 Standaard — beste balans
11.9455 Vloeiende beweging
14.9319 Maximum (inhoud met hoge beweging)

📦 Bestandsgrootte Referentie

FPS Video/min PCM 18157 Hz ADPCM 18157 Hz Geen audio
14.9319 ~6.0 MB ~6.9 MB ~6.5 MB ~6.0 MB
9.9546 ~4.2 MB ~5.0 MB ~4.6 MB ~4.2 MB
5.9727 ~2.5 MB ~3.3 MB ~3.0 MB ~2.5 MB

32 MB cartridge-capaciteit (ongeveer):

FPS PCM 18157 Hz ADPCM 18157 Hz Geen audio
14.9319 ~4:45 ~5:00 ~5:30
9.9546 ~6:30 ~7:00 ~7:45
5.9727 ~9:45 ~10:45 ~12:45

🎮 GBA-bediening (zelfstandige ROM)

Knop PCM ADPCM
START / A — Pauzeren / Hervatten ✓ ✓
B — Dempen / Dempen opheffen ✓ ✓
RECHTS — Vooruit spoelen 3s ✓ ✗
LINKS — Terugspoelen 3s ✓ ✗
SELECT — Bediening vergrendelen / ontgrendelen ✓ ✓

Zoeken (LINKS/RECHTS) is niet beschikbaar in ADPCM omdat de IMA ADPCM-voorspeller cumulatief is — springen naar een willekeurige byte-offset zonder opwarming zou beschadigde audio produceren.

🏗️ Architectuur Overzicht

Gebouwd met Python en PySide6 / PySide2 (automatisch gedetecteerd op basis van Python-versie):

  • VideoEditor — hoofdvenster, beheert het laden, voorvertonen en exporteren van video.
  • VideoController — OpenCV-gebaseerde afspeling met frame-nauwkeurig zoeken.
  • PresetManager — ingebouwde en door de gebruiker gedefinieerde encoderingspresets.
  • VideoEncoderCore — GOP-parallelle VQ-encoder (K-means + bewegingscompensatie).
  • AudioEncoder — PCM / IMA ADPCM-extractor via meegeleverde ffmpeg (imageio-ffmpeg).
  • Translator / ConfigManager — runtime-taalwisseling en persistente configuratie.

📦 Installatie

Optie 1 — Installatieprogramma (aanbevolen)

Download van GitHub Releases:

Installatieprogramma Python OS
GBAVideoStudio_Setup.exe Gebundeld Windows 10 / 11
GBAVideoStudio_Legacy_Setup.exe Gebundeld Windows 7 / 8 / 8.1

Optie 2 — Portable

Download GBAVideoStudio_Portable.7z van GitHub Releases, pak uit waar u wilt en voer GBAVideoStudio.exe uit. Geen installatie vereist.

Archief Python OS
GBAVideoStudio_Portable.7z Gebundeld (PySide2) Windows 7+

De draagbare versie registreert zijn locatie bij eerste opstart in het Windows-register, zodat de ingebouwde updater het kan vinden, ongeacht waar het is uitgepakt.

Optie 3 — Uitvoeren vanuit broncode

Vereisten

Omgeving Python Qt-backend
Modern 3.10+ PySide6 (automatisch)
Legacy 3.8 / 3.9 PySide2 5.15.2 (automatisch)

Externe tools

  • devkitPro — installeer de gba-dev-groep van devkitpro.org (alleen vereist voor ROM-compilatie — videoconversie werkt zonder)

ffmpeg wordt automatisch meegeleverd via imageio-ffmpeg — geen aparte installatie vereist.

Stappen

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

🚀 Snelstart

  1. Open een video — Bestand → Open Video of Ctrl+O.
  2. Stel bereik in (optioneel) — navigeer naar startframe, druk op Ctrl+PageUp; navigeer naar eindframe, druk op Ctrl+PageDown.
  3. Configureer uitvoerfilters — schakel Letterbox in/uit, stel Bijsnijden in (x,y,w,h), klik op Filters Toepassen om voor te vertonen.
  4. Kies een preset — selecteer uit de Preset-dropdown (Standaard, Evenwichtig, Hoge Kwaliteit, Lage FPS, Snelle Codering, Geen Audio) of pas individuele parameters aan.
  5. Selecteer uitvoermap — klik op Bladeren.
  6. Bouw ROM — klik op Bouw ROM. Voortgang en verstreken tijd worden weergegeven in de statusbalk.
  7. Klaar — een pop-up toont geheugengebruik (ROM / EWRAM / IWRAM). Het .gba-bestand staat in uw uitvoermap.

🧩 Integratie met Decompilatieprojecten

Na codering bevat de output/-map alles wat nodig is om de video in een pret-decompilatieproject in te bedden:

output/
  graphics/video/     → kopiëren naar <project>/graphics/video/  (opnieuw gegenereerd bij elke codering)
  include/video.h     → kopiëren naar <project>/include/video.h  (opnieuw gegenereerd bij elke codering)
  src/video.c         → kopiëren naar <project>/src/video.c      (eenmalig kopiëren)
  INTEGRATION.nld.md

Zie INTEGRATION.nld.md voor de volledige integratiegids, Task API-referentie en skip-toetsconfiguratie.

⚙️ Configuratie & Lokalisatie

  • Instellingen worden opgeslagen in config.ini en blijven behouden tussen sessies (taal, uitvoermap, voorbeeldmodus, maximale workers, standaardpreset, etc.).
  • Taal kan tijdens runtime worden gewijzigd via Instellingen → Taal — alle UI-teksten worden onmiddellijk bijgewerkt, inclusief video-informatie, presetnamen en geheugentabelkoppen.

🤝 Bijdragen

  1. Fork deze repository.
  2. Maak een feature-branch aan: git checkout -b feature/mijn-functie
  3. Commit uw wijzigingen: git commit -am "Voeg mijn functie toe"
  4. Push: git push origin feature/mijn-functie
  5. Open een Pull Request.

🙏 Dankbetuigingen

  • Ausar's GBA Video Player door ArcheyChen — Architecturale inspiratie voor videoweergave. De hier gebruikte engine bevat aangepaste bugfixes en kritieke IWRAM/EWRAM-optimalisaties.
  • 8ad ADPCM-codec door Damian Yerrick ("PinoBatch") — Conceptuele basis voor IMA ADPCM-audio-ondersteuning, geoptimaliseerd voor betere geheugenprestaties.

📄 Licentie

Gelicenseerd onder de GNU General Public License v3.0 (GPL-3.0). Afgeleide projecten moeten open source zijn. Zie LICENSE voor details.

📩 Contact & Ondersteuning

Discord-serverWord lid van onze Discord

Als u deze tool nuttig vindt, overweeg dan om de ontwikkeling te ondersteunen:

ko-fi