chore: document multicodec master variant selection seam (closes #64)

[birme]

Summary

Adds a written trace/finding (docs/multicodec-variant-selection.md) documenting exactly where a multicodec (HEVC+AVC) master-manifest variant is selected across the engine and @eyevinn/hls-vodtolive, so the implementation ticket (#65) can be scoped to the right repo.

Finding (grounded in the versions locked in this repo: @eyevinn/hls-vodtolive 4.1.5, eyevinn-channel-engine 5.0.0)

The mismatch originates inside @eyevinn/hls-vodtolive, where variants are reduced to a bandwidth-only index:

• index.js:246 — _loadMediaManifest(url, streamItem.get("bandwidth"), ...) keys the media load by bandwidth only.
• index.js:2603 / 2624-2625 — segments stored in this.segments[bw].
• index.js:2632 / 2844-2846 — segmentsInitiated[bw] guard: the first variant in master order wins the bucket, the second colliding variant is skipped.
• getUsageProfiles() index.js:1155-1157 — still emits ONE profile per input variant, so BOTH codecs are advertised at the colliding bandwidth even though only one variant's segments survive.
• getBandwidths() index.js:898-900 — collapses collisions to one key.
• Engine emits the client master from getUsageProfiles() at eyevinn-channel-engine/dist/engine/session.js:1516-1523, all colliding profiles pointing at the same master<bw>.m3u8.

Which repo must change: @eyevinn/hls-vodtolive (the bandwidth-keyed index / first-writer-wins collision handling is internal to the library; there is no engine/docker-fast hook to disambiguate — a fix needs the library to key by bandwidth+codec).

Codec preference: none exists today. No input-variant codec filter in the HLSVod constructor or load(); the codecs strings in ChannelProfile are used only for output manifest emission, not input filtering.

PROOF

• PROOF: npm run lint → clean
• PROOF: npm run pretty → All matched files use Prettier code style!
• Docs-only change; no source/spec touched, so no test run required.

Closes #64

[birme]

Verdict: APPROVE (posted as comment — author account cannot self-approve)

Docs-only deliverable for #64. Every technical claim and file:line reference in docs/multicodec-variant-selection.md was spot-checked against the actual locked dependency code and verified accurate.

Verified against dependencies

• Locked versions match the doc: @eyevinn/hls-vodtolive 4.1.5, eyevinn-channel-engine 5.0.0.
• index.js:227-250 — per-variant loop; usageProfile.push one-per-variant (232-241); _loadMediaManifest(url, streamItem.get("bandwidth"), ...) keyed by bandwidth only (246). ✓
• index.js:2600/2603/2624-2625 — _loadMediaManifest, let bw = bandwidth, this.segments[bw] = []. ✓
• index.js:2632 if (!this.segmentsInitiated[bw]); 2844 sets = true; 2845-2846 else branch Segments for ${bw} already initiated, skipping — first-writer-wins confirmed. ✓
• index.js:898-900 getBandwidths() returns Object.keys(this.segments); 1155-1157 getUsageProfiles() returns the flat usageProfile array. ✓
• Constructor index.js:26 signature and opts parse block 62-85 — no codec option present. load() index.js:198 — all four args are manifest injectors, no codec selector. ✓
• session.js:1516-1523 — engine iterates getUsageProfiles(), emits one #EXT-X-STREAM-INF ... CODECS line per profile, all pointing at the same master<bw>.m3u8. Call sites 1737 (new HLSVod) and 1751/1760 (load(...) with only loaders) confirm no codec is passed in. ✓
• docker-fast utils.ts:11-17 and plugin_demo.ts:86-88 — codecs are ChannelProfile output-emission strings only, not input filters. ✓
• Fixture master.m3u8: two variants at BANDWIDTH=2000000 with avc1.4d401f and hvc1.1.6.L93.90; characterization test multicodec_master.test.ts present. ✓

Conclusion supported

The doc's conclusion — the fix belongs in @eyevinn/hls-vodtolive (bandwidth-only segment index + first-writer-wins collision are internal to the library; no engine/docker-fast hook can disambiguate) and there is no existing codec-preference mechanism — is fully supported by the code read. Correctly scopes #65.

Gates

• npm run lint → clean.
• npm run pretty → "All matched files use Prettier code style!" (markdown is not ignored; the doc passes prettier).
• No unit-test run required for a docs-only change.
• No trademarks / commercial names in the doc.
• Commit message chore: document multicodec master variant selection seam (closes #64) follows the required format.

No findings. LGTM.