justcaptions

面向 Agent 的 Just Captions

通过 Codex、Claude Code、任何 MCP 客户端或终端为视频添加字幕。此技能可转录语音、生成 SRT/VTT/JSON 文件，并将 TikTok/Reels 风格的字幕烧录到视频中。可一次处理一个视频，也可处理整个文件夹。

15 种动画便携预设采用 Just Captions 应用的风格系列。字体排版和采样动画可能与原生 iOS 不同。渲染在你的机器上通过 Pillow 和 ffmpeg 运行。

选择一种风格并复制任务 · API 文档 · OpenAPI · 风格目录

表情符号	Mega	Reveal

Neon	白色方框	黄色方框

灰色方框	黄色轮廓	单词高亮

高亮方框	Impact	Pop In

打字机	Cinema	Editorial

MCP 快速入门

打包版 MCP/CLI 需要 Python 3.10+、uv 和 ffmpeg。纯技能仍可在 Python 3.9+ 和 Pillow 环境中运行。

Codex — 添加到 ~/.codex/config.toml：

[mcp_servers.justcaptions]
command = "uvx"
args = ["--from", "https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl", "justcaptions-mcp"]
startup_timeout_sec = 120

[mcp_servers.justcaptions_cloud]
url = "https://api.justcaptions.com/mcp"
bearer_token_env_var = "JUSTCAPTIONS_API_KEY"

Claude Code — 合并到项目的 .mcp.json：

{
  "mcpServers": {
    "justcaptions": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl", "justcaptions-mcp"]
    },
    "justcaptions_cloud": {
      "type": "http",
      "url": "https://api.justcaptions.com/mcp",
      "headers": {"Authorization": "Bearer ${JUSTCAPTIONS_API_KEY}"}
    }
  }
}

设置 JUSTCAPTIONS_API_KEY，或通过 CLI 的 --signup YOUR_EMAIL 保存密钥。本地 MCP 也会读取 ~/.config/justcaptions/api_key。切勿将密钥放入提示词或提交中。若要在没有密钥的情况下进行语音识别，请在 uvx 参数中的 "--from" 前添加 "--with", "faster-whisper"。离线模型会在首次使用时下载。

请这样提出请求：“用 Word Highlight 为 TikTok 给 ~/Movies/intro.mp4 添加字幕。将 MP4、SRT、VTT 和 JSON 保存到 ./captioned/，并保留原文件。”

工具	用途
check_environment	检查媒体工具以及语音识别/密钥是否可用；绝不会泄露凭据
list_styles	15 种预设、可接受的覆盖项、别名和安全区域边距
preview_style	根据所选设置渲染的内嵌 PNG，无需调用付费 API
caption_video	启动视频/文件夹任务；立即返回任务 ID
get_job	轮询阶段和经过验证的各文件输出路径
get_usage	当前 API 用量和预计月费

caption_video 接受 input_path、output_dir、style_id、size、position、safe_area、length、overrides、captions_path、engine、language、translate_to、correct、glossary、burn 和 overwrite。有关类型化架构，请参阅 MCP 发现信息。每个文件夹任务最多处理 100 个文件，同时运行两个任务。任务会在本地持久保存，即使进程重启也不会丢失；可使用 list_jobs 和 resume_job 恢复任务。除非明确指定覆盖，否则现有输出会受到保护；文件夹任务会为每个源文件使用独立的输出目录。

远程 MCP

https://api.justcaptions.com/mcp 使用 Streamable HTTP 和你的 API 密钥。它处理音频和字幕文本。它无法访问本地文件、预览样式或渲染 MP4。

对于 Codex：

[mcp_servers.justcaptions_cloud]
url = "https://api.justcaptions.com/mcp"
bearer_token_env_var = "JUSTCAPTIONS_API_KEY"

对于 Claude Code，项目 .mcp.json 条目：

{"mcpServers":{"justcaptions_cloud":{"type":"http","url":"https://api.justcaptions.com/mcp","headers":{"Authorization":"Bearer ${JUSTCAPTIONS_API_KEY}"}}}}

工具：list_styles、get_pricing、get_usage、transcribe_audio、correct_captions、translate_captions、pick_emojis。云端操作使用现有 API 定价和限制。请提供唯一的 request_id，仅在重试完全相同的请求时重复使用。请求哈希和已完成的回复会保留 24 小时，然后在后续请求或每日清理时删除（48 小时内）。重放存储不会保留音频。

样式和自定义

全部 15 种预设都会在视频导出和网站预览中制作动画，效果包括语音词语高亮／显现、弹出入场、淡入淡出、打字效果或脉冲发光。

