Skip to content

README.zht.md

Latest commit

 

History

History
336 lines (234 loc) · 13.4 KB

README.zht.md

File metadata and controls

336 lines (234 loc) · 13.4 KB
Raw

GBA Video Studio

Discord 平台 Python 授權條款

GBA Video Studio

GBA Video Studio 是一款用於在 Game Boy Advance 上轉換和播放影片的桌面應用程式。它能將任何影片檔案轉換為 .gba ROM，可直接在硬體或模擬器上播放，並配有完整的視覺化編輯器，用於修剪、預覽和配置每個編碼參數。

⚠️ 專為需要對 GBA 硬體影片編碼進行精確控制的 GBA 開發者和 ROM 駭客而設計。

🌐 翻譯版本

本 README 提供以下語言版本：

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

✨ 功能特色

  • 影片轉換為 GBA

    • 將任何影片檔案轉換為可播放的 GBA ROM。
    • 使用 YUV444 色彩空間，每個 GOP 採用 VQ 碼書壓縮。
    • 可選的 Floyd-Steinberg 抖色以減少色帶效應。
    • 編碼前可選擇信箱模式、拉伸或自訂裁切。

  • 視覺化編輯器

    • 載入並預覽任何影片檔案，具備完整的播放控制。
    • 設定起始/結束標記，僅編碼選取的範圍。
    • 即時 GBA 輸出預覽（240×160），並套用信箱和裁切效果。

  • 編碼設定檔（預設集）

    • 六個內建預設集：預設、平衡、高品質、低 FPS、快速編碼、無音訊。
    • 儲存、重新載入和管理自訂使用者預設集。
    • 完整參數控制：FPS、碼書大小、K-means 迭代次數、I-frame 間隔、運動補償等。

  • 音訊支援

    • PCM：8 位元有符號單聲道，取樣率 6500–44100 Hz。完整搜尋支援。
    • ADPCM：IMA ADPCM 4 位元（約縮小 50%），對齊 GBA 合適速率。停用搜尋功能。
    • 音量調整和無音訊模式。

  • 反編譯專案整合

    • 輸出可直接用於 pret 專案（pokefirered、pokeemerald 等）的 video.c、video.h 和二進位資源。
    • 可設定的跳過鍵（VIDEO_SKIP_KEY）。
    • 整合步驟請參閱 INTEGRATION.zht.md。

  • 多語言介面

    • 支援 18 種語言。可在執行時變更語言，無需重新啟動。

  • 匯出後動作

    • 可選擇在編碼完成後關機、睡眠、休眠、鎖定、登出或退出。

🖼️ 螢幕截圖

圖片

圖片

🔄 運作原理

轉換流程針對高效能影片編碼進行了最佳化，利用平行處理和記憶體映射（memmap）來處理大型影片檔案，而不會累積 RAM。

