Karaoke Vocal Trainer — Руководство пользователя

Добро пожаловать! Это полный гайд по установке и использованию приложения.

---

Содержание

1. Что умеет приложение
2. Установка — базовая (без Docker)
3. Установка — полная (с Docker, для подготовки треков)
4. Режим Тренировка (Karaoke)
5. Режим Распевка (Warmup)
6. Режим Подготовка трека (Tools)
7. Горячие клавиши
8. Частые вопросы

---

1. Что умеет приложение

Приложение работает прямо в браузере — ничего устанавливать для основных функций не нужно.

Режим	Что нужно	Что делает
Тренировка	Микрофон + MIDI + аудио	Пение под фонограмму с оценкой попаданий в ноты
Распевка	Только микрофон	Упражнения на удержание ноты и пение гамм
Подготовка трека	Микрофон + Docker	Конвертация аудио, выделение вокала, создание MIDI

---

2. Установка — базовая (без Docker)

Для режимов Тренировка и Распевка никаких программ устанавливать не нужно.

Шаг 1 — Скачать файлы

Скачай два файла в одну папку:

• index.html
• pitch-processor.js

Шаг 2 — Открыть в браузере

Рекомендуется Chrome 110+ (Edge тоже работает).

Просто открой index.html двойным кликом.

Шаг 3 — Разрешить микрофон

При первом запуске браузер спросит разрешение на микрофон — нажми Разрешить.

---

3. Установка — полная (с Docker)

Docker нужен только для режима «Подготовка трека» (конвертация, разделение вокала, создание MIDI). Для тренировки и распевки он не нужен.

Шаг 1 — Установить Docker Desktop

1. Перейди на docker.com/products/docker-desktop
2. Нажми Download for Windows и установи
3. Перезагрузи компьютер
4. Запусти Docker Desktop — в трее появится иконка кита 🐳

Шаг 2 — Скачать оригинальные веса модели

Приложение использует модель для отделения вокала. Нужно скачать 4 файла по ~84 MB каждый:

Файл	Ссылка
f7e0c4bc-ba3fe64a.th	https://dl.fbaipublicfiles.com/demucs/hybrid_transformer/f7e0c4bc-ba3fe64a.th
d12395a8-e57c48e6.th	https://dl.fbaipublicfiles.com/demucs/hybrid_transformer/d12395a8-e57c48e6.th
92cfc3b6-ef3bcb9c.th	https://dl.fbaipublicfiles.com/demucs/hybrid_transformer/92cfc3b6-ef3bcb9c.th
04573f0d-f3cf25b2.th	https://dl.fbaipublicfiles.com/demucs/hybrid_transformer/04573f0d-f3cf25b2.th

Скаченные файлы положи в папку models\ рядом с Dockerfile:

karaoke-trainer\
├── index.html
├── pitch-processor.js
└── server\                     ← вся серверная часть здесь
    ├── Dockerfile
    ├── docker-compose.yml
    ├── .dockerignore
    ├── requirements.txt
    ├── tools_server.py
    ├── TOOLS_GUIDE.md
    └── models\
        ├── f7e0c4bc-ba3fe64a.th
        ├── d12395a8-e57c48e6.th
        ├── 92cfc3b6-ef3bcb9c.th
        └── 04573f0d-f3cf25b2.th

Шаг 3 — Собрать и запустить контейнер

Открой PowerShell в папке с файлами и выполни:

docker compose up -d --build

Первая сборка займёт ~5–10 минут. Последующие запуски — мгновенно.

Шаг 4 — Проверить статус

Открой index.html → «Подготовка трека». В верхней строке должен гореть зелёный кружок ● Сервер работает.

Управление контейнером

docker compose up -d       # Запустить
docker compose down        # Остановить
docker compose logs -f     # Смотреть логи
docker compose restart     # Перезапустить

---

4. Режим Тренировка (Karaoke)

Что нужно подготовить

• Аудиофайл — фонограмма (трек без вокала) в формате WAV или MP3
• MIDI-файл — мелодия вокала (только вокальная дорожка!)

