Add OPL4 playback and analyzer support

2026-09-15 14:59:29 +03:00
commit 1686838e03
553 changed files with 50524 additions and 0 deletions
@@ -0,0 +1,153 @@
+# VGMPLAY.WMF — VGM Player for TSConfig / Wild Commander
+
+VGM/VGZ player plugin for **Wild Commander** (WC) on **ZX Spectrum TSConfig** with
+**MultiSound FPGA** sound card.  Written in C (SDCC) + Z80 assembly.
+
+**Version:** v0.9-beta
+
+Исходный проект плагина: [demyanenko-d/VGMPLAY.WMF](https://github.com/demyanenko-d/VGMPLAY.WMF).
+Автор исходного кода — GitHub-пользователь [demyanenko-d](https://github.com/demyanenko-d).
+
+## Supported Sound Chips
+
+| Chip | VGM cmd | Notes |
+|------|---------|-------|
+| **OPL1** (YM3526) | `0x5A`/`0x5B` | Через MultiSound OPL3 (compat mode) |
+| **OPL2** (YM3812) | `0x5A`/`0x5B` | Через MultiSound OPL3 (compat mode) |
+| **OPL3** (YMF262) | `0x5E`/`0x5F` | NEW=1, стерео L/R через C0-C8 |
+| **YMF278B** (OPL4) | `0xD0` | FM (порты 0/1) через OPL3 #C4-#C7; wave-часть (порт 2) через #7E/#7F (ZXM-MoonSound) |
+| **AY-3-8910 / YM2149** | `0xA0` | Single + dual chip |
+| **YM2203** (OPN) | `0x55`/`0xA0` | SSG-часть через AY |
+| **SAA1099** | `0xBD` | Single + dual chip (bit7 chip select) |
+
+**Форматы:** VGM (raw), VGZ (gzip — распаковка через inline inflate).
+
+## Features
+
+- **GD3 metadata** — отображение названия трека, игры, автора, системы
+- **Двойная буферизация** — ISR 683 Hz проигрывает команды, main loop наполняет буферы
+- **Спектроанализатор** — 16-полосный в реальном времени с плавным затуханием
+- **OPL4** — воспроизведение FM- и wave-частей YMF278B на ZXM-MoonSound
+- **Progress bar** — текущее время / общая длительность + счётчик loop
+- **VGZ inflate** — распаковка gzip прямо в память с progress bar
+- **Dual chip** — поддержка двухчиповых VGM (AY×2, SAA×2, YM2203×2)
+- **SAA chip select** — переключение chip0/chip1 клавишами 1/2
+- **Cmdblocks** — предрассчитанные блоки инициализации/silence в SRAM
+- **PS/2 клавиатура** — прямой доступ через CMOS FIFO TSConfig (без WC API)
+- **Варианты сборки** — build_variants.ps1 генерирует множество WMF с разными ISR freq / budget
+
+### OPL4 и спектроанализатор
+
+Для OPL4 анализатор отслеживает `KeyOn`/`KeyOff` 24 wave-каналов. Каналы 0–15
+соответствуют 16 полосам, а каналы 16–23 объединяются с полосами 0–7. При новом
+KeyOn полоса поднимается до максимума, затем плавно опускается до уровня 3, пока
+канал активен; после KeyOff она затухает до нуля. Это индикатор активности
+каналов, а не измеритель фактической амплитуды PCM-сэмплов.
+
+## Управление (PS/2 клавиатура)
+
+| Клавиша | Действие |
+|---------|----------|
+| **Space** | Следующий трек |
+| **P** | Предыдущий трек |
+| **Esc** | Выход из плагина |
+| **1** | SAA режим 1 — chip0 (левый SAA1099) |
+| **2** | SAA режим 2 — chip1 (правый SAA1099) |
+
+> Клавиши 1/2 активны только для dual-SAA музыки на одночиповой плате (`saa_chips=1`).
+> На двухчиповой плате (`saa_chips=2`) режим выбирается автоматически.
+
+## Настройки (wc.ini)
+
+Параметры задаются в конфигурации WC:
+
+```ini
+VGMPLAY.WMF -min_dur=10 -max_dur=4 -loops=1 -saa=1 -saa_chips=1
+```
+
+| # | Параметр | Default | Описание |
+|---|----------|---------|----------|
+| 0 | `min_dur` | 10 | Минимальная длительность трека (секунды) |
+| 1 | `max_dur` | 4 | Максимальная длительность (минуты) |
+| 2 | `loops` | 1 | Количество проигрываний loop-секции |
+| 3 | `saa` | 1 | SAA режим: **1** = chip0, **2** = chip1 |
+| 4 | `saa_chips` | 1 | Конфигурация платы: **1** = один SAA (default), **2** = два SAA |
+
+### Логика SAA режимов
+
+- **`saa_chips=1`** (одночиповая плата, default):
+  - Single-SAA музыка → всегда играет на chip0
+  - Dual-SAA музыка → по умолчанию chip0; переключение клавишами 1/2
+- **`saa_chips=2`** (двухчиповая плата):
+  - Single-SAA музыка → только chip0
+  - Dual-SAA музыка → turbo mode (оба чипа одновременно), переключение недоступно
+
+## Сборка
+
+### Требования
+
+- **SDCC** — компилятор C для Z80 (sdcc, sdasz80, sdld)
+- **sjasmplus** — ассемблер для cmdblocks и inflate
+- **Node.js** — скрипты генерации (pos_table, freq_tables, ihx2wmf)
+
+### Основная сборка
+
+```bat
+cd src_sdcc
+build.bat
+```
+
+Результат: `VGMPLAY.WMF` в корне проекта + `tsconf.img` (образ диска).
+
+### Варианты сборки
+
+```powershell
+cd src_sdcc
+.\build_variants.ps1
+```
+
+Генерирует все комбинации ISR freq / budget / no-short-waits в папку `variants/`.
+
+Параметры варианта задаёт единственный файл `inc/variant_cfg.h`:
+
+| Параметр | Описание |
+|----------|----------|
+| `ISR_FREQ` | Частота ISR (683 / 1367 / 2734 Hz) |
+| `VGM_FILL_CMD_BUDGET` | Макс. VGM-команд между yield (8..64) |
+| `VARIANT_DATA_LOC` | Адрес начала сегмента _DATA (hex) |
+| `VGM_NO_SHORT_WAITS` | Отключить обработку пауз 0x70-0x7F |
+
+## Структура проекта
+
+```
+src_sdcc/           Исходный код (C + ASM)
+  main.c            Главный модуль: UI, playback loop, INI
+  lib/vgm.c         VGM парсер, fill_buffer, emit handlers
+  lib/keys.c        PS/2 клавиатура (FSM, CMOS FIFO)
+  asm/isr.s         ISR: двойная буферизация, pos_table
+  asm/spectrum.s    Спектроанализатор (рендер + decay)
+  asm/cmdblocks.asm Блоки init/silence для всех чипов
+  asm/inflate_call.s Обёртка inflate для VGZ
+  inc/              Заголовочные файлы
+  scripts/          Node.js утилиты сборки
+  build/            Временные артефакты
+variants/           Предсобранные WMF для A/B тестирования
+DiskRef/            Эталонные файлы диска, тестовая музыка
+Ref/                Документация чипов, SDK, FPGA reference
+doc/                Описание WC Plugin API, VGM формата
+SamFlate/           Z80 inflate (распаковка gzip)
+tools/              sjasm, Unreal emulator
+```
+
+## Аппаратные требования
+
+- **ZX Spectrum TSConfig** (ZX Evolution с TSConf FPGA)
+- **Wild Commander** (ОС/файловый менеджер)
+- **MultiSound FPGA** — звуковая карта (OPL3 + AY + SAA1099)
+- **ZXM-MoonSound** (YMF278B) — требуется для воспроизведения OPL4 wave-части
+- CPU 14 MHz (turbo mode, автоматически включается плагином)
+- PS/2 клавиатура
+
+## Лицензия
+
+Проект предназначен для использования с аппаратной платформой TSConfig.