opc - AI 创作工具链

TTS + ASR + 音频处理 + AI 图片生成/编辑 + MiniMax H3/LTX 视频生成与理解 + 视频剪辑。

环境安装

curl -LsSf https://astral.sh/uv/install.sh | sh
cd ~/.claude/skills/opc-cli
uv sync

跨平台：Linux 用 CUDA，macOS 用 MLX，命令一致。

模型下载源：

opc config --set-model-source modelscope   # 默认
opc config --set-model-source huggingface  # 备选
opc config --set-model-cache-dir /vol2/1000/llm/models

快速开始

opc discover --set-default          # 发现播放设备
opc tts "你好" -e edge-tts          # 生成语音
opc say "你好"                       # 生成并播放
opc asr audio.mp3 --format srt      # 生成字幕
opc music --caption "Warm indie pop" --lyrics-file lyrics.txt  # 生成音乐
opc image -w ernie-turbo -p "a cat"  # AI 生图
opc video -w h3-t2v -p "a rainy neon street"  # H3 视频
opc video-gen i2v --image frame.png -p "slow camera push-in"  # 图生视频
opc image kg skeleton subject:food style:photography  # KG prompt 规划

所有命令通过 uv run python scripts/opc.py 执行。

TTS 命令

opc tts <text> — 生成语音文件

opc tts "你好" -e edge-tts                           # edge-tts
opc tts "你好" -e edge-tts --rate +20% --pitch +5Hz  # 带语速/音调
opc tts "你好" -e qwen --speaker Vivian              # qwen 内置音色
opc tts "你好" -e qwen --instruct "用愤怒的语气说"    # 情绪指令
opc tts "你好" -e qwen --mode voice_design --instruct "温柔的女声"  # 声音设计
opc tts "你好" -e qwen --mode voice_clone --ref-audio ref.wav --ref-text "参考"  # 克隆

参数： -e 引擎(edge-tts|qwen)、-v 音色、-l 语言、-o 输出路径、--stdin 从 stdin 读 edge-tts： --rate、--pitch、--volume qwen： -m 模式(custom_voice|voice_design|voice_clone)、-s 音色、-i 情绪指令、--ref-audio、--ref-text

opc say <text> — 生成并播放

参数同 tts，额外 -d 指定播放设备。

opc voices / opc discover

opc voices -e edge-tts   # 322 个音色
opc voices -e qwen       # 9 个内置音色
opc discover --set-default

ASR Pipeline

4 阶段 Pipeline：ASR + Forced Alignment → Sentence Breaking → CSV Fix → Render

opc asr audio.mp3                    # 转录到 stdout
opc asr audio.mp3 --format srt       # 生成 SRT + ASS
opc asr audio.mp3 --format json -o result.json
opc asr audio.mp3 --format srt --fix-dir ./fixes             # CSV 修正
opc asr audio.mp3 --format srt --resume-from break           # 从断句阶段恢复

参数： --format(text|json|srt|ass)、--language、--model-size(1.7B|0.6B)、--style、--fix-dir、--resume-from(asr|break|fix|render)

断句规则

两遍扫描：Pass 1 按句号分段，Pass 2 按逗号断行。没有标点绝对不断行。 超长行由 Check 标记，用 opc asr-split 手动拆分：

opc asr-split audio.lines.json --line 10 --after "理解，"
opc asr audio.mp3 --format srt --resume-from render

CSV 修正格式

在 --fix-dir 放 fix_1.csv, fix_2.csv...，格式：原文本，新文本（新文本留空=删除行）。# 开头为注释。

Image 命令

AI 图片生成 + 图片编辑 + Prompt 知识图谱 + 模板系统。详见 references/image.md。

工作流从 ~/.opc_cli/opc/workflows/ 和仓库内置目录合并发现，用户目录中的同名 alias 优先。用 opc image list 查看本机实际可用的图片和视频工作流。

核心流程：

opc image list                                        # 列出可用工作流
opc image -w ernie-full -p "..."                      # 文生图
opc image -w ideogram4 --text -p "poster design"       # Ideogram 4 生图
opc image-edit --image photo.png -p "add a red hat"   # 图片编辑
opc image kg skeleton subject:food style:photography   # KG 规划
opc image analyze output.png --describe               # 分析

opc image list / info / import — 工作流管理

