Skip to content

README.fra.md

Latest commit

 

History

History
336 lines (234 loc) · 15.8 KB

README.fra.md

File metadata and controls

336 lines (234 loc) · 15.8 KB
Raw

GBA Video Studio

Discord Plateforme Python Licence

GBA Video Studio

GBA Video Studio est une application de bureau pour convertir et lire des vidéos sur la Game Boy Advance. Il convertit tout fichier vidéo en une ROM .gba qui peut être lue directement sur le matériel ou sur un émulateur, avec un éditeur visuel complet pour découper, prévisualiser et configurer chaque paramètre d'encodage.

⚠️ Conçu pour les développeurs GBA et les hackers de ROM qui ont besoin d'un contrôle précis sur l'encodage vidéo pour le matériel GBA.

🌐 Traductions

Ce README est disponible dans les langues suivantes :

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

✨ Fonctionnalités

  • Conversion vidéo vers GBA

    • Convertit tout fichier vidéo en une ROM GBA jouable.
    • Espace colorimétrique YUV444 avec compression par livre de codes VQ par GOP.
    • Tramage Floyd-Steinberg optionnel pour réduire les dégradés de couleur.
    • Letterbox, étirement ou recadrage personnalisé avant l'encodage.

  • Éditeur visuel

    • Charge et prévisualise tout fichier vidéo avec des contrôles de lecture complets.
    • Définit des marqueurs de début/fin pour encoder uniquement une plage sélectionnée.
    • Aperçu en temps réel de la sortie GBA (240×160) avec letterbox et recadrage appliqués.

  • Profils d'encodage (préréglages)

    • Six préréglages intégrés : Par défaut, Équilibré, Haute qualité, Bas FPS, Encodage rapide, Sans audio.
    • Sauvegarde, recharge et gestion des préréglages utilisateur personnalisés.
    • Contrôle total des paramètres : FPS, taille du livre de codes, itérations K-means, intervalle I-frame, compensation de mouvement, etc.

  • Support audio

    • PCM : Mono signé 8 bits, toute fréquence d'échantillonnage 6500–44100 Hz. Support de recherche complet.
    • ADPCM : IMA ADPCM 4 bits (~50% plus petit), aligné sur les taux compatibles GBA. Recherche désactivée.
    • Ajustement du volume et mode sans audio.

  • Intégration dans les projets de décompilation

    • Génère video.c, video.h et des actifs binaires prêts à l'emploi pour les projets pret (pokefirered, pokeemerald, etc.).
    • Touche de saut configurable (VIDEO_SKIP_KEY).
    • Consultez INTEGRATION.fra.md pour les étapes d'intégration.

  • Interface utilisateur multilingue

    • Prend en charge 18 langues. La langue peut être changée à l'exécution sans redémarrage.

  • Actions post-exportation

    • Optionnellement éteindre, mettre en veille, hiberner, verrouiller, fermer la session ou quitter après la fin de l'encodage.

🖼️ Captures d'écran

Image

Image

🔄 Comment ça fonctionne

Le pipeline de conversion est optimisé pour un encodage vidéo hautes performances, utilisant le traitement parallèle et le mappage mémoire (memmap) pour gérer les fichiers vidéo lourds sans accumulation de RAM.

flowchart TD
    A([input.mp4]) --> B[1. Pré-transcodage FFmpeg]
    B --> C[2. Extraction des Images]
    C --> D[3. Traitement GOP en Parallèle]
    D --> E[4. Encodage des Images en Parallèle]
    E --> F[5. Extraction et Adaptation Audio]
    F --> G[6. Compilation devkitPro]
    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

🛠️ Détail du Pipeline

