Edit mode for existing HLS collections

[johan-bell]

Today. CmsCreateSessionDto.existingMedia ({ hlsUrl, hlsKey? }) is validated and accepted, and then ignored — every CMS session produces a brand-new collection in its own <pathPrefix>/<sessionId> subfolder. A user who wants to add one audio language to an existing post re-encodes everything, gets a new URL and a new key, and leaves the old collection behind.

Wanted. When the CMS sends existingMedia, the app should open the collection instead of starting from a blank session:

• Import — resolve hlsUrl back to a bucket/prefix and use POST /api/hls/discover + POST /api/hls/read to enumerate what is there: video angles, audio renditions, subtitle tracks, chapters, thumbnails, waveform sidecar. deriveAngleName and normalizeS3Key in hls-core/src/keys.ts already exist for this.
• Playback with the supplied key — done by feat: player-core wrapper and hls.js reference player (#153) #162. PlayerSource.keyHex is an input to the player, with no opinion about where it came from, so a key handed over by the CMS works exactly like one from a session the app ran itself.
• Chapter editing on an imported collection — the session-scoped chapter routes resolve the prefix from the session's own S3 config; an imported collection needs the same against a discovered prefix (the stateless /api/hls/chapters/{read,write} routes already do exactly this).
• Track management — add / remove / replace an individual audio track or video angle without touching the rest:
  • new hls-edit operations alongside upsertSubtitle / removeSubtitle / upsertChapters / removeChapters in api/src/hls-edit/operations/index.ts (e.g. upsertAudioRendition, removeAudioRendition, upsertVideoAngle, removeVideoAngle)
  • single-track encodes that write into an existing prefix and are encrypted with the existing collection key, not a freshly generated one — EncodeService currently always calls encryptionService.generateKey(), so it needs a path that takes a supplied key. Since feat: player-core wrapper and hls.js reference player (#153) #162 that key also has to decrypt the collection's existing playlists before they can be edited and re-encrypt them after, which hls-edit already does when given a keyHex
  • If-Match ETag concurrency on master.m3u8 via s3-etag.service.ts — already wired for mutate, so the new ops inherit it
  • a track-manager UI in SessionView (list tracks, mark for removal, add a source file per new track)

Watch out for. Segment format and segment duration have to match the existing collection or the new track will not line up; byte-range packing means a "single track" is not a single file; and removing the last rendition of a group leaves a master that no player will accept.

---

---

Migrated from Todo.md item 1, which is removed as the repository is prepared to go public.