Семейства анализа

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

Семейство	Что читает	Что записывает	Что делает доступным
SONARA	пути файлов с нативным декодированием SONARA/Symphonia	подписанные результаты core, timeline, embedding и fingerprint	поиск SONARA, SET, Hybrid, входы классификаторов
MAEST	аудио из общего декодера FFmpeg	жанры и синкопированность в Core, эмбеддинг в Artifacts	отображение и запись жанра, SET, Hybrid, сигнал Audio Dedup
MERT	аудио из общего декодера FFmpeg	эмбеддинг в Artifacts	поиск MERT, SET, Hybrid, сигнал Audio Dedup, входные данные классификаторов
MuQ	аудио из общего декодера FFmpeg с передискретизацией в 24 кГц float32	эмбеддинг в Artifacts	данные для LAB Reference Compare
CLAP	аудио из общего декодера FFmpeg	аудиоэмбеддинг в Artifacts	текстовый поиск CLAP, SET, Hybrid, сигнал Audio Dedup
CLASSIFIERS	точные сохранённые входы каждого опубликованного манифеста	строки Core classifier_scores	фильтры CLASS, предпочтения SET, диагностика Hybrid

Вычислительное устройство

• auto выбирает CUDA, если PyTorch видит GPU, иначе CPU.
• cpu принудительно использует CPU.
• cuda требует CUDA и должен выдавать понятную ошибку при её отсутствии.

SONARA работает в собственном CPU-процессе. MAEST, MERT, MuQ и CLAP используют адаптеры моделей с выбранным устройством. MuQ использует официальные веса OpenMuQ/MuQ-large-msd-iter и получает только аудио 24 кГц float32. Поддерживаются CPU и CUDA, но для полной фонотеки рекомендуется CUDA.

Темп и тональность SONARA

Анализ SONARA передаёт bpm_min=70.0 и bpm_max=180.0. SONARA приводит оценённый темп октавными сдвигами к этому диапазону до сохранения рабочего BPM. SONARA запускается только как отдельная задача на CPU. Она передаёт пути в sonara.analyze_batch() с sr=22050. Декодированием владеет SONARA/Symphonia; запасного пути через FFmpeg или анализ сигнала нет.

Поиск с учётом темпа, диагностика переходов и порядок SET сначала используют актуальные подписанные данные SONARA. При достоверности ниже 0.45 они сохраняют ранжированные варианты SONARA и проверяют тег BPM из Mutagen. grid_stability может снизить надёжность, а недостоверная оценка сдвигается к нейтральной вместо бонуса похожести или автоматического жёсткого исключения.

Тональность выбирается в таком порядке: корректный тег Camelot, key_camelot SONARA, затем преобразование обычного названия, например A minor. Совместимость оценивается как одинаковая, относительная, соседняя или конфликтующая. key_confidence не является отдельной мерой похожести: слабое свидетельство лишь сдвигает гармоническую оценку к нейтральной. Устаревшая диагностика риска перехода v1 сохраняет прежнее поведение тональности, чтобы записанные оценки оставались воспроизводимыми.

Обычная задача анализа пропускает только строки SONARA с запрошенным актуальным контрактом. Старый контракт декодера или пути выполнения блокирует нативную задачу до явного резервного копирования и сброса SONARA. Когда в базе остаётся только нативный контракт, расчёт недостающих актуальных результатов можно продолжить.

Результаты SONARA

SONARA v0.2.9 имеет одну неизменяемую идентичность релиза, выведенную из четырёх контрактов: core, timeline, embedding и fingerprint. Задача может выбирать, какие активные контракты материализовать; CLI и API по умолчанию выбирают core. Добавление другого результата позднее не меняет идентичность релиза с четырьмя контрактами и не заменяет актуальные строки core.

Результат	Основное содержимое	Хранилище
core	BPM/тональность/достоверность, громкость, динамика, спектральные и тембровые значения, Contrast (7), MFCC (13), Chroma (12), компактная структура и сетка долей, vocalness v2, настроение, тишина	таблица Core sonara
timeline	доли, атаки, аккорды, кривые темпа/энергии/громкости, первые доли такта и структурные сегменты	Artifacts sonara_timeline
embedding	48-мерный вектор похожести SONARA	Artifacts sonara_similarity_embeddings
fingerprint	версионный аудиоотпечаток SONARA	Artifacts sonara_fingerprints

bpm_confidence — достоверность рабочего BPM в диапазоне 0..1. key_camelot — собственный код Camelot SONARA, а не преобразование на стороне проекта.

Реестр контрактов хранит канонический JSON, хеш контракта и хеш релиза. Сырые сведения анализатора проверяются при записи, но их полное обратное сохранение для показа не обещается.

У каждого результата собственный контракт совместимости. Его детерминированный хеш охватывает SONARA 0.2.9, схему upstream 4, режим playlist, частоту 22050, диапазон BPM 70..180, отсортированный профиль признаков результата, ревизию проекта 6, decoder_backend="sonara-symphonia" и execution_path="analyze_batch".

Core намеренно не запрашивает доступную только в Full метрограмму time_signature. Она не использовалась в поиске, SET, Hybrid или входах классификаторов, а результаты на реальной фонотеке не давали полезной достоверности и более чем вдвое увеличивали время расчёта Core. Beatgrid использует обычное запасное значение SONARA 4/4 вместо ненадёжной оценки размера.

Название модели проекта sonara-playlist носит информационный характер и не определяет актуальность. Контракт содержит развёрнутые отсортированные имена upstream-признаков, а не только четыре названия результатов проекта. Шаг анализа входит в общие параметры каждого контракта результата и общий хеш релиза. Точные правила хранения и контрактов описаны в контракте SONARA v0.2.9 для проекта.

