tts-voiceover | SkillBundle

TTS Voice Over Skill

Generates per-slide WAV voice-over files from YAML speaker_notes using Azure Speech SDK with SSML pronunciation control.

Overview

This skill reads content.yaml files from a PowerPoint skill content directory, extracts speaker_notes fields, applies SSML acronym aliases for correct pronunciation of technical terms, and produces one WAV file per slide. Supports dry-run mode for SSML template verification without Azure credentials.

Prerequisites

Azure Speech resource — Free tier provides 500K characters per month.
Authentication — Key-based (SPEECH_KEY) or Microsoft Entra ID (SPEECH_RESOURCE_ID).
Python 3.11+ with uv for virtual environment management.
Data handling note — Speaker-notes content is transmitted to the configured SPEECH_REGION for synthesis. Operators must pin an approved region and avoid sending regulated or confidential narration.

Key-Based Auth

export SPEECH_KEY="your-speech-key"
export SPEECH_REGION="eastus"

Microsoft Entra ID Auth

Requires a custom domain on the Speech resource and Cognitive Services Speech User role.

export SPEECH_RESOURCE_ID="/subscriptions/.../Microsoft.CognitiveServices/accounts/your-resource"
export SPEECH_REGION="eastus"

Install dependencies:

# run from this skill folder
uv sync

Quick Start

Verify SSML templates without generating audio:

Generate voice-over WAV files:

Embed audio into a PPTX deck:

Parameters Reference

generate_voiceover.py

Parameter	Type	Default	Description
`--dry-run`	flag	`false`	Print SSML templates without generating audio
`--voice`	string	`en-US-Andrew:DragonHDLatestNeural`	Azure TTS voice name
`--rate`	string	`+10%`	Speech prosody rate
`--content-dir`	path	`content`	Path to slide content directory
`--output-dir`	path	`voice-over`	Path to WAV output directory
`--lexicon`	path	(auto-detect)	Custom acronyms.yaml path
`--collapse-newlines`	flag	`false`	Collapse newlines and whitespace runs in speaker notes into single spaces before synthesis
`--verbose` / `-v`	flag	`false`	Enable verbose (DEBUG) logging output

embed_audio.py

Embeds WAV files into corresponding PPTX slides and adds narration timing XML so PowerPoint recognizes the audio for video export via File > Export > Create a Video > Use Recorded Timings and Narrations.

Parameter	Type	Default	Description
`--input`	path	(required)	Source PPTX file path
`--audio-dir`	path	`voice-over`	Directory with slide-NNN.wav
`--output`	path	`*-narrated.pptx`	Output PPTX file path
`--verbose` / `-v`	flag	`false`	Enable verbose (DEBUG) logging output

Script Reference

Generate with custom voice and rate:

Use a custom lexicon:

Collapse newlines in speaker notes (recommended for block-scalar | notes, whose line breaks are otherwise spoken as pauses):

Embed generated audio:

Acronym Lexicon

The lexicon controls SSML <sub alias> replacements for acronyms and technical terms. Create an acronyms.yaml file:

Lexicon resolution order:

Path specified via --lexicon argument.
acronyms.yaml in the content directory.
Built-in defaults covering common technical acronyms.

SSML Template

Each slide produces an SSML document:

Integration with PowerPoint Skill

This skill reads from the PowerPoint skill's content directory structure:

Each content.yaml should contain a speaker_notes: field with the narration text. The generated WAV files are named slide-NNN.wav matching the directory names.

Troubleshooting

Issue	Solution
`Set SPEECH_KEY ... or SPEECH_RESOURCE_ID`	Export `SPEECH_KEY` (key auth) or `SPEECH_RESOURCE_ID` (Entra ID) with `SPEECH_REGION`.
401 with Entra ID auth	Verify custom domain on the Speech resource and `Cognitive Services Speech User` role. RBAC propagation takes up to 5 minutes.
Empty WAV files or skipped slides	Verify `speaker_notes:` is present and non-empty in `content.yaml`.
Mispronounced acronyms	Add entries to `acronyms.yaml` with phonetic aliases.
`azure-cognitiveservices-speech package is required`	Run `uv sync` in the skill directory.
Audio icon visible in PPTX	Reposition or resize the audio object in PowerPoint after embedding.
Authored slide animations missing after embedding	`embed_audio.py` replaces existing `p:timing` with narration timing; re-apply animations in PowerPoint after embedding audio.
Slides no longer advance on click after embedding	`embed_audio.py` sets `advClick="0"` for auto-advance. To re-enable, select all slides in PowerPoint and check Advance Slide > On Mouse Click in the Transitions tab.
Video export shows "No timings recorded"	Re-embed audio with the updated `embed_audio.py` which adds narration timing XML automatically.