# Требования к проекту 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) — первоначальная редакция документа.