hamori/docs/glossary.md

# Глоссарий hamori

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

Документ содержит определения терминов, используемых в проекте _hamori_,
разделённые на три тематические группы: музыкальные термины, термины
машинного обучения и проектные термины. Внутри каждой группы записи
упорядочены по алфавиту.

---

## 1. Музыкальные термины

### Аккорд

Гармоническая единица — одновременное звучание трёх и более нот. В контексте
проекта аккорд представляется в текстовой нотации (например, `Cmaj7`, `Am`,
`F/G`) и характеризуется четырьмя признаками: корневой тон, качество,
расширение, бас.

### Аккордовая последовательность (прогрессия)

Последовательность аккордов, сопровождающая мелодию или существующая
самостоятельно. Является основным объектом генерации в данном проекте.

### Альтерация

Хроматическое изменение ступени аккорда — повышение или понижение её на
полутон. В рамках формата проекта альтерации записываются как расширения
вида `b9`, `#9`, `#11`, `b13`.

### Анакруза (затакт)

Несколько нот или один аккорд, предшествующих первой сильной доле такта.
В формате проекта затакт записывается через специальное значение `NC`
(no chord) на пустых позициях первого такта.

### Бас

Самая нижняя нота аккорда. Может совпадать с корневым тоном (основной
позиции) или отличаться от него (в инверсиях и слэш-аккордах). В формате
проекта бас выделен в отдельный слот токенизации.

### Гармоническая функция

Роль аккорда в тональной системе: тоника (T), субдоминанта (S), доминанта
(D) и их побочные ступени. Хотя в формате проекта аккорды записываются
абсолютными именами, а не функциональными цифрами, нормализующая
транспозиция в C major / A minor делает функциональные роли явно читаемыми:
после транспозиции `C` всегда тоника мажорной пьесы, `A` — тоника
минорной.

### Гармонический период

Замкнутая гармоническая фраза длиной обычно 4, 8 или 16 тактов, имеющая
ясное начало и завершение (возврат к тонике или полукаденция). Является
**единицей обработки и генерации** в проекте.

### Голосоведение

Способ соединения нот в соседних аккордах: плавное движение голосов,
запрет параллельных квинт и октав, разрешение тяготеющих ступеней.
В текущей версии проекта голосоведение **не моделируется** —
сгенерированные аккорды передаются как абстрактные гармонические единицы,
а конкретное расположение голосов оставлено на ручную работу композитора
в DAW.

### Доминанта

Аккорд пятой ступени лада. Содержит вводный тон и создаёт сильное
тяготение к тонике. Обычная запись в виде доминантового септаккорда — `G7`
в C major, `E7` в A minor (с альтерированной третьей ступенью минора).

### Инверсия (обращение)

Аккорд, в котором в качестве баса выступает не корневой тон, а одна из
других нот аккорда (терция, квинта, септима). В формате проекта инверсии
записываются через слэш-нотацию: `C/E` (C мажор с басом E, первое
обращение), `C/G` (с басом G, второе обращение).

### Каденция

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

### Качество (тип) аккорда

Интервальная структура аккорда независимо от его корневого тона. Базовые
качества, поддерживаемые форматом проекта: мажорное и минорное трезвучия,
уменьшённое и увеличенное трезвучия, sus2 и sus4, мажорный, минорный,
доминантовый, полууменьшённый и уменьшённый септаккорды, минорно-мажорный
септаккорд, доминанта на sus4, увеличенный септаккорд, мажорный и минорный
аккорды с секстой, аккорды с добавленной ноной. Всего 18 качеств.

### Корневой тон

Основная нота, на которой строится аккорд. Не обязательно совпадает с
басом (см. _Инверсия_). В формате проекта корневой тон выделен в отдельный
слот токенизации.

### Лад

Структурно-функциональная организация звуков вокруг центра (тоники).
В проекте моделируются два лада: натуральный мажор и натуральный минор
(включая гармонический и мелодический миноры как разновидности — отдельно
не различаются). Лад фиксируется отдельным метатокеном `MODE_major` или
`MODE_minor`.

### Лид-шит-нотация

