Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(audio): add ElevenLabs narration backend

hugohe3ba3af9f15d8f
diff --git a/.env.example b/.env.example
index a83319f5..3811e8ee 100644
--- a/.env.example
+++ b/.env.example
@@ -127,6 +127,16 @@
# Switch providers by changing IMAGE_BACKEND only.
# 切换提供商时,只改 IMAGE_BACKEND 即可。
+# ─────────────────────────────────────────────────────────────
+# Audio narration TTS (notes_to_audio.py) / 旁白音频 TTS
+# ─────────────────────────────────────────────────────────────
+# edge-tts is the default narration backend and needs no API key.
+# Use ElevenLabs only when you want high-quality cloud narration.
+# edge-tts 是默认旁白后端,无需 API Key。
+# 需要高质量云端旁白时再配置 ElevenLabs。
+#
+# ELEVENLABS_API_KEY=your-elevenlabs-api-key
+
# ─────────────────────────────────────────────────────────────
# Web image search (image_search.py) / 网络图片搜索
# ─────────────────────────────────────────────────────────────
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 619b6a6e..cf68d6fb 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -1,6 +1,6 @@
# Audio Narration & Video Export
-PPT Master can turn the speaker notes into per-slide MP3 narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices), embed the audio back into the PPTX, and let PowerPoint export the deck as an MP4 video — with synced narration and slide transitions, no extra tools.
+PPT Master can turn the speaker notes into per-slide MP3 narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices) by default, or via ElevenLabs when you need higher-quality cloud narration. It can then embed the audio back into the PPTX and let PowerPoint export the deck as an MP4 video — with synced narration and slide transitions, no extra tools.
## What you get
@@ -11,7 +11,7 @@ PPT Master can turn the speaker notes into per-slide MP3 narration via [`edge-tt
## How it works
1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.
-2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the locale-filtered `edge-tts` voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "稳重男声,适合财报"). It also recommends a speaking rate based on notes density.
+2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "稳重男声,适合财报"). It also recommends a speaking rate or provider defaults based on notes density.
3. **One question, one answer.** You are asked once — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.
4. **Generation runs.** The script writes MP3s to `audio/`, then (if you kept embedding) re-exports the deck with audio attached.
@@ -45,16 +45,30 @@ If you want to skip the AI flow and call the script directly:
# 1. Make sure speaker notes are split (post-processing Step 7.1):
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
-# 2. Generate MP3s
+# 2A. Generate MP3s with edge-tts (default, no API key)
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice zh-CN-YunjianNeural --rate +0%
+# 2B. Or generate MP3s with ElevenLabs (requires ELEVENLABS_API_KEY)
+export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --provider elevenlabs \
+ --voice-id <elevenlabs-voice-id> \
+ --elevenlabs-model eleven_multilingual_v2
+
# 3. (Optional) Re-export PPTX with audio embedded
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final \
--recorded-narration audio
```
-`--voice` is required — the script will error out if you forget it. Use `--list-voices --locale <locale>` to see what's available.
+For edge, `--voice` is required. Use `--list-voices --locale <locale>` to see what's available.
+
+For ElevenLabs, `--voice-id` is required. List voices from your ElevenLabs account with:
+
+```bash
+export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
+python3 skills/ppt-master/scripts/notes_to_audio.py --provider elevenlabs --list-voices
+```
## Dependency
@@ -64,6 +78,8 @@ python3 -m pip install edge-tts
Already listed in `skills/ppt-master/requirements.txt`. `edge-tts` calls Microsoft's online TTS service — an internet connection is required at generation time. The MP3s themselves are local files; nothing about playback or PowerPoint export depends on the network afterwards.
+ElevenLabs does not require an extra Python package; it uses HTTPS directly. Configure `ELEVENLABS_API_KEY` in the current shell or in `.env` based on `.env.example`.
+
## Tips
- **Pacing**: PPT Master's default speaker-notes are 2–5 sentences per slide; `+0%` rate sounds natural. If a deck is very dense (long technical paragraphs), try `-5%`.
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index c2c0f66d..7e06a6ec 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -7,6 +7,7 @@ This directory contains user-facing scripts for conversion, project setup, SVG p
- Top-level `scripts/`: runnable entry scripts
- `scripts/source_to_md/`: source-document → Markdown converters (`pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`, `web_to_md.cjs`)
- `scripts/image_backends/`: internal provider implementations used by `image_gen.py`
+- `scripts/tts_backends/`: internal TTS provider implementations used by `notes_to_audio.py`
- `scripts/template_import/`: internal PPTX reference-preparation helpers used by `pptx_template_import.py`
- `scripts/svg_finalize/`: internal post-processing helpers used by `finalize_svg.py`
- `scripts/docs/`: topic-focused script documentation
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index 1e5c51b2..5e4bcb90 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -1,43 +1,35 @@
#!/usr/bin/env python3
"""Generate per-slide narration audio from PPT Master notes.
-This script uses `edge-tts` for the same cross-platform behavior on macOS,
-Linux, and Windows.
+This script uses provider backends for the same per-slide output contract on
+macOS, Linux, and Windows. `edge-tts` remains the default no-key backend.
Usage:
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeural
+ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> --provider elevenlabs --voice-id <voice_id>
python3 skills/ppt-master/scripts/notes_to_audio.py --list-common-voices
python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale zh-CN
-Dependency:
+Dependencies:
python3 -m pip install edge-tts
+ ELEVENLABS_API_KEY=<key> for --provider elevenlabs
"""
from __future__ import annotations
import argparse
import asyncio
-import re
import sys
+from dataclasses import dataclass
from pathlib import Path
+from tts_backends import backend_edge, backend_elevenlabs
-COMMON_VOICES = [
- ("zh-CN", "zh-CN-XiaoxiaoNeural", "女声,普通话,清晰自然,默认推荐"),
- ("zh-CN", "zh-CN-XiaoyiNeural", "女声,普通话,明亮"),
- ("zh-CN", "zh-CN-YunjianNeural", "男声,普通话,稳重"),
- ("zh-CN", "zh-CN-YunxiNeural", "男声,普通话,年轻"),
- ("zh-CN", "zh-CN-YunxiaNeural", "男声,普通话,少年感"),
- ("zh-CN", "zh-CN-YunyangNeural", "男声,普通话,播报感"),
- ("zh-HK", "zh-HK-HiuGaaiNeural", "女声,粤语"),
- ("zh-HK", "zh-HK-WanLungNeural", "男声,粤语"),
- ("zh-TW", "zh-TW-HsiaoChenNeural", "女声,台湾普通话"),
- ("zh-TW", "zh-TW-YunJheNeural", "男声,台湾普通话"),
- ("en-US", "en-US-JennyNeural", "女声,美式英语"),
- ("en-US", "en-US-GuyNeural", "男声,美式英语"),
- ("en-GB", "en-GB-SoniaNeural", "女声,英式英语"),
- ("en-GB", "en-GB-RyanNeural", "男声,英式英语"),
-]
+
+@dataclass(frozen=True)
+class AudioBackend:
+ provider: str
+ extension: str
def spoken_text(markdown: str) -> str:
@@ -55,63 +47,6 @@ def spoken_text(markdown: str) -> str:
return "\n".join(lines).strip()
-def _edge_rate(rate: str) -> str:
- """Normalize a user-provided rate into edge-tts format."""
- value = rate.strip()
- if not value:
- return "+0%"
- if value.endswith("%"):
- if value[0] not in "+-":
- return f"+{value}"
- return value
- if re.fullmatch(r"[+-]?\d+", value):
- number = int(value)
- return f"{number:+d}%"
- return value
-
-
-async def run_edge_tts(text: str, output_path: Path, *, voice: str, rate: str) -> None:
- try:
- import edge_tts
- except ImportError as exc:
- raise RuntimeError(
- "Missing dependency `edge-tts`. Install it with: "
- "python3 -m pip install edge-tts"
- ) from exc
-
- communicate = edge_tts.Communicate(text, voice=voice, rate=_edge_rate(rate))
- await communicate.save(str(output_path))
-
-
-def print_common_voices() -> None:
- print("Common edge-tts voices:")
- print("Locale Voice Notes")
- print("------ ---------------------------- ----------------")
- for locale, voice, notes in COMMON_VOICES:
- print(f"{locale:<8} {voice:<29} {notes}")
-
-
-async def print_edge_voices(locale: str | None = None) -> None:
- try:
- import edge_tts
- except ImportError as exc:
- raise RuntimeError(
- "Missing dependency `edge-tts`. Install it with: "
- "python3 -m pip install edge-tts"
- ) from exc
-
- manager = await edge_tts.VoicesManager.create()
- voices = manager.voices
- if locale:
- voices = [voice for voice in voices if voice.get("Locale") == locale]
- for voice in sorted(voices, key=lambda item: (item.get("Locale", ""), item.get("ShortName", ""))):
- short_name = voice.get("ShortName", "")
- voice_locale = voice.get("Locale", "")
- gender = voice.get("Gender", "")
- friendly = voice.get("FriendlyName", "")
- print(f"{voice_locale:<8} {short_name:<34} {gender:<8} {friendly}")
-
-
def main() -> int:
parser = argparse.ArgumentParser(
description=__doc__,
@@ -119,28 +54,81 @@ def main() -> int:
)
parser.add_argument("project_path", type=Path, nargs="?")
parser.add_argument("-o", "--output", type=Path, default=None)
+ parser.add_argument(
+ "--provider",
+ choices=["edge", "elevenlabs"],
+ default="edge",
+ help="audio generation backend (default: edge)",
+ )
parser.add_argument(
"--voice",
default=None,
- help="edge-tts voice ShortName (required). Run --list-voices --locale <locale> to discover voices, or follow the generate-audio workflow for a locale-aware recommendation.",
+ help="edge-tts voice ShortName. For elevenlabs, --voice-id is preferred.",
+ )
+ parser.add_argument(
+ "--voice-id",
+ default=None,
+ help="ElevenLabs voice ID. If omitted for --provider elevenlabs, --voice is used as a fallback.",
)
parser.add_argument(
"--rate",
default="+0%",
- help='edge-tts speaking rate, e.g. "+0%%", "-10%%", "+15%%" (default: +0%%)',
+ help='edge-tts speaking rate, e.g. "+0%%", "-10%%", "+15%%" (default: +0%%). Ignored by elevenlabs.',
+ )
+ parser.add_argument(
+ "--elevenlabs-api-key-env",
+ default="ELEVENLABS_API_KEY",
+ help="environment variable containing the ElevenLabs API key (default: ELEVENLABS_API_KEY)",
+ )
+ parser.add_argument(
+ "--elevenlabs-model",
+ default="eleven_multilingual_v2",
+ help="ElevenLabs TTS model ID (default: eleven_multilingual_v2)",
+ )
+ parser.add_argument(
+ "--elevenlabs-output-format",
+ default="mp3_44100_128",
+ help="ElevenLabs output format (default: mp3_44100_128)",
+ )
+ parser.add_argument(
+ "--elevenlabs-stability",
+ type=float,
+ default=None,
+ help="optional ElevenLabs voice stability override, 0.0-1.0",
+ )
+ parser.add_argument(
+ "--elevenlabs-similarity-boost",
+ type=float,
+ default=None,
+ help="optional ElevenLabs similarity boost override, 0.0-1.0",
+ )
+ parser.add_argument(
+ "--elevenlabs-style",
+ type=float,
+ default=None,
+ help="optional ElevenLabs style exaggeration override, 0.0-1.0",
+ )
+ parser.add_argument(
+ "--elevenlabs-speaker-boost",
+ action=argparse.BooleanOptionalAction,
+ default=None,
+ help="optionally override ElevenLabs speaker boost",
)
parser.add_argument("--list-common-voices", action="store_true", help="print a curated voice list and exit")
- parser.add_argument("--list-voices", action="store_true", help="query edge-tts voices and exit")
+ parser.add_argument("--list-voices", action="store_true", help="query provider voices and exit")
parser.add_argument("--locale", default=None, help='filter --list-voices by locale, e.g. "zh-CN"')
args = parser.parse_args()
if args.list_common_voices:
- print_common_voices()
+ backend_edge.print_common_voices()
return 0
if args.list_voices:
try:
- asyncio.run(print_edge_voices(args.locale))
+ if args.provider == "elevenlabs":
+ backend_elevenlabs.print_voices(backend_elevenlabs.read_api_key(args.elevenlabs_api_key_env))
+ else:
+ asyncio.run(backend_edge.print_voices(args.locale))
except Exception as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
@@ -149,12 +137,30 @@ def main() -> int:
if args.project_path is None:
parser.error("project_path is required unless --list-voices or --list-common-voices is used")
- if not args.voice:
+ if args.provider == "edge" and not args.voice:
parser.error(
- "--voice is required. Run --list-voices --locale <locale> to discover voices "
+ "--voice is required for --provider edge. Run --list-voices --locale <locale> to discover voices "
"(e.g. --locale zh-CN), or follow skills/ppt-master/workflows/generate-audio.md "
"for an AI-curated recommendation."
)
+ raise AssertionError("unreachable")
+
+ if args.provider == "elevenlabs":
+ voice_id = args.voice_id or args.voice
+ if not voice_id:
+ parser.error("--voice-id is required for --provider elevenlabs")
+ raise AssertionError("unreachable")
+ try:
+ api_key = backend_elevenlabs.read_api_key(args.elevenlabs_api_key_env)
+ extension = backend_elevenlabs.output_extension(args.elevenlabs_output_format)
+ except Exception as exc:
+ print(f"error: {exc}", file=sys.stderr)
+ return 1
+ backend = AudioBackend(provider=args.provider, extension=extension)
+ else:
+ voice_id = args.voice
+ api_key = ""
+ backend = AudioBackend(provider=args.provider, extension=backend_edge.edge_output_extension())
project = args.project_path
notes_dir = project / "notes"
@@ -175,9 +181,23 @@ def main() -> int:
if not text:
print(f"[skip] {note_path.name}: empty spoken text")
continue
- output_path = output_dir / f"{note_path.stem}.mp3"
+ output_path = output_dir / f"{note_path.stem}{backend.extension}"
try:
- asyncio.run(run_edge_tts(text, output_path, voice=args.voice, rate=args.rate))
+ if backend.provider == "elevenlabs":
+ backend_elevenlabs.generate(
+ text,
+ output_path,
+ api_key=api_key,
+ voice_id=voice_id,
+ model=args.elevenlabs_model,
+ output_format=args.elevenlabs_output_format,
+ stability=args.elevenlabs_stability,
+ similarity_boost=args.elevenlabs_similarity_boost,
+ style=args.elevenlabs_style,
+ speaker_boost=args.elevenlabs_speaker_boost,
+ )
+ else:
+ asyncio.run(backend_edge.generate(text, output_path, voice=args.voice, rate=args.rate))
except Exception as exc:
print(f"error: failed to generate {output_path}: {exc}", file=sys.stderr)
return 1
diff --git a/skills/ppt-master/scripts/tts_backends/__init__.py b/skills/ppt-master/scripts/tts_backends/__init__.py
new file mode 100644
index 00000000..c4d2bd4c
--- /dev/null
+++ b/skills/ppt-master/scripts/tts_backends/__init__.py
@@ -0,0 +1,2 @@
+"""Text-to-speech backend helpers for PPT Master narration audio."""
+
diff --git a/skills/ppt-master/scripts/tts_backends/backend_edge.py b/skills/ppt-master/scripts/tts_backends/backend_edge.py
new file mode 100644
index 00000000..8f8445e4
--- /dev/null
+++ b/skills/ppt-master/scripts/tts_backends/backend_edge.py
@@ -0,0 +1,86 @@
+"""edge-tts backend for narration audio generation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+COMMON_VOICES = [
+ ("zh-CN", "zh-CN-XiaoxiaoNeural", "女声,普通话,清晰自然,默认推荐"),
+ ("zh-CN", "zh-CN-XiaoyiNeural", "女声,普通话,明亮"),
+ ("zh-CN", "zh-CN-YunjianNeural", "男声,普通话,稳重"),
+ ("zh-CN", "zh-CN-YunxiNeural", "男声,普通话,年轻"),
+ ("zh-CN", "zh-CN-YunxiaNeural", "男声,普通话,少年感"),
+ ("zh-CN", "zh-CN-YunyangNeural", "男声,普通话,播报感"),
+ ("zh-HK", "zh-HK-HiuGaaiNeural", "女声,粤语"),
+ ("zh-HK", "zh-HK-WanLungNeural", "男声,粤语"),
+ ("zh-TW", "zh-TW-HsiaoChenNeural", "女声,台湾普通话"),
+ ("zh-TW", "zh-TW-YunJheNeural", "男声,台湾普通话"),
+ ("en-US", "en-US-JennyNeural", "女声,美式英语"),
+ ("en-US", "en-US-GuyNeural", "男声,美式英语"),
+ ("en-GB", "en-GB-SoniaNeural", "女声,英式英语"),
+ ("en-GB", "en-GB-RyanNeural", "男声,英式英语"),
+]
+
+
+def edge_output_extension() -> str:
+ return ".mp3"
+
+
+def normalize_rate(rate: str) -> str:
+ """Normalize a user-provided rate into edge-tts format."""
+ value = rate.strip()
+ if not value:
+ return "+0%"
+ if value.endswith("%"):
+ if value[0] not in "+-":
+ return f"+{value}"
+ return value
+ if re.fullmatch(r"[+-]?\d+", value):
+ number = int(value)
+ return f"{number:+d}%"
+ return value
+
+
+async def generate(text: str, output_path: Path, *, voice: str, rate: str) -> None:
+ try:
+ import edge_tts
+ except ImportError as exc:
+ raise RuntimeError(
+ "Missing dependency `edge-tts`. Install it with: "
+ "python3 -m pip install edge-tts"
+ ) from exc
+
+ communicate = edge_tts.Communicate(text, voice=voice, rate=normalize_rate(rate))
+ await communicate.save(str(output_path))
+
+
+def print_common_voices() -> None:
+ print("Common edge-tts voices:")
+ print("Locale Voice Notes")
+ print("------ ---------------------------- ----------------")
+ for locale, voice, notes in COMMON_VOICES:
+ print(f"{locale:<8} {voice:<29} {notes}")
+
+
+async def print_voices(locale: str | None = None) -> None:
+ try:
+ import edge_tts
+ except ImportError as exc:
+ raise RuntimeError(
+ "Missing dependency `edge-tts`. Install it with: "
+ "python3 -m pip install edge-tts"
+ ) from exc
+
+ manager = await edge_tts.VoicesManager.create()
+ voices = manager.voices
+ if locale:
+ voices = [voice for voice in voices if voice.get("Locale") == locale]
+ for voice in sorted(voices, key=lambda item: (item.get("Locale", ""), item.get("ShortName", ""))):
+ short_name = voice.get("ShortName", "")
+ voice_locale = voice.get("Locale", "")
+ gender = voice.get("Gender", "")
+ friendly = voice.get("FriendlyName", "")
+ print(f"{voice_locale:<8} {short_name:<34} {gender:<8} {friendly}")
+
diff --git a/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py b/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py
new file mode 100644
index 00000000..a044b9cd
--- /dev/null
+++ b/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py
@@ -0,0 +1,111 @@
+"""ElevenLabs backend for narration audio generation."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from urllib import error, request
+
+
+API_BASE = "https://api.elevenlabs.io/v1"
+
+
+def read_api_key(env_name: str) -> str:
+ api_key = os.environ.get(env_name, "").strip()
+ if not api_key:
+ raise RuntimeError(f"Missing ElevenLabs API key. Set {env_name}=<key>.")
+ return api_key
+
+
+def output_extension(output_format: str) -> str:
+ codec = output_format.split("_", 1)[0].lower()
+ if codec in {"mp3", "wav"}:
+ return f".{codec}"
+ raise RuntimeError(
+ f"Unsupported ElevenLabs output format for PPT narration: {output_format}. "
+ "Use an mp3_* or wav_* format."
+ )
+
+
+def _read_http_error(exc: error.HTTPError) -> str:
+ try:
+ body = exc.read().decode("utf-8", errors="replace")
+ except Exception:
+ body = ""
+ return f"HTTP {exc.code}: {body or exc.reason}"
+
+
+def generate(
+ text: str,
+ output_path: Path,
+ *,
+ api_key: str,
+ voice_id: str,
+ model: str,
+ output_format: str,
+ stability: float | None,
+ similarity_boost: float | None,
+ style: float | None,
+ speaker_boost: bool | None,
+) -> None:
+ payload: dict[str, object] = {
+ "text": text,
+ "model_id": model,
+ }
+
+ voice_settings: dict[str, object] = {}
+ if stability is not None:
+ voice_settings["stability"] = stability
+ if similarity_boost is not None:
+ voice_settings["similarity_boost"] = similarity_boost
+ if style is not None:
+ voice_settings["style"] = style
+ if speaker_boost is not None:
+ voice_settings["use_speaker_boost"] = speaker_boost
+ if voice_settings:
+ payload["voice_settings"] = voice_settings
+
+ body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+ url = f"{API_BASE}/text-to-speech/{voice_id}?output_format={output_format}"
+ req = request.Request(
+ url,
+ data=body,
+ headers={
+ "Content-Type": "application/json",
+ "xi-api-key": api_key,
+ },
+ method="POST",
+ )
+ try:
+ with request.urlopen(req, timeout=120) as response:
+ output_path.write_bytes(response.read())
+ except error.HTTPError as exc:
+ raise RuntimeError(_read_http_error(exc)) from exc
+ except error.URLError as exc:
+ raise RuntimeError(f"ElevenLabs request failed: {exc.reason}") from exc
+
+
+def print_voices(api_key: str) -> None:
+ req = request.Request(
+ f"{API_BASE}/voices",
+ headers={"xi-api-key": api_key},
+ method="GET",
+ )
+ try:
+ with request.urlopen(req, timeout=60) as response:
+ data = json.loads(response.read().decode("utf-8"))
+ except error.HTTPError as exc:
+ raise RuntimeError(_read_http_error(exc)) from exc
+ except error.URLError as exc:
+ raise RuntimeError(f"ElevenLabs request failed: {exc.reason}") from exc
+
+ print("ElevenLabs voices:")
+ print("Voice ID Name Category")
+ print("----------------------- ----------------------------- ----------")
+ for item in data.get("voices", []):
+ voice_id = item.get("voice_id", "")
+ name = item.get("name", "")
+ category = item.get("category", "")
+ print(f"{voice_id:<23} {name:<29} {category}")
+
diff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/generate-audio.md
index 36d055ff..9e3c0c26 100644
--- a/skills/ppt-master/workflows/generate-audio.md
+++ b/skills/ppt-master/workflows/generate-audio.md
@@ -4,14 +4,15 @@ description: Generate per-slide narration audio with AI-recommended voice select
# Generate Audio Workflow
-> Standalone post-export step. Run when the user asks for "生成音频" / "录制旁白" / "narrated PPT" / "video export with voice", or proactively offer it after a deck is exported. Produces one MP3 per slide via `edge-tts`, then optionally re-exports the PPTX with the audio embedded and per-slide auto-advance timings.
+> Standalone post-export step. Run when the user asks for "生成音频" / "录制旁白" / "narrated PPT" / "video export with voice", or proactively offer it after a deck is exported. Produces one audio file per slide via `edge-tts` by default, or ElevenLabs when the user chooses high-quality cloud narration, then optionally re-exports the PPTX with the audio embedded and per-slide auto-advance timings.
-This workflow is **independent**: it reads `notes/*.md` and queries the TTS voice catalog — no upstream conversation context required. Safe to invoke in a fresh session.
+This workflow is **independent**: it reads `notes/*.md` and queries the selected TTS voice catalog — no upstream conversation context required. Safe to invoke in a fresh session.
## When to Run
- `notes/total.md` exists and has been split into per-page files at `notes/*.md` (post-processing Step 7.1 done).
-- `edge-tts` is installed (`python3 -m pip install edge-tts`).
+- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).
+- High-quality cloud mode: `ELEVENLABS_API_KEY` is set before using `--provider elevenlabs`.
- The deck is in a single dominant language (mixed-language decks: pick the dominant one — the AI uses judgment, not a heuristic).
If `notes/*.md` are missing, run `total_md_split.py <project_path>` first.
@@ -28,16 +29,27 @@ The AI already knows the deck's language from writing the notes. No detection sc
---
-## Step 2: Pull the voice catalog filtered by locale
+## Step 2: Choose audio backend and pull the voice catalog
+
+Default to **edge** unless the user explicitly asks for ElevenLabs / higher-quality cloud narration / custom ElevenLabs voice.
+
+**edge backend**:
```bash
python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale <locale>
```
-The output is a flat list of all available voices for that locale. From this list, the AI picks **3–6 candidates** to recommend, applying these rules:
+**ElevenLabs backend**:
+
+```bash
+python3 skills/ppt-master/scripts/notes_to_audio.py --provider elevenlabs --list-voices
+```
+
+The output is a flat list of all available voices for the selected provider. From this list, the AI picks **3–6 candidates** to recommend, applying these rules:
- **Cover both genders** when both exist for the locale.
-- **Prefer `COMMON_VOICES`-listed voices** (curated set inside `notes_to_audio.py`) when the locale has them — they are battle-tested.
+- **For edge**: prefer `COMMON_VOICES`-listed voices (curated set inside `notes_to_audio.py`) when the locale has them — they are battle-tested.
+- **For ElevenLabs**: prefer voices already present in the user's account; if the user provides a specific `voice_id`, do not override it.
- **Match the deck's tone** — pick the strongest recommendation based on style:
- Consultant / data-driven / 财报 → 稳重男声(如 `zh-CN-YunjianNeural`)or 清晰女声(如 `zh-CN-XiaoxiaoNeural`)
- General / 教学 / 产品介绍 → 明亮女声 / 年轻男声(如 `zh-CN-XiaoyiNeural` / `zh-CN-YunxiNeural`)
@@ -45,7 +57,7 @@ The output is a flat list of all available voices for that locale. From this lis
- English consultant deck → `en-US-GuyNeural` (steady) or `en-US-JennyNeural` (clear)
- Japanese / Korean → pick from `ja-JP-*` / `ko-KR-*` neural voices, mark gender + tone
-For each candidate, write a **one-line Chinese description** covering: 性别 · 调性 · 适用场景。
+For each candidate, write a **one-line Chinese description** covering: 性别 · 调性 · 适用场景。For ElevenLabs, include the voice name and `voice_id`.
---
@@ -57,6 +69,8 @@ Send a single message to the user that asks all three questions at once and prov
> 检测到 notes 主语言为 **<语言>**(locale: `<locale>`)。基于 deck 调性(<风格>),我推荐以下配置:
>
+> **生成模式**:⭐ 推荐 `<edge|elevenlabs>`(理由:<一句话,如"无需配置,稳定生成"或"用户要求高质量云端音色">)。
+>
> **音色**:
> - **[1] <ShortName>** — <性别·调性·适用场景> ⭐ **推荐**
> - [2] <ShortName> — <性别·调性·适用场景>
@@ -65,15 +79,16 @@ Send a single message to the user that asks all three questions at once and prov
> - [5] <ShortName> — <性别·调性·适用场景>
> - 也可直接输入清单中的其他 ShortName。
>
-> **语速**:⭐ 推荐 `<rate>`(理由:<一句话,如"页均 2–3 句,正常语速听感最稳"或"页面信息密度高,建议 -5% 偏慢">)。
+> **语速/风格参数**:⭐ 推荐 `<rate or provider defaults>`(理由:<一句话,如"页均 2–3 句,正常语速听感最稳"或"ElevenLabs 默认 voice settings 保留音色原始表现最稳">)。
>
> **生成完是否重新导出嵌入音频的 PPTX**:⭐ 推荐 **是**(一次到位,自动按音频时长设页面停留)。
>
-> 直接回"好"用全部推荐值,或告诉我想改的部分(如"音色 2,语速 -5%")。
+> 直接回"好"用全部推荐值,或告诉我想改的部分(如"音色 2,语速 -5%"或"用 ElevenLabs 的 voice_id xxx")。
**Recommended-value rules**:
+- 生成模式:默认 `edge`;当用户明确追求高质量云端音色或提供 ElevenLabs voice ID 时用 `elevenlabs`。
- 音色:从 Step 2 候选里挑最贴合 deck 调性的那一个。
-- 语速:默认 `+0%`;notes 字数密集(页均 >4 句长句)建议 `-5%`;notes 简短紧凑建议 `+5%`;超出此范围需说明理由。
+- 语速:edge 默认 `+0%`;notes 字数密集(页均 >4 句长句)建议 `-5%`;notes 简短紧凑建议 `+5%`;超出此范围需说明理由。ElevenLabs 默认不传 voice settings,除非用户明确要更稳定/更夸张。
- 嵌入:默认推荐"是";除非用户已有定制 PPTX 不希望覆盖。
---
@@ -83,16 +98,21 @@ Send a single message to the user that asks all three questions at once and prov
Run sequentially — do NOT bundle:
```bash
-# 1. Generate audio
+# 1A. Generate audio with edge (default)
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice <chosen-ShortName> --rate <chosen-rate>
+# 1B. Or generate audio with ElevenLabs
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --provider elevenlabs --voice-id <chosen-voice-id> \
+ --elevenlabs-model eleven_multilingual_v2
+
# 2. (If user kept embedding) Re-export PPTX with audio embedded
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final \
--recorded-narration audio
```
-If `notes_to_audio.py` errors with a missing dependency, install `edge-tts` and re-run — do NOT swallow the error.
+If `notes_to_audio.py` errors with a missing dependency or missing `ELEVENLABS_API_KEY`, fix the prerequisite and re-run — do NOT swallow the error.
---
@@ -100,7 +120,7 @@ If `notes_to_audio.py` errors with a missing dependency, install `edge-tts` and
Output one summary block listing:
-- Number of MP3 files generated and their location (`<project_path>/audio/*.mp3`).
-- The voice + rate actually used.
+- Number of audio files generated and their location (`<project_path>/audio/*`).
+- The provider, voice, and rate/settings actually used.
- (If embedded) the new narrated PPTX path under `<project_path>/exports/`.
- (If skipped embedding) one-line hint on how to embed later: `python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final --recorded-narration audio`.