# README для плагина "Audio Player" для NGCMS

## Описание

HTML5 музыкальный плеер с плейлистом. Треки читаются из указанной папки внутри `/uploads/`.
Поддерживаются форматы: MP3, OGG, WAV, M4A.

## Установка

1. Скопируйте папку `audioplayer` в директорию `/engine/plugins/`
2. Зайдите в панель администратора NGCMS
3. Перейдите в раздел «Плагины»
4. Найдите плагин «Audio Player» и нажмите «Установить»
5. Перейдите в настройки плагина и укажите папку с треками

## Подготовка музыки

Загрузите MP3/OGG/WAV/M4A файлы в папку `/uploads/files/music/` (или любую другую).
Имена файлов автоматически преобразуются в читаемый вид:

- символы `_` и `-` заменяются на пробелы
- числовые хеши в конце имени убираются

## Настройка

| Поле                | Описание                                          | По умолчанию      |
| ------------------- | ------------------------------------------------- | ----------------- |
| Заголовок           | Название плеера в шапке виджета                   | Музыкальный плеер |
| Папка с треками     | Путь внутри `/uploads/` (например: `files/music`) | files/music       |
| Тема оформления     | Цветовая схема: dark / light / blue               | dark              |
| Автовоспроизведение | Начать воспроизведение при загрузке страницы      | Выключено         |
| Показывать плейлист | Отображать список треков под плеером              | Включено          |
| Режим отображения   | Способ вывода плеера: widget / popup / page       | widget            |

## Использование в шаблоне

```twig
{{ callPlugin("audioplayer.show", {})|raw }}
```

С параметрами (переопределяют настройки из конфига):

```twig
{{ callPlugin("audioplayer.show", {folder: "music", skin: "dark", show_list: "1"})|raw }}
```

## Режимы отображения

| Режим    | Описание                                                              |
| -------- | --------------------------------------------------------------------- |
| `widget` | Компактный виджет — вставляется прямо в страницу (по умолчанию)       |
| `popup`  | Кнопка на странице; клик открывает плавающее модальное окно с плеером |
| `page`   | Полностраничный плеер: слева диск и управление, справа плейлист       |

```twig
{# Виджет #}
{{ callPlugin("audioplayer.show", {})|raw }}
{# Всплывающее окно #}
{{ callPlugin("audioplayer.show", {mode: "popup"})|raw }}
{# Страница #}
{{ callPlugin("audioplayer.show", {mode: "page"})|raw }}
```

## Параметры вызова

| Параметр    | Значения              | Описание                   |
| ----------- | --------------------- | -------------------------- |
| `folder`    | имя папки             | Папка внутри `/uploads/`   |
| `skin`      | dark / light / blue   | Тема оформления            |
| `autoplay`  | 0 / 1                 | Автовоспроизведение        |
| `show_list` | 0 / 1                 | Показывать плейлист        |
| `title`     | строка                | Заголовок плеера           |
| `mode`      | widget / popup / page | Режим отображения          |
| `template`  | имя шаблона           | Альтернативный Twig-шаблон |

## Возможности плеера

- Кнопки: предыдущий / play-pause / следующий / перемешать
- Кликабельный прогресс-бар с отображением времени
- Регулятор громкости
- Прокручиваемый плейлист с подсветкой текущего трека
- Три встроенных скина без внешних зависимостей

## Кастомизация

Шаблон плеера: `/engine/plugins/audioplayer/tpl/audioplayer.tpl`
Для создания своего оформления скопируйте шаблон в папку активной темы:
`/templates/{ваш_шаблон}/plugins/audioplayer/`
