文档、支持与本地排障入口

快速开始

安装 Sonano 后打开 App，欢迎页会启动本地引擎，并等待 `/v1/models` 与 `/voices` 同步完成后进入工作台。第一次生成建议从语音生成页面开始，先选择模型、输出语言和声音；如果模型权重或运行时还没准备好，按提示下载完成后再生成一段短文本。

• 本地服务默认监听 127.0.0.1:19280
• 生成、转写、声音转换都会进入统一任务、产物和历史系统
• 桌面 App 包含主路径运行环境；模型权重按需下载，不同模型仍有内存和磁盘要求
• 用户声音、历史、日志和模型缓存保存在本机，升级 App 默认不清空

curl -i http://127.0.0.1:19280/health
curl -i http://127.0.0.1:19280/v1/models
curl -i http://127.0.0.1:19280/voices?view=slim

系统要求

Sonano 当前面向 macOS 原生桌面工作流。本地推理路径大量依赖 MLX / Metal，因此 Apple Silicon 是推荐环境；模型越大，对内存和磁盘空间要求越高。

界面导览

Sonano 不是单页文本转语音表单，而是桌面声音工作台。左侧导航按创作、资源库和系统组织，中间是工作区，右侧设置栏管理当前模型、声音和参数，底部播放器负责试听与播放。

• 创作：语音生成、转写、声音转换等生产工作流
• 资源库：声音、模型、历史和请求审计等可复用资产和记录
• 系统：模型库、任务与进度、设置、本地引擎状态
• 右侧设置栏：跟随当前工作区变化，不把所有设置堆在同一个页面

典型使用路线

如果你不确定该从哪里开始，可以按目标选择路线。Sonano 的设计重点是让图形界面、普通 API 和 Agent 使用同一套模型、任务和产物系统，因此同一个结果可以在播放器、历史、导出和自动化里继续流转。

模型选择

模型由模型库管理。模型决定语言、声音、流式预听、声音资产、运行时准备方式，也会影响输入区可用的风格提示和内联标签。第一次使用不需要自己改环境变量或猜 Hugging Face 缓存目录；在模型库选择目标模型，Sonano 会提示需要下载的权重或运行时。

• 快速中文 / 英文旁白：优先 qwen3-tts-custom-voice。适合短文案、预设声音、快速试听和反复改稿。
• 固定声线或角色声：选择 qwen3-tts、omnivoice、chatterbox-* 或 voxcpm2。这些路线可以使用出厂、设计、克隆声音，适合品牌声线和多角色脚本。
• 多语言内容：优先查看 OmniVoice。先确认目标语言是否支持，再看该语言下有多少可试听声音；长尾语言可按需搜索 600+ 语言目录。
• 转写与字幕：优先 Qwen3-ASR；如果需要更广覆盖，可把 Whisper 作为备选。
• 声音转换：使用 Chatterbox VC。目标声音必须是 Sonano 管理的出厂、设计或克隆声音；模型内部预设声音不能作为转换目标。
• 长文本、批量生成或 Agent 自动化：重点看下载体积、推荐内存、是否需要额外运行时，以及结果是否进入历史、导出和请求审计。

完整模型矩阵、语言范围、模型版本和场景对照见 模型页。

语音生成

语音生成是主生产工作流：单条朗读、长文本分段、多角色脚本、有声书章节项目、生成队列、历史复用、分段查看和导出都在这里完成。页面左侧是脚本工作区，右侧是模型、声音和参数设置，底部播放器负责试听当前结果。

通用布局

• 左侧主编辑区：这是主要工作区。普通模式显示连续正文编辑框，多角色模式显示按角色和段落拆开的脚本编辑区，有声书模式显示书籍和章节列表。
• 设置 / 生成记录：右侧顶部可在设置和生成记录之间切换；设置用于当前生成，生成记录用于播放、复用、导出或删除历史结果。
• 最近生成：生成完成后会出现可播放记录，显示模式、声音、模型、时长和采样率；长文本结果还可打开分段详情。
• 底部播放器：当前音频会进入统一播放器，可播放、暂停、拖动进度、调整音量，方便边听边改稿。

普通模式

