video-tool

Video Tool CLI

由 AI 驱动的视频处理工具包，支持 ffmpeg 操作、本地或远程 Parakeet/Whisper 转录和内容生成。

安装状态

video-tool: !which video-tool > /dev/null && echo "INSTALLED" || echo "NOT INSTALLED - run installation below" uv: !which uv > /dev/null && echo "INSTALLED" || echo "NOT INSTALLED"

如果尚未安装 video-tool，请先运行下面的安装命令，再继续操作。

安装

# Install uv first (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install video-tool
uv tool install git+https://github.com/alejandro-ao/video-tool-cli.git

依赖项

• ffmpeg：所有视频操作都需要（macOS 上运行 brew install ffmpeg）
• yt-dlp：下载视频时需要（macOS 上运行 brew install yt-dlp）
• 本地转录运行时为可选项；请安装 Transcription & Timestamps 下介绍的平台专用扩展

API 密钥设置

配置 API 密钥（选择一种方式）：

选项 1：非交互式（推荐用于 Claude Code）

video-tool config keys --set groq_api_key=YOUR_KEY
video-tool config keys --set openai_api_key=YOUR_KEY
# Multiple at once:
video-tool config keys --set groq_api_key=xxx --set openai_api_key=yyy

选项 2：直接编辑凭据文件 如果用户不想与 Claude Code 分享密钥，可以直接编辑：

# File: ~/.config/video-tool/credentials.yaml
openai_api_key: sk-xxx
groq_api_key: gsk_xxx
bunny_library_id: xxx
bunny_access_key: xxx
replicate_api_token: xxx

选项 3：交互式设置

video-tool config keys

必需的密钥：

• openai_api_key - CLI 内容生成（描述、上下文卡片、基于转录内容的时间戳）

可选密钥：

• groq_api_key - 远程 Groq Whisper 转录；本地模型不需要此密钥
• bunny_library_id、bunny_access_key - 上传到 Bunny.net CDN
• replicate_api_token - 音频增强

video-tool config keys --show   # View configured keys (masked)
video-tool config keys --reset  # Clear all credentials

重要：处理身份验证错误

当命令因出现 "AUTHENTICATION REQUIRED" 或 "API key not configured" 而失败时：

1. 不要尝试编写自定义脚本来绕过问题
2. 不要尝试直接调用 API
3. 应当使用 AskUserQuestion 向用户提供两个选项：

选项 A：向 Claude 提供密钥（方便）

• 用户直接向你提供 API 密钥
• 你运行：video-tool config keys --set KEY_NAME=VALUE
• 更快捷，但密钥会显示在对话中

选项 B：用户自行私下配置（更安全）

• 用户自行运行命令或直接编辑文件
• 密钥不会出现在与 Claude 的对话中
• 告诉用户运行：video-tool config keys（交互式）
• 或编辑：~/.config/video-tool/credentials.yaml

AskUserQuestion 提示示例： "此命令需要 [Groq/OpenAI] API 密钥。你希望如何配置？"

• 选项 1："我会提供密钥" - 更方便，但 Claude 能看到密钥
• 选项 2："我会自行配置" - 更私密，Claude 看不到密钥

用户完成配置后（无论选择哪种方式），重试原始命令。

需要凭据的命令：

• video-tool generate transcript -m groq/whisper-large-v3-turbo → 需要 Groq API 密钥
• 本地转录模型 → 无需 API 密钥，但必须安装其可选运行时
• video-tool video timestamps -m transcript → 需要 OpenAI API 密钥（结构化输出）
• video-tool upload bunny-* → 需要 Bunny.net 凭据
• video-tool video enhance-audio → 需要 Replicate API 令牌
• video-tool upload x / video-tool upload twitter → 需要 X OAuth 凭据（运行 video-tool config x-auth）
• video-tool upload linkedin → 需要 LinkedIn 访问令牌 + 作者 URN（运行 video-tool config keys 或传入标志）

---

内容生成：CLI 命令与直接生成

某些 CLI 命令会使用 OpenAI 生成内容。Claude 使用此技能时，通常由 Claude 直接生成内容会比调用另一个大模型更好。

使用 CLI 命令（需要 OpenAI API 密钥）：

• video timestamps -m transcript - 使用结构化输出生成精确的 JSON

直接使用 Claude 生成（无需 OpenAI）：

对于这些任务，请阅读转录文本／时间戳，并使用链接的模板生成内容：

