# Глоссарий 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 Дополнение коротких последовательностей до фиксированной длины специальным токеном ``. При батчевой обработке все последовательности в батче должны быть одной длины; паддинг — технический приём для выравнивания. Паддинговые позиции игнорируются в функции потерь через параметр `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 (токен) Служебный токен, отмечающий конец такта в токенизированной последовательности. Помогает модели усваивать ритмическую сетку периода. ### ``, ``, ``, `` Служебные токены словаря: начало последовательности, конец последовательности, паддинг и неизвестный токен соответственно. ### `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) — первоначальная редакция документа.