普通模式适合单人旁白、短视频口播、提示音和通知文本。左侧是一个连续正文编辑区，输入或导入文本后，选择模型、输出语言和声音即可生成。

如果你只是想整体改变语气，使用风格提示输入框；如果你想让某一句出现笑声、叹气或疑问语气，用内联标签插入到对应文本位置。具体可用方式会随当前模型变化。

多角色模式

多角色模式适合故事、对话、播客脚本和分角色旁白。它不是一个连续文本框，而是按“角色 + 段落”组织脚本，每个角色可以绑定不同声音，每个段落也可以单独生成试听。

有声书模式

有声书模式适合长篇文章、课程脚本、小说草稿和需要按章节管理的朗读项目。它把长文保存为本地书籍项目，按章节生成音频，避免每次修改一章都重新处理整本书。

当前 EPUB / TXT / Markdown 文件导入是 App 侧能力；Agent 更适合提交结构化章节内容，完整 audiobook job 会在后续 API 中扩展。

生成结果

curl -s -X POST http://127.0.0.1:19280/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "X-Sonano-Caller: Docs Example" \
  -d '{"model":"qwen3-tts-custom-voice","voice":"Serena","language":"Chinese","input":"你好，欢迎使用 Sonano。","response_format":"wav"}' \
  -o speech.wav

转写

转写用于把音频或视频变成可编辑文本、字幕时间线和可审查的媒体修改计划。它不只是“识别文字”，还会把全文、分段时间码、静音区间、文本清理建议和导出结果放在同一个工作流里。

通用流程

• 导入文件：点击 导入音频或视频 选择本地文件。视频会先由内置 FFmpeg 提取音轨，再进入转写流程。
• 选择模型和语言：默认可使用 Qwen3-ASR；如果需要更广语言覆盖，可把 Whisper 作为备选。语言下拉会影响识别和后续字幕输出。
• 开始转写：点击 转写 后，顶部按钮会显示进度；处理中，转写文本和时间线会在任务完成后统一刷新。
• 取消或换文件：文件名会显示在顶部导入区，旁边可移除当前文件；处理中可取消任务，避免长音频占用本地引擎。
• 先转写，再审查：静音审查和文本审查都依赖转写结果。未完成转写时，审查区只会提示先完成转写。

转写文本

时间线

时间线把转写结果放回媒体时间轴。左侧是序号和时间范围，中间是文本，右侧是片段操作入口。

• 分段 / 单元：分段视图适合按句子或语义段落检查；单元视图适合检查更细的词、字、停顿或字幕边界。
• 高亮提示：重复、口头语、疑似冗余或被审查命中的词会在文本中高亮，方便定位问题，而不是让用户从全文里手动找。
• 片段操作：每行右侧的更多按钮可打开操作，包括播放原媒体、预览修改结果、高级片段修改、恢复原始等。
• 静音片段：采纳静音审查后，时间线会出现独立的静音行，显示静音时长和所在位置，便于确认剪辑是否合理。

审查

静音审查和文本审查是分开的：前者基于时间区间处理停顿，后者基于转写文本处理表达问题。文本审查属于文本 AI 功能，需要先在 设置 页完成相关配置；所有建议都会先展示给用户确认，不会直接黑箱改稿或剪媒体。

高级片段修改

当普通剪切效果不理想，或某一小段识别错误但不想重做整条音频时，可以从时间线片段进入 高级片段修改。

• 修改文本：只调整这一段的转写文本，用于修正错字、漏字或字幕内容。
• 通过声音转换重生成：保留原说话人的音色，先根据修改后的文本生成新片段，再转换回原音色，适合替换短句。
• 重新录音：需要人工补录时使用，避免为了一个片段重跑整段媒体。
• 预览再应用：修改前可预览效果，确认后再应用到时间线；不满意可恢复原始片段。

导出

声音转换

声音转换用于把一段已有音频转换成另一个目标声音。它不是重新写稿或重新做文本转语音，而是在尽量保留原音频节奏、停顿和语气的前提下，更换说话人的音色。

页面布局

