# archer-s02-2009

Second run of `playbooks/import-media/` v1.0. First TV-season run (Lilo & Stitch was a movie).

## Provenance

- **Source path on onyx:** `/home/admin/Downloads/Archer Season 2  [1080p AI 10bit S91 Joy]/`
- **Release group:** Joy (AI-upscale tag `S91`)
- **Quality:** 1080p HEVC 10-bit (Main 10), AI-upscaled from SD source
- **Audio:** HE-AAC 5.1 English
- **Embedded subs:** 3× DVD bitmap (eng, spa, fre)

## Target

- **Library:** tv
- **Path:** `/home/user/media/tv/Archer (2009)/Season 02/`
- **Container view:** `/media/tv/Archer (2009)/Season 02/`
- **Series Item ID:** (existed pre-import; not re-fetched this run)
- **TVDB / TMDb:** matched on existing `Archer (2009)` series folder (Season 1 already in lib)

## Files imported (13)

```
Archer (2009) - S02E01 - Swiss Miss.mkv
Archer (2009) - S02E02 - A Going Concern.mkv
Archer (2009) - S02E03 - Blood Test.mkv
Archer (2009) - S02E04 - Pipeline Fever.mkv
Archer (2009) - S02E05 - The Double Deuce.mkv
Archer (2009) - S02E06 - Tragical History.mkv
Archer (2009) - S02E07 - Movie Star.mkv
Archer (2009) - S02E08 - Stage Two.mkv
Archer (2009) - S02E09 - Placebo Effect.mkv
Archer (2009) - S02E10 - El Secuestro.mkv
Archer (2009) - S02E11 - Jeu Monégasque.mkv
Archer (2009) - S02E12 - White Nights.mkv
Archer (2009) - S02E13 - Double Trouble.mkv
```

Total ~2.8 GiB.

## Counts

| | Before | After | Delta |
|---|---:|---:|---:|
| Episodes in `Archer (2009)` S02 | 0 | 13 | +13 ✅ |
| SeriesCount | 12 | 12 | 0 (series existed) |
| MovieCount | 4 | 4 | 0 |
| `/Items/Counts.EpisodeCount` global | 230 | 230 (stale) | endpoint scope-cached, not authoritative |

**Authoritative verify:** `GET /Shows/9d22c409d5319c3c6068cfd38569714f/Episodes?Season=2` → 13 items, all with `ProviderIds.Tvdb`+`Imdb`+`TvRage`, Primary image present, paths resolve.

## Stream summary (S02E01 sample)

```
Duration: 00:21:03.48, bitrate: 1452 kb/s
Stream #0:0: Video: hevc (Main 10), yuv420p10le(tv), 1920x1080, SAR 1:1 DAR 16:9, 23.98 fps
Stream #0:1(eng): Audio: aac (HE-AAC), 48000 Hz, 5.1, fltp
Stream #0:2(eng): Subtitle: dvd_subtitle (dvdsub), 1920x1080
Stream #0:3(spa): Subtitle: dvd_subtitle (dvdsub), 1920x1080
Stream #0:4(fre): Subtitle: dvd_subtitle (dvdsub), 1920x1080
```

HEVC 10-bit Main10 — direct-play on most clients. DVD-bitmap subs (`dvd_subtitle`) — server burn-in works, but per ARRFLIX subtitle style (1× plain English `.srt` only, no SDH/forced) these may need WhisperX text rebuild later. Add to `playbooks/subtitles/STOPGAP-SUBS.md` if user wants text subs.

## Subtitle status

- Embedded: yes — 3× DVD bitmap (eng, spa, fre)
- External sidecar: none yet
- Action: none for now. Per ARRFLIX style, only English sidecar `.srt` is canonical; embedded multi-lang DVD-subs do not satisfy that. Defer to subtitle playbook if user wants text-based eng.

## Verification checks

- [x] Folder/filename canonical (`Archer (2009)/Season 02/Archer (2009) - S02E<NN> - <Title>.mkv`)
- [x] Permissions `user:user` 644 (file) / 755 (dir) — `ls -la` post-rsync confirmed
- [ ] LibraryMonitor auto-fired — **DID NOT trigger** (same as Lilo run; bind-mount inotify flake confirmed as a pattern, not one-off)
- [x] `POST /Library/Refresh` returned 204 but did NOT trigger task (silent no-op)
- [x] `POST /ScheduledTasks/Running/<scan-task-id>` returned 204 → task ran → episodes added
- [x] All 13 eps indexed with `Tvdb`+`Imdb`+`TvRage` providers populated
- [x] Per-episode Primary artwork present (`ImageTags.Primary` set on all 3 sampled)
- [x] HEVC 10-bit + HE-AAC → direct-play candidate on most clients

## Notes / surprises

- LibraryMonitor flake confirmed: same as Lilo run. v1.0 playbook wording ("auto-refreshes ~1–3 s") is wrong; force-refresh is mandatory. Update to README.
- **`POST /Library/Refresh` is also a silent no-op** in this Jellyfin build. Returned 204 but the `Scan Media Library` task didn't fire and counts stayed flat. Had to fetch the task ID from `/ScheduledTasks` and POST to `/ScheduledTasks/Running/<id>` directly. Update playbook to use task-trigger endpoint, not `/Library/Refresh`.
- **`/Items/Counts` is scope-cached/stale** — kept returning 230 even after 13 new eps were indexed. Use `/Shows/<series-id>/Episodes?Season=N` as authoritative count source, not `/Items/Counts`.
- API token retrieval: no docs in repo for getting an admin token. ApiKeys table empty (no operator-created keys). Pulled an active web-session token from `Devices` table via temp Alpine container mounting `jellyfin.db` read-only (`docker run --rm --userns=host -v ...:ro alpine sh -c "apk add sqlite && sqlite3 /db.sqlite ..."`). Per-session tokens work as `X-Emby-Token` for admin operations when source user has admin role. Worth documenting in ADMIN-GUIDE — or better, create an explicit ApiKeys row labelled "import-pipeline" with permanent rotation policy.
- Source filenames had double-space before `[1080p ...]` group tag — handled by `${f%%  [*}` parameter expansion. May need to be more lenient in future imports (single-space variants, no-space variants).
- HE-AAC audio at 5.1 may transcode-pressure some clients (LG WebOS notably struggles with HE-AAC multichannel). Watch for transcode lines in `docker logs jellyfin | grep transcode` if Archer playback shows lag.
- Source download on laptop retained per `ADMIN-GUIDE.md:74` — DO NOT delete `/home/admin/Downloads/Archer Season 2 ...` until user confirms playback in browser.

## Operator action

User to verify in browser: `https://arrflix.s8n.ru` → Archer (2009) → Season 02 → spot-check episodes 1, 7, 13 → confirm artwork + Play. After confirmed, source download on onyx can be deleted.

## Pending follow-ups

1. Update `playbooks/import-media/README.md`:
   - Drop "LibraryMonitor auto-fires" wording.
   - Replace `/Library/Refresh` with `/ScheduledTasks/Running/<scan-task-id>` (true task trigger).
   - Add note: do NOT use `/Items/Counts` as verification source (cached); use `/Shows/<id>/Episodes?Season=N` per-series.
2. Document API-token retrieval in `ADMIN-GUIDE.md` (DB pull recipe or instructions to mint an ApiKey row labelled `import-pipeline`).
3. Consider adding a `bin/import-tv.sh` that wraps stage → rsync → chmod → task-trigger → poll-by-series.
