H1K0
75fa07bf6c
Add four Russian-language project documents: - README.md: user-facing guide (install, quick start, data prep, training, evaluation, limitations) - docs/architecture.md v1.0: system architecture, data flow diagrams, module interfaces, 7 architectural decision records, extension points - docs/glossary.md v1.0: musical, ML, and project-specific term definitions - docs/requirements.md v1.0: functional/non-functional requirements, acceptance criteria, four use-case scenarios Update CLAUDE.md with project name etymology (hamori / ハモリ) and rename repo root reference from chord-gen to hamori. Refine chord_format_spec.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
468 lines
34 KiB
Markdown
468 lines
34 KiB
Markdown
# Требования к проекту 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.0, включая:
|
||
|
||
- Парсинг шапки с метаданными.
|
||
- Парсинг тела файла, состоящего из последовательности тактов.
|
||
- Распознавание аккордовых символов по правилам §4 спецификации.
|
||
- Поддержку всех восемнадцати базовых качеств аккордов с альтернативными
|
||
написаниями.
|
||
- Поддержку расширений аккордов (одиночный слот).
|
||
- Поддержку слэш-нотации для инверсий.
|
||
- Распознавание специальных значений (точка для удержания, `NC` для паузы,
|
||
`?` для неизвестного аккорда).
|
||
|
||
**ФТ-2.** Система должна выполнять валидацию `.chord`-файлов:
|
||
|
||
- Проверять корректность шапки (все обязательные поля присутствуют, значения
|
||
входят в допустимые множества).
|
||
- Проверять, что число позиций в каждом такте соответствует тактовому
|
||
размеру и подразделению доли.
|
||
- Поднимать информативные ошибки с указанием имени файла, номера такта и
|
||
позиции при обнаружении нарушений.
|
||
|
||
**ФТ-3.** Система должна выполнять нормализующую транспозицию:
|
||
все мажорные периоды приводятся к тональности C major, минорные — к A minor.
|
||
|
||
**ФТ-4.** Система должна выполнять токенизацию `.chord`-файлов в
|
||
последовательности целочисленных идентификаторов согласно словарю,
|
||
описанному в §5 спецификации формата. Словарь содержит 81 токен.
|
||
|
||
**ФТ-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.** Система должна предоставлять единый скрипт обучения, параметризуемый
|
||
аргументами командной строки, поддерживающий:
|
||
|
||
- Обучение модели с нуля (предобучение).
|
||
- Дообучение существующей модели (fine-tuning) — через параметр инициализации
|
||
весов из указанного чекпоинта.
|
||
- Настройку всех ключевых гиперпараметров через аргументы.
|
||
- Установку случайного зерна для воспроизводимости.
|
||
- Автоматический выбор вычислительного устройства (CPU/GPU) с возможностью
|
||
принудительного задания.
|
||
|
||
**ФТ-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.0** (2026-05-19) — первоначальная редакция документа.
|