Use the bundled scripts/volc_voice.py, do not read other local projects or the global Volcano CLI. The client only requires Python 3.10+, FFmpeg, and Volcano Voice service permissions; configuration management only requires Python and does not call paid services.
Account submission and saving
The user may submit a new API Key, or the legacy AppID + Access Token. When the user explicitly submits them for saving, save them directly; do not repeat the key in replies, logs, plans, or project files. The CLI only accepts JSON on standard input, hidden interactive input, or environment variables that the user explicitly requests to save; do not put the key into command-line arguments, temporary text files, repositories, or installation packages.
python scripts/volc_voice.py config --interactive
python scripts/volc_voice.py config --from-env
python scripts/volc_voice.py status
When saving credentials the user has already submitted, use the execution tool to write JSON directly to the standard input of config --stdin-json , without shell string concatenation, and disable terminal echo. The accepted fields are api_key, or submit both app_id and access_token; a non-secret setting speaker、tts_resource、asr_resourcemay be included. When the user has not submitted a new key, do not look for keys in chat history or other project files; configured environment variables may be used for running, but only an explicit save operation persists them.
On Windows it is saved in %APPDATA%/handraw-video-producer/volc-tts.json, encrypted with the current user's DPAPI. Updating the repository, reinstalling, or syncing the Skill will not read or write this file. Changing computers or Windows accounts requires resubmission. Other systems use user configuration files with 0600 permissions. For path overrides and authentication priority, seeAccounts and APIs. On success, only report "saved" and the configuration status; do not show key prefixes or suffixes.
Video voiceover
Through the master control hvp volc-config、hvp volc-status、hvp tts <工程> uses the same implementation. A standalone entry point can also execute:
python scripts/volc_voice.py episode "工程目录"
Video tasks must first pass the plan confirmation, full visual asset review, and output route check of the same package's handraw-video-producer . Read episode.json.narration and each shot's voice_anchor; when there is no confirmed voice ID, check the available voices in the service console; do not guess IDs and do not switch to Edge. For parameter formats, seeVoiceover project。
- Segment by shot semantics. Emotion, pacing, and pauses are designed based on the audience and narrative of the current episode; do not fix five stages, and do not always use a male or female voice.
- After service synthesis, decode to PCM and measure the actual duration by sample count; do not substitute the end point of the last sentence for the file duration. Cache by request and resource; each continuation first passes stage checks, then reuses audio.
- Use the actual word or sentence boundaries from ASR to generate SRT and timing.json; sentence-level returns must not be disguised as word-level, and do not guess timing by character ratio. If ASR differs from the approved text, retain the result and require audited listening; do not silently replace it.
- When narration and pauses exceed the shot, report the shot number and the required frame count; do not truncate, change speed, or modify the timeline. AI rearranges timing within the confirmed direction, and verifies the video, motion, and subtitles afterward. Request caching avoids repeated synthesis; failures have no automatic paid retry.
- Technical success still requires audited listening for voice, pronunciation, emotion, pauses, and subtitles. User aesthetic acceptance is recorded separately; offline tests cannot prove that the real service or listening experience passes.
Standalone text and audio recognition
python scripts/volc_voice.py tts --text-file "台词.txt" --out-dir "语音输出" --speaker "控制台音色ID" --direction "温和、自然的生活讲述" --speech-rate 0
python scripts/volc_voice.py asr --audio "录音.wav" --out-dir "识别输出" --expected-text-file "台词.txt"
Standalone tasks are executed as requested by the user; when the input or output is within a video project, perform the same pre-work check. Video production always prioritizes episode/hvp tts, independent tasks copied outside the project must not be used to bypass stage gates. ASR will upload user-specified audio to the Volcano service. Operations require the corresponding service permissions and network; when network execution is denied, report the actual reason and do not bypass the restriction.
For interface sources, support boundaries, and offline verification, seeAccounts and InterfacesandVerification Records. No real accounts, keys, paid quotas, or finished videos are included.