Appearance
使用 haoone-cli 命令行工具
haoone-cli 在终端中完成转录、文稿匹配、说话人识别、热词和项目管理，与桌面应用共用配置、模型和项目。先在 HaoOne 中完成模型目录、模型下载、登录与所需 API 配置。
本页按 HaoOne 14.5.2 的实际命令帮助与参数处理逻辑整理，覆盖当前开放的全部 15 个子命令。示例路径均为占位符，请换成自己的文件；含空格的路径必须加引号。
安装与基本写法
- 打开「设置 → 命令行工具」，启用并确认显示「已注册」。
- 重新打开终端，使 PATH 配置生效。
- 检查版本、帮助和已安装模型：
bash
haoone-cli --version
haoone-cli --help
haoone-cli installed-models
haoone-cli transcribe --help基本格式为 haoone-cli <子命令> [参数]。长参数与短参数等价，例如 --language zh 与 -l zh；短参数的含义由子命令决定，不能跨命令套用。
| 通用参数 | 作用 |
|---|---|
-h、--help | 查看主命令或任一子命令的帮助 |
-V、--version | 查看 CLI 版本；在主命令后使用 |
布尔参数必须带值，例如 --enable-ai-correction false，不能只写参数名。支持的真值为 true、1、yes、on，假值为 false、0、no、off；建议统一写 true / false，避免拼写错误回退到默认处理。
命令一览
| 命令 | 用途 |
|---|---|
transcribe | 转录单个音视频，可选择本地或在线模型 |
batch-transcribe | 用同一组设置依次转录多个文件 |
installed-models | 列出已安装模型 |
manuscript-matching-ctc | 无需预先转录，直接将文稿与媒体对齐 |
manuscript-matching | 根据已有转录结果进行文稿匹配 |
speaker-diarize | 根据媒体和转录 JSON 识别说话人 |
format-draft | 格式化文稿并将结果打印到终端 |
ai-format-draft | 按软件中的 AI 配置和规则格式化文稿，写入文本文件 |
batch-add-hotwords | 添加或合并热词及别名 |
get-hotwords | 查看热词配置 |
get-config | 查看软件关键配置 |
get-project-list | 查看全部项目 |
get-project-srt-list | 查看某个项目中的 SRT 文件 |
create-project | 创建项目并切换为当前项目 |
delete-project | 删除项目目录并清理项目记录 |
transcribe：单文件转录
bash
haoone-cli transcribe --audio-file-path "/path/to/demo.mp4" --language zh --output "/path/to/output" --enable-ai-correction false| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-f、--audio-file-path <路径> | 必填 | 输入音频或视频文件 |
-n、--name <名称> | 默认媒体文件名，不含扩展名 | 转录任务／时间线名称 |
--from <来源> | cli | 写入任务的来源标识；通常保持默认 |
-o、--output <目录> | 自动选择，见下文 | 输出目录，不是单个 SRT 文件路径 |
-m、--model <模型> | 中英-v2-2026 | 本地模型名称或模型 ID；在线模式使用下表中的在线模型 ID |
-l、--language <代码> | zh | 音频语言代码，必须与所选模型支持的语言一致 |
-w、--enable-online-transcript <布尔值> | false | false 在本机识别，true 使用在线转录 |
-a、--enable-ai-correction <布尔值> | false | 是否执行 AI 纠错；需满足激活、登录和服务配置要求 |
-s、--max-subtitle-length <整数> | 25 | 单行字幕最大长度；中日按字、英语按单词处理 |
--start-time <时间> | 不传则处理完整媒体 | 局部转录开始时间，必须与 --end-time 同时提供 |
--end-time <时间> | 不传则处理完整媒体 | 局部转录结束时间，必须晚于开始时间 |
不传 --output 时，优先写入当前项目的 transcriptions 目录；没有当前项目时，写入输入媒体同级的 transcriptions 目录。完成后终端会报告生成段落和 SRT 路径，使用实际输出路径继续处理。
本地模型与语言
先运行 installed-models 确认安装。以下写法对应当前模型设置中的七个模型；Parakeet 模型建议使用表中的 ID。
| 界面名称 | --model 推荐写法 |
|---|---|
| 中英-v2-2026 | 中英-v2-2026 或 qwen3-asr-0.6b-q8_0 |
| 多语种-增强-2026 | 多语种-增强-2026 或 qwen3-asr-1.7b-q8_0 |
| 中英日-多说话人-2026 | 中英日-多说话人-2026 或 moss-transcribe-diarize-0.9b-q8_0 |
| 中英-最强-2026 | 中英-最强-2026 或 mimo-v2.5-asr |
| 英语-最好-2026 | 英语-最好-2026 或 moss-transcribe |
| 日语-最快-2026 | parakeet-tdt-0.6b-ja |
| 欧洲多语种-2026 | parakeet-ultra-q8_0 |
常用语言代码：zh 中文、en 英语、ja 日语、ko 韩语、fr 法语、de 德语、it 意大利语、es 西班牙语、pt 葡萄牙语、ru 俄语、ar 阿拉伯语、hi 印地语、th 泰语、vi 越南语、id 印尼语。各模型的语言范围与用途见本地转录，不要把语言代码列表当作所有模型都支持的语言列表。
免费本地转录使用基础中英模型，单个媒体限 20 分钟；增强模型及局部转录需满足激活要求。开启本地模式不代表 AI 纠错等后处理也离线执行。
局部转录示例
时间支持非负秒数（可带小数），或 HH:MM:SS（秒可带小数），例如 60.5、00:01:00.5。分、秒部分须小于 60。
bash
haoone-cli transcribe -f "/path/to/demo.mp4" -l zh --start-time 00:01:00 --end-time 00:02:00 -o "/path/to/output"在线转录示例
| 在线模型 ID | 传参方式 |
|---|---|
qwen-audio-3.1-asr-flash-filetrans | 与 --enable-online-transcript true 配合 |
qwen3-asr-flash | 与 --enable-online-transcript true 配合 |
mimo-v2.5-asr | 与 --enable-online-transcript true 配合；同名模型也可用于本地模式，执行位置由开关决定 |
bash
haoone-cli transcribe -f "/path/to/demo.mp4" -w true -m qwen-audio-3.1-asr-flash-filetrans -l zh -a false -o "/path/to/output"在线任务会上传音频，使用前完成登录并确认模型费用。详见远程转录和模型价格。
batch-transcribe：批量转录
使用逗号分隔文件路径；重复 -f 也可以追加文件。任务按文件依次执行，失败文件会被记录，其他文件继续处理。当前 CLI 的批量转录要求激活软件。
bash
haoone-cli batch-transcribe -f "/path/to/a.mp4" -f "/path/to/b.wav" -m "多语种-增强-2026" -l zh -a false -o "/path/to/output"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-f、--audio-file-path <文件列表> | 必填 | 一个或多个输入文件，例如 -f "/path/a.wav,/path/b.wav"；文件名包含逗号时应先重命名，避免被拆成多个路径 |
-o、--output <目录> | 当前项目的 transcriptions；无当前项目时为首个输入文件同级的 transcriptions | 所有文件共用的输出目录 |
-m、--model <模型> | 中英-v2-2026 | 同单文件转录的模型写法 |
-l、--language <代码> | zh | 所有输入文件使用同一语言 |
-w、--enable-online-transcript <布尔值> | false | 是否使用在线转录 |
-a、--enable-ai-correction <布尔值> | true | 批量默认开启 AI 纠错；只需原始转录时显式传 false |
-s、--max-subtitle-length <整数> | 25 | 每行字幕最大长度 |
批量命令不提供 --name、--from、--start-time、--end-time 或并发参数。每个任务名称取媒体文件名；同名文件建议分开输出，避免混淆结果。
installed-models：查看已安装模型
bash
haoone-cli installed-models无业务参数，仅支持通用 --help。用于检查本地模型是否已安装；下载和管理模型仍在桌面应用的「本地模型设置」中完成。
manuscript-matching-ctc：文稿直接对齐
不需要预先转录。读取 UTF-8 文稿，按已有换行生成字幕，用对应语言的 CTC 模型与媒体对齐。
bash
haoone-cli manuscript-matching-ctc -f "/path/to/demo.mp4" --manuscript-path "/path/to/script.txt" -l zh -n "课程_文稿匹配" -o "/path/to/output"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-f、--audio-file-path <路径> | 必填 | 输入音频或视频 |
--manuscript-path <路径> | 必填 | UTF-8 文稿文件；先整理好需要保留的换行 |
-l、--language <代码> | zh | 仅接受 zh、en、ja、ko、fr、ar、pt、it、es、de、hi、th、vi、id |
-o、--output <目录> | 当前项目的 transcriptions 目录 | 输出目录；建议明确指定，避免依赖当前项目 |
-n、--name <名称> | 媒体名_文稿匹配 | 输出文件名，不含扩展名 |
先安装对应语言的字幕与音频对齐模型，完成后检查未匹配内容和字幕首尾时间。
manuscript-matching：匹配已有转录结果
此命令基于已有转录 JSON 进行文稿匹配，当前要求激活。即使显式指定 JSON，仍需提供名称，并指定项目或已有当前项目。
bash
haoone-cli manuscript-matching --manuscript-path "/path/to/script.txt" --transcribe-result-path "/path/to/demo.json" --project "课程项目" --name "demo" --enable-splite-follows-script true| 参数 | 必填／默认值 | 说明 |
|---|---|---|
--manuscript-path <路径> | 必填 | 文稿文件 |
--transcribe-result-path <路径> | 自动查找 | 显式指定转录 JSON，优先于项目和名称推导的路径 |
-p、--project <项目名> | 当前项目 | 项目名称，不是项目目录路径 |
-n、--name <名称> | 必填 | 转录结果名称，用于定位结果；推荐不带扩展名 |
-f、--enable-splite-follows-script <布尔值> | false | 是否让拆行遵循文稿；参数拼写中的 splite 按现有 CLI 保留 |
此命令没有 --output 和 --language 参数；以终端报告的字幕路径为准。
speaker-diarize：识别说话人
需要媒体、已有转录 JSON、已安装的说话人模型及激活状态。可直接指定 JSON，或通过项目与转录名称定位。
bash
haoone-cli speaker-diarize -f "/path/to/demo.wav" -j "/path/to/demo.json" --auto-speaker-count false --speaker-count 3 --enable-voiceprint true -o "/path/to/demo.speaker.json"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-f、--audio-file-path <路径> | 必填 | 与转录结果对应的媒体，确保时间位置一致 |
-j、--transcript-json <路径> | 可选 | 显式指定转录 JSON；传入后优先使用 |
-p、--project <项目名> | 当前项目 | 未传 JSON 时，用此项目查找转录结果 |
-n、--name <名称> | 未传 JSON 时必填 | 在项目的 transcriptions 目录中查找同名 JSON |
-o、--output <输出基名或文件路径> | 输入 JSON 同级的 原名.speaker | 同时生成 .srt 和 .json；传入 .srt 或 .json 路径时使用相同基名；此参数不是输出目录 |
-m、--speaker-model <模型> | titanet-large.gguf | 说话人嵌入模型名称或路径，需确保对应模型已安装；这是 CLI 的默认值，不是转录模型 |
--auto-speaker-count <布尔值> | false | true 自动估计人数，false 按指定人数识别 |
--speaker-count <整数> | 3 | 非自动模式下的人数，内部限制在 2–100 范围 |
--enable-voiceprint <布尔值> | true | 是否匹配已经注册的说话人声纹 |
输出包含说话人信息的 JSON 与 SRT，执行后仍需核对人物身份和交叉说话片段。
format-draft：格式化并打印文稿
bash
haoone-cli format-draft --path "/path/to/script.txt"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-p、--path <路径> | 必填 | 读取文稿，格式化后输出到终端；不覆盖原文件 |
此命令没有 --output、--rules-file 参数。需要将结果直接写成文本文件并使用 AI 规则时，使用下面的 ai-format-draft。
ai-format-draft：AI 格式化文稿
使用软件中保存的模型、API 和文稿格式化规则，支持 TXT、SRT、HTML、Markdown 内容。运行前完成登录和所需服务配置。
bash
haoone-cli ai-format-draft -p "/path/to/script.txt" -o "/path/to/script.cleaned.txt" --rules-file "/path/to/rules.txt"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-p、--path <路径> | 必填 | UTF-8 文稿；也支持别名 --manuscript-path |
-o、--output <文件路径> | 输入同级的 文件名.formatted.txt | 输出文本文件，不是目录；不能与输入文稿相同 |
--rules-file <路径> | 软件保存的格式化规则 | UTF-8 规则文件；传入后替代软件保存的规则，不是追加 |
格式化后先核对正文，再用于文稿匹配，尤其要检查标注清理是否误删内容。
batch-add-hotwords：添加热词
bash
haoone-cli batch-add-hotwords --language zh --file "/path/to/hotwords.txt"
haoone-cli batch-add-hotwords --language zh --input "浩叔=耗叔,好叔"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-l、--language <代码> | 必填 | 热词所属语言，如 zh、en |
-f、--file <路径> | 与 --input 至少提供一个 | 读取 UTF-8 热词文本文件；同时提供两种输入时优先使用文件 |
--input <文本> | 与 --file 至少提供一个 | 直接传热词文本，多行内容应作为同一个带引号的参数 |
推荐每行一个词，使用 正确词=别名1,别名2：
text
浩叔=耗叔,好叔
HaoOne=hao one,haoone也支持「首行为正确词、后续行为别名」的多行块格式；多个词条推荐使用等号格式，边界更清晰。同名热词会合并别名，结果写入共用的 hot_words.json。非中文热词处理可能调用配置的 AI 服务，执行前确认登录和网络配置。
查询热词、配置和项目
下列三个命令均无业务参数，仅支持通用 --help：
| 命令 | 返回内容 |
|---|---|
haoone-cli get-hotwords | 按表格打印已有热词配置 |
haoone-cli get-config | 软件关键配置，包括当前项目与相关设置 |
haoone-cli get-project-list | 软件下的全部项目信息 |
配置输出可能包含私有路径和账号相关信息，分享前先检查内容。
get-project-srt-list：列出项目字幕
bash
haoone-cli get-project-srt-list --project-name "课程项目"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-p、--project-name <项目名> | 当前项目 | 列出指定项目中的 SRT 文件路径；这里的参数是 --project-name，不是 --project |
create-project：创建并切换项目
bash
haoone-cli create-project --name "课程项目"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-n、--name <项目名> | 必填 | 创建项目，并将其设为当前项目；后续省略项目或输出参数的命令可能使用此项目 |
delete-project：删除项目
bash
haoone-cli delete-project --name "待删除项目"| 参数 | 必填／默认值 | 说明 |
|---|---|---|
-n、--name <项目名> | 当前项目 | 删除对应项目目录并清理记录；不传名称会删除当前项目 |
删除前备份所需字幕和媒体，并明确填写目标名称。该操作会实际删除目录，不是只从列表移除。
常见问题
- 找不到命令：回到「设置 → 命令行工具」检查注册状态，重新打开终端。
- 模型不存在：先用
installed-models检查，再去桌面端下载。模型参数使用上表的名称或 ID，语言必须与模型匹配。 - 参数不认识：运行
haoone-cli <子命令> --help。当前 CLI 没有开放独立的翻译、双语字幕、字幕烧录、AI 拆行或降噪参数，不要直接套用桌面功能名称。 - 输出位置不符合预期：区分目录参数与文件参数。转录、CTC 对齐的
--output是目录；AI 格式化的是文件；说话人识别的是输出基名或文件路径。 - 批量执行失败：查看各文件错误和最终退出状态。CLI 正常完成返回
0，业务失败通常返回1，参数格式错误返回非零值；脚本应依据退出码判断，不要只搜索“完成”文字。 - 只想本地识别：显式传
--enable-online-transcript false --enable-ai-correction false，并核对软件保存的其他后处理配置。登录、激活检查与在线服务调用仍取决于所用功能。
升级后以本机帮助为准；涉及付费、在线调用和激活的范围见付费权益说明。