• 描述：参见 templates/description.md
• SEO 关键词：参见 templates/seo-keywords.md
• LinkedIn/Twitter 帖子：参见 templates/social-posts.md
• 上下文卡片：参见 templates/context-cards.md

关于 CLI 命令的说明

CLI 提供 generate description、generate context-cards 等命令，这些命令会使用 OpenAI。它们用于手动使用 CLI。如果用户明确要求使用 CLI 命令，请按要求执行（可能需要 OpenAI 密钥）。否则，请直接生成内容。

---

输出位置

生成文件（转录文本、描述、时间戳等）之前，如果用户尚未指定保存位置，请使用 AskUserQuestion 询问用户要将文件保存在哪里。

示例提示： “我应该将输出文件保存在哪里？”

• 选项 1：“当前目录”——保存到 . 或 ./output/
• 选项 2：“与视频相同的文件夹”——与源视频保存在同一位置
• 选项 3：“我会指定路径”——由用户提供自定义位置

**用户未指定时的默认行为：**先询问，不要擅自假定使用临时目录。

---

长时间运行的操作：使用 tmux

对于下载和任何可能耗时的视频操作，请在命名的 tmux 会话中运行命令，而不是让 Agent shell 阻塞。这包括 YouTube／视频下载、上传、移除静音片段、音频增强、转录以及大型渲染／转码任务。

推荐模式：

# Start the job in the background
tmux new-session -d -s video_download 'video-tool video download -u "URL" -o "./output/video.mp4"'

# Check progress/log output
tmux capture-pane -pt video_download

# Reattach if needed
tmux attach -t video_download

# Clean up after completion
tmux kill-session -t video_download

使用描述性会话名称，例如 video_download、video_transcribe、video_upload 或 video_process_<slug>。启动 tmux 任务后，使用 tmux capture-pane -pt <session> 监控，直到任务完成，然后确认预期的输出文件确实存在。

---

YouTube 身份验证

对于 YouTube 上传，请运行 OAuth2 设置：

video-tool config youtube-auth

---

命令参考

视频处理

下载视频

从 YouTube 或其他受支持的网站下载。

video-tool video download -u "URL" -o ./output/my-video.mp4
video-tool video download -u "URL" -o ./output/%(title)s.%(ext)s

选项	描述
-u, --url	视频 URL
-o, --output-path	输出文件路径（目录将使用标题模板；默认值为 ./output/%(title)s.%(ext)s）

获取视频信息

获取元数据：时长、分辨率、编解码器、比特率。

video-tool video info -i video.mp4

移除静音片段

移除视频中的静音片段。

video-tool video silence-removal -i input.mp4 -o output.mp4 -t 1.0

选项	描述
-i, --input	输入视频
-o, --output-path	输出路径
-t, --threshold	要移除的最短静音时长（默认值：1.0s）

裁剪视频

从视频开头和／或结尾剪切。

video-tool video trim -i input.mp4 -o output.mp4 -s 00:00:10 -e 00:05:00

选项	描述
-s, --start	开始时间戳（HH:MM:SS、MM:SS 或秒数）
-e, --end	结束时间戳
-g, --gpu	使用 GPU 加速

提取片段

仅保留视频中的特定片段。

video-tool video extract-segment -i input.mp4 -o output.mp4 -s 00:01:00 -e 00:02:30

剪去片段

移除视频中间的一段。

video-tool video cut -i input.mp4 -o output.mp4 -f 00:01:00 -t 00:02:00

选项	描述
-f, --from	要移除片段的起始位置
-t, --to	要移除片段的结束位置

更改速度

加快或减慢视频播放速度。

video-tool video speed -i input.mp4 -o output.mp4 -f 1.5

选项	描述
-f, --factor	速度倍率（0.25-4.0）。2.0=两倍速，0.5=半速
-p, --preserve-pitch	保持原始音调（默认值：是）

拼接视频

将多个视频合并为一个。

video-tool video concat -i ./clips/ -o ./output/final.mp4 -f

选项	描述
-i, --input-dir	存放视频的目录
-o, --output-path	输出文件路径
-f, --fast-concat	跳过重新编码（速度更快，但要求编解码器相同）

音频操作

提取音频

将音轨提取为 MP3。

video-tool video extract-audio -i video.mp4 -o audio.mp3

增强音频

使用 Resemble AI 提高音频质量（需要 Replicate API 令牌）。

video-tool video enhance-audio -i input.mp4 -o enhanced.mp4
video-tool video enhance-audio -i input.mp4 -o denoised.mp4 -d  # denoise only

