minimax-tts-pipeline

MiniMax TTS Pronunciation Control

Process pronunciation issues in the text file step by step, and finally call the MiniMax TTS API to generate audio.

Input

Parameter	Required	Description
Text file path	Yes	Absolute path of the .txt file to be processed
Output directory	No	By default, create in the same directory as the input file tts-{YYYYMMDD-HHMMSS}/ directory

User pronunciation rule management

When the user requests to add/query/delete/modify pronunciation rules (such as "Qwen is read as Qianwen", "see what rules there are", "delete the Qwen rule"), read <SKILL_DIR>/references/manage-user-rules.md and <SKILL_DIR>/references/pronunciation-rules.md, then operate according to the instructions <SKILL_DIR>/user-rules.json。

Workflow

输入.txt → input.raw.txt → [脚本] normalize_punctuation.py → input.txt
         → [脚本] scan_terms.py → terms.json(草稿)
         → [Subagent 1] 补全规范化 → terms.json
         → [脚本] validate + generate_normalized.py → normalized.txt
         → [Subagent 2] 补全读法 + 多音字识别 → terms.json
         → [脚本] validate
         → [Subagent 3] 复核 → terms.json(review.pass)
         → [脚本] validate + call_tts.py → output.wav + output.title
         → [脚本] title_to_srt.py → output.srt

Use <SKILL_DIR> to represent the absolute path of this skill's directory. Use <run_dir> to represent the absolute path of the currently running output directory (i.e., the full path of the tts-{YYYYMMDD-HHMMSS}/ directory created in Step 0).

Step -1: Environment pre-check

Before starting any processing, check the runtime environment and the MiniMax API Key in sequence.

Python and dependency check:

1. Run python3 --version, confirm Python >= 3.10. If the version is too low or it is not installed, prompt the user to install it and retry, and stop the process.
2. Run python3 -c "import requests", confirm that the requests library is installed. If it is not installed, prompt the user to run pip3 install requests(or pip install requests) and retry, and stop the process.

API Key check:

1. Check whether <SKILL_DIR>/.env(i.e., the .env file in the same directory as SKILL.md) exists. If it does not exist, create an empty .env file.
2. Read the .env file and check whether MINIMAX_API_KEY exists and its value is non-empty.
3. If it is already configured, continue to the next step.
4. If it is not configured, ask the user for the MiniMax API Key. After the user provides it, append MINIMAX_API_KEY=<用户提供的值> to the <SKILL_DIR>/.env file, then continue.

Step 0: Initialize the run directory

1. Get the text file path from the user input.
2. Create the <input_dir>/tts-{YYYYMMDD-HHMMSS}/ directory, where <input_dir> is the directory containing the input file; unless the user explicitly specifies an output directory, do not switch to the current working directory or the skill project directory.
   • If writing to the same directory as the input file is not possible due to sandbox or permission restrictions, you must first request user authorization; only when the user explicitly agrees may you switch to another directory.
3. Copy the input file as <run_dir>/input.raw.txt。
4. Perform punctuation normalization:

python3 <SKILL_DIR>/scripts/normalize_punctuation.py <run_dir>/input.raw.txt <run_dir>/input.txt

1. Run:

python3 <SKILL_DIR>/scripts/scan_terms.py <run_dir>/input.txt <run_dir>/terms.json

1. Proceed to Step 1.

Step 1: Case normalization determination

Replace <SKILL_DIR> and <run_dir> with the actual absolute paths, then send the following prompt to the subagent:

请先阅读以下文件，然后执行任务。

## 必读文件（按顺序阅读）

1. 操作指引：<SKILL_DIR>/references/step-1-normalize.md
2. 发音规则参考：<SKILL_DIR>/references/pronunciation-rules.md
3. 用户自定义规则：<SKILL_DIR>/user-rules.json（如文件不存在则跳过）
4. 原文：<run_dir>/input.txt
5. 候选词：<run_dir>/terms.json

## 任务

按操作指引的规则，处理 terms.json 中每个 term 的 normalized、category、reason 字段。

## 输出

直接修改并保存 <run_dir>/terms.json（不要创建新文件）。

## 校验

修改完成后，执行 `python3 <SKILL_DIR>/scripts/validate_terms.py <run_dir>/terms.json 1`。如果校验失败，根据 errors 列表修正 terms.json，重新校验，直到通过。

## 收尾

校验通过后，执行 `python3 <SKILL_DIR>/scripts/generate_normalized.py <run_dir>/input.txt <run_dir>/terms.json <run_dir>/normalized.txt`。

Step 2: Pronunciation reading determination

Replace <SKILL_DIR> and <run_dir> with the actual absolute paths, then send the following prompt to the subagent:

请先阅读以下文件，然后执行任务。

## 必读文件（按顺序阅读）

1. 操作指引：<SKILL_DIR>/references/step-2-reading.md
2. 发音规则参考：<SKILL_DIR>/references/pronunciation-rules.md
3. 用户自定义规则：<SKILL_DIR>/user-rules.json（如文件不存在则跳过）
4. 原文：<run_dir>/input.txt
5. 规范化后文本：<run_dir>/normalized.txt
6. 候选词：<run_dir>/terms.json

