obsidian-vault/wiki/tech/media-pipeline-pitfalls.md

title, created, updated, type, tags, confidence

title	created	updated	type	tags	confidence
Media Pipeline — Pitfalls & Debug Notes	2026-05-16	2026-05-16	entity	media-pipeline swift pitfalls debugging	high

Media Pipeline — Pitfalls & Debug Notes

Операционные заметки по Swift media-pipeline (media_files_db / media-toolbox) на Крякне. Связано: personal-os-architecture, wiki/tech/kraken-infra

§9.x Score Engine — Критические питфолы

§9.9 Year tiebreak:

• if count > 1 only — НИКОГДА не штрафовать единственного кандидата
• Если кандидат один — year mismatch не является причиной для снижения score

§9.6 Subset floor:

• Floor 0.35 когда queryToks ⊆ candidateToks (запрос является подмножеством кандидата)
• Это нормально — не считать subset-матч за слабый результат

False resolves:

• Проверять поле title: — если в title шум из имени файла = hasBestEffortResult junk, не настоящий resolve
• Пример: 2001 Космическая одиссея.mkv → title: 2001 Космическая одиссея.mkv = junk

Транслитерация

• transliteratedToLatin для кириллических названий генерирует мусорные запросы — TMDb не находит Migratsiya
• Решение: не эмитить lat-запросы когда источник уже кириллица
• transliteratedToCyrillic из латинских имён — полезен (Osnovnoi → Основной Инстинкт → TMDb находит)

KP (Кинопоиск) Rate Limit

• KP — настоящий fallback, дёргается только если TMDb не дал winner
• 40 KP-запросов vs 8428 TMDb в типичном прогоне
• Лимит исчерпывается только после очистки кеша когда весь TMDb идёт заново
• Проблема не в архитектуре — это нормально

Docker Deploy — Kraken (обязательный порядок)

После каждого деплоя обязательно чистить dangling images, иначе диск забивается (~1-2GB за прогон):

# Mac (после docker build)
docker image prune -f

# Kraken (после docker load)
ssh kraken-ssh "docker image prune -f"

Полная последовательность деплоя:

# 1. Собрать
docker build -f Dockerfile.kraken -t media-pipeline:kraken .

# 2. Перенести
docker save media-pipeline:kraken -o /tmp/mp.tar
scp /tmp/mp.tar kraken-ssh:/tmp/
ssh kraken-ssh "docker load -i /tmp/mp.tar && rm /tmp/mp.tar && docker image prune -f"
rm /tmp/mp.tar

# 3. Почистить локально
docker image prune -f

Docker Run — Kraken

Всегда монтировать unresolved.json явно:

docker run \
  -v "$(pwd)/config.json:/config/config.json:ro" \
  -v "/media:/media" \
  -v "$(pwd)/cache:/cache" \
  -v "$(pwd)/unresolved.json:/config/unresolved.json" \
  media-pipeline

Без явного маунта unresolved.json пишется внутри контейнера и теряется.

Пофикшенные баги (сессии 2026-05)

• Code=516 EEXIST в ApplyPhase — исправлен
• Episode regex \b boundary — исправлен
• BBC prefix strip + trim — исправлен
• Yoficator Linux path — исправлен
• Backtick в TitleParser (/[^'\p{L}\p{N}]+/ → strip apostrophes first) — исправлен
• §9.6 subset floor 0.35 — добавлен
• §9.9 year tiebreak count>1 only — исправлен
• Year-miss retry в TMDb/KP providers — добавлен

Agent/Sync Pitfall — Duplicate unresolved

Проблема: agent пишет canonical dir в /media/library/, но sync при следующем запуске снова добавляет файл в unresolved (нет source marker).

Фикс: updateUnresolvedStore проверяет allOutputDirs на существующий canonical dir → пропускает. Файл: PipelineRunner.swift.

Связанные заметки

• personal-os-architecture
• wiki/tech/kraken-network