Skip to main content

In this article

TTS Voice-Over Skill

The tts-voiceover skill generates per-slide WAV voice-over files from YAML speaker notes using Azure AI Speech neural voices with SSML pronunciation control for technical acronyms.

Overview​

This skill reads content.yaml files, extracts speaker_notes, applies SSML acronym aliases, and produces one WAV per slide. Use demo-video to assemble narration with visuals, or hve-demo-material for the HTML/frame/MP4/caption workflow. Presentation-file embedding is retired.

Prerequisites​

RequirementDetails
Azure Speech resourceSee Azure AI Speech pricing for the free-tier allowance
Python 3.11+With uv for environment management
AuthenticationMicrosoft Entra ID (SPEECH_RESOURCE_ID, recommended) or a resource key (SPEECH_KEY)
RegionSPEECH_REGION, required, with no default

Setup​

Install Dependencies​

cd .github/skills/experimental/tts-voiceover
uv sync

Configure Authentication​

Microsoft Entra ID authentication is recommended because it avoids storing a long-lived key. It requires a custom domain on the Speech resource and the Cognitive Services Speech User role for your identity. The script signs in through DefaultAzureCredential, so an az login session works:

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

Key-based authentication:

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

When both are set, the script uses the key and logs a warning.

Data Handling and Disclosure​

Speaker notes are sent to Azure AI Speech in the region you set. For prebuilt neural voices, Microsoft states that neither the input text nor the output audio is stored in Microsoft logs. See Data, privacy, and security for text to speech. Choose an approved region and leave regulated or confidential content out of narration.

The narration is a synthetic voice. Tell listeners so, following the disclosure design guidelines for synthetic voices.

Usage​

1. Verify SSML Templates (Dry Run)​

Preview the SSML that will be sent to Azure without generating audio:

uv run scripts/generate_voiceover.py --dry-run --content-dir path/to/content

2. Generate Voice-Over WAV Files​

uv run scripts/generate_voiceover.py --content-dir path/to/content --output-dir voice-over

3. Assemble Narration with Visuals​

Hand the WAVs and matching frames or clips to demo-video. For levelled training, use hve-demo-material, which renders HTML through HVE Slides, exports matching frames, and retains captions and a transcript. Standalone HTML and narrated MP4 are separate deliverables; the HTML deck does not embed audio/video.

Cross-Platform Wrappers​

Bash and PowerShell wrappers manage the Python virtual environment automatically.

Bash​

./scripts/generate-voiceover.sh --dry-run --content-dir content

PowerShell​

./scripts/Invoke-GenerateVoiceover.ps1 -DryRun -ContentDir content

Both wrappers accept --skip-venv-setup / -SkipVenvSetup to skip uv sync when the environment is already initialized.

Acronym Lexicon​

The skill ships with built-in SSML aliases for common technical acronyms (OWASP, SBOM, SLSA, CI/CD, and others). To customize pronunciation, create an acronyms.yaml file:

acronyms:
  HVE-Core: "H V E Core"
  OWASP: "Oh wasp"
  SBOM: "S Bomb"

Lexicon resolution order:

  1. --lexicon argument
  2. acronyms.yaml in the content directory
  3. Built-in defaults

Content Directory Structure​

The skill expects this slide content directory structure:

content/
├── slide-001/
│   └── content.yaml    # Must include speaker_notes: field
├── slide-002/
│   └── content.yaml
└── ...

Troubleshooting​

IssueSolution
Set SPEECH_KEY ... or SPEECH_RESOURCE_IDExport authentication environment variables
401 with Entra ID authVerify custom domain and Cognitive Services Speech User role assignment
Empty WAV filesVerify speaker_notes: is present and non-empty in content.yaml
Mispronounced acronymsAdd entries to acronyms.yaml with phonetic aliases
  • SKILL.md: Full skill reference with parameters and SSML template details
  • Contributing Skills: Guidelines for contributing skills to HVE Core

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.