---
name: captioner
description: Use when asked to caption, transcribe, generate SRT, or route a local video or MP3 audio file through the captioner service at caption.chan.dev.
---

# Captioner

Use `https://caption.chan.dev/` as the primary discovery surface. Fetch the root HTML before acting; it links auth.md, the workflow, OpenAPI spec, upload policy, media guidance, storage behavior, and terminology pack discovery.

## Minimal Workflow

1. Read `https://caption.chan.dev/` and follow the auth, OpenAPI, or terminology links as needed.
2. If no credential is available, follow `https://caption.chan.dev/auth.md` to claim a WorkOS API key.
3. For video or non-MP3 audio input, extract speech audio locally as MP3 before upload. Use the ffmpeg command in the root HTML.
4. Upload only `.mp3` audio under 100 MiB to the advertised `PUT /audio/:key` endpoint with `Content-Type: audio/mpeg` and the WorkOS API key as bearer auth. Never print the key.
5. Start the advertised captioner workflow with `wait=result`.
6. Save the returned JSON and SRT near the source media unless the user asks for a different destination.

## Notes

- Reuse a stored Captioner credential first; start Magic Auth only when no credential exists or a previously-working credential returns 401.
- Store a returned WorkOS API key durably only with user consent. Prefer an agent credential vault, then macOS Keychain or another OS secret store, then CI/server secrets, then session-only memory.
- On macOS, after a successful claim ask once: "Store this Captioner API key in macOS Keychain for future runs?" If approved, store it as a generic password with service `captioner.chan.dev` and account equal to the verified email.
- macOS store command: `security add-generic-password -s captioner.chan.dev -a "$CAPTIONER_EMAIL" -U -w "$CAPTIONER_API_KEY"`.
- macOS lookup command when email is known: `CAPTIONER_API_KEY="$(security find-generic-password -s captioner.chan.dev -a "$CAPTIONER_EMAIL" -w)"`.
- macOS delete command for revoked or invalid keys: `security delete-generic-password -s captioner.chan.dev -a "$CAPTIONER_EMAIL"`.
- Source audio is deleted as soon as transcription has consumed it by default; deletion is retried if the workflow fails.
- Use `storage.retainSourceAudio: true` only for reruns or debugging.
- Read plain transcript text from `result.transcript.text` and final SRT from `result.captions.srt`.
- Caption cue text is normalized from punctuated/capitalized transcript tokens; use `result.quality.captions` for deterministic cue QC.
- Treat WorkOS API keys as secrets. Never print, log, screenshot, or paste them into chat.
- Use `GET /terminology/packs` when choosing or validating term packs.
- Treat `/openapi.json` as the current API contract.