hamori/docs/chord_format_spec.md

Спецификация формата данных

Проект: генератор аккордовых последовательностей

Версия: 1.0 Дата: 2026-05-03

---

1. Архитектура формата

Формат двухуровневый:

• Источник — то, что ты пишешь руками. Близок к лид-шиту, человекочитаем, легко правится.
• Токены — то, что видит модель. Факторизованное представление с маленьким словарём.

Между уровнями стоит парсер. Источник → токены — детерминированное преобразование.

---

2. Исходный формат

2.1 Структура файла

Один файл — одна пьеса. Расширение .chord. Кодировка UTF-8.

# title: Sea Glass
# key: D_major
# time: 4/4
# subdivision: 4
# style: user
# tempo_bucket: medium

[intro]
| D     . . . | A/C#  . . . | Bm7  . . . | A     . . . |

[verse]
| D     . . . | F#m7  . . . | G     . . . | A     . . . |
| Bm7   . . . | F#m7  . . . | G     . . . | Asus4 . A . |

[chorus]
| Gmaj7 . . . | A     . . . | F#m7  . . . | Bm7   . . . |
| Gmaj7 . . . | A     . . . | D     . . . | D     . . . |

2.2 Шапка (метаданные)

Любая строка, начинающаяся с #, — метаданные. Формат: # key: value.

Поле	Обязательно	Допустимые значения	Пример
title	да	свободная строка	Sea Glass
key	да	<note>_major или <note>_minor, где <note> — C, C#, D, D#, E, F, F#, G, G#, A, A#, B	D_major
time	да	4/4, 3/4, 6/8, 2/4, 12/8	4/4
subdivision	да	4 (четвертные) или 8 (восьмые)	4
style	да	user, jpop, classical, jazz, other	user
tempo_bucket	нет	slow, medium, fast, very_fast	medium

subdivision определяет, сколько позиций в одном такте. В 4/4 при subdivision: 4 — 4 позиции на такт; при subdivision: 8 — 8 позиций.

2.3 Структурные теги секций

В квадратных скобках на отдельной строке. Действуют до следующего тега.

Тег	Назначение
[intro]	вступление
[verse]	куплет
[prechorus]	предприпев
[chorus]	припев
[bridge]	бридж
[interlude]	проигрыш
[solo]	соло
[outro]	концовка

2.4 Записи аккордов

Внутри секции — последовательность тактов. Каждый такт обрамлён |.

Внутри такта — subdivision позиций, разделённых пробелами. На каждой позиции либо аккордовый символ (новый аккорд начинается здесь), либо . (удержать предыдущий аккорд), либо NC (no chord — пауза/тишина в гармонии).

| D . . . | A/C# . . . |    ← такт 1: D на 4 четверти; такт 2: A/C# на 4 четверти
| Em7 . D . | A . . . |     ← такт 3: Em7 на 2 четверти, D на 2 четверти
| NC . . . | D . . . |      ← такт 4: пауза; такт 5: D

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

2.5 Комментарии

Строки, начинающиеся с //, парсер игнорирует. Можно использовать для пометок.

// здесь модулируем в параллельный минор
[bridge]
| Bm . . . | F#m . . . |

---

3. Аккордовая нотация

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

Один из 12 классов высоты, через диез: C, C#, D, D#, E, F, F#, G, G#, A, A#, B.

Бемольная запись (Db, Eb, Gb, Ab, Bb) допускается на входе и парсер сам приведёт к диезной форме. Энгармоническое написание для модели не значимо.

3.2 Базовые качества (18)

Символ	Название	Состав от корня
maj или ничего	мажорное трезвучие	1, 3, 5
m или min	минорное трезвучие	1, b3, 5
dim или °	уменьшённое трезвучие	1, b3, b5
aug или +	увеличенное трезвучие	1, 3, #5
sus2	sus2	1, 2, 5
sus4	sus4	1, 4, 5
maj7 или M7	большой мажорный септаккорд	1, 3, 5, 7
m7	минорный септаккорд	1, b3, 5, b7
7	доминантовый септаккорд	1, 3, 5, b7
m7b5 или ø	полууменьшённый	1, b3, b5, b7
dim7 или °7	уменьшённый септ	1, b3, b5, bb7
mM7 или m(maj7)	минорно-мажорный септ	1, b3, 5, 7
7sus4	доминанта на сус4	1, 4, 5, b7
aug7 или 7#5	увеличенный септ	1, 3, #5, b7
6	мажорный с секстой	1, 3, 5, 6
m6	минорный с секстой	1, b3, 5, 6
add9	мажор с добавленной ноной	1, 3, 5, 9
m(add9)	минор с добавленной ноной	1, b3, 5, 9

Запись «без качества» (просто C) автоматически = Cmaj.

3.3 Расширения (опционально)

Один опциональный слот после качества. Поддерживаются:

Символ	Значение
9, b9, #9	нона (натуральная, пониженная, повышенная)
11, #11	ундецима
13, b13	терцдецима

Примеры:

• Cmaj9 = Cmaj7 + расширение 9
• C7b9 = C7 + расширение b9
• Fmaj7#11 = Fmaj7 + расширение #11 (лидийский)
• Dm9 = Dm7 + расширение 9

Условные сокращения, которые парсер расшифровывает:

• 9 (например, C9) = 7 + расширение 9 (доминантовая нона)
• maj9 = maj7 + расширение 9
• m9 = m7 + расширение 9
• 13 = 7 + расширение 13
• m11 = m7 + расширение 11

Если хочется указать сразу несколько расширений (например, альтерированный доминант C7#9b13) — модель использует только первое расширение в записи. Это сознательное упрощение, чтобы не раздувать комбинаторику. На практике для J-Pop и поп-музыки этого хватает; для джазовых случаев можно записать как ближайший эквивалент.

3.4 Бас и слэш-аккорды

Для инверсий и слэш-аккордов — стандартный формат <chord>/<bass>:

F/A     ← F с басом A (первое обращение)
G/B     ← G с басом B
F/G     ← F с басом G (характерный «on-аккорд» из J-Pop)
Em7/G   ← Em7 с басом G

Бас может быть как любой из 12 нот, так и любой ступенью аккорда. Парсер не проверяет, входит ли бас в состав аккорда — это ответственность транскрибера.

Если слэш-нотация не указана, считается, что бас совпадает с корнем (BASS = root).

3.5 Специальные значения

Запись	Значение
.	удержать предыдущий аккорд на этой позиции
NC	нет аккорда (пауза в гармонии)
?	unknown — для случаев, когда не уверен в транскрипции; парсер заменит на <UNK>

---

4. Внутреннее токенизированное представление

4.1 Словарь (≈100 токенов)

Служебные (4): <BOS>, <EOS>, <PAD>, <UNK>

Метаданные (всегда в начале последовательности, после <BOS>):

• KEY_<note>_<mode> — 24 токена (12 нот × major/minor)
• TIME_<n>/<m> — 5 токенов: TIME_4/4, TIME_3/4, TIME_6/8, TIME_2/4, TIME_12/8
• STYLE_<x> — 5 токенов: STYLE_user, STYLE_jpop, STYLE_classical, STYLE_jazz, STYLE_other
• TEMPO_<x> — 4 токена: TEMPO_slow, TEMPO_medium, TEMPO_fast, TEMPO_very_fast
• SUB_<n> — 2 токена: SUB_4, SUB_8

Структурные:

• SEC_<x> — 8 токенов: SEC_intro, SEC_verse, SEC_prechorus, SEC_chorus, SEC_bridge, SEC_interlude, SEC_solo, SEC_outro
• BAR — конец такта

Аккордовые (4 слота на каждый аккорд):

• ROOT_<note> — 12 токенов
• QUAL_<x> — 18 токенов (см. §3.2)
• EXT_<x> — 8 токенов: EXT_none, EXT_9, EXT_b9, EXT_#9, EXT_11, EXT_#11, EXT_13, EXT_b13
• BASS_<x> — 13 токенов: BASS_root плюс 12 нот

Временные/специальные:

• HOLD — позиция продолжает предыдущий аккорд
• NC — пауза в гармонии

Итого: ≈100 токенов.

4.2 Структура последовательности

<BOS>
KEY_<x>  TIME_<x>  SUB_<x>  STYLE_<x>  [TEMPO_<x>]
SEC_<x>
ROOT_<x>  QUAL_<x>  EXT_<x>  BASS_<x>   ← новый аккорд = ровно 4 токена
HOLD                                     ← удержание = 1 токен
HOLD
HOLD
BAR
ROOT_<x>  QUAL_<x>  EXT_<x>  BASS_<x>
HOLD
ROOT_<x>  QUAL_<x>  EXT_<x>  BASS_<x>
HOLD
BAR
SEC_<x>
...
<EOS>

4.3 Правила токенизации (источник → токены)

1. Прочитать шапку → выпустить <BOS> и токены метаданных.
2. Каждая [section] строка → SEC_<x>.
3. Для каждой позиции внутри такта:
   • Если аккорд: разобрать на (root, quality, extension, bass). Выпустить 4 токена в этом порядке.
   • Если .: выпустить HOLD.
   • Если NC: выпустить NC.
   • Если ?: выпустить <UNK>.
4. После последней позиции такта → BAR.
5. В конце пьесы → <EOS>.

4.4 Инвариант длины

При subdivision: 4 каждый такт даёт переменное число токенов (от 5 до 17): один BAR + от 4 (один аккорд × 4 поля) до 16 (четыре аккорда × 4 поля), плюс HOLD-ы. В среднем для поп-музыки получится 6–10 токенов на такт.

Типичная пьеса (~80 тактов) → 600–800 токенов. Это комфортно укладывается в стандартное контекстное окно 1024–2048.

---

5. Полный пример

5.1 Источник

# title: Example Song
# key: C_major
# time: 4/4
# subdivision: 4
# style: user
# tempo_bucket: medium

[verse]
| Cmaj7 . . . | Am7 . . . | Dm7 . G7 . | Cmaj7 . . . |

[chorus]
| F . . . | F/G . G . | Em7 . Am7 . | Dm7 . G7sus4 G7 |

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

<BOS>  KEY_C_major  TIME_4/4  SUB_4  STYLE_user  TEMPO_medium

SEC_verse

ROOT_C  QUAL_maj7  EXT_none  BASS_root
HOLD  HOLD  HOLD
BAR

ROOT_A  QUAL_min7  EXT_none  BASS_root
HOLD  HOLD  HOLD
BAR

ROOT_D  QUAL_min7  EXT_none  BASS_root
HOLD
ROOT_G  QUAL_7  EXT_none  BASS_root
HOLD
BAR

ROOT_C  QUAL_maj7  EXT_none  BASS_root
HOLD  HOLD  HOLD
BAR

SEC_chorus

ROOT_F  QUAL_maj  EXT_none  BASS_root
HOLD  HOLD  HOLD
BAR

ROOT_F  QUAL_maj  EXT_none  BASS_G
HOLD
ROOT_G  QUAL_maj  EXT_none  BASS_root
HOLD
BAR

ROOT_E  QUAL_min7  EXT_none  BASS_root
HOLD
ROOT_A  QUAL_min7  EXT_none  BASS_root
HOLD
BAR

ROOT_D  QUAL_min7  EXT_none  BASS_root
HOLD
ROOT_G  QUAL_7sus4  EXT_none  BASS_root
ROOT_G  QUAL_7  EXT_none  BASS_root
BAR

<EOS>

(В реальности — без переносов строк и пустых строк, всё идёт одним потоком; здесь форматирование только для читаемости.)

---

6. Краевые случаи и соглашения

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

Записывается как первый «обычный» такт, но с NC на пустых позициях:

| NC . . D | G . . . |

6.2 Смена тональности

Если внутри пьесы происходит модуляция, можно ввести inline-тег [modulate: F_major]. На уровне токенов это выпустит KEY_F_major посреди последовательности. Для первой версии этим лучше не пользоваться — модель проще учить на тонально стабильных пьесах. Если в твоих работах часто бывают модуляции, расскажи отдельно — обсудим, как разрезать пьесу на тонально-однородные сегменты.

6.3 Смена тактового размера

Аналогично — inline [time: 3/4]. Тоже лучше избегать в первой версии.

6.4 Полиаккорды

Запись D/C (треугольник вверху, квадрат внизу) не поддерживается как полиаккорд, только как inverse/слэш. В подавляющем большинстве случаев в поп-музыке слэш-нотации достаточно. Истинные полиаккорды редки и для проекта не критичны.

6.5 Аккорды вне 12-ступенной системы

Не поддерживаются. Если в материале есть микротональные элементы — округлять до ближайшего темперированного аккорда или отмечать как ?.

6.6 Pickup notes / fills

Гармонические заполнения и проходящие аккорды записываются обычным образом, на сетке. Если они короче subdivision (например, проходящий восьмой аккорд при subdivision: 4) — либо переключить subdivision на 8 для этой пьесы, либо округлить.

6.7 Имена файлов

Рекомендованный формат: YYYY_NN_short-title.chord, где YYYY — год создания пьесы, NN — её номер в этом году. Это упростит хронологическую сортировку датасета и поможет, если потом захочется анализировать эволюцию стиля во времени.

6.8 Что НЕ кодируется

Сознательно вне формата:

• voicing (расположение голосов внутри аккорда сверх баса);
• ритмический паттерн внутри удержания (пунктир, синкопы внутри одного аккорда);
• динамика, артикуляция;
• тембр, аранжировка;
• мелодия (это отдельная задача).

Это правильный уровень абстракции для гармонической задачи. Всё остальное — на ручную работу в DAW при использовании сгенерированной прогрессии.

---

7. Чек-лист транскрипции

При перекладывании пьесы из DAW в .chord-файл:

1. Заполнить шапку: title, key, time, subdivision, style, tempo_bucket.
2. Прослушать пьесу целиком, разметить секции.
3. Для каждой секции — определить шаблонную единицу (4 такта? 8?), записать гармонию по позициям.
4. Прогнать парсер (когда он будет написан) и проверить, что нет <UNK> токенов и предупреждений о неизвестных качествах.
5. Сравнить «на слух»: воспроизвести аккорды в DAW по транскрипции и убедиться, что слышимая гармония совпадает с оригиналом.

Этот шаг 5 особенно важен — даже с абсолютным слухом легко пропустить инверсию или septима↔nona в плотной фактуре.

---

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

• v1.0 — первоначальная спецификация.