xiaocong3/ecommerce-video-skills

AI Voice-over with edge-tts

Sentence-by-sentence synthesis → Remove silence → 48 kHz WAV → durations.json. Subtitles and scene timings will align with the actual voiceover duration, so there's no more "audio out of sync with video."

Part of ecommerce-video-skills · Script: scripts/tts_edge.py (only depends on edge-tts + ffmpeg)

Inputs

• Script (one sentence per line, or the line field of a storyboard.json)
• Language / voice preference (male/female, lively/calm), speaking rate
• Environment: pip install edge-tts, ffmpeg, and network access to Microsoft TTS service

Steps

1. Rewrite the script into an "easy-to-read" spoken version (see rules), 8–20 characters per sentence.

2. Choose a voice (python scripts/tts_edge.py --list zh-CN to see all):

   Scenario	Recommended Voice
   Energetic product showcase (Male)	zh-CN-YunxiNeural
   Friendly product showcase (Female)	zh-CN-XiaoxiaoNeural / zh-CN-XiaoyiNeural
   Passionate promotion	zh-CN-YunjianNeural
   Professional explanation	zh-CN-YunyangNeural
   Taiwan / Hong Kong	zh-TW-HsiaoChenNeural / zh-HK-HiuMaanNeural
   English	en-US-AndrewNeural · en-US-AvaNeural · en-US-EmmaNeural

3. Synthesize:

   pip install edge-tts
   # Single sentence preview
   python scripts/tts_edge.py "夏天带冰水出门，不到中午就变温了？" --voice zh-CN-YunxiNeural --rate "+10%" -o out/hook.wav
   # Full storyboard (one sentence per scene → build/tts/l00.wav … + durations.json)
   python scripts/tts_edge.py --storyboard storyboard.json --outdir build/tts
   

4. Preview 2 sentences before batch processing: Speed +5% to +15% sounds most like a promotional voiceover; over +20% may feel rushed.

5. Hand over to ffmpeg-auto-assemble (which will call this script automatically) or your own editing software.

Script Rewriting Rules

• Write numbers as they are pronounced: 2核8G → 两核八G; 24h → 二十四小时; insert spaces between letters in model names: A I. The subtitle (sub field) can retain the original writing.
• One sentence should express one idea; a comma is a breathing point, and end with a period or question mark to let the intonation fall.
• Remove written-style words: "此款产品具有…" → "这只杯子…".
• If an English brand name is mispronounced, write the phonetic or homophonic spelling in line, and keep the correct spelling in sub.

Prompt Template

Convert the following promotional copy into a script suitable for TTS reading: each sentence 8–20 characters, one idea per sentence, colloquial;
Write numbers and letters as they are pronounced; additionally output a column for "subtitle version" retaining the original writing and **bold** 1 keyword.
Do not add selling points or data not present in the original text.
Original: {…}

Checklist

• Preview 2 sentences to confirm voice and speed
• Numbers, English words, and brand names are pronounced correctly
• durations.json has been generated, total duration meets the target
• Before commercial use, verify the labeling requirements for AI voiceovers on your platform and region (e.g., if "AI-generated" label is needed)

Common Issues and Fixes

Issue	Fix
edge-tts failed / timeout	Network issue; the script retries 3 times; try a different network or retry later; offline, use assemble.py --tts none to preview the video first
Mispronunciation	Write the phonetic/homophonic spelling in line, keep the original in sub
Too long pause between sentences	Leading/trailing silence is automatically removed; adjust the pad in storyboard (default is 0.25s)
Voice sounds flat	Switch to YunjianNeural/XiaoyiNeural; --pitch "+5Hz"; end sentences with a question/exclamation mark
Need a realistic human voice	edge-tts is synthetic speech; for high-fidelity scenarios, use real human recordings; the pipeline still works (place recordings in build/tts/lXX.wav)

edge-tts is maintained by the community (rany2/edge-tts, LGPL-3.0), calling Microsoft's online service; this repository only installs it as a dependency and does not include its code.