Yaps Auto Captions

Yaps Video Captions

Turn one video into a finished, captioned MP4 through Yaps. Yaps transcribes speech locally, aligns captions to the spoken words, and burns them into a new video using one of 14 templates. Make corrections by caption ID, never by hand-editing subtitle markup.

Runtime compatibility

Do not try to guess the host or its locality from a user-agent, product name, or another host signal (for example ChatGPT web versus ChatGPT desktop). Test the capability this workflow actually needs: before account, model, dependency, or input-file checks, resolve the local Yaps CLI through the plugin runner. The runner validates it with a bounded, read-only status command. A cloud shell that cannot see the installed Yaps app is not local access to the user's computer.

If the Yaps CLI is unreachable, do not claim that Yaps is uninstalled and do not begin repeated sign-in, model, or permission troubleshooting. Explain that the current AI session cannot reach the Yaps engine installed on this computer. Direct the user to a local-capable session on the computer where Yaps is installed: in Claude, that is Claude Code or the Claude desktop app; from ChatGPT web or a cloud session, download or open ChatGPT desktop and retry in a local-capable Work or Codex session. They can also access this feature directly in the Yaps application. If they are already in a local-capable desktop session, offer Download or update Yaps, ask them to open it, and retry. Stop until local reachability is restored; only then follow the availability and onboarding steps below.

Private operational diagnostics

Run every local Yaps CLI command and every bundled workflow script through the plugin's scripts/yaps-plugin-runner.mjs. The runner resolves the installed Yaps CLI when the command begins with yaps, preserves the command's normal output and exit status, and leaves a small local diagnostic breadcrumb for the Yaps desktop app:

node <plugin-root>/scripts/yaps-plugin-runner.mjs --action auth.status --stage authentication -- yaps auth status --pretty

Choose a stable, content-free action such as cli.reachability, auth.status, features.list, dictation.setup, transcription.run, or export.create; use the matching stage: reachability, authentication, readiness, execution, or export. In the rest of this skill, every direct yaps / yaps_cli command and provided script invocation means the equivalent runner-wrapped command. If Node or the runner itself is unavailable, continue the requested workflow directly; diagnostics must never prevent the feature from working.

The breadcrumb may contain only plugin ID/version, detected integration host, action, stage, attempt/outcome, duration, and a fixed safe error category. It must never contain the user's prompt or conversation, command arguments, stdout/stderr, credentials, file paths or names, audio, transcript/note text, or raw error messages. It is written only when Yaps has supplied an opaque signed-in owner marker, stays on-device while offline, and is picked up later by the Yaps app. Never create or guess an owner marker.

CLI discovery contract

Always invoke Yaps through scripts/yaps-plugin-runner.mjs; do not locate the binary by hand. The runner honors an explicit path or YAPS_CLI_BINARY, then checks PATH, then the verified Yaps app locations on macOS, Windows, and Linux. It accepts a candidate only after a bounded, read-only status check. Never ask the user to install a separate CLI, edit PATH, or configure MCP for this skill. Never invoke the macOS GUI binary at Yaps.app/Contents/MacOS/yaps. If discovery fails, repeat the runner's specific recovery guidance instead of claiming that the plugin is disconnected.

Availability

Auto Captions commands date back to Yaps 2.0.1, but this plugin requires Yaps 2.3.124 or later for credential-free automatic account handoff. Let the runner resolve and validate the CLI automatically. If yaps captions styles is unavailable, direct the user to update Yaps before continuing. Do not claim the skill contains its own transcription or rendering engine.

Never request Yaps credentials or payment details in the AI client. Yaps no longer has a free tier. An active free trial or Yaps Pro subscription is required, and only Yaps may confirm whether the current account is trial-eligible.

Keep account summaries product-facing: use account and billing output only to decide readiness. Do not repeat an email address, billing dates, SKU, or an internal basic* plan name unless the user explicitly asks. Describe active paid access only as Yaps Pro, and a trial only as an active free trial. Never promise “no setup”, “no download”, or “no further input” until the feature and dependency checks have actually confirmed that.

Account recovery

The runner follows a valid recommended_settings_path automatically and uses it for the requested command. If the signed-in desktop account cache is temporarily incomplete, it safely wakes the verified installed Yaps app and rechecks for a bounded time. Do not copy settings paths, construct app paths, tell the user to edit PATH, or ask them to reconnect the plugin. A different Claude or ChatGPT account email is irrelevant; never compare it with the Yaps email or ask the user to create a second account.

Safe automatic account handoff requires Yaps 2.3.124 or newer. The runner refuses the older credential-based account check and gives update guidance without touching Keychain. auth status must not request a credential or display a Keychain prompt. Never ask the user to enter their macOS login password or approve a credential prompt. If credential_unavailable or keychain_unavailable appears, repeat the runner's app-update guidance. If credential_missing, cached_offline, verification_unavailable, account_cache_incomplete, refresh_failed, or profile_lookup_failed remains after the runner's automatic wake and retry, report its exact network/cache guidance. Do not add a manual reconnection step. Only unauthenticated / signed_out means sign-in is needed.

First-run onboarding

