hamori/docs/glossary.md

Глоссарий hamori

Версия документа: 1.1 Дата: 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, качество (например, maj7) — в слоте QUAL.

Подразделение доли (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-аккорд)

Аккорд с явно указанным басовым тоном, записываемым через косую черту: <аккорд>/<бас>. Бас может быть любой из 12 нот. Если он входит в состав аккорда — это инверсия: C/E (C major с E в басу, первое обращение). Если не входит — это он-аккорд: F/G (F major с чужим G в басу). Характерный приём японской поп-музыки; создаёт плавное движение баса и характерное напряжение.

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

Соотношение числа долей в такте и их длительности. В формате проекта поддерживаются 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

Алгоритм поиска наиболее вероятной последовательности при генерации: вместо того чтобы выбирать один токен и двигаться дальше, алгоритм удерживает несколько (обычно 3–10) лучших «кандидатных» продолжений одновременно, а в конце возвращает то, у которого наибольшая суммарная вероятность. Даёт более «правильные» последовательности, но монотонные — разнообразие и неожиданные идеи теряются. В проекте не используется именно по этой причине.

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

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

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

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

Cross-entropy loss

Функция потерь, измеряющая качество предсказания следующего токена. Если модель назначила правильному токену высокую вероятность (например, 0.9) — потеря мала; если низкую (0.01) — потеря велика. Оптимизатор двигает веса в сторону уменьшения этой потери. Стандартная функция потерь для задач предсказания следующего элемента последовательности.

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

Архитектура нейросети: несколько одинаковых блоков, уложенных стопкой. Каждый блок содержит механизм self-attention с причинной маской и feedforward-слой (две матрицы с нелинейностью между ними). Весь ввод обрабатывается в одном стеке — без разделения на «кодировщик» и «декодировщик», как в ранних переводческих моделях. GPT — наиболее известный пример. Используется в данном проекте.

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

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

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

Числовое векторное представление дискретного элемента: каждому из 81 токенов словаря сопоставляется вектор из d_model (128–256) вещественных чисел. Эти числа не задаются вручную — они обучаются вместе с остальными весами. Можно думать об эмбеддинге как о «характеристике» токена: похожие по контексту токены оказываются близко друг к другу в пространстве эмбеддингов. Размерность эмбеддинга равна d_model.

Epoch (эпоха)

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

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

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

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

Нормализующее преобразование, которое пересчитывает активации внутри каждого слоя так, чтобы их среднее было около нуля, а дисперсия — около единицы. Без нормализации числа в глубоких сетях склонны расти или убывать экспоненциально («взрываться» или «затухать»), что делает обучение нестабильным. В архитектуре проекта применяется в pre-norm варианте (перед операцией внимания, не после).

Learning rate

Скорость обучения — насколько большой шаг делает оптимизатор при каждом обновлении весов. Большое значение — обучение быстрее, но легко «перескочить» мимо оптимума. Малое — стабильно, но медленно. В проекте используется значение около 1e-4 на этапе предобучения и 1e-5 на этапе дообучения: десятикратная разница принципиальна для предотвращения катастрофического забывания.

Logits

Выход последнего слоя модели до применения softmax — 81 ненормализованное вещественное число (по одному на каждый токен словаря), отражающих «предпочтения» модели. Большой логит означает, что модель считает токен более вероятным продолжением. Softmax преобразует их в нормализованное распределение вероятностей с суммой 1.

Multi-head attention

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

Nucleus sampling (top-p sampling)

Стратегия сэмплирования: на каждом шаге берётся минимальное подмножество токенов, чьи вероятности в сумме составляют не менее порога p (например, 0.9), — и следующий токен выбирается случайно из этого подмножества. Это позволяет избежать двух крайностей: «жадный» выбор (всегда берём самый вероятный токен) даёт монотонные результаты, а полностью случайный — бессвязные. Применяется в проекте с p = 0.9 по умолчанию.

Padding

Дополнение коротких последовательностей до фиксированной длины специальным токеном <PAD>. При батчевой обработке все последовательности в батче должны быть одной длины; паддинг — технический приём для выравнивания. Паддинговые позиции игнорируются в функции потерь через параметр ignore_index.

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

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

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

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

Pre-norm vs post-norm

Два варианта размещения LayerNorm внутри блока трансформера. В pre-norm нормализация идёт до операции (attention или feedforward), и результат добавляется к исходному вектору через residual connection (прямое сложение): x + Sublayer(LN(x)). В post-norm нормализация идёт после сложения: LN(x + Sublayer(x)). Pre-norm обычно более стабилен при обучении глубоких моделей. В проекте используется pre-norm.

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

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

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

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

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

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

Self-attention

Механизм, позволяющий каждому токену «посмотреть» на все остальные токены в последовательности и взять от них взвешенную сумму. Для каждой пары позиций вычисляется «вес внимания» — насколько одна позиция важна для другой. Веса определяются скалярным произведением обучаемых проекций: каждая позиция имеет вектор «вопроса» (query) и «ключа» (key), а суммируются «значения» (value). Благодаря этому токен аккорда может «знать» о контексте предыдущего аккорда или о своём положении внутри такта.

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

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

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

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

Токен

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

Токенизация

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

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

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

Warmup (разогрев)

Начальная фаза обучения, в течение которой learning rate линейно возрастает от нуля до целевого значения. На самых первых шагах веса ещё не настроены, и большой шаг оптимизатора может «сломать» начальную конфигурацию — привести к нестабильным потерям. Постепенный разогрев решает эту проблему. В проекте warmup составляет 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.1 (2026-05-19) — исправлены ошибки: определение слэш-аккорда (бас может входить в состав аккорда), термин для #11 (ундецима, не кварта), определение logits (ненормализованные оценки), значение learning rate для предобучения, паддинг (убрана непроверенная привязка к индексу). Все термины машинного обучения переработаны для читателя без опыта в ML: добавлены аналогии, конкретные примеры и пояснения для понятий residual connection, causal mask, warmup и positional embedding.
• 1.0 (2026-05-19) — первоначальная редакция документа.