Если у тебя есть полная запись с вокалом, используй режим «Подготовка трека» чтобы получить и фонограмму, и MIDI автоматически.

Загрузка файлов

1. На главном экране нажми «Тренировка»
2. Перетащи аудиофайл(ы) в зону «Перетащи WAV/MP3»
3. Перетащи MIDI-файл в зону «Перетащи MIDI»
4. Нажми «Старт»

Экран тренировки

┌─────────────────────────────────────────────────┐
│  Ноты движутся справа налево                    │
│  ●  ← Питч-шарик (твой голос)                   │
│  ████  ← Ноты из MIDI (синие/зелёные/жёлтые)    │
└─────────────────────────────────────────────────┘
│  Обзорная полоса (кликни для перемотки)         │
└─────────────────────────────────────────────────┘

• Зелёная нота — попал (≤1 полутон)
• Жёлтая нота — близко (≤2 полутона)
• Тёмная нота — промах

Оценка

После окончания MIDI-дорожки появится результат:

• % точности
• ★ звёзды: ★★★ ≥ 85%, ★★ ≥ 60%, ★ ≥ 30%

Полезные настройки

Элемент	Где найти	Что делает
Транспонирование	Слайдер в топ-баре	Сдвинуть все ноты на ±6 полутонов
Скорость 75%	Кнопка в топ-баре	Замедлить темп для разучивания
Метроном	Кнопка М	Включить/выключить ритм
Текст	Вставь в поле «Текст»	Слова песни под нотами

Сохранение сессии

Нажми кнопку «💾 Сохранить» — создаётся файл .vkt со всеми данными (аудио + MIDI + текст + статистика). Загружается обратно через «📂 Загрузить».

---

5. Режим Распевка (Warmup)

Удержание ноты

1. На главном экране нажми «Распевка» → вкладка «Удержание»
2. Выбери режим: Голос или Пианино

Режим Голос:

• Выбери тип голоса (Сопрано / Меццо / Альт / Тенор / Баритон / Бас)
• Выбери диапазон (Низкий / Средний / Высокий)
• Нажми на целевую ноту
• Пой и удерживай ноту нужное время (4 / 6 / 8 секунд)

Режим Пианино:

• Нажми клавишу на экранном пианино — она прозвучит
• Спой эту ноту
• Используй ◄ / ► для смены октавы

Что показывает экран:

• Большие буквы вверху — целевая нота и твоя спетая нота
• Стабильность — насколько ровно ты держишь ноту
• После окончания — среднее отклонение в полутонах и % точных фреймов

Гаммы

1. Перейди на вкладку «Гаммы»
2. Выбери паттерн (Мажор, Минор, Арпеджио и др.)
3. Выбери корневую ноту и темп (BPM)
4. Нажми «▶ Старт»
5. Пой ноты по мере их появления на экране

Пользовательские гаммы:

• Открой «✏️ Конструктор гаммы»
• Введи интервалы через запятую (напр. 0,2,4,5,7,9,11,12 = мажорная гамма)
• Нажми «💾 Сохранить» — гамма появится в списке

---

6. Режим Подготовка трека (Tools)

Требует запущенного Docker-контейнера (см. раздел 3).

На главном экране нажми «Подготовка трека». Зелёный кружок = сервер работает.

Типичный рабочий процесс

Если есть MP3/WAV с вокалом:

1. Разделить трек → перетащи файл → «▶ Разделить на вокал + фонограмму»
   (~2–5 мин на CPU)
   
2. Нажми «→ Перейти к созданию MIDI»

3. Создать MIDI → «▶ Создать MIDI» (~30–90 сек)

4. При необходимости настрой ползунки в панели «Настройка MIDI»

5. Нажми «→ Использовать как MIDI в Karaoke»
   (переходишь на экран загрузки Тренировки с готовым MIDI)

6. В панели «Разделить трек» нажми «→ Использовать как фонограмму в Karaoke»
   (добавляет no_vocals.wav как аудио)

7. Нажми «Старт»!

Если есть WebM/OGG (запись браузера):

