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