xiaocong3/ecommerce-video-skills

AI voice-over: Use free edge-tts (Microsoft Edge online TTS) to generate voiceovers sentence by sentence for e-commerce short videos, automatically trim leading/trailing silence, count durations per sentence, cache for reuse, with optional voice, speed, and pitch adjustments, and provide rewriting rules for the script.

What is ecommerce-video-skills?

This skill, part of the ecommerce-video-skills suite, provides an end-to-end solution for generating AI voice-overs for short e-commerce videos (e.g., for Douyin, TikTok, or WeChat Channels). It leverages the free edge-tts tool, which utilizes Microsoft Edge's online text-to-speech service, to synthesize each sentence of a script into high-quality 48 kHz WAV audio. Key features include automatic removal of leading and trailing silence, generation of a `durations.json` file for precise alignment of subtitles and visuals with the voiceover, caching of generated audio for reuse, and a comprehensive set of rewrite rules designed to transform written promotional copy into natural, easy-to-read spoken scripts. The skill allows selection from dozens of Chinese and English voices, adjustment of speaking rate and pitch, and includes a dry-run mode for previewing the visual sequence without audio. It is designed to integrate seamlessly with other tools in the ecommerce-video-skills pipeline, such as the `ffmpeg-auto-assemble` script, and provides clear guidance on voice selection, script optimization, and common troubleshooting steps, making it ideal for content creators and AI agent users looking to automate the audio track for e-commerce videos.

Works with~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/xiaocong3/ecommerce-video-skills/tree/HEAD/skills/ai-voiceover-edge-tts

Documentation

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

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

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`

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

Preview 2 sentences before batch processing: Speed +5% to +15% sounds most like a promotional voiceover; over +20% may feel rushed.
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.