• 模型状态：顶部显示当前声音转换模型，例如 Chatterbox，以及是否已安装。模型未就绪时需要先下载或安装运行时。
• 源音频：左侧用于导入要被转换的音频。导入后会显示文件名、时长和播放按钮，可先确认原音频是否选对。
• 目标声音：右侧用于选择转换后的声音。卡片会显示声音名称、语言、性别、来源和标签，并提供试听按钮。
• 转换按钮：源音频和目标声音都选好后，转换声音 按钮才会可用；转换中会显示进度和取消入口。

源音频

源音频是你想“换声”的原始素材，可以是录音、旁白、短视频音轨或语音生成结果。Sonano 会先在本地引擎内把音频归一化为适合模型处理的格式，再送入声音转换运行时。

目标声音

目标声音决定转换后的音色。这里选择的是 Sonano 管理的声音资产，而不是模型内部的临时预设。

• 可用目标：出厂声音、声音设计和克隆声音可以作为目标声音，因为它们有可追踪的参考音频。
• 不可用目标：预设声音没有独立参考音频，不能作为声音转换目标。
• 声音信息：目标声音卡片会展示语言、性别、来源和标签，选择前可以先试听，确认音色是否适合当前素材。
• 找不到合适声音：可以先到声音库创建声音设计或克隆声音，保存后再回到声音转换页面选择。

转换过程

最近转换与导出

右侧 最近转换 会保留已完成结果，方便你对比不同目标声音或继续复用。

• 播放：直接试听某次转换结果，不必重新运行模型。
• 复用：把历史结果带回当前工作区，继续作为参考或再次导出。
• 导出音频：把转换结果导出为常用音频格式，用于剪辑软件、播客、视频或其他工具。
• 移除：删除不需要的历史项；已经导出的文件不会受到影响。

声音转换更适合单人、干净、说话清晰的音频。它会尽量保留原音频的内容和节奏，但不能保证把环境噪声、多人重叠或严重失真的素材修好。

声音库与声音资产

声音库是 Sonano 的声音资产中心。它不只是一个“选择声音”的下拉菜单，而是把内置声音、模型自带声音、你设计的新声音和你克隆/导入的声音统一管理起来，让语音生成、声音转换、API 和 Agent 都能复用同一套声音资源。

在 App 中进入 资源库 > 声音 可以打开完整声音库。常见操作包括搜索名称或描述、按语言/性别/标签过滤、试听样本、收藏常用声音、查看/编辑元数据、重命名自建声音、删除不再需要的自定义声音。语音生成右侧设置栏的 浏览全部 会打开同一个声音库弹层，因此你不需要离开当前生成工作流就能挑选或更换声音。

• 快速挑选：先选择语音模型和输出语言，再打开声音列表；Sonano 会自动过滤当前模型和语言可用的声音。
• 试听确认：点击播放按钮先听参考样本，适合在播客、旁白、教学、新闻、角色对白等风格之间快速比较。
• 收藏常用声音：星标会作为本地偏好保存，适合把常用旁白、角色声、品牌声线放在前面。
• 创建新声音：点击 新建声音，用声音设计描述想要的声线，或用声音克隆上传/录制参考音频；完成后会自动进入同一个声音库。
• 跨工作流复用：同一个声音资产可被图形界面、OpenAI 兼容 API 和 Agent skill 复用；在接口里通常通过声音资产编号（voice_asset_id）引用。

小经验：如果你只是想快速朗读一段中文或英文，先从预设声音开始；如果你想固定品牌声线、多人脚本角色、声音转换目标，优先使用出厂 / 设计 / 克隆这类带参考音频的声音资产。

模型

资源库里的 模型 页面用于管理本机可用的语音生成、转写和声音转换模型。它解决的是“当前有哪些模型、装没装、该下哪个版本、为什么某个工作流不可用”这类问题；入门里的模型选择则更偏使用场景推荐。

模型列表

• 模型类型：区分语音生成、转写、声音转换等能力。不同类型会出现在不同工作流里，例如 Qwen3-ASR 用于转写，Chatterbox 用于声音转换。
• 安装状态：查看已安装、未安装、下载中、运行时缺失或不可用等状态。未就绪的模型不会直接出现在可用工作流中。
• 模型信息：关注参数规模、量化版本、下载体积、推荐内存、语言范围和采样率。下载体积影响准备时间，推荐内存影响能否稳定运行。
• 能力标签：模型卡片会标出是否支持多语言、流式预听、声音资产、内联标签、声音转换或转写等能力。

