skill-materialsub/skills/materialsub/references/embedded-hls.md

Browser-confirmed authorized embedded HLS

Use this fallback only after the ordinary fetch_video.py probe reports an unsupported URL and an available browser visibly plays the requested video under the user's public or subscription access. Never use it to bypass a paywall, DRM, login barrier, CAPTCHA, safety interstitial, or unavailable entitlement.

Resolve one selected media playlist

Inspect the loaded player state without reading cookies, local storage, passwords, or account details. Record only resources already used by the playing page:

• the final HLS media playlist selected during playback, not a master playlist;
• one original-language dialogue subtitle track, preferring a manual track over automatic captions;
• the cover or poster URL when available;
• public title, video ID, duration, and display dimensions.

Use visible track labels or <track> metadata to distinguish ordinary dialogue from audio description, translated tracks, commentary, or metadata. If the original language remains ambiguous, ask the user; never guess. The fallback accepts ordinary HLS AES-128 transport encryption with an authorized identity key, but rejects SAMPLE-AES, non-identity key formats, and other DRM methods.

Private resource map

Write exactly one JSON resource map with mode 0600. Never print its signed URLs, put them in command arguments, commit it, or include it in the final response.

{
  "schema_version": 1,
  "page_url": "https://example.com/public-video-page",
  "playlist_url": "https://media.example.com/video/media.m3u8?<signed-query>",
  "title": "Public video title",
  "id": "public-video-id",
  "duration_seconds": 289.7,
  "width": 1920,
  "height": 1080,
  "cover_url": "https://example.com/poster.jpg",
  "subtitle": {
    "url": "https://example.com/captions.vtt",
    "language": "en",
    "kind": "manual",
    "label": "English",
    "format": "vtt"
  }
}

Omit cover_url when unavailable. Set subtitle to null when no suitable foreign-language dialogue track exists; do not invent captions. subs and bilingual-subs deliveries require a selected subtitle.

Ingest

Create a new empty job directory, then run:

python3 <skill-dir>/scripts/ingest_embedded_hls.py \
  --resource-map "<private-resource-map.json>" \
  --output-dir "<job-dir>" \
  --cleanup-resource-map

Pass the same --target-lang, --deliver, --mp4-fallback, or --resume intent used by the ordinary downloader. The ingest script:

• never exposes signed URLs in its process arguments or diagnostics;
• propagates authorization query fields only to same-origin playlist segments, maps, and AES-128 identity keys;
• uses concurrent fragment downloading and preserves the source codecs;
• keeps the downloaded original subtitle byte-for-byte unchanged and derives a separate SRT;
• creates the same localized delivery names and download-manifest.json schema as fetch_video.py;
• removes its private rewritten playlist automatically and deletes the exact resource map only with --cleanup-resource-map.

Exit 3 is the normal handoff to subtitle_pipeline.py next-batch. Continue the standard translation, render, burn, and verify_delivery.py workflow from SKILL.md. On failure, keep a valid resumable partial; before a clean retry, move only known stale partials or sensitive agent-created maps to Trash rather than deleting broadly.