Shengyue Voice guides
Connect local AI narration to your agent workflow
AI agents that can execute local commands can use the Shengyue Voice CLI. The agent prepares a script, the local model generates audio and the CLI returns file paths. Use it for course narration, voiceovers and multi-role scripts. The installer includes the CLI, with no separate Node.js requirement or desktop window needed. The current desktop interface and downloadable full CLI reference are Chinese.
1. Find the executable and read the current protocol
On macOS, call the executable inside the app. In Windows PowerShell, use the actual installation path. Installing the desktop app does not automatically register a shengyue command. Keep the Chinese executable name below: it is the actual app filename. Replace INSTALL_DIRECTORY with your installation folder on Windows.
"/Applications/声悦.app/Contents/MacOS/声悦" --cli describe
"/Applications/声悦.app/Contents/MacOS/声悦" --cli status
# Windows PowerShell: replace INSTALL_DIRECTORY
& "C:\INSTALL_DIRECTORY\声悦.exe" --cli describe | Out-String
& "C:\INSTALL_DIRECTORY\声悦.exe" --cli status | Out-String2. Check compatibility, activate and prepare resources
Before activation, you can inspect the protocol, status, license and compatibility checks. Catalog access, setup and custom generation require activation. Check your computer and listen to fixed test samples first, then purchase and obtain a device-bound SY2 activation code. Email freeteamlite@gmail.com with purchase or activation questions.
An agent should check resource status first. If components are missing, explain the download and obtain the user’s agreement before explicitly running setup. Generation does not download models automatically. Keep activation codes out of public scripts and logs. The full downloadable CLI reference below is in Chinese.
3. Describe a multi-role script with JSON
After activation, use catalog to obtain the voice IDs available locally. Save the example as a UTF-8 script.json file. Top-level fields set defaults, and each row can specify its own voice and filename. This English example uses the fixed Ryan and Aiden voices.
{
"engine": "standard",
"language": "English",
"sampleRate": 48000,
"project": "Lesson introduction",
"rows": [
{
"text": "First, look at the rectangle’s length and width. Then write the formula for its area.",
"speaker": "Aiden",
"emotion": "natural",
"filename": "lesson-01"
},
{
"text": "Now try the next exercise at your own pace.",
"speaker": "Ryan",
"emotion": "natural",
"filename": "lesson-02"
}
]
}4. Generate audio and read the local file paths
A successful regular generation returns one JSON line on stdout with ok and result. Read local audio paths from result.items[].paths.wav or paths.mp3; stderr carries progress. Describe and version return their own JSON formats, while help is plain text. Do not parse every command as if it returned the same envelope.
Each batch allows up to 5,000 characters and 100 rows, with at most 600 characters per row. Input files or stdin may be at most 2 MB. The CLI does not split long lines automatically or parse DOCX, PPTX or PDF. Import Office documents in desktop projects; convert CLI requests to the documented JSON or plain-text format.
"/Applications/声悦.app/Contents/MacOS/声悦" --cli generate --input script.json --output-dir ./audio5. Keep voices consistent across batches
Character voices lock to a chosen sample by default and reuse it for later lines. Keep voiceScopeId, voiceId, voiceRevision and voice settings stable across batches and individual retakes. Use a new voiceRevision when intentionally changing a voice. Locked and reference voices in the current release retain their sample’s expression; line-level emotion instructions do not redefine them.
The desktop and CLI share a lock for the same data directory. Do not run competing generation, download or mutation operations in parallel. On BUSY, wait and retry a limited number of times. After a timeout or cancellation, inspect history first so you do not regenerate completed segments unnecessarily.
Exports, privacy and agent costs
The CLI’s regular ZIP export packages individual audio segments. It does not mix projects, merge audio or create subtitles. Manage take selection, waveform edits, background music and merged WAV, MP3 and SRT in desktop projects.
Once resources are ready, Shengyue generation and license verification run locally. External agents handle writing, reasoning, network use and scripts according to their own settings and billing. Integration uses the local CLI, with no dedicated MCP server or guaranteed token-saving percentage.