下载与版本

和工作流的关系

模型页是资源管理入口，工作流页面是使用入口。你可以先在模型页准备好模型，也可以在语音生成、转写或声音转换页面遇到未安装提示时再按需下载。

常见排查

• 工作流里找不到模型：先确认模型类型是否匹配当前页面，再看模型状态是否已安装并可用。
• 声音列表为空：通常是模型、输出语言和声音类型不兼容。先切换语言或模型，再打开声音库筛选。
• 下载完成仍不可用：检查运行时是否安装完成，或在任务、历史与审计中查看失败原因。
• 内存不足或很慢：换用更小的量化版本，关闭其它占用内存的任务，或选择推荐内存更低的模型。

模型页面向本机资源管理；如果你只是想知道某个场景该选哪个模型，先看入门里的 模型选择。

任务、历史与审计

历史页负责保存可复用结果，请求审计负责记录本地 API / Agent 调用，任务与进度负责展示下载、生成、转写、转换和媒体处理的运行状态。三者共用同一套任务和产物系统，但用途不同：历史面向“结果复用”，审计面向“谁调用了什么”，任务面向“现在跑到哪了”。

历史页

• 类型切换：顶部可在语音生成、声音转换、转写和请求审计之间切换。前三类是用户结果历史，请求审计是本地 API 调用记录。
• 搜索历史：搜索框可按文本片段、文件名、声音、模型或任务信息查找历史项。
• 列表 / 网格：列表视图适合看长文本、时间和操作按钮；网格视图适合快速浏览较多音频结果。
• 选择与删除：点击 选择 可进入批量选择模式；删除只清理选中的历史记录，全部清除 会清空当前类型的历史。
• 刷新：刷新按钮会重新读取本地历史和审计数据，适合刚完成任务但列表尚未更新时使用。

三类结果历史

复用不是简单复制文件：语音生成会尽量回填文本、声音和模型；转写会带回转写结果和时间线；声音转换会带回源音频和目标声音信息，方便继续迭代。

请求审计

请求审计记录本地能力调用，适合排查“是谁触发了这个任务”“用了哪个模型或声音”“请求失败在哪里”。它会包含 App 自己的调用，也会包含外部脚本或 Agent 的调用。

• 概览信息：顶部显示今日请求数和最近活动时间，方便判断本机能力最近是否被频繁调用。
• 最近请求：列表展示能力类型、子任务、时间、状态和请求 id，例如语音生成、转写、文本审查、静音审查、声音转换、分析脚本等。
• 状态边界：已接受表示请求已进入任务系统；已完成表示任务成功产出结果；失败记录会保留错误信息，便于排障。
• 详情面板：选择一条请求后，右侧会显示能力、任务参数、声音、模型、调用方、来源地址、请求端点和请求 id。
• 复制字段：请求、请求 id、任务 id 等字段旁边提供复制按钮，方便反馈问题或调试 Agent 调用。

任务与进度

任务与进度弹窗用于查看正在运行或刚完成的后台任务，覆盖模型下载、运行时安装、语音生成、转写、声音转换和媒体处理。

清理策略

• 删除历史：删除的是结果记录和关联产物；已经导出到外部位置的文件不会被回收。
• 清理任务：只清理任务列表中的完成项，不影响历史页里保存的可复用结果。
• 审计保留：请求审计用于本地可解释性和排障，存储页可配置保留和清理策略。
• 反馈问题：遇到异常时，优先提供任务 id、请求 id、模型、声音、调用方和日志片段。

导出与文件格式

Sonano 内部以可追踪产物管理结果，用户导出时再选择交付格式。正式音频产物以 WAV 作为源文件，App 侧提供常用导出格式。

Agent 接入

Agent 接入页面用于把 Sonano 的本地声音能力交给外部 Agent 使用。这里可以确认本地服务状态、复制服务地址、安装 Skill、集成 Hermes，并查看 Agent 可调用的能力入口。

服务状态

