hamori/docs/requirements.md

Требования к проекту hamori

Версия документа: 1.0 Дата: 2026-05-19

Документ описывает функциональные и нефункциональные требования к проекту hamori — генератору гармонических периодов в авторском композиторском стиле. Описываются ограничения, критерии приёмки и явно выведенные за рамки возможности.

---

1. Контекст и цели проекта

1.1 Постановка задачи

Разработать генеративную нейросетевую модель, способную создавать гармонические последовательности заданной длины и стилистики, обученную в том числе на корпусе собственных произведений автора, с целью использования получившейся модели как творческого инструмента в композиторской работе.

1.2 Заинтересованные стороны

Сторона	Интерес
Автор-разработчик (студент)	Закрытие курсовой дисциплины, получение работающего инструмента для собственной композиторской практики
Преподаватель курса	Демонстрация владения полным циклом ML-проекта: постановка задачи, подготовка данных, обучение, оценка, интерпретация
Потенциальные читатели исходного кода	Понимание принятых архитектурных решений и возможность повторного использования компонентов

1.3 Учебные цели

Демонстрация компетенций в следующих областях машинного обучения:

• Проектирование задачи генерации последовательностей в условиях ограниченного объёма обучающих данных.
• Выбор и реализация архитектуры авторегрессионной модели для дискретных последовательностей.
• Подготовка и токенизация специализированного датасета.
• Применение схемы предобучение / дообучение.
• Количественная и качественная оценка генеративной модели.
• Анализ распределений и интерпретация результатов.

1.4 Прикладные цели

Получение программного инструмента, обладающего следующими функциональными характеристиками:

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

---

2. Ограничения

2.1 Временные ограничения

Жёсткий срок реализации: менее одного календарного месяца с момента начала работ. Бюджет ручного труда автора: около 50 часов.

Распределение времени:

• Подготовка инфраструктуры данных: ~12 часов.
• Ручная транскрипция собственного корпуса: ~10–15 часов.
• Реализация модели и обучение: ~12 часов.
• Оценка и подготовка примеров: ~6 часов.
• Написание отчёта и оформление: ~10 часов.

2.2 Ресурсные ограничения

Аппаратные ресурсы: персональный ноутбук автора. Использование облачных GPU-ресурсов (Google Colab) допустимо, но не должно быть критически необходимым — модель проектируется так, чтобы обучение было выполнимо на CPU.

Программные ресурсы: открытое программное обеспечение, бесплатные публичные датасеты.

2.3 Ограничения по данным

Объём собственного корпуса автора ограничен числом существующих композиторских работ и временем, доступным на ручную транскрипцию. Реалистичный ориентир: 80–150 гармонических периодов из 20–25 пьес.

Это значение на два-три порядка меньше типичного объёма данных, на которых обучаются современные музыкальные генеративные модели. Из этого ограничения вытекает принципиальное архитектурное решение: модель должна использовать схему «предобучение на публичном корпусе плюс дообучение на собственном корпусе», обучение с нуля исключительно на собственных данных нецелесообразно.

2.4 Языковые требования

Согласно требованиям учебного заведения:

• Итоговый отчёт оформляется на русском языке по стандартам ГОСТ для студенческих работ.
• Документация для пользователя (README, спецификация формата, описания архитектуры) ведётся на русском языке.
• Технические артефакты кода (идентификаторы, комментарии, сообщения логов, сообщения коммитов) ведутся на английском языке для совместимости с общепринятыми стандартами разработки и удобства совместной работы с инструментами вроде Claude Code.

---

3. Функциональные требования

3.1 Подсистема работы с форматом данных

ФТ-1. Система должна поддерживать чтение .chord-файлов в формате, описанном в docs/chord_format_spec.md версии 2.2, включая:

• Парсинг шапки с метаданными.
• Парсинг тела файла, состоящего из последовательности тактов.
• Распознавание аккордовых символов по правилам §4 спецификации.
• Поддержку всех восемнадцати базовых качеств аккордов с альтернативными написаниями.
• Поддержку расширений аккордов (одиночный слот).
• Поддержку слэш-нотации для инверсий.
• Распознавание специальных значений (точка для удержания, NC для паузы, ? для неизвестного аккорда).

ФТ-2. Система должна выполнять валидацию .chord-файлов:

• Проверять корректность шапки (все обязательные поля присутствуют, значения входят в допустимые множества).
• Проверять, что число позиций в каждом такте соответствует тактовому размеру и подразделению доли.
• Поднимать информативные ошибки с указанием имени файла, номера такта и позиции при обнаружении нарушений.