1. Конвертация аудио → перетащи файл → выбери WAV → «▶ Конвертировать»
2. Нажми «→ Передать в "Разделить трек"»
3. Далее как выше с шага 1

Описание панелей

🎵 Конвертация аудио

Конвертирует WebM, OGG, M4A, MP4, FLAC в WAV или MP3.

• Выбери формат (WAV рекомендуется)
• После конвертации: ⬇ Сохранить файл или → Передать в «Разделить трек»

🎤 Разделить трек

Разделяет трек на вокал и фонограмму с помощью Demucs.

• Принимает WAV или MP3
• Результат: vocals.wav (вокал) и no_vocals.wav (фонограмма без вокала)
• ⬇ Сохранить vocals.wav — скачать вокальную дорожку
• ⬇ Сохранить фонограмму — скачать трек без вокала
• → Использовать как фонограмму в Karaoke — отправить no_vocals.wav в Тренировку
• → Перейти к созданию MIDI — передать вокал в следующую панель

🎼 Создать MIDI

Транскрибирует вокальный WAV/MP3 в MIDI-файл с помощью Basic Pitch.

Ползунок	Что делает	Совет
Чувствительность нот	Порог обнаружения (0.3–0.9)	Увеличь → меньше ложных нот
Минимальная длина	Фильтр коротких нот (50–600 мс)	Увеличь → убрать артефакты

• ⬇ Save MIDI — скачать .mid файл
• → Использовать как MIDI в Karaoke — передать в Тренировку и перейти туда

⚙️ Настройка MIDI (появляется после создания MIDI)

Дополнительная фильтрация нот перед отправкой в тренировку.

Ползунок	Что делает	Совет
Объединять паузы короче	Сшивает ноты с маленькой паузой	0.3–0.6 с для пения
Удалять ноты короче	Убирает очень короткие ноты	0.2–0.4 с

Блок «До / После» показывает количество нот до и после фильтрации.

Кнопка «→ Отправить в тренировку» — применяет настройки и переходит в Тренировку.

---

7. Горячие клавиши

(Только в режиме Тренировка)

Клавиша	Действие
Пробел	Воспроизведение / Пауза
R	Перезапуск с начала
M	Метроном вкл/выкл
L	Показать/скрыть панель с текстом
T	Транспонировать +1 полутон
← / →	Перемотка −5 сек / +5 сек
?	Показать справку по клавишам
Esc	Закрыть диалог

---

8. Частые вопросы

Приложение не видит микрофон → Проверь, что браузер получил разрешение на микрофон (замок в адресной строке → Микрофон → Разрешить).

Питч определяется плохо / с задержкой → Запусти приложение через python -m http.server 8080 вместо прямого открытия файла.

В Тренировке ноты не совпадают с фонограммой → Используй транспонирование (слайдер ±6 полутонов) чтобы сдвинуть MIDI под свой голос.

Разделение трека зависает на 85% очень долго → Нормально для длинных треков (1–3 мин трека ≈ 5–15 мин обработки на CPU). Если зависло более 45 минут — выполни docker compose restart.

Сервер показывает «Недоступен» хотя Docker работает → Подожди — при тяжёлой обработке пинг может задерживаться. Статус станет зелёным через 20–30 секунд после завершения задачи. Если красный долго — выполни docker compose restart.

MIDI содержит много лишних нот в тишине → Увеличь «Чувствительность нот» до 0.85–0.9 и «Минимальную длину» до 400–500 мс. Также используй панель «Настройка MIDI» для дополнительной фильтрации.

Кнопки в «Подготовке трека» неактивны → Убедись что файл выбран (зелёная рамка у зоны загрузки). Нотификация о доступности будет когда сервер ответит на пинг.

Как сохранить результаты тренировки? → В режиме Тренировка нажми «📸 Скриншот» для PNG-картинки, или «💾 Сохранить» для полного .vkt файла проекта.

Язык интерфейса → Кнопки EN / RU / ZH в правом верхнем углу в режимах Тренировка и Распевка.

---

Karaoke Vocal Trainer v3.x.x