• 运行状态：页面顶部会显示本地引擎是否运行、版本号和监听地址。默认只监听 127.0.0.1，面向本机 App、脚本和 Agent。
• 服务地址：复制 URL 后可交给本机脚本或 Agent 使用，例如 http://127.0.0.1:19280。
• 健康检查：点击健康检查可确认本地服务是否可达；如果失败，先回到顶部状态和任务与进度里查看本地引擎是否启动。
• 请求审计：Agent 触发的能力调用会进入请求审计，便于用户看到调用方、端点、请求 id、任务和错误边界。

Hermes 集成

Hermes 集成用于把 Sonano 接入 Hermes 自身的语音能力。点击 安装 Hermes 集成 后，Sonano 会按当前 App 约定写入所需配置；安装完成后，Hermes 可以通过 Sonano 的本地能力生成、转写或转换声音。

给 Agent 安装 Skill

Skill 是推荐的接入方式。安装后，Agent 不需要自己猜接口参数，而是根据 Sonano 提供的说明读取能力清单、选择声音和模型，并把长任务交给任务系统追踪。

如果同一个 Agent 同时支持共享目录和自己的专属目录，优先使用 App 推荐的安装项；已有旧版 Skill 时，使用“重新安装”更新到当前版本。

可用操作

页面底部会列出 Agent 可调用的本地能力，并提供复制示例。Agent 应先做能力发现，再按当前模型、语言和声音状态调用具体能力。

调用建议

BASE="http://127.0.0.1:19280"
curl -s "$BASE/health"
curl -s "$BASE/agent/manifest?view=slim"
curl -s "$BASE/v1/models"
curl -s "$BASE/voices?view=slim&status=ready"

• 调用方建议传 X-Sonano-Caller，并使用和客户端一致的名称，例如 Codex、Claude Code、OpenCode、Cursor、OpenClaw 或 Pi。
• 长任务不要轮询文件路径，应使用任务状态和产物 id；结果进入历史、产物和请求审计。
• Agent 不应硬编码声音 id、模型版本或本地缓存路径，应该先读取清单、模型和声音列表。
• 文本 AI 相关能力需要用户先在 设置 页配置文本 AI，Agent 调用前应检查能力清单和错误提示。

设置

设置页集中管理应用行为、本地引擎、文本 AI、存储、审计和隐私。它不是只改界面偏好的地方：多角色脚本分析、转写文本审查、Agent 后台调用、历史保留、缓存清理和麦克风权限，都需要先在这里确认前置项。

通用

本地引擎

本地引擎负责实际的模型、任务和本地 API 服务。Agent 接入、语音生成、转写、声音转换、模型下载和任务进度都依赖它。

• 健康检查：服务异常时，先检查本地引擎状态，再查看任务与进度、请求审计和日志。
• 资源监控：状态区显示 CPU、内存和本地服务状态，适合判断模型运行是否占用过高。
• 端口冲突：如果欢迎页或 Agent 接入页连接失败，先确认端口没有被其它进程占用，再重启本地引擎。

文本 AI

文本 AI 用于理解和整理文本，不负责直接生成声音。多角色脚本分析、转写文本审查、部分文本预处理和 Agent 的文本智能能力，都需要先在这里完成配置。

• 语音生成：多角色模式里的 分析脚本 需要文本 AI，用于拆分段落、识别说话者和生成角色草稿。
• 转写：文本审查里的 执行 AI 分析 需要文本 AI，用于发现语气词、重复和重说。
• Agent：Agent 调用文本整理类能力前，应先确认文本 AI 已配置且测试连接成功。
• 网络边界：使用外部提供方时，请求会发往你配置的服务；不配置文本 AI 时，这些写作辅助功能不会调用外部 API。

如果你在语音生成里看不到“分析脚本”，或在转写里无法执行文本审查，先回到设置页检查文本 AI 配置。

存储

存储设置用于理解和清理 Sonano 的本地数据。这里会把模型缓存、受管运行时、生成产物、音色库、状态数据库、审计日志和临时文件分开统计，方便判断到底是谁占用了磁盘。

