🎵 MusicForDance

Подготовка музыки к танцевальному уроку: тики обратного отсчёта перед треком + замедленные копии (10/20/30%) без изменения высоты тона.

🎯 Что это и зачем

Хореограф запускает трек, и группа должна стартовать синхронно. Если трек начинается резко, без обратного отсчёта — половина танцоров промахивается с первым шагом. Готовые «countdown intro» в виде отдельной дорожки приходится каждый раз вручную сводить с треком.

Этот инструмент решает проблему за одну команду: из любого аудиофайла создаёт четыре версии для класса:

Файл	Скорость	Зачем
`1.0x <ваш-трек>.<ext>`	100 %	Оригинал + 5 тиков обратного отсчёта в начале
`0.9x <ваш-трек>.<ext>`	90 %	Замедление на 10 % — для разучивания связок
`0.8x <ваш-трек>.<ext>`	80 %	Замедление на 20 % — для медленного прохода по технике
`0.7x <ваш-трек>.<ext>`	70 %	Замедление на 30 % — для самых сложных моментов

Главные особенности:

✅ Высота тона сохраняется при замедлении — без эффекта замедленной плёнки и «гнусавого» вокала.
✅ Длинный последний тик заканчивается точно на первой ноте музыки — группа стартует синхронно, по обрыву гудка.
✅ Формат и качество выхода = формату и качеству источника. Загрузили MP3 320 кб/с — получите 4 файла MP3 320 кб/с. Загрузили FLAC 24-bit — получите 4 файла FLAC 24-bit.
✅ Один файл index.js — никаких node_modules, никаких пакетов из npm. Скопировали — работает.

🚀 Быстрый старт за 30 секунд

Перед началом нужны Node.js 18+ и ffmpeg — инструкция по установке (одна команда winget/brew/apt). Дальше — три команды и готово:

# 1. Скачать инструмент (Windows PowerShell):
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/bivlked/MusicForDance/main/index.js" -OutFile "index.js"

# 1. Скачать инструмент (macOS / Linux):
curl -O https://raw.githubusercontent.com/bivlked/MusicForDance/main/index.js

# 2. Запустить (любая операционная система):
node index.js "путь/к/Вашему треку.mp3"

В папке с треком появятся четыре новых файла: 1.0x ..., 0.9x ..., 0.8x ..., 0.7x ... — готово к использованию.

⚙️ Установка

Программе нужно две вещи:

Node.js 18 или новее — это среда, в которой запускается сам инструмент.
ffmpeg 6 или новее с библиотеками librubberband (замедление с сохранением высоты тона) и libmp3lame (для записи MP3, нужно только если используете --mp3).

Windows

Развернуть инструкцию для Windows (рекомендуется)

Откройте PowerShell от имени администратора (правый клик по кнопке «Пуск» → «Терминал (Администратор)»).
Выполните по очереди:
```
winget install OpenJS.NodeJS
winget install Gyan.FFmpeg
```
Gyan.FFmpeg — это «полная» сборка, в неё уже включены и librubberband, и libmp3lame. Других действий по установке этих библиотек делать не нужно.
Закройте терминал и откройте заново — это нужно, чтобы система увидела новые программы.
Проверка: в новом окне терминала выполните node --version и ffmpeg -version. Если обе команды выводят номер версии без ошибок — всё установлено правильно.

macOS

Развернуть инструкцию для macOS

Через Homebrew:

brew install node ffmpeg

brew install ffmpeg устанавливает сборку с включёнными librubberband и libmp3lame.

Linux (Debian / Ubuntu)

Развернуть инструкцию для Linux

sudo apt update
sudo apt install nodejs ffmpeg

В стандартных пакетах Ubuntu начиная с 22.04 librubberband уже включён в ffmpeg. На старых дистрибутивах может потребоваться сборка ffmpeg с флагом --enable-librubberband — детали в docs/ARCHITECTURE.md.

Получить сам инструмент

Достаточно скачать только один файл — index.js:

Windows:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/bivlked/MusicForDance/main/index.js" -OutFile "index.js"

macOS / Linux:

curl -O https://raw.githubusercontent.com/bivlked/MusicForDance/main/index.js

