154 lines
7.7 KiB
Markdown
154 lines
7.7 KiB
Markdown
# 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.
|