Skip to content
OpenSmartRoute
Skillv1.0.0

media-transcription

Run, monitor, cancel, and resume the durable media transcription pipeline (media-transcription-pipeline-v2) for raw meeting media on /Volumes/badass-media. Use when the user asks to transcribe a meeti

by joelhooks(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from joelhooks/joelclaw (skills/media-transcription/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill media-transcription. Copyright stays with the author.

Media Transcription

Durable, event-driven transcription of raw meeting media on the NAS. Inngest orchestrates; MLX Whisper (chunked ASR) and pyannote (whole-file diarization) run as detached local actor processes — no Inngest step ever holds a request open across inference. Built 2026-07-11 after the v1 monolith died to request-bound 2h timeouts and Whisper hallucination loops (design receipt: .brain/projects/transcription-pipeline-v2-2026-07-11.svx).

Where it runs (hard constraints)

  • Flagg host worker only (hostFunctionDefinitions, launchd com.joel.system-bus-worker). Needs the direct NFS mount /Volumes/badass-media and the rig checkout.
  • Local inference implementation: ~/Code/joelhooks/transcript-rig (public repo joelhooks/transcript-rig; override path with TRANSCRIPT_RIG_ROOT). Raw media on the NAS is immutable — the pipeline only writes derived artifacts.
  • From any other fleet machine: send the event (Inngest routes it to flagg's worker) or SSH to flagg to inspect on-disk state.

Start a transcription

joelclaw send media/transcription.requested -d '{
  "requestId": "req-'$(uuidgen | tr 'A-Z' 'a-z')'",
  "sourcePath": "/Volumes/badass-media/joel/meetings/<meeting-dir>"
}'
  • requestId is the idempotency key — always mint a fresh one; a reused id is silently deduped. Optional flags: "publish": false, "index": false (both default true).
  • sourcePath must be under /Volumes/badass-media/ or the run fails NonRetriable.

Monitor

  • joelclaw event <event-id> → run id; joelclaw run <run-id> for step trace. Orchestrator steps keep NN- prefixes for the pi job-monitor widget (packages/pi-extensions/inngest-monitor).
  • Progress events: media/transcription.chunk.completed (per chunk, with index/total/cached), terminal media/transcription.completed or .failed.
  • On-disk truth (flagg): <rig>/.transcript-rig-work/<artifactId>/
    • orchestration/plan.v1.json — chunk plan (requestId, tracks, chunk ids)
    • orchestration/actors/<chunkId>/status.v1.json — actor heartbeat/state
    • orchestration/actors/<chunkId>/actor.log — inference stdout/stderr
    • state.v1.json — rig stage (staged → transcribed → … → complete)
    • editorial/transcript.{md,txt,srt,vtt,tsv} — final outputs
  • Published result: <sourcePath>/derived/transcripts/current.v1.json pointer + artifact directory.

Cancel

joelclaw send media/transcription.cancelled -d '{"requestId": "<the-request-id>"}'

Cancels all runs (cancelOn) AND triggers transcription-cleanup-v1, which SIGTERM→10s→SIGKILLs live actor process groups (identity-verified via ps — PID reuse safe) and writes orchestration/cancelled.v1.json, which blocks new actor spawns. Optionally include artifactId to skip the plan scan.

Resume / re-drive

Re-send media/transcription.requested with a fresh requestId and the same sourcePath. Everything valid on disk is adopted, nothing recomputes:

  • Whole-track raw/asr/<sourceId>/asr.json passing the repetition screen ⇒ track done. A repetitive one is quarantined (.rejected-<ts>) and the track re-chunks.
  • Existing chunk WAV layouts (raw/chunked/<sourceId>/chunks/NNN.wav) are adopted; offsets recomputed from ffprobe. Valid chunk out/<i>/asr.json ⇒ cached, no actor spawned.
  • Diarization raw/diarization/<sourceId>.jsonl (first line parses) ⇒ cached.
  • Remove orchestration/cancelled.v1.json first if the artifact was previously cancelled.

Failure modes (typed, in actor status / run errors)

Error Meaning Action
repetitive_output: … Whisper hallucination loop survived collapse (decode mostly padding) Retries respawn actors; deterministic loops usually pass after collapse-then-screen. Inspect the chunk WAV — genuinely silent/broken audio fails honestly
inference_required: … A fast rig stage (resume --no-inference) found a missing claim check Inference didn't complete/adopt; check chunk statuses
cancelled_by_signal Actor's child died to un-initiated SIGTERM/SIGKILL (group kill, operator, or Bun's in-process signal-dispatch race) Expected during cancel/reap; standalone occurrences mean someone killed processes manually
actor stalled Heartbeat stale >3m Watchdog killed + retried automatically
chunk_result_missing Aggregation found no valid chunk output Chunk failed all retries; see its actor.log
mount_unavailable NFS mount down media/transcription.blocked emitted; remount and re-drive

Design invariants (don't regress these)

  • ASR outputs are parsed with parseAsrJson (mlx_whisper emits bare NaN).
  • Repetition screening is collapse-then-screen (screenWithCollapse): consecutive-duplicate segments collapse to one; >50% collapsed ⇒ failed decode. Aggregation persists the collapsed form.
  • ASR actors run --condition-on-previous-text False --hallucination-silence-threshold 2; diarization uses MPS (TRANSCRIPT_RIG_DIARIZE_DEVICE=cpu to opt out).
  • waitForEvent results are verified in code against the spawned actorId — the dev-mode Inngest server leaks foreign events past match expressions.
  • Known dev-server gap: concurrency keys (transcription-gpu limit 1) are not enforced; expect parallel whispers until the Inngest server is upgraded.

Code: packages/system-bus/src/transcription/ + packages/system-bus/src/inngest/functions/{media-transcription-pipeline,transcription-asr-chunk,transcription-diarize,transcription-cleanup}.ts.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/joelhooks-joelclaw-media-transcription/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

joelhooks-joelclaw-media-transcription.ocm.jsonjson
{
  "ocm": "1",
  "id": "joelhooks-joelclaw-media-transcription",
  "kind": "skill",
  "name": "media-transcription",
  "description": "Run, monitor, cancel, and resume the durable media transcription pipeline (media-transcription-pipeline-v2) for raw meeting media on /Volumes/badass-media. Use when the user asks to transcribe a meeting or media file from the NAS, check transcription progress, cancel a transcription, resume a failed/partial run, or debug ASR/diarization actors. Flagg-host-only execution.",
  "publisher": "joelhooks",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "customer_support",
      "hr"
    ],
    "tags": [
      "skill-md",
      "media",
      "transcription",
      "whisper",
      "diarization",
      "inngest",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Run, monitor, cancel, and resume the durable media transcription pipeline (media-transcription-pipeline-v2) for raw meeting media on /Volumes/badass-media. Use when the user asks to transcribe a meeting or media file from the NAS, check transcription progress, cancel a transcription, resume a failed/partial run, or debug ASR/diarization actors. Flagg-host-only execution."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/joelhooks/joelclaw",
      "path": "skills/media-transcription/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/joelhooks/joelclaw/blob/HEAD/skills/media-transcription/SKILL.md",
      "key": "joelhooks/joelclaw/skills/media-transcription/SKILL.md"
    }
  },
  "instructions": "# Media Transcription\n\nDurable, event-driven transcription of raw meeting media on the NAS. Inngest\norchestrates; MLX Whisper (chunked ASR) and pyannote (whole-file diarization)\nrun as **detached local actor processes** — no Inngest step ever holds a\nrequest open across inference. Built 2026-07-11 after the v1 monolith died to\nrequest-bound 2h timeouts and Whisper hallucination loops (design receipt:\n`.brain/projects/transcription-pipeline-v2-2026-07-11.svx`).\n\n## Where it runs (hard constraints)\n\n- **Flagg host worker only** (`hostFunctionDefinitions`, launchd\n  `com.joel.system-bus-worker`).",
  "cost": {
    "context_tokens": 1388
  }
}

Fetch it by URL: GET /api/v1/registry/joelhooks-joelclaw-media-transcription/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.