# XM Player

Плагин для Wild Commander (ZX Evolution / TS-Conf), проигрывающий XM, XMZ
(запакованный gzip'ом XM) и S3M модули через ESP32-сопроцессор платы. Z80
только передаёт файл на ESP32 и отображает окно со статусом; сам разбор
модуля и синтез звука выполняет прошивка ESP32.

> ⚠️ **Несовместим со стандартным ftview.** Оригинальный (стандартный)
> плагин `ftview` сам регистрируется на расширения `.XM` и `.XMZ` — ровно
> те же, что и у этого плагина. У Wild Commander таблица "расширение →
> плагин" статическая, зашита в заголовок при сборке, и если файл поставить
> вместе со стандартным `ftview`, они будут конфликтовать за одни и те же
> расширения. Используйте переработанную версию `ftview` (расширения `.XM`
> и `.XMZ` из неё убраны, воспроизведение вынесено в этот плагин) —
> она лежит отдельным репозиторием: https://git.alexkorochinskiy.ru/alex/ftview.git

## Требования

- ZX Evolution / TS-Conf с прошитым ESP32-сопроцессором
- Wild Commander (заголовок плагина версии 10+, есть в текущих сборках)
- переработанная версия `ftview` (см. предупреждение выше), а не стандартная

## Возможности

- Проигрывание `.XM`, `.XMZ`, `.S3M`
- Окно с живым статусом: имя файла, статус загрузки/воспроизведения,
  паттерн, строка, BPM, прошедшее/общее время, прогресс-бар
- Ошибки выводятся прямо в строке статуса (с кодом ошибки ESP32, например
  `Playback error (0x90)`), без отдельного всплывающего окна
- Автоматический переход к следующему файлу по окончании трека
- Параметр `stoponerror` в ini — остановка на ошибке вместо автоперехода,
  удобно, чтобы найти, какой именно файл в подборке вызывает проблему

## Управление

| Клавиша      | Действие                                    |
|--------------|----------------------------------------------|
| PgDn, Enter  | Следующий файл                                |
| PgUp         | Предыдущий файл                               |
| Esc          | Остановить воспроизведение и выйти            |
| Space        | Выйти, не останавливая текущее воспроизведение |

## Установка

Скопировать `xmplay.wmf` в каталог плагинов Wild Commander. Плагин сам
регистрируется на расширения `.XM`, `.XMZ` и `.S3M`.

Чтобы при ошибке воспроизведения плагин останавливался, а не переходил
сразу к следующему файлу, добавить в `wc.ini`:

```
XMPLAY.WMF -stoponerror=1
```

(`0` или отсутствие параметра — поведение по умолчанию: автопереход при ошибке.)

## Сборка

Нужен [SDCC](http://sdcc.sourceforge.net/) версии 4.6.0 (зафиксирована в
`build.bat`) и `hex2bin` — оба есть в тулчейне SDK ZX Evolution.

```
build.bat
```

Результат — `xmplay.wmf` в корне проекта.

## Благодарности

Собран на основе `wc_api.lib` из `demyanenko-d/VGMPLAY.WMF` — используется
для доступа к API Wild Commander (окна, вывод текста, клавиатура, ini-параметры).

## Статус

Проверено на реальном железе: воспроизведение, живая статистика,
прогресс-бар, обработка ошибок и управление с клавиатуры.