flowchart TD
    A([input.mp4]) --> B[1. FFmpeg 預先轉碼]
    B --> C[2. 影格提取]
    C --> D[3. GOP 平行處理]
    D --> E[4. 影格平行編碼]
    E --> F[5. 音訊提取與調整]
    F --> G[6. 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

🛠️ 流程解析

1. FFmpeg 預先轉碼

  • 幾何處理： 可選裁切 $\rightarrow$ 強制調整大小為 240×160（支援信箱模式或拉伸）。
  • 時間處理： 影格率轉換為精確的 GBA 原生 FPS 目標。
  • 修剪： 透過可選的起始時間參數進行精確時間軸定位。

2. 影格提取與色彩管理

  • 色彩空間： 直接提取為 YUV444 色彩空間。
  • 抖色： 可選的 Floyd-Steinberg 空間誤差擴散，以獲得最佳的 15 位元色彩表現。
  • 記憶體佔用： 影格直接串流到磁碟備份的 memmap 矩陣中，即使在長達一小時的影片上也確保 0% RAM 累積。

3. GOP（圖片群組）處理 平行

  • 分割： 影片被切割為獨立的 GOP，每個 GOP 由一個 I-frame 和多個 P-frame 組成。
  • 量化： 使用 K-means 聚類演算法為每個 GOP 訓練局部向量量化（VQ）碼書。
  • 最佳化： 碼書會按結構使用頻率自動排序，以最小化索引開銷。

4. 影格編碼 平行

  • I-frame： 使用全影格空間資料結合局部 VQ 碼書進行編碼。
  • P-frame： 時間壓縮，僅儲存相對於前一影格的差異區塊（變化的區域）和運動向量。

5. 音訊提取與適應性

  • PCM 模式： 以您選擇的取樣率提供清晰、未壓縮的單聲道 8 位元有符號音訊。
  • ADPCM 模式： 壓縮的 4 位元 IMA ADPCM，數學上對齊到最接近的 GBA 友好播放速率，以避免重新取樣造成的卡頓。

6. 編譯

  • 資源編譯器將編碼後的影片、音訊二進位檔案和播放引擎元件捆綁在一起。
  • 自動呼叫 devkitPro / make 將所有內容連結成一個獨立且符合硬體規範的 GBA_Video.gba ROM。

📊 編碼參數

影片

參數 預設值 範圍 影響
目標 FPS 9.9546 5.97 – 14.93 越高 = 越流暢，檔案越大
I-frame 間隔 60 1–999 越短 = 搜尋越好，檔案越大
差異臨界值 2.5 0.0–50.0 越低 = 越銳利，檔案越大
變異數臨界值 10.0 0.0–100.0 分離平坦區塊與紋理區塊
色彩回退 10.0 0.0–100.0 平坦區塊回退距離
強制 I 臨界值 0.7 0.0–1.0 場景變換 I-frame 敏感度
碼書大小 256 2–256 越大 = 品質越好
K-means 迭代次數 200 1–2000 越多 = 品質越好，速度越慢
I-frame 權重 3 1–10 聚類中 I-frame 區塊權重
運動臨界值 6 0–16 每個 8×8 MC 區塊最多更新的 2×2 子區塊數
抖色 開啟 開啟/關閉 Floyd-Steinberg，大小差異可忽略
運動補償 開啟 開啟/關閉 關閉可加快編碼，P-frame 較大

音訊

參數 預設值 範圍
格式 PCM PCM / ADPCM
取樣率 18157 Hz 6500–44100 Hz
音量 100% 0–200%

GBA 原生 FPS 值

FPS 使用案例
5.9727 最小體積
6.6364 非常緊湊
7.4659 緊湊
8.5325 中等
9.9546 預設 — 最佳平衡
11.9455 流暢動作
14.9319 最大（高動態內容）

📦 檔案大小參考

FPS 影片/分鐘 PCM 18157 Hz ADPCM 18157 Hz 無音訊
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 卡匣容量（約）：

FPS PCM 18157 Hz ADPCM 18157 Hz 無音訊
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 控制（獨立 ROM）

按鈕 PCM ADPCM
START / A — 暫停 / 繼續 ✓ ✓
B — 靜音 / 取消靜音 ✓ ✓
右 — 快轉 3 秒 ✓ ✗
左 — 倒轉 3 秒 ✓ ✗
SELECT — 鎖定 / 解鎖控制 ✓ ✓

搜尋（左/右）在 ADPCM 中不可用，因為 IMA ADPCM 預測器是累積的 — 跳轉到任意位元組偏移而無需預熱會產生損壞的音訊。

🏗️ 架構概述

使用 Python 和 PySide6 / PySide2（根據 Python 版本自動偵測）構建：

  • VideoEditor — 主視窗，管理影片載入、預覽和匯出。
  • VideoController — 基於 OpenCV 的播放，具有影格精確搜尋功能。
  • PresetManager — 內建和使用者定義的編碼預設集。
  • VideoEncoderCore — GOP 平行 VQ 編碼器（K-means + 運動補償）。
  • AudioEncoder — 通過捆綁的 ffmpeg (imageio-ffmpeg) 提取 PCM / IMA ADPCM。
  • Translator / ConfigManager — 執行時語言切換和持久化配置。

📦 安裝

選項 1 — 安裝程式（建議）

從 GitHub Releases 下載：

安裝程式 Python 作業系統
GBAVideoStudio_Setup.exe 內建 Windows 10 / 11
GBAVideoStudio_Legacy_Setup.exe 內建 Windows 7 / 8 / 8.1

選項 2 — 可攜版

從 GitHub Releases 下載 GBAVideoStudio_Portable.7z，解壓縮到任意位置並執行 GBAVideoStudio.exe。無需安裝。

壓縮檔 Python 作業系統
GBAVideoStudio_Portable.7z 內建 (PySide2) Windows 7+

可攜版在首次啟動時會將其位置註冊到 Windows 登錄檔中，以便內建更新程式無論解壓縮到何處都能找到它。

選項 3 — 從原始碼執行

需求

環境 Python Qt 後端
現代 3.10+ PySide6（自動）
舊版 3.8 / 3.9 PySide2 5.15.2（自動）

外部工具

  • devkitPro — 從 devkitpro.org 安裝 gba-dev 群組（僅 ROM 編譯需要 — 影片轉換無需此工具也可運作）

ffmpeg 通過 imageio-ffmpeg 自動捆綁 — 無需單獨安裝。

步驟

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. 開啟影片 — 檔案 → 開啟影片 或 Ctrl+O。
  2. 設定範圍（可選）— 導航到起始影格，按下 Ctrl+PageUp；導航到結束影格，按下 Ctrl+PageDown。
  3. 設定輸出濾鏡 — 啟用/停用信箱模式，設定裁切（x,y,w,h），點擊套用濾鏡進行預覽。
  4. 選擇預設集 — 從預設集下拉選單中選擇（預設、平衡、高品質、低 FPS、快速編碼、無音訊）或調整個別參數。
  5. 選擇輸出資料夾 — 點擊瀏覽。
  6. 建構 ROM — 點擊建構 ROM。進度和經過時間顯示在狀態列中。
  7. 完成 — 彈出視窗顯示記憶體使用情況（ROM / EWRAM / IWRAM）。.gba 檔案位於您的輸出資料夾中。

🧩 反編譯專案整合

編碼完成後，output/ 資料夾包含將影片嵌入 pret 反編譯專案所需的一切：

output/
  graphics/video/     → 複製到 <專案>/graphics/video/  （每次編碼重新生成）
  include/video.h     → 複製到 <專案>/include/video.h  （每次編碼重新生成）
  src/video.c         → 複製到 <專案>/src/video.c      （複製一次）
  INTEGRATION.zht.md

完整的整合指南、任務 API 參考和跳過鍵配置，請參閱 INTEGRATION.zht.md。

⚙️ 配置與本地化

  • 設定儲存在 config.ini 中，並在會話間持久化（語言、輸出資料夾、預覽模式、最大工作執行緒數、預設預設集等）。
  • 可透過 設定 → 語言 在執行時變更語言 — 所有介面字串立即更新，包括影片資訊、預設集名稱和記憶體表格標題。

🤝 貢獻

  1. Fork 此儲存庫。
  2. 建立功能分支：git checkout -b feature/我的功能
  3. 提交變更：git commit -am "新增我的功能"
  4. 推送：git push origin feature/我的功能
  5. 開啟 Pull Request。

🙏 致謝

  • Ausar 的 GBA 影片播放器 作者 ArcheyChen — 影片播放的架構靈感。此處使用的引擎具有自訂錯誤修復和關鍵的 IWRAM/EWRAM 最佳化。
  • 8ad ADPCM 編解碼器 作者 Damian Yerrick（"PinoBatch"）— IMA ADPCM 音訊支援的概念基礎，針對更好的記憶體效能進行了最佳化。

📄 授權條款

基於 GNU General Public License v3.0 (GPL-3.0) 授權。 衍生專案必須開源。詳情請參閱 LICENSE。

📩 聯絡與支援

Discord 伺服器加入我們的 Discord

如果您覺得這個工具有用，請考慮支持其開發：

ko-fi