权威的版本化目录位于 skills/justcaptions/assets/styles.json：Emoji、Mega、Reveal、Neon、White box、Yellow box、Gray box、Yellow outline、Word Highlight、Highlight Box、Impact、Pop In、Typewriter、Cinema 和 Editorial。历史 CLI 名称 karaoke、black-box 和 white-outline 仍受支持。wordHighlight 等应用 ID 会映射到可移植的预设 ID。

本地 MCP 接受 overrides，例如：

{"highlight_color":"#1A9E7A","text_color":"#FFFFFF","font_multiplier":1.2,"max_words":3}

随附的命名字体可确保本地渲染结果一致。运行 justcaptions --list-fonts 或调用 MCP list_fonts；公开的 GET /v1/fonts 端点会返回相同的目录。在 overrides 或样式配置文件中设置 {"font_id":"anton"}。13 种选项包括 Inter、Poppins、Montserrat、Merriweather、Bebas Neue、Oswald、Roboto Flex、Anton、Barlow Condensed、Nunito、Caveat、Patrick Hand 和 Permanent Marker。可变字体使用目录中的粗细轴设置。命名字体优先于 font_family；"font_id":null 会恢复通用字体系列选择。这些命名字体适用于拉丁文字字幕；其他文字系统会继续使用渲染器的系统字体回退。SRT/VTT 仍是纯字幕，不会嵌入字体。

CLI 使用 --style-config FILE.json 接受相同的对象。未知键和无效值会被拒绝。颜色、背景、描边、字体系列、大小、词数和字母大小写均可配置。使用 --safe-area tiktok|reels|shorts|none；保守的边距可让字幕保持水平居中。平台 UI 布局可能有所不同。

如果文本未更改，则会保留语音识别的词语时间戳。修正／翻译后的文本和导入的纯字幕文件使用的是估算的词语时间，而非强制对齐。衬线／常规字体系列使用可用的系统字体，并以随附的 Geist 作为回退字体。

安装

你需要 ffmpeg 和带有 Pillow 的 Python 3.9+：

brew install ffmpeg          # or: sudo apt install ffmpeg
pip install Pillow
pip install faster-whisper   # optional: offline transcription

作为 Claude Code 插件

/plugin marketplace add SpaceSheepBoy/justcaptions-skill
/plugin install justcaptions@justcaptions

作为普通技能

git clone https://github.com/SpaceSheepBoy/justcaptions-skill
cp -r justcaptions-skill/skills/justcaptions ~/.claude/skills/

然后可以向 Claude 提出类似这样的请求：“为 interview.mp4 添加 emoji 样式的字幕”，或 “为 ./clips 中的所有视频烧录西班牙语字幕”。

不使用 Claude

S=skills/justcaptions/scripts
python3 $S/jc.py talk.mp4 --burn                      # talk.srt, talk.json, talk.captioned.mp4
python3 $S/jc.py clips/ --style karaoke --burn        # batch: every video in the folder
python3 $S/jc.py talk.mp4 --style emoji --burn
python3 $S/jc.py talk.mp4 --formats srt,vtt           # subtitle files only
python3 $S/jc.py talk.mp4 --captions talk.srt --burn  # burn a subtitle file you edited
python3 $S/jc.py talk.mp4 --style word-highlight --safe-area tiktok --burn --json
python3 $S/jc.py --help

选项	取值
--style	全部 15 种预设 ID 及旧名称；--list-styles --json 会返回目录
--position	top、middle、bottom，或类似 0.7 的分数
--size	small、medium、large
--length	short、medium、long：屏幕上显示的词数
--language	语音语言提示，例如 en、zh、es
--glossary	拼写正确的名称和术语："Kila Labs, Just Captions"
--engine	api 或 local（设置密钥时默认使用 API）
--correct	AI 修正识别错误（需要 API 密钥）
--translate LANG	翻译字幕（需要 API 密钥）

若要在烧录字幕前修改措辞：运行脚本时不加 --burn，编辑 NAME.json 或 NAME.srt，然后再次运行并添加 --captions NAME.json --burn。JSON 文件会保留逐词时间信息，供 karaoke 和 emoji 使用。

Just Captions API

无需密钥，所有操作都会使用 faster-whisper 离线运行。有了密钥，你还可以使用：

• 云端转录（在处理口音、嘈杂音频和多种语言时表现更好）
• --correct 和 --translate
• 为 Emoji 样式选择 AI 表情符号（离线备用方案使用关键词表）

获取密钥即时完成，无需银行卡：

python3 skills/justcaptions/scripts/jc.py --signup [email protected]

密钥会保存到 ~/.config/justcaptions/api_key（仅你可读取）。如果设置了 JUSTCAPTIONS_API_KEY，则会改用该值。

python3 skills/justcaptions/scripts/jc.py --account   # usage this month and estimated charge