Серверный API использует sonara_outputs, а CLI — --sonara-outputs core,timeline,embedding,fingerprint. Каждая нативная партия запрашивает одно и то же каноническое объединение upstream-признаков, необходимое всем четырём контрактам результатов. Выбор управляет только сохранением: конвертер записывает каждый выбранный результат в таблицу его контракта. core явно выбирает встроенную модель vocalness v2 SONARA. sonara_batch_size не зависит от ML-партий и принимает 1..16. Значение по умолчанию — 8. Клиент React ещё не перенесён на этот контракт v7, поэтому текущие элементы браузера здесь не объявляются рабочими.

Адаптер не запрашивает передачу файловых тегов upstream или жанровую модель SONARA. Источником файловых тегов остаётся Mutagen, поэтому tags.original_year SONARA в этом семействе не хранится.

Лёгкие поля — скаляры, компактные варианты и фиксированные векторы — остаются в метаданных Core. Сюда входят все четыре значения mood_*, true peak, ReplayGain, максимум моментальной громкости и диапазон громкости. Contrast, MFCC и Chroma сохраняют все компоненты, поскольку это фиксированные векторы, а не временные ряды. Длинные числовые последовательности сворачиваются только тогда, когда Core нужен компактный показатель, например energy_curve_summary.

Полные последовательности beats, onset_frames, chord_sequence, chord_events, tempo_curve, energy_curve, segments, loudness_curve и downbeats относятся к timeline. embedding и fingerprint — отдельные результаты. Поиск и классификаторы не читают данные временной шкалы.

Диагностика риска перехода v2 использует grid_stability как показатель надёжности сетки долей. При наличии структуры она также сравнивает исходящее аутро со входящим интро, границы сегментов, уровень энергии и лёгкий показатель energy_curve_summary, сохранённый рядом с этими полями. Отсутствующие необязательные данные не превращаются в нулевой признак. Настроение, true peak и ReplayGain не участвуют в расчёте перехода.

Само хранение не означает участия в расчёте. Значения mood_* сохранены для изучения и будущих сценариев, но не входят в текущую похожесть SONARA, SET, Hybrid или классификаторы Rhythm Lab. True peak и ReplayGain не являются прямыми измерениями похожести SONARA: они сохранены для возможных функций управления громкостью. Скаляры громкости доступны варианту классификатора sonara2, максимум моментальной громкости и диапазон громкости — существующему сравнению динамики SONARA, а vocalness остаётся явным модификатором поиска и необязательным вариантом sonara2vocal.

Результаты SONARA embedding, fingerprint и кривая темпа пока хранятся как данные. Поисковыми эмбеддингами остаются MERT и CLAP, а Audio Dedup и текущие матрицы похожести и классификаторов не используют представления SONARA.

Таблицы Artifacts

Обязательная база Artifacts хранит эмбеддинги в отдельных таблицах:

• maest_embeddings — эмбеддинги MAEST
• mert_embeddings — эмбеддинги MERT
• muq_embeddings — эмбеддинги MuQ
• clap_embeddings — эмбеддинги CLAP
• sonara_similarity_embeddings — эмбеддинги похожести SONARA

Общей рабочей таблицы embeddings и команды миграции v6 в v7 нет. Для нового выбранного пути создаются Core v7 и обязательная база Artifacts. База не v7 отклоняется.

Диапазоны партий и меток

Настройка	Диапазон	По умолчанию
top_k	1..10	3
track_batch_size	1..64	8
inference_batch_size	1..128	16

Отсутствующие результаты

Задачи выбирают отсутствующие результаты. Для SONARA каждый отмеченный результат должен иметь актуальный контракт активного релиза с четырьмя контрактами. Отсутствующая строка timeline не делает core устаревшим, а отсутствующий отпечаток не вынуждает переписывать core. Выбор меньшего числа результатов меняет только материализуемые задачей строки, но не неизменяемую идентичность релиза. Остальные уже готовые семейства пропускаются до сброса.

Сохранение core заменяет только строку признаков Core. Сохранение timeline, embedding или fingerprint обновляет соответствующий результат Artifacts. Неотмеченные актуальные результаты остаются нетронутыми.

Требования классификаторов

Задачи используют точные входы манифеста: актуальный SONARA Core, если требуется, и только эмбеддинги MERT, MAEST и CLAP, указанные в признаках или required_inputs. SONARA не выполняется в одной аудиозадаче с GPU-моделями, а расчёт классификаторов — третья задача только по базе. Сначала рассчитайте недостающие этапы.

Зависимые от SONARA артефакты классификаторов хранят точный контракт обучающих данных в манифесте версии 2. Публикация и расчёт отклоняют отсутствующие, устаревшие или несовпадающие контракты. Трек должен соответствовать контракту артефакта и содержать все запрошенные значения SONARA; отсутствующее необязательное поле, например vocalness, пропускается вместо значения 0.0.

После изменения ревизии признаков SONARA основная база делает недействительными зависимые оценки классификаторов, а база Rhythm Lab — зависимые предсказания. Правило охватывает combined и каждый разделённый знаком плюс источник, имя которого начинается с sonara, включая сочетания sonara, sonara2 и sonara2vocal. Метки и обратная связь сохраняются. Устаревшим артефактам не доверяют: расчёт остаётся заблокированным до переобучения и публикации профиля с актуальным подписанным манифестом.

Текущие опубликованные файлы model.json в репозитории всё ещё объявляют манифест версии 1. Исполняемая версия 2 блокирует их до переобучения и публикации.