Или клонировать весь репозиторий целиком (если хотите получить заодно run.bat для перетаскивания файлов и историю изменений):

git clone https://github.com/bivlked/MusicForDance.git
cd MusicForDance

🎬 Как пользоваться

Способ 1. Перетащить трек на `run.bat` (Windows, без терминала)

Если Вы клонировали репозиторий через git clone — рядом с index.js лежит файл run.bat. Просто перетащите аудиофайл мышью на run.bat — программа отработает сама и положит четыре готовые версии в ту же папку, где лежал исходный трек.

Способ 2. Командная строка

# По умолчанию: формат и качество как у источника
node index.js "Ваш трек.mp3"

# Несколько треков сразу — все в указанную папку
node index.js a.wav b.mp3 c.flac --out-dir "./урок"

# Свои скорости (вместо 1.0 / 0.9 / 0.8 / 0.7)
node index.js "Ваш трек.wav" --ticks 4 --speeds 1.0,0.85,0.7

# Принудительный формат
node index.js "Ваш трек.mp3" --wav            # → WAV
node index.js "Ваш трек.wav" --mp3            # → MP3 192 кб/с
node index.js "Ваш трек.mp3" --bitrate 320k   # → MP3 320 кб/с

Способ 3. Получить справку

node index.js --help

Параметры

При первом упоминании в скобках — английский эквивалент термина (битрейт = bitrate, кодек = codec, разрядность = bit depth, частота дискретизации = sample rate). Дальше по тексту используется короткая русская форма.

Параметр	По умолчанию	Что делает	Когда менять
`--ticks <N>`	`5`	Сколько тиков обратного отсчёта (от 1 до 20). Последний всегда длинный.	Если хочется отсчёт «4-3-2-1-и» вместо «5-4-3-2-1-и» — поставьте `4`.
`--silence-db <X>`	`-50`	Порог тишины в дБ для обрезки начала трека.	Если в треке есть тихий осмысленный вступление (ambient) — понизьте до `-90`.
`--speeds <a,b,c>`	`1.0,0.9,0.8,0.7`	Список скоростей через запятую (от 0.25 до 4).	Если для класса нужен только оригинал и одна замедленная — `1.0,0.7`.
`--mp3`	(выкл.)	Принудительно сохранить в `MP3` (битрейт (bitrate) из источника или 192 кб/с по умолчанию).	Источник — `WAV`/`FLAC`, нужно сжать в `MP3` для смартфона.
`--wav`	(выкл.)	Принудительно сохранить в `WAV` (без потерь).	Источник — `MP3`/`AAC`, нужен `WAV` без потерь для дальнейшей обработки.
`--bitrate <X>`, `-b`	(из источника)	Переопределить битрейт для форматов с потерями: `320k`, `128k`, `320`.	Хотите принудительно сжать сильнее или слабее, чем у источника.
`--out-dir <путь>`	рядом с источником	Папка для готовых файлов (создастся, если не существует).	Хотите сложить все версии в одну общую папку для урока.
`--setup <папка>`	—	Развернуть программу (`index.js` + `run.bat`) в указанную папку.	Перенос на другой компьютер.
`--force`, `-f`	(выкл.)	Разрешить `--setup` перезаписывать файлы в непустой папке.	Только если понимаете, что делаете.
`-h`, `--help`		Показать справку.

Что получите на выходе

По умолчанию инструмент сохраняет тот же формат, кодек (codec) и качество, что и у источника. Форматы делятся на две группы:

Без потерь (форматы WAV, FLAC, ALAC) — звук сохраняется точно бит-в-бит, при повторных операциях ничего не теряется. Сохраняется разрядность (bit depth) — 16-, 24- или 32-битная.
С потерями (форматы MP3, AAC, Opus, Vorbis, AC3) — для уменьшения размера файла часть звуковой информации отбрасывается. Сохраняется тот же битрейт, что у источника.