ФТ-3. Система должна выполнять нормализующую транспозицию: все мажорные периоды приводятся к тональности C major, минорные — к A minor.

ФТ-4. Система должна выполнять токенизацию .chord-файлов в последовательности целочисленных идентификаторов согласно словарю, описанному в §5 спецификации формата. Словарь содержит 85 токенов.

ФТ-5. Система должна поддерживать обратную детокенизацию: преобразование последовательности целочисленных идентификаторов обратно в .chord-файл, с последующей опциональной транспозицией в произвольную тональность.

ФТ-6. Система должна обеспечивать round-trip эквивалентность: для любого корректного .chord-файла операция parse → tokenize → detokenize → serialize должна давать .chord-файл, эквивалентный исходному по гармоническому содержанию.

3.2 Подсистема экспорта в MIDI

ФТ-7. Система должна обеспечивать экспорт .chord-файлов в стандартный формат MIDI с двумя треками: трек аккордов и трек баса. Темп задаётся параметром, по умолчанию 90 ударов в минуту.

ФТ-8. Длительности нот в MIDI должны соответствовать длительностям удержания аккордов в исходном .chord-файле.

3.3 Подсистема конвертации внешних корпусов

ФТ-9. Система должна предоставлять конвертер McGill Billboard Project → формат .chord, выполняющий:

• Чтение Harte-нотации.
• Разрезание исходных пьес на гармонические периоды по границам секций.
• Сохранение каждого периода как отдельного .chord-файла.
• Простановку стилевого тега и функциональной роли в шапке.

ФТ-10. Конвертер должен быть устойчив к некорректным или неполным аннотациям в исходном корпусе: периоды, которые не могут быть однозначно сконвертированы, пропускаются с записью в лог, выполнение скрипта при этом не прерывается.

3.4 Подсистема обучения

ФТ-11. Система должна реализовывать архитектуру авторегрессионного трансформера со следующими параметрами:

• Количество слоёв: настраиваемое, 2–4 по умолчанию.
• Размерность модели: настраиваемая, 128–256 по умолчанию.
• Число голов внимания: настраиваемое, 4–8 по умолчанию.
• Контекстное окно: 512 токенов.
• Связанные веса входного и выходного эмбеддингов.

ФТ-12. Система должна предоставлять два высокоуровневых скрипта обучения:

• scripts/pretrain.py — предобучение на публичном корпусе McGill.
• scripts/train.py — дообучение на собственном корпусе с инициализацией весов из чекпоинта предобучения.

Оба скрипта имеют флаг --skip-training для повторного построения графиков и отчёта без перезапуска обучения. Низкоуровневая параметризация (гиперпараметры, архитектурные параметры, устройство) доступна через src/train.TrainConfig.

ФТ-13. В процессе обучения система должна:

• Логировать значения функции потерь на тренировочной и валидационной выборках после каждой эпохи.
• Логировать перплексию на валидационной выборке.
• Сохранять лучший по валидационной потере чекпоинт.
• Поддерживать раннюю остановку по валидационной потере с настраиваемым параметром терпения.
• Сохранять полный лог обучения в формате CSV.

3.5 Подсистема инференса

ФТ-14. Система должна предоставлять CLI-инструмент генерации со следующими настраиваемыми параметрами:

• Путь к чекпоинту модели.
• Лад (мажор / минор).
• Тональность (любой из 12 классов высоты).
• Тактовый размер.
• Подразделение доли.
• Стилевой тег.
• Функциональная роль.
• Опциональная гармоническая затравка (последовательность аккордовых символов).
• Температура сэмплирования.
• Параметр top-p (nucleus sampling).
• Максимальное число токенов.
• Случайное зерно.
• Пути для сохранения .chord- и MIDI-файлов.

ФТ-15. Инференс должен использовать nucleus sampling с настраиваемой температурой. Beam search не используется.

ФТ-16. Система должна предотвращать генерацию грамматически невалидных последовательностей токенов (например, токена расширения сразу после токена удержания) через маскирование невалидных кандидатов на каждом шаге.

3.6 Подсистема оценки

ФТ-17. Система должна предоставлять скрипт оценки, принимающий на вход два чекпоинта (базовый и целевой) и отложенную выборку, и формирующий:

• Численные метрики перплексии для обеих моделей.
• Графики распределений по ключевым гармоническим признакам.
• Сгенерированные образцы для качественного сравнения.

ФТ-18. Графики распределений должны включать:

• Распределение типов качеств аккордов.
• Долю аккордов с расширениями.
• Долю аккордов с инверсиями.
• Распределение интервалов движения корня.
• Распределение наиболее частых пар «корень-корень» (биграммы).

Каждый график должен показывать baseline-распределение и target-распределение на одной координатной плоскости с легендой.

---

4. Нефункциональные требования

4.1 Производительность

НФТ-1. Парсинг одного .chord-файла должен выполняться менее чем за 100 миллисекунд на стандартном персональном компьютере.

НФТ-2. Один проход обучения по тренировочной выборке (одна эпоха) на полном McGill корпусе должен укладываться в 10 минут на CPU современного ноутбука.

НФТ-3. Генерация одного периода должна занимать менее 10 секунд на CPU.

4.2 Корректность

НФТ-4. Парсер аккордовых символов должен корректно обрабатывать все примеры, перечисленные в §4.6 спецификации формата.

НФТ-5. Round-trip эквивалентность (см. ФТ-6) должна подтверждаться автоматизированными тестами для всех тестовых фикстур.

НФТ-6. Транспозиция должна быть точной: после транспозиции мажорного периода в C major все аккорды должны находиться в правильных функциональных отношениях с новой тоникой.

4.3 Воспроизводимость

НФТ-7. Все скрипты обучения, инференса и оценки должны принимать параметр случайного зерна и устанавливать его одновременно для PyTorch, NumPy и стандартного модуля random.

НФТ-8. При фиксированном случайном зерне и идентичных входных данных запуски обучения должны давать численно воспроизводимые результаты.

НФТ-9. Все эксперименты, упомянутые в итоговом отчёте, должны быть воспроизводимы посредством запуска документированных команд.

4.4 Надёжность работы с данными

НФТ-10. Невалидные или непарсимые аккордовые символы должны вызывать явные ошибки с информативным сообщением. Тихая подмена неизвестных символов на «ближайшие» категорически запрещена: это приводит к молчаливому повреждению обучающего корпуса.

НФТ-11. Файлы из отложенной выборки не должны использоваться на этапах тренировки или валидации. Любой скрипт подготовки данных, при обнаружении файла в data/holdout/, должен направлять его в отдельную holdout-выборку.

4.5 Сопровождаемость

НФТ-12. Все публичные функции в модулях src/ должны иметь аннотации типов и краткие docstrings.

НФТ-13. Логика парсинга, токенизации и MIDI-экспорта должна покрываться модульными тестами с использованием pytest.

НФТ-14. Спецификация формата .chord является контрактом между уровнем человекочитаемых данных и уровнем обучения модели. Любые изменения формата должны сопровождаться обновлением docs/chord_format_spec.md и инкрементом номера версии спецификации.

4.6 Удобство использования

НФТ-15. Каждый CLI-скрипт должен поддерживать флаг --help с информативным описанием параметров.

НФТ-16. Сообщения об ошибках должны содержать достаточно информации для самостоятельного устранения проблемы пользователем: имя файла, номер строки, характер нарушения, ожидаемое значение.

---

5. Критерии приёмки

Проект считается завершённым при выполнении всех нижеперечисленных условий.

5.1 Учебные критерии

ID	Критерий
УК-1	Реализован полный цикл подготовки данных, обучения, инференса и оценки.
УК-2	Имеется как минимум одна обученная модель, прошедшая стадии предобучения и дообучения.
УК-3	Подготовлен итоговый отчёт, оформленный по стандартам ГОСТ для учебных работ.
УК-4	Отчёт содержит количественное сравнение базовой и дообученной моделей.
УК-5	Отчёт содержит качественные примеры сгенерированных периодов.
УК-6	Все эксперименты, упомянутые в отчёте, воспроизводимы по командам, приведённым в README или в самом отчёте.

5.2 Технические критерии

ID	Критерий
ТК-1	Все автоматизированные тесты проходят.
ТК-2	Round-trip эквивалентность парсера-токенизатора подтверждена на всех тестовых фикстурах.
ТК-3	Транспозиция протестирована для мажорных и минорных периодов с разными исходными тональностями.
ТК-4	Модель обучается до сходимости (валидационная потеря выходит на плато или снижается монотонно).
ТК-5	Перплексия дообученной модели на отложенной выборке ниже перплексии базовой модели на той же выборке.
ТК-6	На графиках распределений виден заметный сдвиг от baseline в сторону характеристик собственного корпуса автора.

5.3 Прикладные критерии