Способ записи музыки, при котором над тактами выписывается мелодия, а
гармония указывается аккордовыми символами без точной нотации каждой ноты
аккорда. Формат `.chord` в проекте — упрощённый аналог лид-шита,
содержащий только гармоническую часть.

### Минор гармонический

Разновидность минорного лада с повышенной седьмой ступенью, создающая
выраженную доминанту. Внутренние альтерации (V становится мажорным,
появляется уменьшённый VII7) трактуются в формате проекта как обычные
аккорды.

### Модуляция

Смена тональности в произведении. В рамках текущей версии формата
поддерживается только модуляция **между периодами** (каждый период
хранится в своей тональности). Модуляция **внутри периода** обрабатывается
через разрезание периода на два — до и после момента модуляции.

### Нонаккорд

Аккорд, расширенный девятой ступенью от корня. В формате проекта —
`Cmaj9` (мажорный септаккорд + натуральная нона), `C9` (доминантовый
септаккорд + нона), `Cm9` (минорный септаккорд + нона), `Cmaj7#11` (с
повышенной квартой), и другие. Записывается как качество + расширение в
слоте `EXT`.

### Подразделение доли (subdivision)

Параметр формата, определяющий, на сколько временных позиций делится один
такт. При `subdivision: 4` в размере 4/4 каждый такт делится на четыре
четверти (четыре позиции). При `subdivision: 8` — на восемь восьмых
(восемь позиций). Выбирается в зависимости от того, как часто меняются
аккорды в конкретной пьесе.

### Полиаккорд

Одновременное звучание двух функционально различных аккордов в разных
регистрах (например, мажорное трезвучие D-F♯-A над мажорным трезвучием
C-E-G). В текущей версии формата полиаккорды **не поддерживаются**.
Близкие по звучанию структуры записываются через слэш-нотацию (`C/D`,
`F/G`) или ближайший один аккорд с расширениями.

### Расширение аккорда

Дополнительный интервал, надстраивающийся над септаккордом: нона (9),
ундецима (11), терцдецима (13), с возможными альтерациями (`b9`, `#9`,
`#11`, `b13`). В формате проекта расширение записывается одним токеном
в отдельном слоте `EXT`. Поддерживается ровно один слот расширения на
аккорд.

### Royal Road progression

Характерная гармоническая прогрессия японской популярной музыки:
IV — V — iii — vi (например, в C major: `F → G → Em → Am`). Прогрессия
ассоциируется с мелодичной, ностальгической эмоциональной окраской и
встречается в значительной части анисонга и J-Pop в широком смысле.

### Sus-аккорды

Аккорды с задержанной квартой (sus4) или секундой (sus2), заменяющей
терцию. Лишены терцового тона, не определены как мажорные или минорные.
В формате проекта — `Csus4`, `Csus2`, а также `C7sus4` (доминантовый
септаккорд на sus4, часто встречается перед разрешением в обычный
доминантовый аккорд).

### Слэш-аккорд (slash chord, on-аккорд)

Аккорд с явно указанным басом, отличным от любой ноты собственного состава.
Записывается как `<аккорд>/<бас>`. Характерный приём японской поп-музыки:
`F/G`, `C/D`, `Em7/A` — обеспечивают плавное движение баса и характерное
напряжение.

### Тактовый размер

Соотношение числа долей в такте и их длительности. В формате проекта
поддерживаются `4/4`, `3/4`, `6/8`, `2/4`, `12/8`. Большинство периодов
ожидается в размере `4/4`.

### Тональность

Конкретное положение лада на звукоряде, определяемое тоникой и видом
лада (`F# major`, `B♭ minor`, `C major`). В формате `.chord` указывается
в шапке файла полем `key`. Перед обучением модели все периоды
нормализуются в C major / A minor; в словарь модели тональность не
входит.

### Тонизация (отклонение)

Кратковременный заход в другую тональность через её собственную доминанту
без полноценной модуляции. Например, в C major последовательность
`Dm — A7 — Dm` содержит тонизацию D minor. В формате проекта тонизации
записываются обычными аккордовыми символами и не требуют специальной
разметки.

### Тоника

Главный устойчивый тон лада, опора. В формате после нормализующей
транспозиции тоника — `C` для мажорных периодов и `A` для минорных.

### Функциональная роль периода