Источник	Что получите
`MP3` 320 кб/с	`MP3` 320 кб/с
`MP3` 128 кб/с	`MP3` 128 кб/с
`AAC` 256 кб/с (`M4A`)	`AAC` 256 кб/с (`M4A`)
`FLAC` 24-bit	`FLAC` 24-bit
`FLAC` 16-bit	`FLAC` 16-bit
`WAV PCM` 32-bit	`WAV PCM` 32-bit
`WAV PCM` 32-bit float	`WAV PCM` 32-bit float — формат с плавающей точкой (используется в профессиональных аудио-программах), теперь сохраняется как есть (исправлено в v1.0.1; раньше тихо пересохранялся в 32-битное целое)
`WAV PCM` 24-bit	`WAV PCM` 24-bit
`WAV PCM` 16-bit	`WAV PCM` 16-bit
`Opus`	`Opus` (тот же битрейт)
`Vorbis` (`OGG`)	`Vorbis` (`OGG`)
`AC3` / `E-AC3`	`AC3` / `E-AC3`
`ALAC`	`ALAC`
`WMA`, `DTS` (нет кодировщика)	резервный вариант: `WAV` 24-bit

Каналы: моно или стерео. Окружающий звук (5.1, 7.1) автоматически сводится в стерео.

Частота дискретизации (sample rate) сохраняется. Исключение: MP3 поддерживает максимум 48 кГц — если у источника частота выше (например, 96 кГц), она будет приведена к ближайшей подходящей, и в логе появится явное предупреждение (добавлено в v1.0.1):

⚠ MP3 не поддерживает 96000 Hz → snap к 48000 Hz

📚 Подробности про сжатие на уровне битов, точность 24-bit FLAC, поведение для VBR-кодеков — docs/ARCHITECTURE.md §2.

Пример работы

[1/3] Анализ «Ваш трек.mp3»
      mp3, 44100 Hz, 2ch, 0-bit, 320 kbps, длительность 215.43 с

[2/3] Генерация intro (5 тиков, 44100 Hz, stereo)
      861.3 KB → tmp

[3/3] Сборка 4 версий (MP3 320k)
  ✓ 1.0x Ваш трек.mp3  (1.4s)
  ✓ 0.9x Ваш трек.mp3  (8.2s)
  ✓ 0.8x Ваш трек.mp3  (9.1s)
  ✓ 0.7x Ваш трек.mp3  (10.6s)

Готово за 29.3s. Файлы в: C:\Music\Class

Цифры скорости — типичный трек 3,5 минуты на современном ноутбуке. Большая часть времени уходит на замедленные версии — растяжение по времени с сохранением высоты тона требует больше вычислений, чем оригинальная скорость.

❓ Частые вопросы

Программа не находит ffmpeg или librubberband. Что делать?

После установки ffmpeg через winget или brew обязательно перезапустите терминал (закройте окно полностью и откройте заново). Это нужно, чтобы система увидела новую программу.

Проверка установки:

ffmpeg -version
ffmpeg -filters | findstr rubberband   # Windows
ffmpeg -filters | grep rubberband      # macOS / Linux

Первая команда выводит версию ffmpeg. Вторая — должна показать строку с упоминанием rubberband. Если её нет — Ваша сборка ffmpeg без librubberband. На Windows используйте winget install Gyan.FFmpeg (это полная сборка, с librubberband).

Как остановить процесс, если я нажал Enter случайно?

Нажмите Ctrl+C в окне терминала. Программа корректно остановит обработку, завершит дочерний процесс ffmpeg и удалит временные файлы. Это поведение исправлено в версии 1.0.1 — раньше при Ctrl+C мог оставаться «висящий» процесс ffmpeg в системе и временный файл в папке временных файлов операционной системы.

Как проверить, что всё работает правильно (без своих треков)?

В репозитории есть встроенный самопроверочный тест — он сам синтезирует тестовый аудиофайл, прогоняет через программу и проверяет, что результат соответствует ожиданиям:

node tests/smoke.js

Если выводит ✓ smoke OK (4/4 tests) — всё установлено и работает. Если ffmpeg отсутствует, тест аккуратно пропускается с пояснением (без ошибки).

MP3 или WAV — что выбрать для класса?

MP3 192–320 кб/с — оптимально для большинства случаев. Файл меньше, легко переносить на телефон или флешку, никаких слышимых потерь качества.
WAV — если планируете дальше сводить трек в редакторе (например, делать обрезки в Audacity). Без потерь, но файл в 5–10 раз больше.
Если источник FLAC или WAV — оставьте по умолчанию (программа сохранит тот же формат). Нет смысла принудительно конвертировать в MP3, если не нужна экономия места.

