tech/hamori
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: add README, architecture, glossary, requirements; update CLAUDE.md

Browse Source 
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>
This commit is contained in:
Masahiko AMANO
2026-05-19 11:00:21 +03:00
parent 9929209bcf
commit 75fa07bf6c
6 changed files with 2312 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/requirements.md
+467
View File
@@ -0,0 +1,467 @@
# Требования к проекту 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) — первоначальная редакция документа.