替换音频

替换视频中的音轨。

video-tool video replace-audio -v video.mp4 -a new_audio.mp3 -o output.mp4

转录与时间戳

生成转录文本

使用自动选择的已安装运行时、指定的本地模型或 Groq 创建 VTT 字幕。

在一台机器上首次转录前，请查看推荐内容和可用的模型 ID：

video-tool config transcription --recommend
video-tool config transcription --list-models

需要本地转录时，请安装适当的可选运行时：

# Apple Silicon: MLX Parakeet (English) and MLX Whisper (multilingual)
uv tool install --force 'video-tool[transcription-mlx] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# Portable CPU/CUDA Whisper
uv tool install --force 'video-tool[transcription-faster-whisper] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# Standard Hugging Face Transformers Whisper
uv tool install --force 'video-tool[transcription-transformers] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# NVIDIA NeMo Parakeet on Linux/CUDA
uv tool install --force 'video-tool[transcription-nemo] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

使用自动选择或指定的模型进行转录：

video-tool generate transcript -i video.mp4 -o transcript.vtt
video-tool generate transcript -i video.mp4 -o transcript.vtt -m mlx/parakeet-tdt-0.6b-v2 --language en
video-tool generate transcript -i video.mp4 -o transcript.vtt -m mlx/whisper-large-v3-turbo --language es
video-tool generate transcript -i video.mp4 -o transcript.vtt -m groq/whisper-large-v3-turbo

模型建议：

• Apple Silicon + 英语：mlx/parakeet-tdt-0.6b-v2
• Apple Silicon + 多语言：mlx/whisper-large-v3-turbo
• 通用 CPU/CUDA：faster-whisper/large-v3-turbo
• 标准 Transformers/MPS/CUDA：transformers/whisper-large-v3-turbo
• NVIDIA Linux/CUDA + 英语：nemo/parakeet-tdt-0.6b-v2
• 无本地运行时或偏好远程处理：groq/whisper-large-v3-turbo

Parakeet TDT 0.6B V2 仅支持英语。模型会在首次使用时下载并缓存在本地。缺少可选运行时时，会显示安装命令。只有 Groq 转录需要 Groq API 密钥。

高级选项：

选项	描述
--backend	后端覆盖项：auto、groq、mlx-parakeet、mlx-whisper、faster-whisper、transformers、nemo
-m, --model	已注册的模型 ID；优先于仅选择后端
--language	auto 或语言代码，例如 en、es 或 fr
--device	auto、cpu、mps 或 cuda
--compute-type	运行时精度，例如 float16 或 int8

保存或查看默认设置：

video-tool config transcription --model mlx/parakeet-tdt-0.6b-v2 --language en
video-tool config transcription --show
video-tool config transcription --reset

使用此技能时，如果已安装相应运行时，请优先选择推荐的本地模型。安装大型可选运行时或下载模型权重前，请先征求用户同意。如果用户偏好远程处理，或本地硬件/运行时不适用，请使用 Groq。

生成时间戳

创建章节标记（转录模式需要 OpenAI API 密钥）。

# From video clips directory
video-tool video timestamps -m clips -i ./clips/ -o timestamps.json

# From transcript
video-tool video timestamps -m transcript -i transcript.vtt -o timestamps.json -g medium

选项	描述
-m, --mode	clips 或 transcript
-g, --granularity	low、medium、high（转录模式）
-n, --notes	给 LLM 的其他指示

上传

上传到 YouTube

将视频作为草稿上传（需要通过 video-tool config youtube-auth 进行 OAuth2 身份验证）。

video-tool upload youtube-video -i video.mp4 -t "Title" -d "Description" -p private
video-tool upload youtube-video -i video.mp4 --metadata-path metadata.json

选项	描述
-t, --title	视频标题
-d, --description	描述文本
--description-file	从文件读取描述
--tags	逗号分隔的标签
--tags-file	从文件读取标签（每行一个）
-c, --category	YouTube 类别 ID（默认值：27 Education）
-p, --privacy	仅限 private（草稿）或 unlisted
--thumbnail	缩略图图片路径

更新 YouTube 元数据

更新现有视频的元数据。

video-tool upload youtube-metadata -v VIDEO_ID --description-file description.md

上传 YouTube 转录文本

为 YouTube 视频添加字幕。

video-tool upload youtube-transcript -v VIDEO_ID -t transcript.vtt -l en

上传到 Bunny.net

