Update to Yaps Video Captions

{
  "name": "yaps-auto-captions",
  "description": "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 173
    }
  ],
  "skill_md_contents": "---\nname: yaps-auto-captions\ndescription: 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.\n---\n\n# Yaps Video Captions\n\nTurn 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.\n\n## Runtime compatibility\n\nDo not try to guess the host or its locality from a user-agent, product name,\nor another host signal (for example ChatGPT web versus ChatGPT desktop). Test\nthe capability this workflow actually needs: before account, model, dependency,\nor input-file checks, resolve the local Yaps CLI through the plugin runner. The\nrunner validates it with a bounded, read-only `status` command. A cloud shell\nthat cannot see the installed Yaps app is not local access to the user's\ncomputer.\n\nIf the Yaps CLI is unreachable, do not claim that Yaps is uninstalled and do\nnot begin repeated sign-in, model, or permission troubleshooting. Explain that\nthe current AI session cannot reach the Yaps engine installed on this computer.\nDirect the user to a local-capable session on the\ncomputer where Yaps is installed: in Claude, that\nis Claude Code or the Claude desktop app; from ChatGPT web or a cloud session,\n[download or open ChatGPT desktop](https://chatgpt.com/download/) and retry in a\nlocal-capable Work or Codex session. They can also access this feature directly\nin the Yaps application. If they are already in a local-capable desktop session,\noffer [Download or update Yaps](https://yaps.ai/download), ask them to open it,\nand retry. Stop until local reachability is restored; only then follow the\navailability and onboarding steps below.\n\n## Private operational diagnostics\n\nRun every local Yaps CLI command and every bundled workflow script through the\nplugin's `scripts/yaps-plugin-runner.mjs`. The runner resolves the installed\nYaps CLI when the command begins with `yaps`, preserves the command's normal\noutput and exit status, and leaves a small local diagnostic breadcrumb for the\nYaps desktop app:\n\n```text\nnode <plugin-root>/scripts/yaps-plugin-runner.mjs --action auth.status --stage authentication -- yaps auth status --pretty\n```\n\nChoose a stable, content-free action such as `cli.reachability`,\n`auth.status`, `features.list`, `dictation.setup`,\n`transcription.run`, or `export.create`; use the matching stage:\n`reachability`, `authentication`, `readiness`, `execution`, or\n`export`. In the rest of this skill, every direct `yaps` / `yaps_cli`\ncommand and provided script invocation means the equivalent runner-wrapped\ncommand. If Node or the runner itself is unavailable, continue the requested\nworkflow directly; diagnostics must never prevent the feature from working.\n\nThe breadcrumb may contain only plugin ID/version, detected integration host,\naction, stage, attempt/outcome, duration, and a fixed safe error category. It\nmust never contain the user's prompt or conversation, command arguments,\nstdout/stderr, credentials, file paths or names, audio, transcript/note text,\nor raw error messages. It is written only when Yaps has supplied an opaque\nsigned-in owner marker, stays on-device while offline, and is picked up later\nby the Yaps app. Never create or guess an owner marker.\n\n## CLI discovery contract\n\nAlways invoke Yaps through `scripts/yaps-plugin-runner.mjs`; do not locate the\nbinary by hand. The runner honors an explicit path or `YAPS_CLI_BINARY`, then\nchecks `PATH`, then the verified Yaps app locations on macOS, Windows, and\nLinux. It accepts a candidate only after a bounded, read-only `status` check.\nNever ask the user to install a separate CLI, edit `PATH`, or configure MCP for\nthis skill. Never invoke the macOS GUI binary at\n`Yaps.app/Contents/MacOS/yaps`. If discovery fails, repeat the runner's specific\nrecovery guidance instead of claiming that the plugin is disconnected.\n\n## Availability\n\nAuto 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.\n\nNever 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.\n\nKeep 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.\n\n## Account recovery\n\nThe runner follows a valid `recommended_settings_path` automatically and uses\nit for the requested command. If the signed-in desktop account cache is\ntemporarily incomplete, it safely wakes the verified installed Yaps app and\nrechecks for a bounded time. Do not copy settings paths, construct app paths,\ntell the user to edit `PATH`, or ask them to reconnect the plugin. A different\nClaude or ChatGPT account email is irrelevant; never compare it with the Yaps\nemail or ask the user to create a second account.\n\nSafe automatic account handoff requires Yaps 2.3.124 or newer. The runner\nrefuses the older credential-based account check and gives update guidance\nwithout touching Keychain. `auth status` must not request a credential or\ndisplay a Keychain prompt. Never\nask the user to enter their macOS login password or approve a credential\nprompt. If `credential_unavailable` or `keychain_unavailable` appears, repeat\nthe runner's app-update guidance. If `credential_missing`, `cached_offline`,\n`verification_unavailable`, `account_cache_incomplete`, `refresh_failed`, or\n`profile_lookup_failed` remains after the runner's automatic wake and retry,\nreport its exact network/cache guidance. Do not add a manual reconnection step.\nOnly `unauthenticated` / `signed_out` means sign-in is needed.\n\n## First-run onboarding\n\n1. 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.\n2. 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.\n3. 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.\n4. 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.\n5. 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`, Debian/Ubuntu Linux: `sudo apt install ffmpeg`; on other Linux distributions use the native package that includes libass). Do not install system packages without explicit approval. If `libass_available` is false, the FFmpeg build cannot burn captions and needs reinstalling with libass.\n6. Resolve the exact video path and confirm it exists.\n\n## Workflow\n\n1. 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 curated catalogue is:\n   - Bold social: `bold-highlight`, `shout`, `spotlight`, `pulse`, `marker`.\n   - Karaoke / sweep: `color-sweep`, `word-karaoke`.\n   - Boxed / pill: `boxed-subtitle` (Lower Third), `caption-card` (Paper).\n   - Editorial / cinematic: `minimal`, `editorial`, `typewriter`, `glass`, `cinema`.\n   Retired ids (`glow`, `outline`, `two-tone`, `frosted-sweep`) remap to a live look.\n2. 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.\n3. 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>`.\n4. Make corrections, always addressing captions by their `caption-NNN` id:\n   - `yaps captions correct <project> --segment caption-003 --text \"...\"` fixes one caption's wording.\n   - `yaps captions replace <project> --find \"old\" --with \"new\"` fixes a phrase everywhere; when a replacement is ambiguous, show the user the proposed change first.\n   - `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`.\n   - `yaps captions merge <project> --segment caption-003 --direction previous` (or `next`) joins neighbouring captions.\n   - `yaps captions reset <project>` rebuilds every caption from the original transcript.\n5. 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`).\n6. 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.\n\nTreat 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`).\n\n## Generalist Yaps mode\n\nAuto Captions is this plugin's default focus, not a boundary around what it can\ndo. When the user explicitly asks for another Yaps workflow, use the same\nresolved `yaps_cli` rather than making them find another integration. The full\nlocal surface is:\n\n```text\nstatus · settings list|get|set|unset · auth status|usage|billing\nfeatures list|dictation|cleanup|reading|subtitles|auto-captions|audio-cleaner|text-in-between|background-removal|translation|meeting\nvault 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\nspeech synthesize (alias: tts) · srt generate\nmeeting transcribe|show|correct|assign|rename-speaker|export\ncaptions styles|create|show|correct|replace|split|merge|style|reset|render|verify\nmedia extract-audio|remove-background|generate-image · audio clean · translate\nhistory-list · usage-local\n```\n\nRun `<cli> --help` or the relevant group help before using a less familiar\ncommand. Keep the local safety rules: confirm destructive changes, existing\noutput replacement, and large model downloads. If the session cannot reach the\nlocal CLI (for example ChatGPT web), offer a local-capable session — Claude\nCode, or [ChatGPT desktop](https://chatgpt.com/download/) for a Work or Codex\ntask — or offer to guide the user through the same workflow in\n**Yaps → Media → Auto Captions**.\n\n## Friendly completion and discovery\n\nLead with a warm outcome such as **Done — I created …**, then use a short\nsummary, linked output files, and only useful metadata. Do not dump raw JSON or\ninternal plan names. After a successful task, add one compact **More with Yaps**\nsection with up to three relevant next steps, such as exporting an SRT,\ntranslating captions, or opening **Yaps → Media → Auto Captions** for visual\nedits. Skip it after a failure, a decline, or when the user asks for a terse\nresult.\n\n## Boundaries\n\n- 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.\n- If the user wants a separate `.srt` subtitle file instead of a burned-in video, use Yaps Subtitle Generator.\n- If the user only wants the audio track pulled out of the video, use Yaps Video to Audio.\n"
}