定价

	价格	每月免费额度
转录	每分钟音频 $0.01，按秒计费	30 分钟
校正、翻译、表情符号	每发送 1,000 个字幕字符 $0.01	50,000 个字符

• 免费方案（无需银行卡）：免费额度用完后即停止。如果已安装 faster-whisper，转录会继续在本地进行。
• 按量付费：在 https://justcaptions.com/api/account/ 添加银行卡，即可在免费额度用完后继续使用。Stripe 会按月向你开具账单，默认月度消费上限为 $100。
• 失败的请求不会计费。

API 仅接收音频。脚本会从视频中提取一段单声道音轨，因此视频本身绝不会上传，字幕烧录也始终在你的设备上完成。API 参考：https://justcaptions.com/api/

想在 iPhone 上使用？

App Store 上的 Just Captions 可在手机上提供原生字幕样式，以及设备端转录、编辑和批量导出功能。

开发

使用 uv pip install -e . 在隔离环境中安装。Worker MCP 适配器是开源的，位于 remote/mcp.mjs；宿主会注入现有的已认证 API 处理程序。tools/sync-agent-assets.py --site SITE_DIR --backend BACKEND_DIR 会将规范目录、OpenAPI 和适配器发布到网站和 Worker 源码中。请勿单独编辑生成的副本。

python3 -m unittest discover -s tests
python3 tools/smoke-mcp.py  # exercise the installed MCP with synthetic media
python3 tools/agent-previews.py --site SITE_DIR  # regenerate videos/posters and animated README previews
python3 tools/gallery.py   # regenerate the legacy five-style PNG gallery

字幕烧录方式：每个字幕状态（卡拉 OK 和表情符号字幕中每个词对应一个状态）都会绘制为一张全帧透明 PNG。concat 解复用器会按精确时长将这些 PNG 播放为单个图像流，再通过一个 overlay 滤镜将其叠加到视频上。这样，无论字幕数量有多少，ffmpeg 命令的长度都保持不变。

许可证

代码采用 MIT 许可证。字体名称对应的许可证和原始来源网址记录在目录中；许可证文本包含在 assets/fonts/licenses/ 中（SIL OFL 1.1，以及 Permanent Marker 使用的 Apache 2.0）。随附的 Geist 字体采用 SIL OFL 1.1 许可证（skills/justcaptions/assets/fonts/OFL.txt）。

完成首次导出

安装 Python 3.10+、ffmpeg 和此软件包后，运行 justcaptions --demo --out-dir ./demo --style word-highlight。随附的人声旁白示例包含逐词时间戳，无需 API 密钥或下载模型。在 MCP 中使用 run_demo，然后使用 get_job。旁白署名见演示鸣谢。

持久化任务与账户控制

list_jobs、get_job、cancel_job 和 resume_job 用于操作保存在 ~/.local/share/justcaptions 中的任务（可通过 JUSTCAPTIONS_STATE_DIR 覆盖）。恢复任务时会跳过已完成的文件，并复用成功的云端响应。源文件必须保持不变。取消任务后，正在进行的云端请求仍可能完成并产生费用。超过服务器重放窗口的未确定云端请求需要手动检查用量，不能在不提示的情况下重复执行付费操作。

识别前请使用 estimate_video；对于编辑任务，请提供已知的 text_chars。估算不包括未知的后续文本，也不会预留额度。API 会为并发请求以原子方式预留容量，所有专用密钥共用一个账户的额度。在 https://justcaptions.com/api/account/ 管理月度支出限额、作用域密钥、有效期和撤销操作。降低限额不会移除已有费用和正在运行的预留额度。

设置和导出统计信息为可选项。只有网站访客选择加入后，JUSTCAPTIONS_METRICS_ID 才会启用复制配置中包含的计数器。这些计数器不会发送文件路径、字幕或 API 密钥。若要停用已安装客户端的统计报告，请移除该变量并重启 MCP 服务。

分发

从最新的 GitHub 发布版本安装标准 wheel：

pip install https://github.com/SpaceSheepBoy/justcaptions-skill/releases/download/v1.3.1/justcaptions_agent-1.3.1-py3-none-any.whl

GitHub Actions 会构建并检查 wheel/sdist 工件，将其附加到发布版本，并使用 GitHub OIDC 将 server.json 发布到官方 MCP Registry。所有者启用后，PyPI 发布会使用受信任的发布者；完成该注册前，网站会使用发布版本中的 wheel。

PyPI 待配置的受信任发布者信息：项目 justcaptions-agent；GitHub 所有者 SpaceSheepBoy；仓库 justcaptions-skill；工作流 release.yml；环境 pypi。注册完成后，启用仓库变量 PYPI_PUBLISH_ENABLED=true 并重新运行发布工作流。