opc image list                    # 列出可用工作流
opc image info ernie-turbo        # 查看工作流参数详情
opc image import workflow.json --name my-workflow  # 导入工作流

opc image analyze — 图片/工作流分析

opc image analyze output.png --describe     # 视觉模型描述图片
opc image analyze output.png --describe --compare ref.png  # 对比两张图片
opc image analyze workflow.json             # 分析工作流 JSON 结构

opc image test — 工作流连通性测试

opc image test ernie-turbo --prompt "test image"  # 测试工作流连通性

opc image — 文生图

opc image -w ernie-turbo -p "a cat sitting on a windowsill"
opc image -w ernie-full -p '{"subject":"美食摄影","style":"photography"}'
opc image -w klein -p "a beautiful landscape"

参数： -w 工作流别名、-p 提示词、-P 工作流参数 key=value、--text 纯文本模式

opc image-edit — 图片编辑

基于 Klein-Edit 等工作流的图片编辑，需要提供输入图片和编辑指令。

opc image-edit --image photo.png -p "add a red hat to the person"
opc image-edit -w klein-edit --image photo.png -p "make it look like a painting"
opc image-edit --image ref1.png --image ref2.png -p "blend these two images"
opc image-edit --image photo.png -p "add sunset" --param steps=30 --param seed=42

参数： -w 工作流别名(默认 klein-edit)、--image/-i 输入图片(可多次)、-p 编辑指令(必需)、-P 工作流参数、--text 纯文本模式

opc image kg — Prompt 知识图谱

opc image kg list                              # 列出所有实体分类
opc image kg list --category style             # 按分类筛选
opc image kg info style:photography            # 实体详情
opc image kg search portrait                   # 模糊搜索
opc image kg query style:cyberpunk            # 查询搭配推荐
opc image kg skeleton subject:food lighting:neon  # 生成 prompt 骨架
opc image kg validate subject:cat style:photography lighting:dramatic  # 验证组合
opc image kg similar subject:cat               # 查找相似 prompt
opc image kg templates                         # 列出模板
opc image kg templates --entity style:cyberpunk  # 按实体查模板

Video 命令

视频生成依赖 ComfyUI 工作流。默认 alias 为 ltx-i2v 和 ltx-flf，需先确认它们出现在 opc image list 中。

# 单图动画化
opc video-gen i2v --image frame.png -p "camera slowly zooms in"

# 首尾帧过渡
opc video-gen flf --first-frame start.png --last-frame end.png -p "smooth cinematic transition"

# 更快的蒸馏模式
opc video-gen i2v --image frame.png -p "slow motion" --turbo

# 下载在线视频并用 Qwen3-ASR 转录（需要 yt-dlp 和 ffmpeg）
opc video-transcribe "https://example.com/video"

# 使用 OpenAI-compatible 视觉接口理解本地视频
opc video-describe video.mp4

生成参数： --workflow/-w 工作流、--prompt/-p 运动描述、--param/-P key=value 参数覆盖、--output/-o 输出目录、--turbo 快速模式。

视频理解配置： opc config --set-video-desc-api-url <url>、--set-video-desc-model <name>，API key 可单独设置，也可复用图片视觉模型配置。

Audio 命令

音频压缩与分析工具。

opc audio compress input.mp3 --preset voice   # 人声压缩预设
opc audio compress input.mp3 -t -20 -r 4 -a 10 --release 130  # 自定义参数
opc audio analyze input.mp3                   # 分析响度 (LUFS)
opc audio presets                              # 列出可用预设

压缩参数： -t, --threshold 阈值 dB (默认 -20.0)、-r, --ratio 压缩比 (默认 4.0)、-a, --attack 启动时间 ms (默认 10.0)、--release 释放时间 ms (默认 130.0)、--knee 拐点宽度 dB (默认 0.0)、--makeup 补偿增益 dB (默认 0.0)、--mix 干湿比 0-1 (默认 1.0)、--preset 预设名称

预设： voice 人声优化 (-20dB, 4:1, 10ms, 130ms)、music 音乐轻压缩 (-18dB, 2.5:1, 15ms, 200ms)、limiter 硬限制器 (-6dB, 20:1, 1ms, 50ms)、punch 打击乐冲击感 (-12dB, 6:1, 3ms, 80ms)、gentle 极轻压缩 (-24dB, 1.8:1, 30ms, 300ms)

Music 命令

