yt-dlp Ingest First

Standard flow for video -> text -> analysis in OpenClaw Android.

Scope

• In-scope:
  • metadata probe
  • subtitle/caption discovery
  • subtitle fetch
  • optional audio fallback (only when subtitles are unavailable/insufficient)
• Out-of-scope:
  • default full-video download
  • playlist batch ingestion without explicit user request
  • browser-cookie/account-dependent workflows as default path

Trigger Rules

• Positive:
  • user gives a public video URL and asks to analyze content
  • user asks for subtitles/captions/transcript extraction
  • user asks to inspect metadata before deeper analysis
• Negative:
  • user explicitly asks for media download/archive workflow
  • user asks for heavy ffmpeg post-processing pipeline not prepared on host
• Escalation:
  • if no subtitle/caption exists, return PARTIAL and ask to approve audio fallback + ASR path

Environment Contract (Android/OpenClaw)

Always use:

/data/adb/openclaw/node/bin/python -W ignore -m yt_dlp ...

Operational flags for YouTube robustness (default in this skill):

--js-runtimes deno --remote-components ejs:github

Do not assume yt-dlp, python3, ffmpeg, or desktop paths are preconfigured.

Runtime preconditions for full lane:

• ffmpeg + ffprobe available via /data/adb/openclaw/node/bin/{ffmpeg,ffprobe}
• deno available via /data/adb/openclaw/node/bin/deno
• If these are missing, downgrade verdict to PARTIAL and report blockers.

Path Contract

• temp artifacts: workspace/.ops/tmp/<task-id>/
• logs/state: workspace/.ops/state/<task-id>/
• do not write outside workspace without explicit approval

SOP

1. Input gate
   • validate URL + task intent (metadata-only | sub-first | deep-transcript)
2. Mode A: metadata probe
   • run --skip-download -J
3. Mode B: subtitle discovery
   • run --list-subs
4. Mode C: subtitle fetch
   • try uploader subs (--write-subs) + auto subs (--write-auto-subs)
   • language priority: requested -> vi.* -> en.*
5. Decision
   • if subtitles fetched: PASS for text ingest
   • if no subtitles: return PARTIAL + propose Mode D
6. Mode D: audio fallback (explicitly approved)
   • extract audio for downstream ASR
   • if ffmpeg missing: keep PARTIAL, report blocker and remediation

Deterministic Decision Tree

1. Input gate -> Mode A (metadata)
2. Mode A complete -> Mode B (list subtitles)
3. Mode B result:
   • subtitles/auto-captions found -> Mode C (fetch text)
   • none found -> PARTIAL + ask approval for Mode D
4. Mode D approved:
   • ffmpeg available -> extract audio for ASR pipeline
   • ffmpeg missing -> PARTIAL with blocker + remediation
5. Return verdict only with artifact evidence in .ops/tmp + .ops/state

Command Recipes

Recipe 1 — Metadata only

mkdir -p ".ops/tmp/<task-id>" ".ops/state/<task-id>"
/data/adb/openclaw/node/bin/python -W ignore -m yt_dlp \
  --js-runtimes deno --remote-components ejs:github \
  --skip-download -J "<URL>" \
  > ".ops/tmp/<task-id>/meta.json" \
  2> ".ops/state/<task-id>/meta.err"

Recipe 2 — Subtitle discovery

/data/adb/openclaw/node/bin/python -W ignore -m yt_dlp \
  --js-runtimes deno --remote-components ejs:github \
  --skip-download --list-subs "<URL>" \
  > ".ops/tmp/<task-id>/list-subs.txt" \
  2> ".ops/state/<task-id>/list-subs.err"

Recipe 3 — Subtitle fetch (text-first default)

/data/adb/openclaw/node/bin/python -W ignore -m yt_dlp \
  --js-runtimes deno --remote-components ejs:github \
  --skip-download --write-subs --write-auto-subs \
  --sub-langs "vi.*,en.*" \
  --sub-format "vtt/srt/best" \
  -o ".ops/tmp/<task-id>/%(id)s.%(ext)s" \
  "<URL>" \
  > ".ops/state/<task-id>/subs.out" \
  2> ".ops/state/<task-id>/subs.err"

Recipe 4 — Audio fallback (only when approved)

/data/adb/openclaw/node/bin/python -W ignore -m yt_dlp \
  --js-runtimes deno --remote-components ejs:github \
  -x --audio-format mp3 \
  -o ".ops/tmp/<task-id>/%(id)s.%(ext)s" \
  "<URL>" \
  > ".ops/state/<task-id>/audio.out" \
  2> ".ops/state/<task-id>/audio.err"

Error Taxonomy -> Next Action

• HTTP 429 / rate limit:
  • wait/backoff and retry; avoid tight loops; keep PARTIAL
• has no subtitles / has no automatic captions:
  • this is a content-state result (not a runtime failure); switch to approved audio fallback path
• ffmpeg not found:
  • cannot complete audio fallback; return blocker + install requirement
• JS runtime / challenge-solver warning for YouTube extractor:
  • enforce --js-runtimes deno --remote-components ejs:github; if still present, mark PARTIAL with reduced extraction confidence
• auth/geo/private video errors:
  • report exact extractor error; do not auto-use browser cookies

Output Contract

Must return:

1. mode(s) executed
2. artifact paths (.ops/tmp, .ops/state)
3. findings:
   • metadata summary
   • subtitle availability/fetch result
4. risk/blockers (429, ffmpeg, JS runtime, geo/auth)
5. verdict:
   • PASS: got text material (subs/metadata per requested scope)
   • PARTIAL: some data found, but transcript path incomplete
   • FAIL: ingest path blocked with no usable output

Safety Rules

• default to text-first / download-light
• do not auto-download playlists/full media
• do not use browser-cookie extraction as default
• if fallback requires new dependencies or policy changes, ask first

Trigger Rules

• Positive: Trigger when user asks to analyze a public video URL via metadata/subtitle/transcript-first ingest.
• Negative: Do not trigger for unrelated tasks or full downloader workflows unless explicitly requested.
• Escalation: For audio fallback and any larger media workflow, confirm scope/approval before proceeding.

Error Handling

• missing tool/dependency: report exact missing component + safe remediation
• extractor/network failure: return exact error and next action
• no subtitle path: mark PARTIAL, propose approved fallback

Output Contract

• Deliverable: concise evidence-backed ingest report with artifacts and verdict.
• Validation: include command class run + observable output.
• Failure mode: state root cause and actionable next step.

Minimal Reusable Report Template

⚡ [yt-dlp] mode=A+B+C -> metadata+subs probe complete
⚡ [artifacts] tmp=.ops/tmp/<task-id>/ ; state=.ops/state/<task-id>/
🛡️ [status] subtitles=<found|none> auto-captions=<found|none>
🛡️ [risk] <429|ffmpeg-missing|js-runtime-warning|none>
✅ Verdict: PASS | PARTIAL | FAIL

Compliance

• This skill standardizes a deterministic text-first ingest workflow; no completion claims without artifact evidence.
• For state-changing or long-running verification sequences, follow workspace reporting gate: send PARTIAL immediately when verification is still pending.