ID	Критерий
ПК-1	Автор может сгенерировать гармоническую последовательность по произвольным входным параметрам и воспроизвести её в DAW.
ПК-2	Сгенерированные последовательности отличаются от случайного шума: соблюдается тональная стабильность, аккорды функционально связаны.
ПК-3	На качественном уровне в нескольких из сгенерированных примеров автор слышит элементы собственного стиля.

---

6. Намеренно выведенное за рамки

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

Возможность	Причина выведения
Генерация мелодической линии	Кратно увеличивает сложность задачи; не помещается в срок
Расположение голосов в аккорде (voicing) выше баса	Требует существенно большего датасета; ручная реализация в DAW проще
Ритмический паттерн внутри удержания аккорда	Требует моделирования времени с большим разрешением; не критично для задачи
Дообучение на корпусе японской поп-музыки	Запланировано как отдельный последующий эксперимент
Графический интерфейс	Не добавляет ценности с точки зрения учебных целей; занимает время
Прямая интеграция с REAPER	Обмен через MIDI-файлы достаточен и проще в реализации
Сравнение нескольких архитектур модели	Не помещается в срок; выбрана одна архитектура с обоснованием
Слепой listening-тест с привлечением слушателей	Не помещается в срок; используются качественные примеры
Обработка модуляций внутри одного периода	Решено разрезанием периодов по точке модуляции
Поддержка микротональных аккордов	Не встречается в целевом материале; округление до темперированного эквивалента
Поддержка полиаккордов	Редкое явление в целевом материале; запись через слэш-нотацию или ближайший single chord

---

7. Сценарии использования

7.1 Сценарий У-1. Транскрипция собственной пьесы

Действующее лицо: автор-композитор.

Предусловия: в DAW-проекте имеется готовая пьеса с гармонической структурой, доступной анализу. Установлена и настроена среда разработки.

Основной поток:

1. Автор прослушивает пьесу и определяет границы периодов.
2. Для каждого периода создаёт .chord-файл и заполняет шапку.
3. Транскрибирует гармонию по позициям, фиксируя инверсии и расширения.
4. Запускает валидатор формата для проверки корректности.
5. Экспортирует периоды в MIDI и прослушивает в DAW параллельно с оригиналом.
6. Корректирует транскрипцию в случае расхождений.

Постусловия: в data/raw_user/ появились новые .chord-файлы, прошедшие валидацию.

7.2 Сценарий У-2. Полный цикл обучения

Действующее лицо: автор-композитор.

Предусловия: подготовлен собственный корпус и сконвертирован публичный корпус.

Основной поток:

1. Запуск скрипта подготовки данных для публичного корпуса.
2. Запуск скрипта подготовки данных для собственного корпуса.
3. Запуск скрипта предобучения, ожидание сходимости.
4. Запуск скрипта дообучения с инициализацией из чекпоинта предобучения.
5. Запуск скрипта оценки для сравнения базовой и дообученной моделей.
6. Анализ полученных графиков и метрик.

Постусловия: в checkpoints/ сохранены обученные модели, в reports/ сформированы графики и численные метрики.

7.3 Сценарий У-3. Генерация гармонической идеи

Действующее лицо: автор-композитор в процессе работы над новой пьесой.

Предусловия: имеется обученная модель.

Основной поток:

1. Автор определяет желаемые параметры будущего периода: тональность, функциональную роль, общий характер.
2. Запускает скрипт генерации с этими параметрами.
3. Получает .chord-файл и MIDI-файл результата.
4. Открывает MIDI-файл в DAW и прослушивает.
5. В случае удовлетворительного результата — переносит гармоническую последовательность в свой композиторский проект.
6. В противном случае — повторяет генерацию с другим случайным зерном или другими параметрами сэмплирования.

Постусловия: автор получает гармоническую идею в требуемом стилистическом ключе.

7.4 Сценарий У-4. Продолжение начатой идеи

Действующее лицо: автор-композитор, у которого уже есть начало гармонической последовательности.

Предусловия: имеется обученная модель и сформулированная гармоническая затравка из нескольких аккордов.

Основной поток:

1. Автор формулирует затравку в виде строки аккордовых символов.
2. Запускает скрипт генерации с параметром --prefix.
3. Модель достраивает остаток периода с учётом затравки.
4. Получает MIDI и прослушивает.

Постусловия: автор получает варианты продолжения для своей гармонической идеи.

---

8. История изменений

• 1.1 (2026-05-20) — ФТ-12 обновлён: два скрипта (pretrain.py, train.py) вместо единого универсального CLI.
• 1.0 (2026-05-19) — первоначальная редакция документа.