MiniMax Music3 本地歌曲与纯音乐生成。详细格式与参数见 references/music.md。

创建、改写或扩写 Music3 Caption 时，必须优先使用 MiniMax 官方 music-caption-rewriter skill。把用户的音乐 brief、原始段落标签、目标时长和排除项交给该 Skill；将它返回的三段式英文 Caption 作为 --caption，原歌词或纯器乐结构标签仍单独传入 Music3。官方 Skill 只负责编曲描述，不替代 OPC 的真实时长和音频完整性验收。

opc music --caption-file caption.txt --lyrics-file lyrics.txt --duration 120 -o song.mp3
opc music --caption "Cinematic orchestral score" --instrumental --format flac
opc music --caption-file caption.txt --lyrics-file lyrics.txt --dry-run

官方 Rewriter 必须返回英文三段式 Structured Caption：Global Metadata、Vocal Details、Arrangement，通常为 250–450 词；歌词单独传入并保留 [Verse]、[Chorus] 等段落标签。默认 30 steps、CFG 1.7、top-k 50，支持 0.04-360 秒非流式生成。输出默认必须达到目标时长的 95%，不足或音频损坏会自动换 seed 重试三次；--min-duration 和 --attempts 可调整验收门槛。

Cut 命令

基于 ASR 字词级时间戳的视频剪辑。详见 references/cut.md。

opc cut --video video.mp4        # 启动剪辑 Web 界面

Video 命令

MiniMax H3 本地文生视频、首尾帧图生视频、参考图视频，以及 SeedVR2 超分。详见 references/video.md。

H3 创意规划路由

• 创建、改写或扩写任何 H3 Prompt 时，必须优先使用 MiniMax 官方 h3-prompt-writing skill，并读取与输入模式对应的官方 reference。不要自行改动官方字段名、字段顺序、媒体标签或时间格式。
• 模式映射：h3-t2v 使用 T2VA；h3-i2v 仅首帧使用 I2VA、首尾帧使用 FL2VA、仅尾帧使用 L2VA；h3-r2v 使用 Ref2VA。
• 用户还需要创意策划、参考素材分工、审美设计、测试矩阵或生成后质检时，在官方 Skill 之后读取内置 H3 Guide。内置指南补充创意决策，不替换官方 Prompt 结构。
• 用户只查询工作流、参数、安装、连接、缓存和报错，或已经给出符合官方结构的完整 Prompt 要直接执行时，读取 references/video.md。
• 冲突优先级：官方 h3-prompt-writing 管 Prompt 结构；references/video.md 管 CLI 与本机工作流能力；内置 h3-guide 管创意规划和质检。
• H3 默认采用两阶段生成：抽卡、试 Prompt 和筛选 seed 时使用 --turbo；确定方案后保持 Prompt、参考素材和 seed 不变，移除 --turbo，使用 Base 20 steps 按目标分辨率最终出片。不要把 Turbo 预览直接当最终交付。

opc video list
opc video -w h3-t2v -p "..." --width 864 --height 480 --duration 5
opc video -w h3-t2v -p "..." --width 608 --height 352 --duration 5 --seed 42 --turbo  # 抽卡/筛 Prompt
opc video -w h3-t2v -p "..." --width 1376 --height 768 --duration 5 --seed 42 --steps 20  # 最终出片，不用 Turbo
opc video -w h3-i2v -p "..." --first-frame first.png --last-frame last.png
opc video -w h3-r2v -p "..." --reference-image subject.png
opc video -w h3-t2v-upscale -p "..." --upscale-factor 2
opc video -w h3-t2v -p "..." --no-fbc  # 无近似缓存的精确基线
opc video -w h3-t2v -p "..." --duration 20  # 实验性原生 20 秒（481 帧）

CLI 支持 5–20 秒。超过 15 秒属于 ComfyUI 节点允许、但超出 H3 已验证训练区间的实验模式；需要预留更多显存并重点检查长时一致性。

H3 默认启用独立 FirstBlockCache 的 H3 Safe 预设。--no-fbc 可关闭； 显式启用 --easy-cache 时会自动省略 FBC，避免两个近似缓存叠加。

Dashboard

技能管理面板。详见 references/dashboard.md。

配置

配置文件：~/.opc_cli/opc/config.json

opc config --show
opc config --set-engine qwen
opc config --set-comfyui-host 192.168.100.10