Роль данного периода в форме исходной пьесы: куплет, припев, пре-припев,
бридж, вступление, проигрыш, концовка. В формате `.chord` указывается в
шапке поле `function`. Передаётся в модель как метатокен `FUNC_x` и может
использоваться как conditioning на инференсе.

---

## 2. Термины машинного обучения

### Авторегрессионная модель

Модель, генерирующая последовательность по одному элементу за раз, причём
каждый следующий элемент условен на всех предыдущих. Декодер-only
трансформер, используемый в проекте, — пример авторегрессионной модели.

### Beam search

Алгоритм поиска наиболее вероятной последовательности при генерации:
вместо сэмплирования удерживается несколько лучших кандидатов на каждом
шаге, выбирается итоговая последовательность с максимальной совместной
вероятностью. В проекте **не используется**, поскольку для генеративных
творческих задач даёт монотонные результаты.

### Catastrophic forgetting (катастрофическое забывание)

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

### Causal mask (причинная маска)

Маска внимания в декодер-only трансформере, не позволяющая каждой позиции
«видеть» будущие позиции в последовательности. Обеспечивает корректное
обучение задачи предсказания следующего токена.

### Cross-entropy loss

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

### Декодер-only трансформер

Архитектура нейросети, состоящая из стека одинаковых блоков, каждый из
которых содержит self-attention с причинной маской и feedforward-слой.
В отличие от encoder-decoder архитектуры, у декодер-only нет отдельного
блока для кодирования входа — всё обрабатывается одной башней. GPT-семейство
языковых моделей — наиболее известный пример. Используется в данном проекте.

### Дообучение (fine-tuning)

Адаптация модели, ранее обученной на большом корпусе, к конкретной задаче
или домену через дополнительное обучение на меньшем целевом наборе данных.
В проекте после предобучения на McGill Billboard модель дообучается на
собственном корпусе автора.

### Embedding (эмбеддинг)

Числовое векторное представление дискретного элемента (токена). В трансформере
эмбеддинги токенов и позиций суммируются и подаются в первый блок. Размерность
эмбеддинга равна размерности модели (`d_model`).

### Epoch (эпоха)

Один полный проход обучающего цикла по всем элементам тренировочной выборки.
В проекте предобучение длится до 50 эпох с ранней остановкой,
дообучение — до 15.

### Holdout (отложенная выборка)

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

### LayerNorm (нормализация слоя)

Нормализующее преобразование, стабилизирующее распределение активаций
внутри сети. В архитектуре проекта применяется в pre-norm варианте
(перед residual connection, не после).

### Learning rate

Скорость обучения, коэффициент шага оптимизатора. В проекте используется
значение `3e-4` на этапе предобучения и `1e-5` на этапе дообучения —
двухпорядковая разница принципиальна для предотвращения катастрофического
забывания.

### Logits

Выход модели перед применением softmax — нормализованные числовые
оценки, отражающие предпочтения модели по каждому возможному следующему
токену. Используются в функции потерь и в процессе сэмплирования.

### Multi-head attention

Механизм self-attention, в котором операция внимания выполняется
параллельно несколькими «головами», каждая со своими обучаемыми
проекциями. Результаты голов конкатенируются. В проекте используется
6 голов.

### Nucleus sampling (top-p sampling)

Стратегия сэмплирования, при которой на каждом шаге сохраняется
минимальный по числу элементов набор кандидатов с накопленной
вероятностью не менее заданного порога `p`, после чего из этого набора
происходит сэмплирование. Применяется в проекте с `p = 0.9` по умолчанию.

### Padding

Дополнение коротких последовательностей до фиксированной длины специальным
токеном. В проекте — токен `<PAD>` (индекс 2 в словаре), игнорируемый в
функции потерь через параметр `ignore_index`.

### Perplexity (перплексия)

Метрика качества языковой модели, рассчитываемая как экспонента средней
кросс-энтропии. Содержательно — «эффективное число равновероятных
альтернатив», между которыми модель колеблется на каждом шаге. Чем
меньше, тем лучше. В проекте используется как основная численная метрика
сравнения базовой и дообученной моделей.

### Positional embedding (позиционный эмбеддинг)

