# AutoSubtitles for AI agents

Add styled, burned-in captions to a local video, or generate SRT/VTT subtitle files from it, with the `autosubtitles` command. Speech is transcribed by AutoSubtitles and the captions are rendered locally inside the user's own Chrome. Only the audio track is uploaded; the video stays on the machine.

Human-readable page: https://autosubtitles.com/agent
Source and agent skill: https://github.com/autosubtitles/skills
npm package: https://www.npmjs.com/package/autosubtitles

## Install as a skill

Any one of these:

```bash
npx autosubtitles install            # adds the skill to every agent on the machine
npx skills add autosubtitles/skills  # through skills.sh
```

Or as a Claude Code plugin, typed inside Claude Code:

```
/plugin marketplace add autosubtitles/skills
/plugin install autosubtitles@autosubtitles
```

After that the user can ask in plain words, for example "Caption talk.mp4 in the Karaoke style." Without the skill, the commands below work as they are.

## Requirements

- Node.js 20 or later
- Google Chrome or Microsoft Edge installed on the same machine
- A shell on the user's machine. Cloud-only agents cannot use this, because it needs a local browser.

## Commands

| Command | What it does |
|---|---|
| `npx autosubtitles <video> --preset <style> --json` | Caption a video directly, in a named style. No window |
| `npx autosubtitles review <video> --json` | Open a small window: the user picks a style, optionally checks captions, clicks Render. Blocks until they do |
| `npx autosubtitles review <video> --live --json` | The same window as a conversation: returns at once, then `poll` for what the user does and `reply` with changes |
| `npx autosubtitles poll --json` | Live: wait for the next event (`steer`, `render`, `cancel`, `timeout`, `waiting`) |
| `npx autosubtitles reply --steer <id> --set key=value --replace "a=>b" --message "…" --json` | Live: apply changes in the window while the user watches |
| `npx autosubtitles close --json` | Live: end the session |
| `npx autosubtitles presets --json` | List caption styles |
| `npx autosubtitles plan --json` | Free or Pro, and what each allows |

Render directly when the user named a style. Open a window when they did not, or when they want to see styles or check captions. Never open a window when nobody is at the computer. The full reference, including every value `--set` accepts, is in the skill: https://github.com/autosubtitles/skills/tree/main/skills/autosubtitles

## Before the first render: free or Pro

```bash
npx autosubtitles plan --json
```

Returns `{ "plan": "free" | "licensed", ... }`. It never prints the license key or any account details. If the plan is `licensed`, carry on. If it is `free`, tell the user the difference and ask which they want before rendering:

| | Free | Pro |
|---|---|---|
| Watermark | AutoSubtitles logo on the video | None |
| Resolution | Up to 720p | Up to 4K |
| Video length | Up to 10 minutes | No limit |
| Subtitle files (SRT, VTT, word timings) | No | Yes |

Do not ask again when the user has already chosen. If they only want subtitle files and the plan is `free`, tell them that needs Pro instead of running the command.

## Caption a video

```bash
npx autosubtitles <video> --preset <style> --json
```

Prints one JSON object on stdout:

```json
{
  "ok": true,
  "outputs": { "mp4": "/abs/path/video.captioned.mp4" },
  "durationSeconds": 60,
  "captionCount": 32,
  "seconds": 8.3,
  "preset": "Karaoke",
  "watermark": true,
  "maxShortSide": 720,
  "skipped": []
}
```

Tell the user where the files are. If the result has a `notice` field, pass it on once: it means the export used the free tier.

## Choose a style

```bash
npx autosubtitles presets --json
```

Returns `[{ "id": "...", "name": "..." }]`. If the user named a style, match it to an `id`. Otherwise use `classic` for talking-head or business video and `beast` for short-form social video, and say which you picked.

The transcript is cached on the user's machine, in the system cache folder and never beside the video, so re-rendering in another style does not transcribe again.

## Subtitle files (Pro)

Add `--srt`, `--vtt` or `--words` to the caption command to write subtitle files beside the video. On the free plan these are skipped and listed in the result's `skipped` field. To get only the files:

```bash
npx autosubtitles <video> --captions-only --srt --vtt --json
```

`--words` also writes word-level timings as JSON.

## Options

| Flag | Meaning |
|---|---|
| `-o, --output <path>` | Output MP4. Default `<name>.captioned.mp4` beside the input |
| `-p, --preset <id>` | Caption style. Default `classic` |
| `--lang <code>` | Spoken language such as `en`, `es`, `de`. Default auto-detect |
| `--res <shortSide>` | `720`, `1080`, `1440` or `2160`. Above 720 needs a license |
| `--no-cache` | Transcribe again, ignoring the cached transcript |
| `--headed` | Show the browser window |

## Errors

With `--json`, a failure prints `{ "ok": false, "error": { "code", "message" } }` and exits non-zero.

| Exit | Meaning | What to do |
|---|---|---|
| 2 | Bad arguments, unknown preset, or file not found | Fix the command. Run `presets` to see valid styles |
| 3 | No Chrome or Edge installed | Ask the user to install Google Chrome |
| 4 | Needs Pro (subtitle files only, or a video over 10 minutes), or a rate limit | Tell the user what Pro adds. Do not retry |
| 5 | Transcription failed | Check the video has speech, then retry once |
| 6 | Render failed | Retry once with `--headed`, then report the message |

## Free and licensed use

Free: captioned video, watermarked, up to 720p, videos up to 10 minutes. Pro: no watermark, up to 4K, no length limit, plus SRT, VTT and word-timing files. Get Pro: https://autosubtitles.com

Never ask for, read, print or store a license key. If the user wants licensed output, tell them to set `AUTOSUBTITLES_LICENSE_KEY` in their own shell.