上传到 Bunny.net CDN（需要通过 config keys 配置 Bunny 凭据）。

video-tool upload bunny-video -v video.mp4
video-tool upload bunny-transcript -v VIDEO_ID -t transcript.vtt
video-tool upload bunny-chapters -v VIDEO_ID -c timestamps.json

发布 X（Twitter）帖子

在 X（Twitter）上发布串文（需要通过 video-tool config x-auth 进行 X OAuth 身份验证）。

video-tool upload x --text "First post" --thread-item "Follow-up" --video-path video.mp4
video-tool upload twitter --text-file post.txt --thread-file thread.txt

选项	描述
--text / --text-file	首条帖子文本
--thread-item / --thread-file	其他串文条目（可重复使用，或以 --- 分隔）
--video-path / --video-url	要包含的视频文件或 URL
--output-dir	元数据输出目录

发布 LinkedIn 帖子

发布 LinkedIn 帖子（需要通过 video-tool config keys 配置 LinkedIn 凭据）。

video-tool upload linkedin --text-file post.md --video-path video.mp4

选项	描述
--text / --text-file	帖子文本
--video-path / --video-url	要包含的视频文件或 URL
--output-dir	元数据输出目录
--access-token	覆盖访问令牌
--author-urn	覆盖作者 URN

配置

video-tool config keys                        # Configure API keys (interactive)
video-tool config keys --set KEY=VALUE        # Set key non-interactively
video-tool config keys --show                 # View configured keys
video-tool config llm                         # Configure LLM settings and persistent links
video-tool config transcription --recommend  # Recommend a transcription model
video-tool config transcription --list-models # List supported transcription models
video-tool config transcription --show       # Show saved transcription defaults
video-tool config x-auth                      # Set up X OAuth credentials
video-tool config youtube-auth                # Set up YouTube OAuth2
video-tool config youtube-status              # Check YouTube credentials

---

技能的命令模板

其他技能可按名称引用的常见任务。

转录视频

使用自动选择或指定模型，从视频/音频文件生成 VTT 转录文本。

video-tool config transcription --recommend
video-tool generate transcript -i <INPUT_FILE> -o <OUTPUT_FILE> [-m <MODEL_ID>] [--language <LANGUAGE>]

输入：

• <INPUT_FILE>：视频或音频文件的路径
• <OUTPUT_FILE>：输出 VTT 文件的路径
• <MODEL_ID>：可选的已注册本地模型或 Groq 模型 ID
• <LANGUAGE>：可选的语言代码；使用 Parakeet 时请用 en

**要求：**所选的本地运行时扩展，或仅在选择 Groq 时使用 Groq API 密钥

---

拼接视频

将多个视频片段合并为一个文件。

video-tool video concat -i <INPUT_DIR> -o <OUTPUT_FILE> --fast-concat

输入：

• <INPUT_DIR>：包含编号片段的目录（01-.mp4、02-.mp4 等）
• <OUTPUT_FILE>：输出视频文件的路径
• --fast-concat：跳过重新处理（可选，推荐用于提高速度）

**注意：**片段必须以数字前缀命名，才能按正确顺序排列。

---

根据片段生成时间戳

根据片段文件名创建章节时间戳。

video-tool video timestamps --mode clips -i <INPUT_DIR> -o <OUTPUT_FILE>

输入：

• <INPUT_DIR>：包含编号片段的目录
• <OUTPUT_FILE>：输出 JSON 文件的路径

输出格式：

{
  "timestamps": [
    {"time": "00:00:00", "title": "Introduction"},
    {"time": "00:05:30", "title": "Main Content"}
  ]
}

---

上传到 YouTube

将视频及其元数据上传到 YouTube。

video-tool upload youtube-video \
  -i <VIDEO_FILE> \
  -t "<TITLE>" \
  --description-file <DESCRIPTION_FILE> \
  --tags-file <TAGS_FILE> \
  --privacy <PRIVACY>

输入：

• <VIDEO_FILE>：视频文件的路径
• <TITLE>：视频标题（加引号）
• <DESCRIPTION_FILE>：Markdown 描述文件的路径
• <TAGS_FILE>：包含标签的文本文件的路径（每行一个）
• <PRIVACY>：private、unlisted 或 public

**要求：**YouTube OAuth2 身份验证（video-tool config youtube-auth）

**输出：**包含 video_id 和 url 的 JSON（保存到 youtube-upload.json，供发布技能使用）

---

常见工作流

详细示例请参见 workflows.md。