1. Pré-transcodage FFmpeg

  • Géométrie : Recadrage optionnel $\rightarrow$ redimensionnement forcé à 240×160 (prend en charge le letterbox ou l'étirement).
  • Temps : Conversion du taux d'images vers des cibles FPS exactement natives du GBA.
  • Découpage : Recherche précise dans la timeline via des paramètres de temps de début optionnels.

2. Extraction des Images et Gestion des Couleurs

  • Espace colorimétrique : Extraction directe dans l'espace colorimétrique YUV444.
  • Tramage : Diffusion d'erreur spatiale Floyd-Steinberg optionnelle pour une représentation optimale des couleurs 15 bits.
  • Empreinte mémoire : Les images sont diffusées directement dans une matrice memmap sauvegardée sur disque, garantissant 0% d'accumulation de RAM même sur des vidéos d'une heure.

3. Traitement GOP (Groupe d'Images) en Parallèle

  • Segmentation : La vidéo est découpée en GOP indépendants composés d'une I-frame suivie de plusieurs P-frames.
  • Quantification : Entraîne un livre de codes de Quantification Vectorielle (VQ) localisé par GOP en utilisant l'algorithme de clustering K-means.
  • Optimisation : Les livres de codes sont automatiquement triés par fréquence d'utilisation structurelle pour minimiser le surcoût d'indexation.

4. Encodage des Images en Parallèle

  • I-frames : Encodées en utilisant les données spatiales de l'image complète combinées au livre de codes VQ local.
  • P-frames : Compression temporelle qui stocke uniquement les blocs delta (zones modifiées) et les vecteurs de mouvement par rapport à l'image précédente.

5. Extraction et Adaptabilité Audio

  • Mode PCM : Audio mono signé 8 bits non compressé et net à la fréquence d'échantillonnage choisie.
  • Mode ADPCM : Audio compressé IMA ADPCM 4 bits, mathématiquement aligné sur le taux de lecture le plus proche compatible avec le GBA pour éviter les saccades de rééchantillonnage.

6. Compilation

  • Le compilateur d'actifs regroupe la vidéo encodée, le binaire audio et les composants du moteur de lecture.
  • Invoque automatiquement devkitPro / make pour tout lier en une ROM GBA_Video.gba autonome et compatible avec le matériel.

📊 Paramètres d'Encodage

Vidéo

Paramètre Par défaut Plage Effet
FPS cible 9.9546 5.97 – 14.93 Plus élevé = plus fluide, fichier plus gros
Intervalle I-frame 60 1–999 Plus court = meilleure recherche, fichier plus gros
Seuil de différence 2.5 0.0–50.0 Plus bas = plus net, fichier plus gros
Seuil de variance 10.0 0.0–100.0 Sépare les blocs plats vs texturés
Repli de couleur 10.0 0.0–100.0 Distance de repli pour blocs plats
Seuil de force I 0.7 0.0–1.0 Sensibilité I-frame pour changement de scène
Taille du livre de codes 256 2–256 Plus grand = meilleure qualité
Itérations K-means 200 1–2000 Plus = meilleure qualité, plus lent
Poids I-frame 3 1–10 Poids du bloc I-frame dans le clustering
Seuil de mouvement 6 0–16 Max de sous-blocs 2×2 mis à jour par bloc MC 8×8
Tramage activé activé/désactivé Floyd-Steinberg, différence de taille négligeable
Compensation de mouvement activée activée/désactivée Désactiver pour un encodage plus rapide, P-frames plus grandes

Audio

Paramètre Par défaut Plage
Format PCM PCM / ADPCM
Fréquence d'échantillonnage 18157 Hz 6500–44100 Hz
Volume 100% 0–200%

Valeurs FPS natives du GBA

FPS Cas d'usage
5.9727 Taille minimale
6.6364 Très compact
7.4659 Compact
8.5325 Modéré
9.9546 Par défaut — meilleur équilibre
11.9455 Mouvement fluide
14.9319 Maximum (contenu à mouvement élevé)

📦 Référence des Tailles de Fichier

FPS Vidéo/min PCM 18157 Hz ADPCM 18157 Hz Sans audio
14.9319 ~6.0 Mo ~6.9 Mo ~6.5 Mo ~6.0 Mo
9.9546 ~4.2 Mo ~5.0 Mo ~4.6 Mo ~4.2 Mo
5.9727 ~2.5 Mo ~3.3 Mo ~3.0 Mo ~2.5 Mo

Capacité de cartouche 32 Mo (env.) :

FPS PCM 18157 Hz ADPCM 18157 Hz Sans 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

🎮 Commandes GBA (ROM autonome)

Bouton PCM ADPCM
START / A — Pause / Reprendre ✓ ✓
B — Muet / Activer le son ✓ ✓
DROITE — Avance rapide 3s ✓ ✗
GAUCHE — Reculer 3s ✓ ✗
SELECT — Verrouiller / déverrouiller les commandes ✓ ✓

La recherche (GAUCHE/DROITE) n'est pas disponible en ADPCM car le prédicteur IMA ADPCM est cumulatif — sauter à un octet arbitraire sans préchauffage produirait un audio corrompu.

🏗️ Aperçu de l'Architecture

Construit avec Python et PySide6 / PySide2 (détection automatique selon la version de Python) :

  • VideoEditor — fenêtre principale, gère le chargement, la prévisualisation et l'exportation des vidéos.
  • VideoController — lecture basée sur OpenCV avec recherche précise par image.
  • PresetManager — préréglages d'encodage intégrés et définis par l'utilisateur.
  • VideoEncoderCore — encodeur VQ parallèle par GOP (K-means + compensation de mouvement).
  • AudioEncoder — extracteur PCM / IMA ADPCM via ffmpeg inclus (imageio-ffmpeg).
  • Translator / ConfigManager — changement de langue à l'exécution et configuration persistante.

📦 Installation

Option 1 — Installeur (recommandé)

Téléchargez depuis GitHub Releases :

Installeur Python OS
GBAVideoStudio_Setup.exe Intégré Windows 10 / 11
GBAVideoStudio_Legacy_Setup.exe Intégré Windows 7 / 8 / 8.1

Option 2 — Portable

Téléchargez GBAVideoStudio_Portable.7z depuis GitHub Releases, extrayez où vous voulez et exécutez GBAVideoStudio.exe. Aucune installation requise.

Archive Python OS
GBAVideoStudio_Portable.7z Inclus (PySide2) Windows 7+

La version portable enregistre son emplacement dans le registre Windows au premier lancement afin que l'outil de mise à jour intégré puisse le localiser quel que soit l'endroit où il est extrait.

Option 3 — Exécuter à partir des sources

Prérequis

Environnement Python Backend Qt
Moderne 3.10+ PySide6 (auto)
Hérité 3.8 / 3.9 PySide2 5.15.2 (auto)

Outils externes

  • devkitPro — installez le groupe gba-dev depuis devkitpro.org (requis uniquement pour la compilation de ROM — la conversion vidéo fonctionne sans)

ffmpeg est inclus automatiquement via imageio-ffmpeg — aucune installation séparée n'est requise.

Étapes

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

🚀 Démarrage Rapide

  1. Ouvrir une vidéo — Fichier → Ouvrir une vidéo ou Ctrl+O.
  2. Définir la plage (optionnel) — naviguez jusqu'à l'image de début, appuyez sur Ctrl+PageUp ; naviguez jusqu'à l'image de fin, appuyez sur Ctrl+PageDown.
  3. Configurer les filtres de sortie — activer/désactiver le letterbox, définir le recadrage (x,y,w,h), cliquer sur Appliquer les filtres pour prévisualiser.
  4. Choisir un préréglage — sélectionnez dans le menu déroulant des Préréglages (Par défaut, Équilibré, Haute qualité, Bas FPS, Encodage rapide, Sans audio) ou ajustez les paramètres individuels.
  5. Sélectionner le dossier de sortie — cliquez sur Parcourir.
  6. Construire la ROM — cliquez sur Construire la ROM. La progression et le temps écoulé sont affichés dans la barre d'état.
  7. Terminé — une fenêtre contextuelle affiche l'utilisation de la mémoire (ROM / EWRAM / IWRAM). Le fichier .gba se trouve dans votre dossier de sortie.

🧩 Intégration dans les Projets de Décompilation

Après l'encodage, le dossier output/ contient tout ce qui est nécessaire pour intégrer la vidéo dans un projet de décompilation pret :

output/
  graphics/video/     → copier vers <projet>/graphics/video/  (régénéré à chaque encodage)
  include/video.h     → copier vers <projet>/include/video.h  (régénéré à chaque encodage)
  src/video.c         → copier vers <projet>/src/video.c      (copier une fois)
  INTEGRATION.fra.md

Consultez INTEGRATION.fra.md pour le guide d'intégration complet, la référence de l'API Task et la configuration de la touche de saut.

⚙️ Configuration et Localisation

  • Les paramètres sont stockés dans config.ini et persistent entre les sessions (langue, dossier de sortie, mode de prévisualisation, nombre max de workers, préréglage par défaut, etc.).
  • La langue peut être changée à l'exécution via Paramètres → Langue — toutes les chaînes de l'interface sont mises à jour immédiatement, y compris les informations vidéo, les noms des préréglages et les en-têtes des tableaux de mémoire.

🤝 Contribuer

  1. Forkez ce dépôt.
  2. Créez une branche de fonctionnalité : git checkout -b feature/ma-fonctionnalite
  3. Committez vos modifications : git commit -am "Ajoute ma fonctionnalité"
  4. Poussez : git push origin feature/ma-fonctionnalite
  5. Ouvrez une Pull Request.

🙏 Remerciements

  • Lecteur Vidéo GBA d'Ausar par ArcheyChen — Inspiration architecturale pour la lecture vidéo. Le moteur utilisé ici comporte des corrections de bogues personnalisées et des optimisations critiques IWRAM/EWRAM.
  • Codec ADPCM 8ad par Damian Yerrick ("PinoBatch") — Base conceptuelle pour le support audio IMA ADPCM, optimisé pour de meilleures performances mémoire.

📄 Licence

Sous licence GNU General Public License v3.0 (GPL-3.0). Les projets dérivés doivent être open source. Voir LICENSE pour plus de détails.

📩 Contact et Support

Serveur DiscordRejoignez notre Discord

Si vous trouvez cet outil utile, envisagez de soutenir son développement :

ko-fi