## 任务

按操作指引的规则，处理 terms.json 中每个 term 的 reading、category 字段，并识别原文中遗漏的多音字。

## 输出

直接修改并保存 <run_dir>/terms.json（不要创建新文件）。

## 校验

修改完成后，执行 `python3 <SKILL_DIR>/scripts/validate_terms.py <run_dir>/terms.json 2`。如果校验失败，根据 errors 列表修正 terms.json，重新校验，直到通过。

Step 3: Quality review

Replace <SKILL_DIR> and <run_dir> After replacing with the actual absolute path, send the following prompt to the subagent:

请先阅读以下文件，然后执行任务。

## 必读文件（按顺序阅读）

1. 操作指引：<SKILL_DIR>/references/step-3-review.md
2. 发音规则参考：<SKILL_DIR>/references/pronunciation-rules.md
3. 用户自定义规则：<SKILL_DIR>/user-rules.json（如文件不存在则跳过）
4. 原文：<run_dir>/input.txt
5. 规范化文本：<run_dir>/normalized.txt
6. 完整候选词：<run_dir>/terms.json

## 任务

按操作指引的检查项，对 terms.json 做最终质量复核。

## 输出

直接修改并保存 <run_dir>/terms.json（不要创建新文件）。

## 校验

修改完成后，执行 `python3 <SKILL_DIR>/scripts/validate_terms.py <run_dir>/terms.json 3`。如果校验失败，根据 errors 列表修正 terms.json，重新校验，直到通过。

Step 4: Generate audio and subtitle JSON

Call the MiniMax TTS API:

python3 <SKILL_DIR>/scripts/call_tts.py <run_dir>/normalized.txt <run_dir>/terms.json <run_dir>/output.wav <run_dir>/output.title

This step will:

• Generate and save WAV audio to disk:<run_dir>/output.wav
• Download and save the subtitle JSON returned by MiniMax to disk:<run_dir>/output.title

Step 5: Generate SRT subtitles

Based on the MiniMax subtitle JSON obtained in Step 4 and the WAV audio, generate SRT subtitles:

python3 <SKILL_DIR>/scripts/title_to_srt.py <run_dir>/output.title <run_dir>/output.wav <run_dir>/output.srt

Report the results to the user:

• Audio file path
• MiniMax subtitle JSON file path
• SRT subtitle file path
• How many tone rules were used
• How many text replacements were made

Files saved to disk

tts-YYYYMMDD-HHMMSS/
  input.raw.txt    # 原始输入（只读）
  input.txt        # 标点规范化后的输入（只读）
  terms.json       # 全流程唯一结构化工作文件
  normalized.txt   # 规范化后的文本
  output.wav       # MiniMax TTS 输出音频
  output.title     # MiniMax 返回的字级时间戳字幕 JSON
  output.srt       # 根据 output.title + output.wav 生成的 SRT 字幕

Constraints

• Only one terms.json is maintained throughout the entire workflow; all subagents directly modify this same file.
• The LLM only modifies terms.json, and does not directly modify normalized.txt or input.txt.
• Text replacement, tone generation, and API calls are all executed by scripts.
• If validation fails at any stage, stop and do not continue to subsequent stages.
• MINIMAX_API_KEY is read from the <SKILL_DIR>/.env file.

Resources

scripts/

• normalize_punctuation.py <input> <output> — Stage 0: Add periods to text whose sentence-ending punctuation is missing due to line breaks
• scan_terms.py — Stage 0: Extract candidate terms from the source text and generate a terms.json draft
• validate_terms.py <terms_json> <stage> — Stage 1/2/3: Validate the terms.json schema
• generate_normalized.py <input> <terms> <output> — After Stage 1: Generate normalized text based on terms.json
• call_tts.py <normalized> <terms> <output_wav> [output_title] — Stage 4: Call the MiniMax TTS API to generate WAV audio and download the subtitle JSON
• title_to_srt.py <input_title> <input_wav> [output_srt] — Stage 5: Generate SRT subtitles based on the MiniMax subtitle JSON and WAV audio

references/

• pronunciation-rules.md — Pronunciation rules quick reference (category enum, reading format, key constraints)
• manage-user-rules.md — User pronunciation rule management guide (loaded on demand)
• api-voice-settings.md — Explanation of the voice_id, speed, vol, and pitch parameters in the MiniMax API request and where to modify them
• step-1-normalize.md — Step 1 operating guide: capitalization normalization decision
• step-2-reading.md — Step 2 operating guide: pronunciation reading decision + polyphonic character identification
• step-3-review.md — Step 3 operating guide: quality review

Other files

• user-rules.json — User-defined pronunciation rules (maintained by the agent through dialogue, consumed by each step)
• .env — MiniMax API Key storage

Modify API voice parameters

If the user asks about or wants to modify the voice, speed, volume, or pitch parameters in the MiniMax TTS API request (voice_id、speed、vol、pitch, please first read <SKILL_DIR>/references/api-voice-settings.md. These parameters need to be modified directly in the payload of <SKILL_DIR>/scripts/call_tts.py .