KrillinAI Documentation

File: README.md Copy Chapter

Growee Skills — KrillinAI's Agent Skills are available through this full-lifecycle AI growth skills collection.

Project Introduction ([Explore Growee Skills](https://github.com/krillinai/growee-skills)) Copy Chapter

Quick Start

KrillinAI is a versatile audio and video localization and enhancement solution developed by the Krillin AI team, designed for both human users and AI Agents. The tool covers the complete pipeline including video download, speech transcription, subtitle translation, TTS dubbing, portrait conversion, and cover generation, supporting both landscape and portrait formats to ensure perfect presentation on all major platforms (Bilibili, Xiaohongshu, Douyin, WeChat Video, Kuaishou, YouTube, TikTok, etc.). Human users can complete end-to-end content localization with one click via the client; each capability can also be invoked independently via CLI, and AI Agents can orchestrate single or multiple stages on demand to flexibly compose automated workflows.

New Features Copy Chapter

🤖 CLI Support: Provides a phased command-line interface where each stage executes independently and outputs structured results, supporting cross-stage artifact reuse.

🧩 Skills Collection: The skills/ directory provides per-stage Skills for AI Agents to invoke directly under a stable contract, no need to parse CLI documentation.

🔗 Pipeline Orchestration: Chain multiple stages in one command, enabling full automation from download to rendering.

🖼️ Cover Generation: Automatically generate platform cover images from the original video thumbnail and a prompt template.

Key Features and Functions: Copy Chapter

📥 Video Acquisition: Supports yt-dlp downloads or local file uploads

📜 Accurate Recognition: High-accuracy speech recognition based on Whisper

🧠 Intelligent Segmentation: Subtitle segmentation and alignment using LLM

🔄 Terminology Replacement: One-click replacement of professional vocabulary

🌍 Professional Translation: LLM translation with context to maintain natural semantics

🎙️ Voice Cloning: Offers selected voice tones from CosyVoice or custom voice cloning

🎬 Video Composition: Automatically processes landscape and portrait videos and subtitle layout

💻 Cross-Platform: Supports Windows, Linux, macOS, providing desktop, server, and CLI modes

Effect Demonstration Copy Chapter

The image below shows the effect of the subtitle file generated after importing a 46-minute local video and executing it with one click, without any manual adjustments. There are no omissions or overlaps, the segmentation is natural, and the translation quality is very high.

| ### Subtitle Translation

https://github.com/user-attachments/assets/bba1ac0a-fe6b-4947-b58d-ba99306d0339 | ### Dubbing

https://github.com/user-attachments/assets/0b32fad3-c3ad-4b6a-abf0-0865f0dd2385 | ### Portrait Mode

https://github.com/user-attachments/assets/c2c7b528-0ef8-4ba9-b8ac-f9f92f6d4e71 |
| --- | --- | --- |

🔍 Supported Speech Recognition Services Copy Chapter

All local models in the table below support automatic installation of executable files + model files; you just need to choose, and Klic will prepare everything for you.

🚀 Large Language Model Support Copy Chapter

✅ Compatible with all cloud/local large language model services that comply with OpenAI API specifications, including but not limited to:

• OpenAI
• Gemini
• DeepSeek
• Tongyi Qianwen
• Locally deployed open-source models
• Other API services compatible with OpenAI format

🎤 TTS Text-to-Speech Support Copy Chapter

• Alibaba Cloud Voice Service
• OpenAI TTS
• MiniMax TTS

Language Support Copy Chapter

Input languages supported: Chinese, English, Japanese, German, Turkish, Korean, Russian, Malay (continuously increasing)

Translation languages supported: English, Chinese, Russian, Spanish, French, and 101 other languages

Interface Preview Copy Chapter

🚀 Quick Start Copy Chapter

You can ask questions on the Deepwiki of KrillinAI. It indexes the files in the repository, so you can find answers quickly.

Basic Steps Copy Section

First, download the executable file that matches your device system from the Release, then follow the tutorial below to choose between the desktop version or non-desktop version. Place the software download in an empty folder, as running it will generate some directories, and keeping it in an empty folder will make management easier.

【If it is the desktop version, i.e., the release file with "desktop," see here】
The desktop version is newly released to address the issues of new users struggling to edit configuration files correctly, and there are some bugs that are continuously being updated.

1. Double-click the file to start using it (the desktop version also requires configuration within the software)

【If it is the non-desktop version, i.e., the release file without "desktop," see here】
The non-desktop version is the initial version, which has a more complex configuration but is stable in functionality and suitable for server deployment, as it provides a UI in a web format.

1. Create a config folder within the folder, then create a config.toml file in the config folder. Copy the contents of the config-example.toml file from the source code's config directory into config.toml, and fill in your configuration information according to the comments.
2. Double-click or execute the executable file in the terminal to start the service
3. Open your browser and enter http://127.0.0.1:8888 to start using it (replace 8888 with the port you specified in the configuration file)

To: macOS Users Copy Section

【If it is the desktop version, i.e., the release file with "desktop," see here】
Due to signing issues, the desktop version currently cannot be double-clicked to run or installed via dmg; you need to manually trust the application. The method is as follows:

1. Open the terminal in the directory where the executable file (assuming the file name is KrillinAI_1.0.0_desktop_macOS_arm64) is located
2. Execute the following commands in order:

sudo xattr -cr ./KrillinAI_1.0.0_desktop_macOS_arm64
sudo chmod +x ./KrillinAI_1.0.0_desktop_macOS_arm64
./KrillinAI_1.0.0_desktop_macOS_arm64

【If it is the non-desktop version, i.e., the release file without "desktop," see here】
This software is not signed, so when running on macOS, after completing the file configuration in the "Basic Steps," you also need to manually trust the application. The method is as follows:

1. Open the terminal in the directory where the executable file (assuming the file name is KrillinAI_1.0.0_macOS_arm64) is located

2. Execute the following commands in order:

   text Copy

   sudo xattr -rd com.apple.quarantine ./KrillinAI_1.0.0_macOS_arm64
    sudo chmod +x ./KrillinAI_1.0.0_macOS_arm64
    ./KrillinAI_1.0.0_macOS_arm64

   This will start the service

Docker Deployment Copy Section

This project supports Docker deployment; please refer to the Docker Deployment Instructions

CLI Usage Copy Section

KrillinAI provides a staged CLI suitable for scripting, automation pipelines, and AI Agent invocation. The CLI executes synchronously by default, outputs a single JSON line to stdout upon completion, and writes krillinai_manifest.json to the working directory for subsequent stages to reuse prior artifacts.

Build from source:

go build -o build/krillinai-cli ./cmd/cli

Command overview:

Typical workflow:

# 1. Generate subtitles: original, target, bilingual, and vertical short subtitles
./build/krillinai-cli subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --origin-lang en \
  --target-lang zh_cn \
  --workdir tasks/demo \
  --caption-source any

# 2. Generate dubbing from target-language subtitles
./build/krillinai-cli tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt \
  --line-mode target-only \
  --video tasks/demo/origin_video.mp4

# 3. Produce horizontal bilingual-subtitle video
./build/krillinai-cli render-horizontal \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/bilingual_srt.srt

# 4. Produce vertical short-subtitle video
./build/krillinai-cli render-vertical \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/short_origin_mixed_srt.srt \
  --major-title "今日话题" \
  --minor-title "AI Video"

Agent integration conventions:

• Parse the last JSON line on stdout and krillinai_manifest.json — do not parse plain-text logs.
• The outputs field records stage artifact paths; subsequent commands can pass only --workdir to reuse the manifest.
• Supports --dry-run to validate parameters and generate a manifest without downloading video or calling external AI services.
• Handle errors by error.kind: usage → fix parameters, retryable → retry, dependency → install ffmpeg / ffprobe / yt-dlp.

For a complete parameter reference, see CLI Capability Summary.

Agent Skills Copy Section

The repository also includes ready-to-use Agent Skills under skills/ so coding agents can call the CLI with stable conventions:

• krillinai-cli: top-level routing skill for choosing subtitle, TTS, render, pipeline, or cover workflows.
• krillinai-subtitle, krillinai-tts, krillinai-render-horizontal, and krillinai-render-vertical: stage-specific operating guides.
• krillinai-pipeline and krillinai-cover: planning/reserved guides for pipeline orchestration and cover generation until those execution paths are fully wired.
• cli-contract.md: shared JSON, manifest, outputs, and error-handling contract.

Based on the provided configuration file, here is the updated "Configuration Help (Must Read)" section for your README file:

Configuration Help (Must Read) Copy Section

The configuration file is divided into several sections: [app], [server], [llm], [transcribe], and [tts]. A task is composed of speech recognition (transcribe) + large model translation (llm) + optional voice services (tts). Understanding this will help you better grasp the configuration file.

Easiest and Quickest Configuration:

For Subtitle Translation Only:

• In the [transcribe] section, set provider.name to openai.
• You will then only need to fill in your OpenAI API key in the [llm] block to start performing subtitle translations. The app.proxy, model, and openai.base_url can be filled in as needed.

Balanced Cost, Speed, and Quality (Using Local Speech Recognition):

• In the [transcribe] section, set provider.name to fasterwhisper.
• Set transcribe.fasterwhisper.model to large-v2.
• Fill in your large language model configuration in the [llm] block.
• The required local model will be automatically downloaded and installed.

Text-to-Speech (TTS) Configuration (Optional):

• TTS configuration is optional.
• First, set the provider.name under the [tts] section (e.g., aliyun or openai).
• Then, fill in the corresponding configuration block for the selected provider. For example, if you choose aliyun, you must fill in the [tts.aliyun] section.
• Voice codes in the user interface should be chosen based on the selected provider's documentation.
• Note: If you plan to use the voice cloning feature, you must select aliyun as the TTS provider.

Alibaba Cloud Configuration:

• For details on obtaining the necessary AccessKey, Bucket, and AppKey for Alibaba Cloud services, please refer to the Alibaba Cloud Configuration Instructions. The repeated fields for AccessKey, etc., are designed to maintain a clear configuration structure.

Short Subtitle Configuration:

• short_subtitle_max_chars: Maximum characters per line for English short subtitles (default: 20)
  • Designed for portrait/vertical videos
  • Chinese text remains intact, English text is split according to this length
  • Recommended value: 15-25

Frequently Asked Questions Copy Chapter

Please visit Frequently Asked Questions

Contribution Guidelines Copy Chapter

1. Do not submit useless files, such as .vscode, .idea, etc.; please use .gitignore to filter them out.
2. Do not submit config.toml; instead, submit config-example.toml.

Contact Us Copy Chapter

1. Join our QQ group for questions: 754069680
2. Follow our social media accounts, Bilibili, where we share quality content in the AI technology field every day.

Star History Copy Chapter

File: docs/zh/aliyun.md Copy Chapter

前提条件 Copy Chapter

您需要拥有一个 阿里云 账户并完成实名认证。大多数服务都有免费配额。

获取阿里云 `access_key_id` 和 `access_key_secret` Copy Chapter

1. 访问 阿里云 AccessKey 管理页面。

2. 点击“创建 AccessKey”。如有需要，选择使用方式为“用于本地开发环境”。

3. 妥善保管；最好将其复制到本地文件中进行存储。

激活阿里云语音服务 Copy Chapter

1. 访问 阿里云语音服务管理页面。您需要在首次访问时激活该服务。

2. 点击“创建项目”。

3. 选择功能并激活它们。

4. “流式文本转语音（CosyVoice 大模型）”需要升级到商业版；其他服务可以使用免费试用版。

5. 直接复制应用密钥。

激活阿里云 OSS 服务 Copy Chapter

1. 访问 阿里云对象存储服务控制台。您需要在首次访问时激活该服务。

2. 在左侧选择 Bucket 列表，然后点击“创建”。

3. 选择“快速创建”，填写合规的 Bucket 名称，并选择 上海 区域以完成创建（您在此处输入的名称将作为配置项 aliyun.oss.bucket 的值）。

4. 创建后，进入该 Bucket。

5. 关闭“阻止公共访问”开关，并将读写权限设置为“公共读取”。

File: docs/zh/cli.md Copy Chapter

KrillinAI CLI 能力总结

KrillinAI 提供一套阶段化命令行工具，适用于脚本编排、CI/CD 流水线以及 AI Agent 调用。所有命令默认同步执行，完成后向 stdout 输出 JSON 结果。

命令总览 Copy Chapter

通用机制 Copy Chapter

输入方式 Copy Section

• YouTube URL：https://www.youtube.com/watch?v=xxx，自动通过 yt-dlp 下载视频
• 本地文件：local:demo.mp4 或直接路径 path/to/video.mp4
• SRT 字幕文件：path/to/subtitle.srt

JSON 输出 Copy Section

所有命令执行完毕后，向 stdout 输出一行 JSON。Agent 或调用方应以此为唯一可靠输出，不要解析普通日志。

{
  "ok": true,
  "stage": "subtitle",
  "workdir": "tasks/demo",
  "task_id": "abc123",
  "outputs": {
    "origin_video": "tasks/demo/origin_video.mp4",
    "origin_srt": "tasks/demo/origin_srt.srt",
    "target_srt": "tasks/demo/target_language_srt.srt",
    "bilingual_srt": "tasks/demo/bilingual_srt.srt"
  },
  "warnings": [],
  "duration_ms": 45200
}

失败时：

{
  "ok": false,
  "error": {
    "kind": "retryable",
    "code": "audio_transcription_failed",
    "message": "transcription error: connection timeout",
    "retryable": true
  }
}

退出码 Copy Section

Dry-Run 模式 Copy Section

所有命令支持 --dry-run 参数，仅校验参数合法性并生成 manifest 文件，不调用任何外部服务（不下载视频、不调用 AI API）。

krillinai subtitle "https://youtube.com/watch?v=abc" --origin-lang en --target-lang zh_cn --workdir tasks/demo --dry-run

Manifest 持久化 Copy Section

每个任务在工作目录下生成 krillinai_manifest.json，记录所有阶段的输入输出路径和完成状态。后续命令可加载该 manifest 复用已有产物。

错误分类 Copy Section

命令详解 Copy Chapter

1. subtitle — 字幕生成 Copy Section

从视频生成双语字幕。输入可以是 YouTube 链接或本地视频文件。

krillinai subtitle <输入源> [flags]

字幕来源（caption-source）：

输出产物：

示例：

# YouTube 视频字幕翻译
krillinai subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --origin-lang en \
  --target-lang zh_cn \
  --workdir tasks/demo

# 本地视频强制 Whisper 转录
krillinai subtitle "local:my_video.mp4" \
  --origin-lang ja \
  --target-lang zh_cn \
  --caption-source whisper \
  --workdir tasks/my_task

# 仅校验参数
krillinai subtitle "https://youtube.com/watch?v=abc" \
  --origin-lang en \
  --target-lang zh_cn \
  --dry-run

2. tts — 语音合成 Copy Section

将 SRT 字幕文件合成为配音音频，并将配音嵌入原视频生成带配音的视频文件。

krillinai tts --input-srt <字幕文件> [flags]

行模式（line-mode）：

输出产物：

示例：

# 从翻译后字幕生成配音
krillinai tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt \
  --line-mode target-only

# 生成配音并嵌入视频
krillinai tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt \
  --video tasks/demo/origin_video.mp4 \
  --voice longxiaochun_v2

3. voices — 查看 TTS 音色 Copy Section

列出 TTS provider 可用的音色代码，用于 tts --voice。

krillinai voices [flags]

示例：

# 查看阿里云 TTS 常用音色代码
krillinai voices --provider aliyun

输出中的 voices[].code 可直接传给 tts --voice。

4. render-horizontal / render-vertical — 视频合成 Copy Section

将字幕或配音合成到视频中，生成横屏或竖屏成品。

krillinai render-horizontal [flags]
krillinai render-vertical [flags]

默认行为（未显式指定 video/subtitle）：

• 未指定 --video：自动使用 manifest 中记录的原始视频（配音模式则使用 video_with_tts.mp4）
• 未指定 --subtitle：横屏用双语字幕，竖屏用简短混排字幕

输出产物：

示例：

# 横屏双语字幕视频
krillinai render-horizontal \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/bilingual_srt.srt

# 竖屏配音视频（带标题）
krillinai render-vertical \
  --workdir tasks/demo \
  --video tasks/demo/video_with_tts.mp4 \
  --subtitle tasks/demo/target_language_srt.srt \
  --dubbed \
  --major-title "今日话题" \
  --minor-title "AI 改变世界"

5. pipeline — 全流程编排 Copy Section

一键串联多个阶段，按序执行。

krillinai pipeline --outputs <阶段列表> [flags]

支持的 outputs 值：

示例：

# 字幕 + 配音 + 横屏成品
krillinai pipeline \
  --outputs "subtitle,tts,horizontal-bilingual"

# 仅字幕 + 竖屏配音视频
krillinai pipeline \
  --outputs "subtitle,vertical-dubbed"

# 全链路（字幕 + 配音 + 封面）
krillinai pipeline \
  --outputs "subtitle,tts,horizontal-dubbed,cover"

6. cover — 封面生成 Copy Section

基于视频内容和翻译信息，生成 AI 封面图。

krillinai cover [flags]

该命令参数和细节由 manifest 驱动，与 pipeline 中的 cover 阶段一致。

7. status — 状态查询 Copy Section

查询任务的当前状态和进度。

krillinai status

CLI 与 Manifest 的协作模式 Copy Chapter

KrillinAI CLI 的命令设计为可独立执行：每个命令可以单独运行，也可以串联使用。串联时，后续命令通过读取前一步生成的 krillinai_manifest.json 获取输入文件路径，实现无缝衔接。

典型工作流：

# 第一步：生成字幕（输出 manifest.json 供后续使用）
krillinai subtitle "https://youtube.com/watch?v=abc" \
  --origin-lang en --target-lang zh_cn --workdir tasks/demo

# 第二步：在字幕基础上生成配音（自动从 manifest 读取 SRT）
krillinai tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt

# 第三步：合成横屏视频
krillinai render-horizontal --workdir tasks/demo

# 等价于一次性 pipeline：
krillinai pipeline --outputs "subtitle,tts,horizontal-bilingual"

Agent 集成指南 Copy Chapter

AI Agent 调用 KrillinAI CLI 时，应遵循以下约定：

1. 输出解析：优先解析 stdout 的 JSON 行，不要依赖日志输出
2. 错误处理：根据 error.kind 字段决定是否重试（retryable → 重试，usage → 修正参数，dependency → 引导用户安装依赖）
3. 进度感知：读取 krillinai_manifest.json 了解各阶段完成状态
4. 产物定位：outputs 字段中记录了所有产物的绝对或相对路径
5. Dry-Run 先行：复杂任务建议先 --dry-run 校验参数合法性

File: docs/zh/docker.md Copy Chapter

Docker 部署指南

快速开始 Copy Chapter

先准备好配置文件，设置服务器监听端口为8888、服务器监听地址为0.0.0.0

docker run启动 Copy Section

docker run -d \
  -p 8888:8888 \
  -v /path/to/config.toml:/app/config/config.toml \
  -v /path/to/tasks:/app/tasks \
  asteria798/krillinai

docker-compose启动 Copy Section

version: '3'
services:
  krillin:
    image: asteria798/krillinai
    ports:
      - "8888:8888"
    volumes:
      - /path/to/config.toml:/app/config/config.toml # 配置文件
      - /path/to/tasks:/app/tasks # 输出目录

持久化模型 Copy Chapter

如果使用fasterwhisper模型， KrillinAI 会自动下载模型所需文件到/app/models目录和/app/bin目录。容器删除后，这些文件会丢失。如果需要持久化模型，可以将这两个目录映射到宿主机的目录。

docker run启动 Copy Section

docker run -d \
  -p 8888:8888 \
  -v /path/to/config.toml:/app/config/config.toml \
  -v /path/to/tasks:/app/tasks \
  -v /path/to/models:/app/models \
  -v /path/to/bin:/app/bin \
  asteria798/krillinai

docker-compose启动 Copy Section

version: '3'
services:
  krillin:
    image: asteria798/krillinai
    ports:
      - "8888:8888"
    volumes:
      - /path/to/config.toml:/app/config/config.toml      
      - /path/to/tasks:/app/tasks
      - /path/to/models:/app/models
      - /path/to/bin:/app/bin

注意事项 Copy Chapter

1. 如果docker容器的网络模式不为host，建议将配置文件服务器监听地址设置为0.0.0.0，否则可能无法访问服务。
2. 如果容器内需要访问宿主机的网络代理，请将代理地址配置项proxy的127.0.0.1设置为host.docker.internal，例如http://host.docker.internal:7890

File: docs/zh/faq.md Copy Chapter

1. 程序报告“找不到配置文件”或“xxxxx需要配置xxxxx API密钥。”我该如何解决？ Copy Section

这是一个常见的设置问题。可能发生这种情况的原因有几个：

1. 文件位置或名称不正确：

• 程序需要一个名为config.toml的配置文件。确保您没有意外地将其命名为config.toml.txt。
• 此文件必须放置在config文件夹内。工作目录的正确结构应为：
  text Copy

  /── config/
  │   └── config.toml
  └── krillinai.exe（您的可执行文件）

• 对于Windows用户： 建议将整个软件目录放在不在C:驱动器上的文件夹中，以避免潜在的权限问题。

2. API密钥配置不完整：

• 应用程序需要为大型语言模型（用于翻译）、语音服务（用于转录和语音合成）和tts服务分别配置。
• 即使您使用OpenAI进行所有操作，您也必须在config.toml文件的不同部分填写密钥。查找llm部分、transcribe部分、tts部分，并填写相应的API密钥和其他所需信息。

2. 我收到包含“yt-dlp错误”的错误。该怎么办？ Copy Section

此错误指向视频下载器的问题，通常与您的网络或下载器的版本有关。

• 网络： 如果您使用代理，请确保在config.toml文件中的代理设置中正确配置。

• 更新yt-dlp： 随软件捆绑的yt-dlp版本可能已过时。您可以通过在软件的bin目录中打开终端并运行以下命令手动更新：

  text Copy

  ./yt-dlp.exe -U

  （如果文件名与您的操作系统不同，请将yt-dlp.exe替换为正确的文件名）。

3. 最终视频中的字幕乱码或显示为方块，特别是在Linux上。 Copy Section

这几乎总是由于系统缺少字体，特别是那些支持中文字符的字体。要解决此问题，您需要安装所需的字体。

1. 下载所需的字体，例如Microsoft YaHei和Microsoft YaHei Bold。
2. 创建一个新的字体目录：sudo mkdir -p /usr/share/fonts/msyh。
3. 将下载的.ttc字体文件复制到此新目录中。
4. 执行以下命令以重建字体缓存：
   text Copy

   cd /usr/share/fonts/msyh
   sudo mkfontscale
   sudo mkfontdir
   sudo fc-cache -fv

4. 在macOS上，应用程序无法启动并显示“KrillinAI已损坏，无法打开”的错误。 Copy Section

这是由于macOS的安全功能Gatekeeper，限制了来自未识别开发者的应用程序。要解决此问题，您必须手动删除隔离属性。

1. 打开终端应用程序。
2. 输入命令xattr -cr后跟一个空格，然后将KrillinAI.app文件从Finder窗口拖到终端中。命令看起来像这样：
   text Copy

   xattr -cr /Applications/KrillinAI.app

3. 按Enter键。您现在应该能够打开该应用程序。

5. 在处理过程中，我收到类似`ffmpeg错误`、`audioToSrt错误`或`退出状态1`的错误。 Copy Section

这些错误通常指向依赖项或系统资源的问题。

• ffmpeg错误： 这表明ffmpeg未安装或无法从系统的PATH访问。确保您安装了完整的官方版本的ffmpeg，并且其位置已添加到系统的环境变量中。
• audioToSrt错误或退出状态1： 此错误发生在转录阶段（音频转文本）。常见原因包括：
  • 模型问题： 本地转录模型（例如fasterwhisper）未能加载或在下载过程中损坏。
  • 内存不足（RAM）： 运行本地模型资源密集。如果您的机器内存不足，操作系统可能会终止该进程，从而导致错误。
  • 网络故障： 如果您使用在线转录服务（如OpenAI的Whisper API），这表明您的网络连接存在问题或API密钥无效。

6. 进度条没有移动。程序是冻结了吗？ Copy Section

不是的，只要您没有看到错误消息，程序就正在工作。进度条仅在主要任务（如转录或视频编码）完全完成后更新。这些任务可能非常耗时，导致进度条长时间暂停。请耐心等待任务完成。

7. 我的NVIDIA 5000系列GPU不支持`fasterwhisper`。我该怎么办？ Copy Section

观察到fasterwhisper模型可能无法与NVIDIA 5000系列GPU正常工作（截至2025年中期）。您有几个替代方案进行转录：

1. 使用基于云的模型： 在config.toml文件中将transcribe.provider.name设置为openai或aliyun。然后，填写相应的API密钥和配置详细信息。这将使用云提供商的Whisper模型，而不是本地模型。
2. 使用其他本地模型： 您可以尝试其他本地转录模型，例如原始的whisper.cpp。

8. 如何找到并填写文本转语音的正确语音/音调代码？ Copy Section

可用的语音及其对应的代码由您使用的语音服务提供商定义。请参考他们的官方文档。

• OpenAI TTS： 文档（查看voice选项）。
• 阿里云： 文档（查看音调列表中的voice参数）。

9. 我如何使用本地大型语言模型（LLM），例如在Ollama上运行的模型进行翻译？ Copy Section

是的，您可以配置KrillinAI使用任何提供OpenAI兼容API端点的本地LLM。

1. 启动您的本地LLM： 确保您的本地服务（例如，运行Llama3的Ollama）处于活动状态并可访问。
2. 编辑config.toml： 在大型语言模型（翻译器）部分：

• 将提供者name（或type）设置为"openai"。
• 将api_key设置为任何随机字符串（例如，"ollama"），因为本地调用不需要它。
• 将base_url设置为您本地模型的API端点。对于Ollama，这通常是http://localhost:11434/v1。
• 将model设置为您提供的模型名称，例如"llama3"。

10. 我可以自定义最终视频中的字幕样式（字体、大小、颜色）吗？ Copy Section

不可以。目前，KrillinAI生成硬编码字幕，这意味着它们直接嵌入到视频帧中。该应用程序不提供自定义字幕样式的选项；它使用预设样式。

对于高级自定义，推荐的解决方法是：

1. 使用KrillinAI生成翻译后的.srt字幕文件。
2. 将您的原始视频和此.srt文件导入专业视频编辑器（例如，Premiere Pro、Final Cut Pro、DaVinci Resolve），以在渲染之前应用自定义样式。

11. 我已经有一个翻译后的`.srt`文件。KrillinAI可以仅使用它进行配音吗？ Copy Section

不可以，目前不支持此功能。该应用程序运行从转录到最终视频生成的完整流程。

File: docs/zh/README.md Copy Chapter

Growee Skills — KrillinAI 的 Agent Skills 已整合至全生命周期 AI 增长技能合集。

项目介绍（[查看 Growee Skills](https://github.com/krillinai/growee-skills)） Copy Chapter

快速开始

KrillinAI 是由 Krillin AI团队开发的多功能音视频本地化与增强解决方案，同时面向人类用户和 AI Agent 设计。工具覆盖视频下载、音频转录、字幕翻译、TTS 配音、竖屏转换、封面生成等完整链路，支持横屏与竖屏格式，确保在所有主要平台（Bilibili、小红书、抖音、微信视频、快手、YouTube、TikTok 等）上完美呈现。人类用户可通过客户端一键完成端到端内容本地化；每项能力也均可通过 CLI 独立调用，AI Agent 可按需编排单个或多个阶段，灵活组合成自动化工作流。

2.0版本新增特性 Copy Chapter

🤖 支持CLI调用：提供阶段化命令行接口，每个阶段独立执行并输出结构化结果，支持跨阶段产物复用。

🧩 Skills集合：skills 目录下提供各阶段 Skills，AI Agent 可按稳定约定直接调用，无需自行解析 CLI 文档。

🔗 Pipeline 串联编排：将多个阶段一键串联，实现从下载到渲染的全流程自动化。

🖼️ 封面生成：根据原视频封面与提示词模板自动生成平台封面图。

主要特点和功能： Copy Chapter

📥 视频获取：支持 yt-dlp 下载或本地文件上传

📜 准确识别：基于 Whisper 的高精度语音识别

🧠 智能分段：使用 LLM 进行字幕分段和对齐

🔄 术语替换：一键替换专业词汇

🌍 精准翻译：基于上下文的 LLM 翻译，保持自然语义

🎙️ 语音克隆：提供 CosyVoice 中选择的语音音调或自定义语音克隆

🎬 视频合成：自动处理横屏和竖屏视频及字幕布局

💻 多平台体验：支持 Windows、Linux、macOS，提供桌面、服务器和 CLI 三种使用方式

效果演示 Copy Chapter

下图展示了在导入一段 46 分钟的本地视频并一键执行后生成的字幕文件效果，无需任何手动调整。没有遗漏或重叠，分段自然，翻译质量非常高。

| ### 字幕翻译

https://github.com/user-attachments/assets/bba1ac0a-fe6b-4947-b58d-ba99306d0339 | ### 配音

https://github.com/user-attachments/assets/0b32fad3-c3ad-4b6a-abf0-0865f0dd2385 | ### 竖屏模式

https://github.com/user-attachments/assets/c2c7b528-0ef8-4ba9-b8ac-f9f92f6d4e71 |
| --- | --- | --- |

🔍 支持的语音识别服务 Copy Chapter

下表中的所有本地模型支持可执行文件 + 模型文件的自动安装；您只需选择，Klic 将为您准备一切。

🚀 大语言模型支持 Copy Chapter

✅ 兼容所有符合 OpenAI API 规范 的云/本地大语言模型服务，包括但不限于：

• OpenAI
• Gemini
• DeepSeek
• 通义千问
• 本地部署的开源模型
• 其他兼容 OpenAI 格式的 API 服务

🎤 TTS 文本转语音支持 Copy Chapter

• 阿里云语音服务
• OpenAI TTS

语言支持 Copy Chapter

支持的输入语言：中文、英语、日语、德语、土耳其语、韩语、俄语、马来语（持续增加中）

支持的翻译语言：英语、中文、俄语、西班牙语、法语及其他 101 种语言

界面预览 Copy Chapter

🚀 快速开始 Copy Chapter

您可以在 KrillinAI 的 Deepwiki 上提问。它会索引库中的文件，因此您可以快速找到答案。

基本步骤 Copy Section

首先，从 Release 下载与您的设备系统匹配的可执行文件，然后按照下面的教程选择桌面版或非桌面版。将软件下载放在一个空文件夹中，因为运行它会生成一些目录，保持在空文件夹中会使管理更容易。

【如果是桌面版，即带有“desktop”的发布文件，请查看这里】
桌面版是新发布的，旨在解决新用户在正确编辑配置文件时遇到的问题，并且有一些错误正在持续更新。

1. 双击文件开始使用（桌面版也需要在软件内进行配置）

【如果是非桌面版，即不带“desktop”的发布文件，请查看这里】
非桌面版是初始版本，配置更复杂，但功能稳定，适合服务器部署，因为它以网页格式提供 UI。

1. 在文件夹内创建一个 config 文件夹，然后在 config 文件夹中创建一个 config.toml 文件。将源代码 config 目录中的 config-example.toml 文件内容复制到 config.toml 中，并根据注释填写您的配置信息。
2. 双击或在终端中执行可执行文件以启动服务
3. 打开浏览器并输入 http://127.0.0.1:8888 开始使用（将 8888 替换为您在配置文件中指定的端口）

对于：macOS 用户 Copy Section

【如果是桌面版，即带有“desktop”的发布文件，请查看这里】
由于签名问题，桌面版目前无法双击运行或通过 dmg 安装；您需要手动信任该应用程序。方法如下：

1. 在可执行文件所在目录打开终端（假设文件名为 KrillinAI_1.0.0_desktop_macOS_arm64）
2. 按顺序执行以下命令：

sudo xattr -cr ./KrillinAI_1.0.0_desktop_macOS_arm64
sudo chmod +x ./KrillinAI_1.0.0_desktop_macOS_arm64
./KrillinAI_1.0.0_desktop_macOS_arm64

【如果是非桌面版，即不带“desktop”的发布文件，请查看这里】
该软件未签名，因此在 macOS 上运行时，在完成“基本步骤”中的文件配置后，您还需要手动信任该应用程序。方法如下：

1. 在可执行文件所在目录打开终端（假设文件名为 KrillinAI_1.0.0_macOS_arm64）

2. 按顺序执行以下命令：

   text Copy

   sudo xattr -rd com.apple.quarantine ./KrillinAI_1.0.0_macOS_arm64
   sudo chmod +x ./KrillinAI_1.0.0_macOS_arm64
   ./KrillinAI_1.0.0_macOS_arm64

   这将启动服务

Docker 部署 Copy Section

该项目支持 Docker 部署；请参阅 Docker 部署说明

CLI 用法 Copy Section

KrillinAI 现在提供阶段化 CLI，适合脚本、自动化流水线和 AI Agent 调用。CLI 默认同步执行，完成后在 stdout 输出一行 JSON，并在工作目录写入 krillinai_manifest.json，方便后续阶段复用已有产物。

从源码构建 CLI：

go build -o build/krillinai-cli ./cmd/cli

命令总览：

典型工作流：

# 1. 生成字幕：源语言、目标语言、双语字幕、竖屏短字幕
./build/krillinai-cli subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --origin-lang en \
  --target-lang zh_cn \
  --workdir tasks/demo \
  --caption-source any

# 2. 根据目标语言字幕生成配音
./build/krillinai-cli tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt \
  --line-mode target-only \
  --video tasks/demo/origin_video.mp4

# 3. 生成横屏双语字幕视频
./build/krillinai-cli render-horizontal \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/bilingual_srt.srt

# 4. 生成竖屏双语短字幕视频
./build/krillinai-cli render-vertical \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/short_origin_mixed_srt.srt \
  --major-title "今日话题" \
  --minor-title "AI Video"

Agent 集成约定：

• 优先解析 stdout 最后一行 JSON 和 krillinai_manifest.json，不要解析普通日志。
• outputs 字段会记录阶段产物路径，后续命令可以只传 --workdir 复用 manifest。
• 支持 --dry-run 校验参数并生成 manifest，不会下载视频或调用外部 AI 服务。
• 根据 error.kind 处理错误：usage 修正参数，retryable 可重试，dependency 需要安装 ffmpeg / ffprobe / yt-dlp。

更完整的参数说明请参考 CLI 能力总结。

Agent Skills Copy Section

仓库还在 skills/ 目录下提供了可直接给 Agent 使用的 Skills，用于按稳定约定调用 CLI：

• krillinai-cli：总入口 skill，用于选择字幕、TTS、渲染、pipeline 或封面工作流。
• krillinai-subtitle、krillinai-tts、krillinai-render-horizontal、krillinai-render-vertical：各阶段的调用指南。
• krillinai-pipeline 和 krillinai-cover：pipeline 编排和封面生成的规划/预留指南，等对应执行路径完全接通后再用于真实执行。
• cli-contract.md：共享的 JSON、manifest、产物路径和错误处理约定。

根据提供的配置文件，以下是您 README 文件中更新的“配置帮助（必读）”部分：

配置帮助（必读） Copy Section

配置文件分为几个部分：[app]、[server]、[llm]、[transcribe] 和 [tts]。一个任务由语音识别（transcribe）+ 大模型翻译（llm）+ 可选的语音服务（tts）组成。理解这一点将帮助您更好地掌握配置文件。

最简单和最快的配置：

仅用于字幕翻译：

• 在 [transcribe] 部分，将 provider.name 设置为 openai。
• 然后，您只需在 [llm] 块中填写您的 OpenAI API 密钥即可开始进行字幕翻译。app.proxy、model 和 openai.base_url 可根据需要填写。

平衡成本、速度和质量（使用本地语音识别）：

• 在 [transcribe] 部分，将 provider.name 设置为 fasterwhisper。
• 将 transcribe.fasterwhisper.model 设置为 large-v2。
• 在 [llm] 块中填写您的大语言模型配置。
• 所需的本地模型将自动下载和安装。

文本转语音（TTS）配置（可选）：

• TTS 配置是可选的。
• 首先，在 [tts] 部分设置 provider.name（例如，aliyun 或 openai）。
• 然后，填写所选提供商的相应配置块。例如，如果选择 aliyun，则必须填写 [tts.aliyun] 部分。
• 用户界面中的语音代码应根据所选提供商的文档进行选择。
• 注意： 如果您计划使用语音克隆功能，则必须选择 aliyun 作为 TTS 提供商。

阿里云配置：

• 有关获取阿里云服务所需的 AccessKey、Bucket 和 AppKey 的详细信息，请参阅 阿里云配置说明。重复的 AccessKey 等字段旨在保持清晰的配置结构。

短字幕配置：

• short_subtitle_max_chars: 短字幕英文每行最大字符数，默认 20
  • 适用于竖屏视频
  • 中文保持完整，英文按此长度拆分
  • 建议值：15-25

常见问题 Copy Chapter

请访问 常见问题

贡献指南 Copy Chapter

1. 请勿提交无用文件，如 .vscode、.idea 等；请使用 .gitignore 过滤它们。
2. 请勿提交 config.toml；请提交 config-example.toml。

联系我们 Copy Chapter

1. 加入我们的 QQ 群以获取问题解答：754069680
2. 关注我们的社交媒体账号，Bilibili，我们每天分享 AI 技术领域的优质内容。

Star 历史 Copy Chapter

File: docs/vi/aliyun.md Copy Chapter

Điều kiện tiên quyết Copy Chapter

Bạn cần có một tài khoản Alibaba Cloud và hoàn thành xác minh danh tính. Hầu hết các dịch vụ đều có hạn mức miễn phí.

Lấy `access_key_id` và `access_key_secret` của Alibaba Cloud Copy Chapter

1. Truy cập trang quản lý AccessKey của Alibaba Cloud.

2. Nhấp vào "Tạo AccessKey." Nếu cần, chọn phương thức sử dụng là "Sử dụng trong môi trường phát triển cục bộ."

3. Giữ nó an toàn; tốt nhất là sao chép nó vào một tệp cục bộ để lưu trữ.

Kích hoạt Dịch vụ Giọng nói Alibaba Cloud Copy Chapter

1. Truy cập trang quản lý Dịch vụ Giọng nói Alibaba Cloud. Bạn cần kích hoạt dịch vụ khi truy cập lần đầu.

2. Nhấp vào "Tạo Dự án."

3. Chọn các tính năng và kích hoạt chúng.

4. "Streaming Text-to-Speech (Mô hình Lớn CosyVoice)" cần được nâng cấp lên phiên bản thương mại; các dịch vụ khác có thể sử dụng phiên bản dùng thử miễn phí.

5. Chỉ cần sao chép khóa ứng dụng.

Kích hoạt Dịch vụ OSS của Alibaba Cloud Copy Chapter

1. Truy cập Bảng điều khiển Dịch vụ Lưu trữ Đối tượng Alibaba Cloud. Bạn cần kích hoạt dịch vụ khi truy cập lần đầu.

2. Chọn danh sách Bucket ở bên trái, sau đó nhấp vào "Tạo."

3. Chọn "Tạo Nhanh," điền tên Bucket hợp lệ và chọn khu vực Thượng Hải để hoàn tất việc tạo (tên bạn nhập ở đây sẽ là giá trị cho mục cấu hình aliyun.oss.bucket).

4. Sau khi tạo, vào Bucket.

5. Tắt công tắc "Chặn Truy cập Công khai" và đặt quyền đọc và ghi thành "Đọc Công khai."

File: docs/vi/docker.md Copy Chapter

Hướng dẫn triển khai Docker

Bắt đầu nhanh Copy Chapter

Trước tiên, chuẩn bị tệp cấu hình, thiết lập cổng lắng nghe của máy chủ là 8888, địa chỉ lắng nghe của máy chủ là 0.0.0.0.

Khởi động bằng docker run Copy Section

docker run -d \
  -p 8888:8888 \
  -v /path/to/config.toml:/app/config/config.toml \
  -v /path/to/tasks:/app/tasks \
  asteria798/krillinai

Khởi động bằng docker-compose Copy Section

version: '3'
services:
  krillin:
    image: asteria798/krillinai
    ports:
      - "8888:8888"
    volumes:
      - /path/to/config.toml:/app/config/config.toml # Tệp cấu hình
      - /path/to/tasks:/app/tasks # Thư mục đầu ra

Lưu trữ mô hình Copy Chapter

Nếu sử dụng mô hình fasterwhisper, KrillinAI sẽ tự động tải xuống các tệp cần thiết cho mô hình vào thư mục /app/models và thư mục /app/bin. Sau khi xóa container, các tệp này sẽ bị mất. Nếu cần lưu trữ mô hình, bạn có thể ánh xạ hai thư mục này đến thư mục của máy chủ.

Khởi động bằng docker run Copy Section

docker run -d \
  -p 8888:8888 \
  -v /path/to/config.toml:/app/config/config.toml \
  -v /path/to/tasks:/app/tasks \
  -v /path/to/models:/app/models \
  -v /path/to/bin:/app/bin \
  asteria798/krillinai

Khởi động bằng docker-compose Copy Section

version: '3'
services:
  krillin:
    image: asteria798/krillinai
    ports:
      - "8888:8888"
    volumes:
      - /path/to/config.toml:/app/config/config.toml      
      - /path/to/tasks:/app/tasks
      - /path/to/models:/app/models
      - /path/to/bin:/app/bin

Lưu ý Copy Chapter

1. Nếu chế độ mạng của container docker không phải là host, nên thiết lập địa chỉ lắng nghe của máy chủ trong tệp cấu hình là 0.0.0.0, nếu không có thể không truy cập được dịch vụ.
2. Nếu trong container cần truy cập proxy mạng của máy chủ, hãy thiết lập mục cấu hình proxy 127.0.0.1 thành host.docker.internal, ví dụ http://host.docker.internal:7890.

File: docs/vi/faq.md Copy Chapter

1. Chương trình báo "Không tìm thấy tệp cấu hình" hoặc "xxxxx yêu cầu cấu hình khóa API xxxxx." Làm thế nào để tôi khắc phục điều này? Copy Section

Đây là một vấn đề thiết lập phổ biến. Có một vài lý do điều này có thể xảy ra:

1. Vị trí hoặc Tên Tệp Không Chính Xác:

• Chương trình yêu cầu một tệp cấu hình có tên chính xác là config.toml. Đảm bảo bạn không vô tình đặt tên là config.toml.txt.
• Tệp này phải được đặt trong một thư mục config. Cấu trúc đúng của thư mục làm việc nên là:
  text Copy

  /── config/
  │   └── config.toml
  └── krillinai.exe (tệp thực thi của bạn)

• Đối với người dùng Windows: Nên đặt toàn bộ thư mục phần mềm vào một thư mục không nằm trên ổ C: để tránh các vấn đề về quyền truy cập.

2. Cấu Hình Khóa API Chưa Hoàn Chỉnh:

• Ứng dụng yêu cầu các cấu hình riêng biệt cho mô hình ngôn ngữ lớn (để dịch), dịch vụ giọng nói (để chuyển văn bản thành giọng nói và tổng hợp giọng nói) và dịch vụ tts.
• Ngay cả khi bạn sử dụng OpenAI cho tất cả, bạn vẫn phải điền khóa vào các phần khác nhau của tệp config.toml. Tìm phần llm, phần transcribe, phần tts và điền các Khóa API tương ứng và thông tin cần thiết khác.

2. Tôi nhận được một lỗi chứa "lỗi yt-dlp." Tôi nên làm gì? Copy Section

Lỗi này chỉ ra một vấn đề với trình tải video, thường liên quan đến mạng của bạn hoặc phiên bản của trình tải.

• Mạng: Nếu bạn sử dụng proxy, hãy đảm bảo nó được cấu hình đúng trong cài đặt proxy trong tệp config.toml của bạn.

• Cập nhật yt-dlp: Phiên bản của yt-dlp đi kèm với phần mềm có thể đã lỗi thời. Bạn có thể cập nhật nó thủ công bằng cách mở một terminal trong thư mục bin của phần mềm và chạy lệnh:

  text Copy

  ./yt-dlp.exe -U

  (Thay thế yt-dlp.exe bằng tên tệp đúng cho hệ điều hành của bạn nếu nó khác).

3. Phụ đề trong video cuối bị rối hoặc xuất hiện dưới dạng các khối vuông, đặc biệt trên Linux. Copy Section

Điều này hầu như luôn do thiếu phông chữ trên hệ thống, đặc biệt là những phông hỗ trợ ký tự Trung Quốc. Để khắc phục điều này, bạn cần cài đặt các phông chữ cần thiết.

1. Tải xuống các phông chữ cần thiết, chẳng hạn như Microsoft YaHei và Microsoft YaHei Bold.
2. Tạo một thư mục phông chữ mới: sudo mkdir -p /usr/share/fonts/msyh.
3. Sao chép các tệp phông .ttc đã tải xuống vào thư mục mới này.
4. Thực hiện các lệnh sau để xây dựng lại bộ nhớ cache phông chữ:
   text Copy

   cd /usr/share/fonts/msyh
   sudo mkfontscale
   sudo mkfontdir
   sudo fc-cache -fv

4. Trên macOS, ứng dụng không khởi động và hiển thị lỗi như "KrillinAI bị hỏng và không thể mở." Copy Section

Điều này do tính năng bảo mật của macOS, Gatekeeper, hạn chế các ứng dụng từ các nhà phát triển không xác định. Để khắc phục điều này, bạn phải xóa thuộc tính cách ly một cách thủ công.

1. Mở ứng dụng Terminal.
2. Gõ lệnh xattr -cr theo sau là một khoảng trắng, sau đó kéo tệp KrillinAI.app từ cửa sổ Finder của bạn vào Terminal. Lệnh sẽ trông giống như sau:
   text Copy

   xattr -cr /Applications/KrillinAI.app

3. Nhấn Enter. Bây giờ bạn nên có thể mở ứng dụng.

5. Tôi nhận được các lỗi như `lỗi ffmpeg`, `lỗi audioToSrt`, hoặc `trạng thái thoát 1` trong quá trình xử lý. Copy Section

Các lỗi này thường chỉ ra các vấn đề với các phụ thuộc hoặc tài nguyên hệ thống.

• lỗi ffmpeg: Điều này cho thấy ffmpeg không được cài đặt hoặc không thể truy cập từ PATH của hệ thống. Đảm bảo bạn đã cài đặt một phiên bản đầy đủ, chính thức của ffmpeg và rằng vị trí của nó đã được thêm vào biến môi trường của hệ thống.
• lỗi audioToSrt hoặc trạng thái thoát 1: Lỗi này xảy ra trong giai đoạn chuyển đổi (từ âm thanh sang văn bản). Các nguyên nhân phổ biến là:
  • Vấn đề với Mô Hình: Mô hình chuyển đổi cục bộ (ví dụ: fasterwhisper) không thể tải hoặc bị hỏng trong quá trình tải xuống.
  • Thiếu Bộ Nhớ (RAM): Chạy các mô hình cục bộ tiêu tốn nhiều tài nguyên. Nếu máy của bạn hết bộ nhớ, hệ điều hành có thể kết thúc quá trình, dẫn đến lỗi.
  • Lỗi Mạng: Nếu bạn đang sử dụng dịch vụ chuyển đổi trực tuyến (như API Whisper của OpenAI), điều này chỉ ra một vấn đề với kết nối mạng của bạn hoặc một khóa API không hợp lệ.

6. Thanh tiến trình không di chuyển. Chương trình có bị treo không? Copy Section

Không, miễn là bạn không thấy thông báo lỗi, chương trình đang hoạt động. Thanh tiến trình chỉ cập nhật sau khi một nhiệm vụ lớn (như chuyển đổi hoặc mã hóa video) hoàn thành hoàn toàn. Những nhiệm vụ này có thể mất nhiều thời gian, khiến thanh tiến trình tạm dừng trong một khoảng thời gian dài. Xin hãy kiên nhẫn và chờ đợi nhiệm vụ hoàn thành.

7. GPU dòng NVIDIA 5000 của tôi không được `fasterwhisper` hỗ trợ. Tôi nên làm gì? Copy Section

Đã có thông báo rằng mô hình fasterwhisper có thể không hoạt động đúng với GPU dòng NVIDIA 5000 (tính đến giữa năm 2025). Bạn có một vài lựa chọn thay thế cho việc chuyển đổi:

1. Sử dụng Mô Hình Dựa Trên Đám Mây: Đặt transcribe.provider.name thành openai hoặc aliyun trong tệp config.toml của bạn. Sau đó, điền khóa API và chi tiết cấu hình tương ứng. Điều này sẽ sử dụng mô hình Whisper của nhà cung cấp đám mây thay vì mô hình cục bộ.
2. Sử dụng Mô Hình Cục Bộ Khác: Bạn có thể thử nghiệm với các mô hình chuyển đổi cục bộ khác, chẳng hạn như whisper.cpp gốc.

8. Làm thế nào để tôi tìm và điền mã giọng nói/tone chính xác cho chuyển văn bản thành giọng nói? Copy Section

Các giọng nói có sẵn và mã tương ứng của chúng được xác định bởi nhà cung cấp dịch vụ giọng nói mà bạn đang sử dụng. Vui lòng tham khảo tài liệu chính thức của họ.

• OpenAI TTS: Tài liệu (xem các tùy chọn voice).
• Alibaba Cloud: Tài liệu (xem tham số voice trong danh sách tone).

9. Làm thế nào tôi có thể sử dụng một Mô Hình Ngôn Ngữ Lớn (LLM) cục bộ, như một cái chạy trên Ollama, để dịch? Copy Section

Có, bạn có thể cấu hình KrillinAI để sử dụng bất kỳ LLM cục bộ nào cung cấp một điểm cuối API tương thích với OpenAI.

1. Khởi động LLM Cục Bộ của Bạn: Đảm bảo dịch vụ cục bộ của bạn (ví dụ: Ollama chạy Llama3) đang hoạt động và có thể truy cập.
2. Chỉnh sửa config.toml: Trong phần cho mô hình ngôn ngữ lớn (người dịch):

• Đặt name (hoặc type) của nhà cung cấp thành "openai".
• Đặt api_key thành bất kỳ chuỗi ngẫu nhiên nào (ví dụ: "ollama"), vì nó không cần thiết cho các cuộc gọi cục bộ.
• Đặt base_url thành điểm cuối API của mô hình cục bộ của bạn. Đối với Ollama, điều này thường là http://localhost:11434/v1.
• Đặt model thành tên của mô hình bạn đang phục vụ, ví dụ, "llama3".

10. Tôi có thể tùy chỉnh kiểu phụ đề (phông chữ, kích thước, màu sắc) trong video cuối không? Copy Section

Không. Hiện tại, KrillinAI tạo ra phụ đề cứng, có nghĩa là chúng được đốt trực tiếp vào các khung video. Ứng dụng không cung cấp tùy chọn để tùy chỉnh kiểu phụ đề; nó sử dụng một kiểu đã được định sẵn.

Để tùy chỉnh nâng cao, cách làm việc được khuyến nghị là:

1. Sử dụng KrillinAI để tạo tệp phụ đề .srt đã dịch.
2. Nhập video gốc của bạn và tệp .srt này vào một trình chỉnh sửa video chuyên nghiệp (ví dụ: Premiere Pro, Final Cut Pro, DaVinci Resolve) để áp dụng các kiểu tùy chỉnh trước khi xuất.

11. Tôi đã có một tệp `.srt` đã dịch. KrillinAI có thể sử dụng nó chỉ để thực hiện lồng ghép không? Copy Section

Không, tính năng này hiện không được hỗ trợ. Ứng dụng chạy một quy trình đầy đủ từ chuyển đổi đến tạo video cuối cùng.

File: docs/vi/README.md Copy Chapter

Giới Thiệu Dự Án ([Xem Growee Skills](https://github.com/krillinai/growee-skills)) Copy Chapter

Khởi Đầu Nhanh

KrillinAI là giải pháp đa năng cho việc địa phương hóa và nâng cao âm thanh và video được phát triển bởi nhóm Krillin AI, được thiết kế cho cả người dùng con người và AI Agent. Công cụ bao gồm toàn bộ quy trình bao gồm tải video, chép lại giọng nói, dịch phụ đề, lồng tiếng TTS, chuyển đổi dọc và tạo ảnh bìa, hỗ trợ cả định dạng ngang và dọc để đảm bảo trình bày hoàn hảo trên tất cả các nền tảng chính (Bilibili, Xiaohongshu, Douyin, WeChat Video, Kuaishou, YouTube, TikTok, v.v.). Người dùng con người có thể hoàn thành bản địa hóa nội dung đầu cuối chỉ với một cú nhấp chuột qua client; mỗi khả năng cũng có thể được gọi độc lập qua CLI, và AI Agent có thể điều phối một hoặc nhiều giai đoạn theo nhu cầu để tạo thành các quy trình tự động linh hoạt.

Tính Năng Mới Copy Chapter

🤖 Hỗ Trợ CLI: Cung cấp giao diện dòng lệnh theo giai đoạn, mỗi giai đoạn thực thi độc lập và xuất kết quả có cấu trúc, hỗ trợ tái sử dụng sản phẩm giữa các giai đoạn.

🧩 Bộ Skills: Thư mục skills/ cung cấp Skills cho từng giai đoạn để AI Agent có thể gọi trực tiếp theo quy ước ổn định, không cần tự phân tích tài liệu CLI.

🔗 Phối Hợp Pipeline: Kết nối nhiều giai đoạn trong một lệnh, cho phép tự động hóa hoàn toàn từ tải xuống đến kết xuất.

🖼️ Tạo Ảnh Bìa: Tự động tạo ảnh bìa nền tảng từ hình thu nhỏ video gốc và mẫu gợi ý.

Tính Năng và Chức Năng Chính: Copy Chapter

📥 Lấy Video: Hỗ trợ tải xuống yt-dlp hoặc tải lên tệp cục bộ

📜 Nhận Diện Chính Xác: Nhận diện giọng nói chính xác cao dựa trên Whisper

🧠 Phân Đoạn Thông Minh: Phân đoạn và căn chỉnh phụ đề sử dụng LLM

🔄 Thay Thế Thuật Ngữ: Thay thế từ vựng chuyên ngành chỉ với một cú nhấp

🌍 Dịch Chuyên Nghiệp: Dịch LLM với ngữ cảnh để duy trì ngữ nghĩa tự nhiên

🎙️ Nhân Bản Giọng Nói: Cung cấp các tông giọng được chọn từ CosyVoice hoặc nhân bản giọng nói tùy chỉnh

🎬 Biên Tập Video: Tự động xử lý video ngang và dọc và bố cục phụ đề

💻 Đa Nền Tảng: Hỗ trợ Windows, Linux, macOS, cung cấp phiên bản máy tính để bàn, máy chủ và CLI

Minh Họa Hiệu Ứng Copy Chapter

Hình ảnh dưới đây cho thấy hiệu ứng của tệp phụ đề được tạo ra sau khi nhập một video cục bộ dài 46 phút và thực hiện nó chỉ với một cú nhấp, không cần điều chỉnh thủ công. Không có sự bỏ sót hay chồng chéo, phân đoạn tự nhiên và chất lượng dịch rất cao.

| ### Dịch Phụ Đề

https://github.com/user-attachments/assets/bba1ac0a-fe6b-4947-b58d-ba99306d0339 | ### Lồng Ghép

https://github.com/user-attachments/assets/0b32fad3-c3ad-4b6a-abf0-0865f0dd2385 | ### Chế Độ Dọc

https://github.com/user-attachments/assets/c2c7b528-0ef8-4ba9-b8ac-f9f92f6d4e71 |
| --- | --- | --- |

🔍 Dịch Vụ Nhận Diện Giọng Nói Hỗ Trợ Copy Chapter

Tất cả các mô hình cục bộ trong bảng dưới đây hỗ trợ cài đặt tự động các tệp thực thi + tệp mô hình; bạn chỉ cần chọn, và Klic sẽ chuẩn bị mọi thứ cho bạn.

🚀 Hỗ Trợ Mô Hình Ngôn Ngữ Lớn Copy Chapter

✅ Tương thích với tất cả các dịch vụ mô hình ngôn ngữ lớn cục bộ/đám mây tuân thủ các thông số kỹ thuật API của OpenAI, bao gồm nhưng không giới hạn ở:

• OpenAI
• Gemini
• DeepSeek
• Tongyi Qianwen
• Các mô hình mã nguồn mở triển khai cục bộ
• Các dịch vụ API khác tương thích với định dạng OpenAI

🎤 Hỗ Trợ TTS Chuyển Văn Bản Thành Giọng Nói Copy Chapter

• Dịch Vụ Giọng Nói Alibaba Cloud
• OpenAI TTS

Hỗ Trợ Ngôn Ngữ Copy Chapter

Ngôn ngữ đầu vào được hỗ trợ: Tiếng Trung, Tiếng Anh, Tiếng Nhật, Tiếng Đức, Tiếng Thổ Nhĩ Kỳ, Tiếng Hàn, Tiếng Nga, Tiếng Mã Lai (liên tục tăng)

Ngôn ngữ dịch được hỗ trợ: Tiếng Anh, Tiếng Trung, Tiếng Nga, Tiếng Tây Ban Nha, Tiếng Pháp và 101 ngôn ngữ khác

Xem Trước Giao Diện Copy Chapter

🚀 Khởi Đầu Nhanh Copy Chapter

Bạn có thể đặt câu hỏi trên Deepwiki của KrillinAI. Nó lập chỉ mục các tệp trong kho, vì vậy bạn có thể tìm câu trả lời nhanh chóng.

Các Bước Cơ Bản Copy Section

Đầu tiên, tải xuống tệp thực thi phù hợp với hệ điều hành của bạn từ Release, sau đó làm theo hướng dẫn dưới đây để chọn giữa phiên bản máy tính để bàn hoặc phiên bản không phải máy tính để bàn. Đặt tệp tải xuống phần mềm vào một thư mục trống, vì việc chạy nó sẽ tạo ra một số thư mục, và giữ nó trong một thư mục trống sẽ giúp quản lý dễ dàng hơn.

【Nếu là phiên bản máy tính để bàn, tức là tệp phát hành có "desktop," xem ở đây】
Version máy tính để bàn được phát hành mới để giải quyết các vấn đề của người dùng mới gặp khó khăn trong việc chỉnh sửa tệp cấu hình đúng cách, và có một số lỗi đang được cập nhật liên tục.

1. Nhấp đúp vào tệp để bắt đầu sử dụng (phiên bản máy tính để bàn cũng yêu cầu cấu hình trong phần mềm)

【Nếu là phiên bản không phải máy tính để bàn, tức là tệp phát hành không có "desktop," xem ở đây】
Version không phải máy tính để bàn là phiên bản ban đầu, có cấu hình phức tạp hơn nhưng ổn định về chức năng và phù hợp cho triển khai máy chủ, vì nó cung cấp giao diện người dùng ở định dạng web.

1. Tạo một thư mục config trong thư mục, sau đó tạo một tệp config.toml trong thư mục config. Sao chép nội dung của tệp config-example.toml từ thư mục config của mã nguồn vào config.toml, và điền thông tin cấu hình của bạn theo các chú thích.
2. Nhấp đúp hoặc thực thi tệp thực thi trong terminal để bắt đầu dịch vụ
3. Mở trình duyệt của bạn và nhập http://127.0.0.1:8888 để bắt đầu sử dụng (thay thế 8888 bằng cổng bạn đã chỉ định trong tệp cấu hình)

Đối với: Người Dùng macOS Copy Section

【Nếu là phiên bản máy tính để bàn, tức là tệp phát hành có "desktop," xem ở đây】
Do vấn đề ký, phiên bản máy tính để bàn hiện tại không thể nhấp đúp để chạy hoặc cài đặt qua dmg; bạn cần phải tin tưởng ứng dụng một cách thủ công. Phương pháp như sau:

1. Mở terminal trong thư mục nơi tệp thực thi (giả sử tên tệp là KrillinAI_1.0.0_desktop_macOS_arm64) nằm
2. Thực hiện các lệnh sau theo thứ tự:

sudo xattr -cr ./KrillinAI_1.0.0_desktop_macOS_arm64
sudo chmod +x ./KrillinAI_1.0.0_desktop_macOS_arm64
./KrillinAI_1.0.0_desktop_macOS_arm64

【Nếu là phiên bản không phải máy tính để bàn, tức là tệp phát hành không có "desktop," xem ở đây】
Phần mềm này không được ký, vì vậy khi chạy trên macOS, sau khi hoàn thành cấu hình tệp trong "Các Bước Cơ Bản," bạn cũng cần phải tin tưởng ứng dụng một cách thủ công. Phương pháp như sau:

1. Mở terminal trong thư mục nơi tệp thực thi (giả sử tên tệp là KrillinAI_1.0.0_macOS_arm64) nằm

2. Thực hiện các lệnh sau theo thứ tự:

   text Copy

   sudo xattr -rd com.apple.quarantine ./KrillinAI_1.0.0_macOS_arm64
   sudo chmod +x ./KrillinAI_1.0.0_macOS_arm64
   ./KrillinAI_1.0.0_macOS_arm64

   Điều này sẽ khởi động dịch vụ

Triển Khai Docker Copy Section

Dự án này hỗ trợ triển khai Docker; vui lòng tham khảo Hướng Dẫn Triển Khai Docker

Cách dùng CLI Copy Section

KrillinAI hiện cung cấp CLI theo từng giai đoạn, phù hợp cho script, pipeline tự động hóa và AI Agent. Theo mặc định, CLI chạy đồng bộ, in một dòng JSON ra stdout khi hoàn tất và ghi krillinai_manifest.json vào thư mục làm việc để các giai đoạn sau có thể tái sử dụng các sản phẩm đã tạo.

Biên dịch CLI từ mã nguồn:

go build -o build/krillinai-cli ./cmd/cli

Tổng quan lệnh:

Quy trình điển hình:

# 1. Tạo phụ đề ngôn ngữ gốc, ngôn ngữ đích, song ngữ và phụ đề ngắn cho video dọc
./build/krillinai-cli subtitle "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  --origin-lang en \
  --target-lang zh_cn \
  --workdir tasks/demo \
  --caption-source any

# 2. Tạo lồng tiếng từ phụ đề ngôn ngữ đích
./build/krillinai-cli tts \
  --workdir tasks/demo \
  --input-srt tasks/demo/target_language_srt.srt \
  --line-mode target-only \
  --video tasks/demo/origin_video.mp4

# 3. Tạo video ngang với phụ đề song ngữ
./build/krillinai-cli render-horizontal \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/bilingual_srt.srt

# 4. Tạo video dọc với phụ đề song ngữ ngắn
./build/krillinai-cli render-vertical \
  --workdir tasks/demo \
  --video tasks/demo/origin_video.mp4 \
  --subtitle tasks/demo/short_origin_mixed_srt.srt \
  --major-title "Chủ đề hôm nay" \
  --minor-title "AI Video"

Quy ước tích hợp cho Agent:

• Ưu tiên đọc dòng JSON cuối cùng trong stdout và krillinai_manifest.json; không phân tích log thông thường.
• Trường outputs ghi lại đường dẫn sản phẩm, các lệnh sau có thể tái sử dụng manifest chỉ bằng cách truyền --workdir.
• --dry-run xác thực tham số và tạo manifest mà không tải video hoặc gọi dịch vụ AI bên ngoài.
• Xử lý lỗi theo error.kind: usage là sửa tham số, retryable là có thể thử lại, dependency là cần cài ffmpeg / ffprobe / yt-dlp.

Để biết mô tả tham số đầy đủ hơn, xem tóm tắt khả năng CLI.

Dựa trên tệp cấu hình đã cung cấp, đây là phần "Hỗ Trợ Cấu Hình (Cần Đọc)" đã được cập nhật cho tệp README của bạn:

Hỗ Trợ Cấu Hình (Cần Đọc) Copy Section

Tệp cấu hình được chia thành nhiều phần: [app], [server], [llm], [transcribe], và [tts]. Một nhiệm vụ bao gồm nhận diện giọng nói (transcribe) + dịch mô hình lớn (llm) + dịch vụ giọng nói tùy chọn (tts). Hiểu điều này sẽ giúp bạn nắm bắt tốt hơn tệp cấu hình.

Cấu Hình Dễ Nhất và Nhanh Nhất:

Chỉ Dành Cho Dịch Phụ Đề:

• Trong phần [transcribe], đặt provider.name thành openai.
• Bạn chỉ cần điền khóa API OpenAI của mình trong khối [llm] để bắt đầu thực hiện dịch phụ đề. Các trường app.proxy, model, và openai.base_url có thể được điền theo nhu cầu.

Chi Phí, Tốc Độ và Chất Lượng Cân Bằng (Sử Dụng Nhận Diện Giọng Nói Cục Bộ):

• Trong phần [transcribe], đặt provider.name thành fasterwhisper.
• Đặt transcribe.fasterwhisper.model thành large-v2.
• Điền cấu hình mô hình ngôn ngữ lớn của bạn trong khối [llm].
• Mô hình cục bộ cần thiết sẽ được tự động tải xuống và cài đặt.

Cấu Hình Chuyển Văn Bản Thành Giọng Nói (TTS) (Tùy Chọn):

• Cấu hình TTS là tùy chọn.
• Đầu tiên, đặt provider.name trong phần [tts] (ví dụ: aliyun hoặc openai).
• Sau đó, điền khối cấu hình tương ứng cho nhà cung cấp đã chọn. Ví dụ, nếu bạn chọn aliyun, bạn phải điền phần [tts.aliyun].
• Mã giọng nói trong giao diện người dùng nên được chọn dựa trên tài liệu của nhà cung cấp đã chọn.
• Lưu Ý: Nếu bạn dự định sử dụng tính năng nhân bản giọng nói, bạn phải chọn aliyun làm nhà cung cấp TTS.

Cấu Hình Alibaba Cloud:

• Để biết chi tiết về cách lấy AccessKey, Bucket, và AppKey cần thiết cho dịch vụ Alibaba Cloud, vui lòng tham khảo Hướng Dẫn Cấu Hình Alibaba Cloud. Các trường lặp lại cho AccessKey, v.v., được thiết kế để duy trì cấu trúc cấu hình rõ ràng.

Câu Hỏi Thường Gặp Copy Chapter

Vui lòng truy cập Câu Hỏi Thường Gặp

Hướng Dẫn Đóng Góp Copy Chapter

1. Không gửi các tệp vô dụng, chẳng hạn như .vscode, .idea, v.v.; vui lòng sử dụng .gitignore để lọc chúng ra.
2. Không gửi config.toml; thay vào đó, gửi config-example.toml.

Liên Hệ Với Chúng Tôi Copy Chapter

1. Tham gia nhóm QQ của chúng tôi để đặt câu hỏi: 754069680
2. Theo dõi các tài khoản mạng xã hội của chúng tôi, Bilibili, nơi chúng tôi chia sẻ nội dung chất lượng trong lĩnh vực công nghệ AI mỗi ngày.

Lịch Sử Sao Copy Chapter