---
title: Media Pipeline — Pitfalls & Debug Notes
created: '2026-05-16'
updated: '2026-05-16'
type: entity
tags:
  - media-pipeline
  - swift
  - pitfalls
  - debugging
confidence: 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 Run — Kraken

Всегда монтировать `unresolved.json` явно:
```bash
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 — добавлен

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

- [[personal-os-architecture]]
- [[wiki/tech/kraken-infra]]