Векторное представление позиции токена в последовательности, добавляемое
к токеновому эмбеддингу. Позволяет модели учитывать порядок элементов
(сам по себе self-attention перестановочно-инвариантен). В проекте
используются обучаемые позиционные эмбеддинги.

### Pre-norm vs post-norm

Два варианта размещения LayerNorm в блоке трансформера: до residual
connection (pre-norm) или после (post-norm). Pre-norm обычно более
стабилен при обучении. В проекте используется pre-norm.

### Предобучение (pre-training)

Этап обучения модели на большом и общем по содержанию корпусе данных,
после которого следует адаптация модели к более узкой задаче или домену.
В проекте предобучение выполняется на McGill Billboard Project.

### Ранняя остановка (early stopping)

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

### Round-trip эквивалентность

Свойство пары взаимно обратных преобразований: при последовательном
применении прямого и обратного преобразования исходное представление
восстанавливается с точностью до канонической нормализации. В проекте
требуется для пары «парсинг + токенизация / детокенизация + сериализация»
и проверяется автоматизированными тестами.

### Self-attention

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

### Softmax с температурой

Модификация softmax, в которой логиты предварительно делятся на
параметр температуры. При температуре больше 1 распределение становится
более равномерным (генерация разнообразнее), при меньше 1 — более
концентрированным (генерация консервативнее). По умолчанию в проекте — 1.0.

### Tied weights (связанные веса)

Приём, при котором веса входного эмбеддинга и финальной проекции на
словарь совпадают (одна и та же матрица). Снижает число параметров и
часто улучшает обобщающую способность. Применяется в проекте.

### Токен

Элементарная единица обработки модели — целочисленный идентификатор
из конечного словаря. В данном проекте словарь содержит 81 токен,
обозначающих служебные значения, метаданные периода и компоненты
аккордов.

### Токенизация

Преобразование исходного представления данных в последовательность
токенов. В проекте — преобразование `.chord`-файла в последовательность
целочисленных идентификаторов.

### Тренировочная и валидационная выборки (train / val)

Разбиение обучающих данных: тренировочная выборка используется для
обновления весов модели, валидационная — для контроля переобучения и
выбора лучшего чекпоинта. В проекте используется разбиение 90/10. Кроме
того, отдельно выделяется отложенная выборка (см. _Holdout_).

### Warmup (разогрев)

Начальная фаза обучения, в течение которой learning rate линейно растёт
от нуля до целевого значения. Стабилизирует обучение трансформеров на
первых шагах. В проекте — 5% от общего числа шагов.

### Чекпоинт

Сохранённое на диск состояние модели (веса, конфигурация, опционально
состояние оптимизатора), пригодное для возобновления обучения или для
инференса. В проекте сохраняются чекпоинты `pretrained.pt` и
`finetuned.pt`.

---

## 3. Проектные термины

### `.chord`-файл

Текстовый файл в формате, описанном в `docs/chord_format_spec.md`. Содержит
шапку с метаданными периода и тело — последовательность тактов с
аккордовыми символами. Один файл = один гармонический период.

### hamori

Название проекта. Транслитерация японского слова ハモリ, означающего
вокальную гармонизацию — практику добавления второго или третьего голоса
к основной мелодической линии в певческом ансамбле. Само слово образовано
от глагола ハモる (_hamoru_) — «гармонизировать», в свою очередь
заимствованного из английского _harmony_. Название отражает основную
функциональную идею проекта: модель не пишет музыку с нуля, а предлагает
гармонические идеи в дополнение к замыслу композитора.

### BAR (токен)

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

### `<BOS>`, `<EOS>`, `<PAD>`, `<UNK>`

Служебные токены словаря: начало последовательности, конец последовательности,
паддинг и неизвестный токен соответственно.

### `ChordTokens`

Dataclass, представляющий разобранный аккорд: четыре строковых поля —
`root`, `quality`, `extension`, `bass`. Является промежуточным
представлением между текстовым аккордовым символом и токенами модели.

### `ChordPeriod`

Dataclass, представляющий полностью разобранный гармонический период:
метаданные шапки и список тактов, каждый из которых — список позиций.
Является промежуточным представлением между `.chord`-файлом и токенами.