В моём треке тихое вступление (ambient на низкой громкости). Программа его обрезает.

По умолчанию программа считает «тишиной» всё ниже −50 дБ. Если интересный вступительный пассаж тише — понизьте порог:

node index.js "Ваш трек.flac" --silence-db -90

Тогда программа обрежет только настоящую тишину (ниже −90 дБ — это уже шум кодирования), а вступление сохранит.

Можно ли поменять звук тиков (вместо щелчка — гонг, голос, что-то другое)?

Да, но это требует правки исходного кода. Тики синтезируются простыми синусоидами в функциях generateTickMono (короткий тик) и generateLongBuzzMono (длинный финальный тик) внутри index.js. Можно менять частоты, длительности, форму огибающей. Подробное описание — docs/ARCHITECTURE.md §3.

Перенос на другой компьютер

Программа полностью помещается в один файл index.js. Чтобы развернуть её на новом компьютере:

Скопируйте index.js (через флешку, облако, почту — что угодно).
Выполните на новом компьютере:
```
node index.js --setup "C:\Tools\MusicForDance"
```
В указанной папке появятся index.js + run.bat (для перетаскивания мышью на Windows). Программа также проверит, установлены ли ffmpeg, librubberband, libmp3lame и подскажет, что и как доставить, если чего-то не хватает.

Пример вывода:

[setup] Целевая папка: C:\Tools\MusicForDance
[setup] ✓ index.js  (32.1 KB)
[setup] ✓ run.bat

[setup] Проверка окружения:
  ✓ Node.js — v24.15.0
  ✓ ffmpeg — 8.1-full_build-www.gyan.dev
  ✓ librubberband filter
  ✓ libmp3lame encoder

[setup] Готово. Использование на этом ПК:
  cd "C:\Tools\MusicForDance"
  node index.js "путь\к\треку.mp3"
  (или перетащите аудиофайл на run.bat)

📚 Углублённые материалы

📖 Архитектура и внутренности — как устроена цепочка обработки, как сделаны тики, чем отличаются движки librubberband, структура index.js.
📋 История изменений — что менялось от версии к версии.
🤝 Как помочь проекту — для тех, кто хочет предложить улучшение или сообщить об ошибке.
📜 Лицензия MIT — условия использования.

Ограничения

Окружающий звук (5.1 / 7.1) автоматически сводится в стерео. Если для урока нужен 5.1 — обрабатывайте каналы вручную через ffmpeg.
MP3 поддерживает максимум 48 кГц. Источники с более высокой частотой (например, 96 кГц) будут пересчитаны (с предупреждением в выводе).
WMA, DTS — у стандартного ffmpeg нет кодировщика для этих форматов, на выходе будет WAV 24-bit (резервный вариант).
Тихое вступление в треке может быть ошибочно принято за тишину и обрезано. Решение — параметр --silence-db -90 (см. вопрос в FAQ).

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
docs		docs
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package.json		package.json
run.bat		run.bat

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🎵 MusicForDance

🎯 Что это и зачем

🚀 Быстрый старт за 30 секунд

⚙️ Установка

Windows

macOS

Linux (Debian / Ubuntu)

Получить сам инструмент

🎬 Как пользоваться

Способ 1. Перетащить трек на `run.bat` (Windows, без терминала)

Способ 2. Командная строка

Способ 3. Получить справку

Параметры

Что получите на выходе

Пример работы

❓ Частые вопросы

Перенос на другой компьютер

📚 Углублённые материалы

Ограничения

📜 Лицензия

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🎵 MusicForDance

🎯 Что это и зачем

🚀 Быстрый старт за 30 секунд

⚙️ Установка

Windows

macOS

Linux (Debian / Ubuntu)

Получить сам инструмент

🎬 Как пользоваться

Способ 1. Перетащить трек на run.bat (Windows, без терминала)

Способ 2. Командная строка

Способ 3. Получить справку

Параметры

Что получите на выходе

Пример работы

❓ Частые вопросы

Перенос на другой компьютер

📚 Углублённые материалы

Ограничения

📜 Лицензия

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Способ 1. Перетащить трек на `run.bat` (Windows, без терминала)

Packages