# Yaps Auto Captions

> Add editable, styled, word-timed captions to a video and export a new burned-in MP4 through the installed Yaps desktop engine. Trigger for add captions to video, auto caption video, caption a video, video subtitle editor, animated captions, TikTok captions, Instagram Reels captions, YouTube Shorts captions, karaoke captions, word-by-word captions, burn subtitles into video, or subtitle a video into a finished file. Do not use when the user only wants a separate .srt subtitle file (use yaps-srt-generator) or a plain-text transcript.

- Skill: `richawo/yaps-auto-captions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add richawo/yaps-auto-captions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richawo/yaps-auto-captions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: richawo (https://skillmd.com/u/richawo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/richawo/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](https://chatgpt.com/download/) 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](https://yaps.ai/download), 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:

```text
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:

```text
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](https://chatgpt.com/download/) 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.