1. Confirm that Yaps 2.3.124 or later is installed through the runner. Do not ask the user to open it first, install models, or process media.
2. Run yaps auth status --pretty. Require authenticated: true and status: "active" (an active free trial or Yaps Pro both count). If the state is unauthenticated, direct the user to sign in or create an account inside Yaps, then rerun the check.
3. Do not run auth billing as an automatic gate. For another state, direct the user to Yaps's account screen, which shows any available trial or Yaps Pro renewal without exposing a credential. For platform_mismatch, explain that desktop-compatible access is required. Stop until auth status becomes active.
4. Run yaps features list --pretty. Find the auto_captions feature. If enabling it requires a model download, explain that Auto Captions reuses the same Whisper model as Subtitles and ask once for approval. If the required model is already installed and only the feature toggle is off, enable it automatically without adding an approval step. Verify readiness and resume the original task.
5. Read the render_dep block on the auto_captions feature. If ffmpeg_found is false, explain that FFmpeg is required (macOS: brew install ffmpeg, Windows: winget install Gyan.FFmpeg); do not install system packages without explicit approval. If libass_available is false, the FFmpeg build cannot burn captions and needs reinstalling with libass.
6. Resolve the exact video path and confirm it exists.

Workflow

1. Run yaps captions styles --pretty and use its returned catalogue as authoritative. If the user did not name a style, use bold-highlight as the sensible social-video default without adding a preference question. The Yaps 2.0.1 catalogue is:
   • Social and animated: bold-highlight, color-sweep, word-karaoke, spotlight, shout, glow, marker, outline, two-tone, and typewriter.
   • Clean and readable: boxed-subtitle, minimal, editorial, and caption-card.
2. Create the project: yaps captions create <video> --style <style> (use bold-highlight when the user explicitly wants the default; add --max-words <1-12> only when they request a caption-length override). Report the returned project_id, segment count, and duration.
3. Inspect the result with yaps captions show <project> --full --pretty. Present caption IDs and wording in a readable list when the user wants to review or correct them. Apply a different template with yaps captions style <project> --style <style>.
4. Make corrections, always addressing captions by their caption-NNN id:
   • yaps captions correct <project> --segment caption-003 --text "..." fixes one caption's wording.
   • yaps captions replace <project> --find "old" --with "new" fixes a phrase everywhere; when a replacement is ambiguous, show the user the proposed change first.
   • yaps captions split <project> --segment caption-003 --at <seconds> breaks one caption in two. To split after a specific word, read that word's end from yaps captions show <project> --full and pass it as --at.
   • yaps captions merge <project> --segment caption-003 --direction previous (or next) joins neighbouring captions.
   • yaps captions reset <project> rebuilds every caption from the original transcript.
5. Render the finished video: yaps captions render <project> --output "<name> (Captioned).mp4". Never pass --overwrite without explicit user confirmation, and never target the source video — Yaps refuses (output_is_source).
6. Verify the result with yaps captions verify <output> and report the finished file path. If Yaps returns no_speech, say so rather than producing an empty success.

Treat the returned JSON as authoritative. Coded failures arrive as { "error": ..., "error_code": ... }; branch on error_code (for example exists, no_audio, too_long, ffmpeg_missing).

Generalist Yaps mode

Auto Captions is this plugin's default focus, not a boundary around what it can do. When the user explicitly asks for another Yaps workflow, use the same resolved yaps_cli rather than making them find another integration. The full local surface is:

status · settings list|get|set|unset · auth status|usage|billing
features list|dictation|cleanup|reading|subtitles|auto-captions|audio-cleaner|text-in-between|background-removal|translation|meeting
vault status|list|get|create|update|move|rename|delete|search|search-semantic|daily-open|create-from-template|history-list|history-restore|pin|folders|tags|mentions|backlinks
speech synthesize (alias: tts) · srt generate
meeting transcribe|show|correct|assign|rename-speaker|export
captions styles|create|show|correct|replace|split|merge|style|reset|render|verify
media extract-audio|remove-background · audio clean · translate
history-list · usage-local

Run <cli> --help or the relevant group help before using a less familiar command. Keep the local safety rules: confirm destructive changes, existing output replacement, and large model downloads. If the session cannot reach the local CLI (for example ChatGPT web), offer a local-capable session — Claude Code, or ChatGPT desktop for a Work or Codex task — or offer to guide the user through the same workflow in Yaps → Media → Auto Captions.

Friendly completion and discovery

Lead with a warm outcome such as Done — I created …, then use a short summary, linked output files, and only useful metadata. Do not dump raw JSON or internal plan names. After a successful task, add one compact More with Yaps section with up to three relevant next steps, such as exporting an SRT, translating captions, or opening Yaps → Media → Auto Captions for visual edits. Skip it after a failure, a decline, or when the user asks for a terse result.

Boundaries

• For visual previews, fine positioning, font, size, colours, words per caption, bulk correction, or project history, open the Yaps app and go to Media → Auto Captions, where the project sits at the top of Recent projects.
• If the user wants a separate .srt subtitle file instead of a burned-in video, use Yaps Subtitle Generator.
• If the user only wants the audio track pulled out of the video, use Yaps Video to Audio.