### `ChordFormatError` / `ChordParseError`

Типы исключений, поднимаемые при некорректном формате файла или
некорректном аккордовом символе соответственно. Содержат информативные
сообщения с указанием места ошибки.

### EXT (расширение)

Один из четырёх слотов токенизации аккорда. Кодирует расширение аккорда:
`EXT_none` (расширения нет), `EXT_9`, `EXT_b9`, `EXT_#9`, `EXT_11`,
`EXT_#11`, `EXT_13`, `EXT_b13`. Восемь возможных значений.

### FUNC (функциональная роль)

Метатокен периода, указывающий на функциональную роль в исходной пьесе.
Возможные значения: `FUNC_verse`, `FUNC_chorus`, `FUNC_prechorus`,
`FUNC_bridge`, `FUNC_intro`, `FUNC_outro`, `FUNC_interlude`, `FUNC_other`,
`FUNC_unspecified`.

### HOLD (токен)

Служебный токен, означающий, что текущая позиция продолжает звучание
предыдущего аккорда. Использование `HOLD` существенно сокращает длину
последовательности по сравнению с повторением всех четырёх токенов
аккорда.

### MODE (лад)

Метатокен периода, указывающий на лад. Только два значения: `MODE_major`
для мажора и `MODE_minor` для минора. После нормализующей транспозиции
этот токен — единственный носитель информации о ладе в обучающих данных.

### NC (No Chord)

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

### Нормализующая транспозиция

Преобразование, переводящее любой период в каноническую тональность:
мажорные периоды — в C major, минорные — в A minor. Применяется перед
токенизацией. На инференсе обратное преобразование возвращает результат
в требуемую пользователем тональность.

### Период (см. также _Гармонический период_ в музыкальной части)

Единица обработки и генерации в проекте. Замкнутая гармоническая фраза
4–16 тактов, представленная одним `.chord`-файлом.

### QUAL (качество)

Один из четырёх слотов токенизации аккорда. Кодирует качество аккорда:
`QUAL_maj`, `QUAL_m`, `QUAL_dim`, `QUAL_aug`, `QUAL_sus2`, `QUAL_sus4`,
`QUAL_maj7`, `QUAL_m7`, `QUAL_7`, `QUAL_m7b5`, `QUAL_dim7`, `QUAL_mM7`,
`QUAL_7sus4`, `QUAL_aug7`, `QUAL_6`, `QUAL_m6`, `QUAL_add9`,
`QUAL_m_add9`. Восемнадцать возможных значений.

### ROOT (корень)

Один из четырёх слотов токенизации аккорда. Кодирует корневой тон:
`ROOT_C`, `ROOT_C#`, ..., `ROOT_B`. Двенадцать возможных значений.

### BASS (бас)

Один из четырёх слотов токенизации аккорда. Кодирует басовый тон:
`BASS_root` (бас совпадает с корнем) или конкретная нота
(`BASS_C`, `BASS_C#`, ..., `BASS_B`). Тринадцать возможных значений.

### Стилевой тег (STYLE)

Метатокен периода, указывающий на стилистическую принадлежность.
Возможные значения: `STYLE_user` (собственный корпус автора), `STYLE_jpop`
(японская поп-музыка), `STYLE_classical` (классическая музыка),
`STYLE_jazz` (джазовая музыка), `STYLE_other` (прочее, включая публичные
корпуса вроде McGill Billboard). Может использоваться как conditioning
на инференсе.

### SUB (подразделение доли)

Метатокен периода, указывающий, как делится такт на временные позиции.
Возможные значения: `SUB_4` (по четвертям) и `SUB_8` (по восьмым).

### TIME (тактовый размер)

Метатокен периода, указывающий тактовый размер. Возможные значения:
`TIME_4/4`, `TIME_3/4`, `TIME_6/8`, `TIME_2/4`, `TIME_12/8`.

### Шапка файла

Часть `.chord`-файла, содержащая метаданные периода. Строки шапки
начинаются с символа `#` и имеют вид `# key: value`. Шапка обязательно
содержит поля `title`, `key`, `time`, `subdivision`, `style` и
опционально — `function`.

---

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

- **1.0** (2026-05-19) — первоначальная редакция документа.