• 存储概览：模型缓存通常按占本机磁盘的比例展示；运行时和应用 / 任务数据则按 Sonano 本地数据组内比例展示。
• 请求审计：可设置是否记录本地 API 请求、保留天数、是否隐藏系统噪声，以及是否只显示面向用户的有意义请求。
• 操作历史：可设置历史保留天数，并决定是否把 Agent / API 请求加入语音生成、转写和声音转换的历史列表。
• 清理入口：可分别清理临时文件、未引用产物、过期请求审计、过期操作历史和旧任务记录。清理策略会影响 App 启动和后台定期清理。
• 相关入口：存储页可以跳到历史、音色库、模型库和审计中心，分别处理单条结果、自定义声音、本地模型和请求明细。
• 危险操作：清除所有本地生成数据会删除生成产物、历史、自定义音色和相关临时文件；模型缓存和诊断日志会保留。

隐私

Sonano 默认本地优先。隐私页用于控制敏感音频数据、声音克隆确认、源录音保留和 macOS 权限，让用户明确知道哪些数据留在本机、哪些操作需要额外确认。

• 本地服务默认使用回环地址 127.0.0.1。
• 声音克隆确认：保存或使用克隆声音前可以要求确认，适合避免误用未经授权的声音样本。
• 克隆后保留源录音：开启后会保留原始参考录音；关闭后更利于减少敏感音频留存。
• 麦克风权限：只有在 Sonano 内录制声音克隆样本时才需要。未授权时，可以在隐私页发起 macOS 权限请求。
• 本地优先：Sonano 默认不会上传音频。除非你主动下载模型、检查更新，或配置并使用外部文本 AI，核心音频工作流都在本机完成。

API 契约速查

Sonano 会尽量保持本地 API 稳定。Agent 和脚本不应猜测界面状态，而应该通过能力发现、模型状态、声音列表、任务状态和产物元数据组合调用。

BASE="http://127.0.0.1:19280"
curl -s "$BASE/agent/manifest?view=slim" | jq .
curl -s "$BASE/v1/models" | jq '.data[] | {id,status,active_variant}'
curl -s "$BASE/voices?view=slim&status=ready" | jq '.voices[0]'

本地数据与升级

Sonano 的应用包、用户数据、模型缓存、运行时、日志和状态数据库分开存放。升级默认只替换 App，不清空 Application Support 或 Caches。

隐私、审计与清理

Sonano 的核心边界是本地优先。默认服务面向本机回环地址，本地能力调用可审计，声音克隆和声音设计会进入 Sonano 管理的声音资产系统。

• 默认服务地址是 127.0.0.1，面向本机图形界面、脚本和 Agent
• 声音克隆 / 声音设计保留来源、语言、授权确认和元数据
• 请求审计可隐藏系统噪声，只保留有意义能力调用
• 存储页可清理临时文件、过期历史、过期审计和本地数据

更新、授权与发布状态

当前官网先保留下载和价格结构。正式发布时，下载页会提供稳定安装包、版本说明和更新入口；价格页会承接Free + Pro 一次性买断。

• 应用更新：检查发布清单、查看发布说明、打开下载页
• 升级边界：替换应用包，不自动清空用户数据和模型缓存
• 正式安装包和系统安全提示说明会以下载页最终状态为准
• Pro 授权、账号和权益会在商业化阶段接入

排障

遇到问题时，先确认本地引擎、模型状态、任务状态和日志。大多数问题可以定位到：本地引擎未启动、模型未下载、运行时缺失、语言/声音不兼容、Agent 使用了错误的服务地址。

FAQ

这里收集的是用户最容易卡住的概念差异：模型权重、运行时、声音类型、本地数据和 Agent 调用边界。如果你已经遇到具体错误，建议先看上面的 排障 表，再用这里确认原因。

反馈信息包

如果需要反馈问题，最有帮助的信息不是一整段“不能用”，而是能把本地引擎、模型、任务和日志串起来的最小上下文。下面这些信息可以让支持排障快很多。

联系支持

正式发布前，这里先作为支持入口占位。用户反馈问题时，建议附上 Sonano 版本、macOS 版本、芯片、模型 id、任务 id、是否通过 Agent 调用，以及相关日志片段。

• 打开日志目录：~/Library/Application Support/Sonano/logs/
• 复制本地引擎状态：GET /health
• 复制模型状态：GET /v1/models 中对应模型条目
• 复制任务 id：任务与进度或 API 返回的 job_id