Tts Voiceover

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Automation and integrations
MIT
Low risk
Has scripts

From the author

Text-to-speech voice-over generation from YAML speaker notes using Azure AI Speech neural voices with SSML pronunciation control

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill automates the creation of synthetic voice-over audio for slide presentations. It processes speaker notes defined in YAML files, applies custom acronym pronunciations via an SSML-based lexicon, and utilizes Azure AI Speech neural voices to generate individual WAV files for each slide. The tool supports both key-based and Microsoft Entra ID authentication and includes a dry-run mode for verifying SSML templates without incurring synthesis costs.

What it does

Extracts speaker notes from YAML files within a structured directory.
Generates WAV audio files using Azure AI Speech neural voices.
Applies custom pronunciation aliases for acronyms and technical terms.
Supports SSML template verification through a dry-run mode.
Allows configuration of speech rate and specific voice selection.
Enables targeted synthesis for individual slides or entire decks.

When to use it

When you need to generate consistent synthetic narration for slide-based presentations.
When you require precise control over the pronunciation of technical acronyms in audio.
When integrating automated voice-over generation into a slide content pipeline.
When you need to verify SSML output before committing to full audio synthesis.

Advantages

Automates the conversion of text-based speaker notes into audio assets.
Provides granular control over pronunciation using custom lexicon files.
Supports secure authentication via Microsoft Entra ID.
Offers flexibility to re-synthesize specific slides without processing the entire deck.

Usage examples

“Generate voice-over files for all slides in the content directory.”: The script processes all slide-NNN folders in the content directory and outputs corresponding WAV files to the voice-over folder.
“Verify the SSML templates for my slides without generating audio.”: The tool runs in dry-run mode, printing the generated SSML to the console for review without calling the Azure Speech service.
“Synthesize audio for slide 005 using a specific voice and rate.”: The tool generates a WAV file for slide-005 using the specified Azure neural voice and prosody rate settings.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/tts-voiceover/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip tts-voiceover.zip -d .agents/skills

Documentation by Microsoft

TTS Voice Over Skill

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

Overview

This skill reads content.yaml files from a slide content directory (slide-NNN/content.yaml), extracts speaker_notes fields, applies 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.

Synthesis uses Azure AI Speech neural voices, including the HD voices such as en-US-Andrew:DragonHDLatestNeural. HD voices are offered in a subset of Azure regions; check the Speech service regions before choosing SPEECH_REGION.

Narration produced by this skill is synthetic. Tell listeners that the voice is AI-generated, following Microsoft's disclosure design guidelines for synthetic voices. HVE demo-material CI does not synthesize speech; it generates silent videos.

Prerequisites

Azure Speech resource: see Azure AI Speech pricing for the free-tier allowance and HD voice rates.
Authentication: Microsoft Entra ID (SPEECH_RESOURCE_ID, recommended) or a resource key (SPEECH_KEY).
Region: SPEECH_REGION is required for synthesis and has no default. Dry-run mode does not need it.
Python 3.11+ with uv for virtual environment management.
Data handling note: Speaker-notes content is transmitted to the configured SPEECH_REGION for synthesis. 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. Operators must still set an approved region and avoid sending regulated or confidential narration.

Microsoft Entra ID Auth (Recommended)

Entra ID avoids storing a long-lived key. It requires a custom domain on the Speech resource and the Cognitive Services Speech User role for the signed-in identity. The script resolves the identity through DefaultAzureCredential, so an az login session, a managed identity, or a GitHub Actions OIDC login through azure/login all work.

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

Key-Based Auth

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

When both SPEECH_KEY and SPEECH_RESOURCE_ID are set, the script warns and uses the key. Unset SPEECH_KEY to use Entra ID.

Install dependencies:

# run from this skill folder
uv sync

Quick Start

Verify SSML templates without generating audio:

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

Generate voice-over WAV files:

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

Use demo-video to combine the WAV files with approved frames or clips. Use hve-slides for HTML presentations and hve-demo-material for the HTML/frame/MP4/caption workflow. Audio embedding into presentation files is retired.

Parameters Reference

For different speakers, synthesize one voice's selected slides per invocation using repeated --slide <number> arguments. Only those canonical slide-NNN folders are read and their WAVs replaced; other speakers' outputs are untouched. Omit --slide to synthesize the whole deck.

generate_voiceover.py

Parameter	Type	Default	Description
`--dry-run`	flag	`false`	Print SSML without generating audio
`--voice`	string	`en-US-Andrew:DragonHDLatestNeural`	Azure AI Speech 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
`--slide`	integer	all slides	Repeat to synthesize only the selected canonical slide numbers
`--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

Script Reference

Generate with custom voice and rate:

uv run scripts/generate_voiceover.py \
  --content-dir content \
  --output-dir voice-over \
  --voice "en-US-Jenny:DragonHDLatestNeural" \
  --rate "+5%"

Use a custom lexicon:

uv run scripts/generate_voiceover.py \
  --content-dir content \
  --lexicon custom-acronyms.yaml

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

uv run scripts/generate_voiceover.py \
  --content-dir content \
  --collapse-newlines

Acronym Lexicon

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

acronyms:
  HVE-Core: "H V E Core"
  OWASP: "Oh wasp"
  SBOM: "S Bomb"
  SLSA: "Salsa"
  CI/CD: "C I C D"

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:

<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis"
 xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="en-US">
  <voice name="en-US-Andrew:DragonHDLatestNeural">
    <prosody rate="+10%">
      Text with <sub alias="Oh wasp">OWASP</sub> aliases applied.
    </prosody>
  </voice>
</speak>

Content Directory Contract

This skill reads a slide content directory with this structure:

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

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`.
`SPEECH_REGION must be set`	Export `SPEECH_REGION` with an approved Azure region. Synthesis has no default 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.

Files

ATTRIBUTION.mdAdded by AutoGineer874 B
LICENSELicence file added by AutoGineer1.1 KiB
SECURITY.md20.1 KiB
SKILL.md9.0 KiB
pip-audit-known-vulnerabilities.txt260 B
pyproject.toml1.6 KiB
scripts/Invoke-GenerateVoiceover.ps1Script4.3 KiB
scripts/Modules/TtsVoiceoverHelpers.psm1Script2.1 KiB
scripts/generate-voiceover.shScript2.8 KiB
scripts/generate_voiceover.pyScript16.8 KiB
tests/Invoke-GenerateVoiceover.Tests.ps1Script2.3 KiB
tests/TtsVoiceoverHelpers.Tests.ps1Script4.9 KiB
tests/conftest.pyScript7.2 KiB
tests/corpus/0_acronym_text19 B
tests/corpus/0_empty0 B
tests/corpus/0_ssml_fragment29 B
tests/corpus/0_valid_yaml25 B
tests/fuzz_harness.pyScript6.0 KiB
tests/test_generate_voiceover.pyScript10.5 KiB
tests/test_generate_voiceover_boundaries.pyScript9.1 KiB
uv.lock144.1 KiB

tests/test_generate_voiceover.py

# Copyright (c) 2026 Microsoft Corporation. All rights reserved.
# SPDX-License-Identifier: MIT
"""Tests for generate_voiceover module."""

from pathlib import Path

import yaml
from generate_voiceover import (
    DEFAULT_VOICE,
    _resolve_lexicon,
    apply_acronym_aliases,
    create_parser,
    wrap_ssml,
)


class TestResolveLexicon:
    """Tests for _resolve_lexicon."""

    def test_given_explicit_arg_when_resolved_then_returns_arg(self, tmp_path):
        # Arrange
        explicit = tmp_path / "custom.yaml"

        # Act
        result = _resolve_lexicon(explicit, tmp_path)

        # Assert
        assert result == explicit

    def test_given_content_dir_lexicon_when_resolved_then_returns_it(self, tmp_path):
        # Arrange
        lexicon = tmp_path / "acronyms.yaml"
        lexicon.write_text("acronyms:\n  FOO: bar\n", encoding="utf-8")

        # Act
        result = _resolve_lexicon(None, tmp_path)

        # Assert
        assert result == lexicon

    def test_given_no_lexicon_and_no_content_file_when_resolved_then_returns_default(
        self,
    ):
        # Act
        result = _resolve_lexicon(None, Path("/nonexistent"))

        # Assert
        assert result == Path("acronyms.yaml")


class TestCreateParser:
    """Tests for create_parser."""

    def test_given_defaults_when_parsed_then_has_expected_values(self):
        # Act
        parser = create_parser()
        args = parser.parse_args(["--content-dir", "c", "--output-dir", "o"])

        # Assert
        assert str(args.content_dir) == "c"
        assert str(args.output_dir) == "o"
        assert args.dry_run is False
        assert args.voice == DEFAULT_VOICE
        assert args.rate is not None

    def test_given_dry_run_flag_when_parsed_then_dry_run_true(self):
        # Act
        parser = create_parser()
        args = parser.parse_args(
            ["--content-dir", "c", "--output-dir", "o", "--dry-run"]
        )

        # Assert
        assert args.dry_run is True

    def test_given_custom_voice_when_parsed_then_voice_set(self):
        # Act
        parser = create_parser()
        args = parser.parse_args(
            [
                "--content-dir",
                "c",
                "--output-dir",
                "o",
                "--voice",
                "en-US-Jenny",
            ]
        )

        # Assert
        assert args.voice == "en-US-Jenny"


class TestRunDryRun:
    """Tests for _run in dry-run mode."""

    def test_given_valid_content_when_dry_run_then_returns_success(self, tmp_path):
        from generate_voiceover import _run

        # Arrange
        content = tmp_path / "content"
        slide = content / "slide-001"
        slide.mkdir(parents=True)
        (slide / "content.yaml").write_text(
            yaml.dump(
                {
                    "slide": 1,
                    "title": "Test",
                    "speaker_notes": "Hello world",
                }
            ),
            encoding="utf-8",
        )
        output = tmp_path / "output"
        parser = create_parser()
        args = parser.parse_args(
            [
                "--content-dir",
                str(content),
                "--output-dir",
                str(output),
                "--dry-run",
            ]
        )

        # Act
        rc = _run(args)

        # Assert
        assert rc == 0

    def test_given_missing_content_dir_when_run_then_returns_failure(self, tmp_path):
        from generate_voiceover import _run

        # Arrange
        parser = create_parser()
        args = parser.parse_args(
            [
                "--content-dir",
                str(tmp_path / "missing"),
                "--output-dir",
                str(tmp_path / "out"),
                "--dry-run",
            ]
        )

        # Act
        rc = _run(args)

        # Assert
        assert rc == 1

    def test_given_empty_notes_when_dry_run_then_slide_skipped(self, tmp_path, capsys):
        from generate_voiceover import _run

        # Arrange
        content = tmp_path / "content"
        slide = content / "slide-001"
        slide.mkdir(parents=True)
        (slide / "content.yaml").write_text(
            yaml.dump({"slide": 1, "title": "Empty", "speaker_notes": ""}),
            encoding="utf-8",
        )
        output = tmp_path / "output"
        parser = create_parser()
        args = parser.parse_args(
            [
                "--content-dir",
                str(content),
                "--output-dir",
                str(output),
                "--dry-run",
            ]
        )

        # Act
        rc = _run(args)

        # Assert
        assert rc == 0


class TestCollapseNewlines:
    """Tests for the --collapse-newlines option."""

    def _run_dry(self, tmp_path, notes, extra_args):
        from generate_voiceover import _run

        content = tmp_path / "content"
        slide = content / "slide-001"
        slide.mkdir(parents=True)
        (slide / "content.yaml").write_text(
            yaml.dump({"slide": 1, "title": "Multi", "speaker_notes": notes}),
            encoding="utf-8",
        )
        parser = create_parser()
        args = parser.parse_args(
            [
                "--content-dir",
                str(content),
                "--output-dir",
                str(tmp_path / "output"),
                "--dry-run",
                *extra_args,
            ]
        )
        return _run(args)

    def test_given_multiline_notes_when_collapse_then_no_newlines_in_ssml(
        self, tmp_path, capsys
    ):
        # Arrange
        notes = "First line.\nSecond line.\nThird line."

        # Act
        rc = self._run_dry(tmp_path, notes, ["--collapse-newlines"])
        out = capsys.readouterr().out

        # Assert
        assert rc == 0
        assert "First line. Second line. Third line." in out

    def test_given_multiline_notes_when_not_collapsed_then_newlines_preserved(
        self, tmp_path, capsys
    ):
        # Arrange
        notes = "First line.\nSecond line."

        # Act
        rc = self._run_dry(tmp_path, notes, [])
        out = capsys.readouterr().out

        # Assert
        assert rc == 0
        assert "First line.\nSecond line." in out


class TestApplyAcronymAliases:
    """Tests for apply_acronym_aliases."""

    def test_given_known_acronym_when_applied_then_wraps_in_sub(self):
        # Arrange
        text = "Use OWASP guidelines"
        acronyms = {"OWASP": "Oh wasp"}

        # Act
        result = apply_acronym_aliases(text, acronyms)

        # Assert
        assert '<sub alias="Oh wasp">OWASP</sub>' in result

    def test_given_empty_acronyms_when_applied_then_returns_unchanged(self):
        # Arrange
        text = "no replacements here"

        # Act
        result = apply_acronym_aliases(text, {})

        # Assert
        assert result == text

    def test_given_escaped_input_when_applied_then_no_double_escape(self):
        # Arrange
        text = "&amp; &lt;tag&gt;"

        # Act
        result = apply_acronym_aliases(text, {})

        # Assert
        assert result == text

    def test_given_multiple_acronyms_when_applied_then_all_replaced(self):
        # Arrange
        text = "Use API and SDK"
        acronyms = {"API": "A P I", "SDK": "S D K"}

        # Act
        result = apply_acronym_aliases(text, acronyms)

        # Assert
        assert '<sub alias="A P I">API</sub>' in result
        assert '<sub alias="S D K">SDK</sub>' in result


class TestRunSelectedSlides:
    """Tests for _run with --slide selection."""

    def test_given_two_speakers_when_selected_in_two_passes_then_prior_wav_unchanged(
        self, tmp_path, monkeypatch, mocker
    ):
        import sys

        from generate_voiceover import _run

        # Arrange
        content = tmp_path / "content"
        for number, notes in ((1, "First speaker"), (2, "Second speaker")):
            slide = content / f"slide-{number:03d}"
            slide.mkdir(parents=True)
            (slide / "content.yaml").write_text(
                yaml.dump({"slide": number, "title": "T", "speaker_notes": notes}),
                encoding="utf-8",
            )
        output = tmp_path / "output"
        monkeypatch.setenv("SPEECH_REGION", "eastus")
        monkeypatch.setenv("SPEECH_KEY", "test-key")
        monkeypatch.delenv("SPEECH_RESOURCE_ID", raising=False)
        mocker.patch.dict(
            sys.modules,
            {
                "azure": mocker.MagicMock(),
                "azure.cognitiveservices": mocker.MagicMock(),
                "azure.cognitiveservices.speech": mocker.MagicMock(),
            },
        )

        def synthesize(ssml, destination, _config):
            destination.write_bytes(b"first" if "first" in ssml else b"second")
            return 1.0

        generator = mocker.patch(
            "generate_voiceover.generate_audio", side_effect=synthesize
        )
        args = create_parser().parse_args(
            [
                "--content-dir",
                str(content),
                "--output-dir",
                str(output),
                "--slide",
                "1",
                "--voice",
                "first",
            ]
        )

        # Act
        assert _run(args) == 0
        first = (output / "slide-001.wav").read_bytes()
        args.slide = [2]
        args.voice = "second"
        assert _run(args) == 0

        # Assert
        assert (output / "slide-001.wav").read_bytes() == first == b"first"
        assert (output / "slide-002.wav").read_bytes() == b"second"
        assert generator.call_count == 2


class TestWrapSsml:
    """Tests for wrap_ssml."""

    def test_given_text_when_wrapped_then_contains_speak_element(self):
        # Arrange
        text = "Hello world"

        # Act
        result = wrap_ssml(text, voice="en-US-AriaNeural", rate="0%")

        # Assert
        assert "<speak" in result
        assert "</speak>" in result

    def test_given_voice_when_wrapped_then_voice_attribute_present(self):
        # Arrange
        voice = "en-US-AriaNeural"

        # Act
        result = wrap_ssml("test", voice=voice, rate="0%")

        # Assert
        assert voice in result

    def test_given_rate_when_wrapped_then_prosody_rate_set(self):
        # Arrange
        rate = "-10%"

        # Act
        result = wrap_ssml("test", voice="en-US-AriaNeural", rate=rate)

        # Assert
        assert rate in result

    def test_given_ssml_output_when_parsed_then_valid_xml(self):
        # Arrange
        import xml.etree.ElementTree as ET

        text = "Hello &amp; world"

        # Act
        result = wrap_ssml(text, voice="en-US-AriaNeural", rate="0%")

        # Assert
        ET.fromstring(result)

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/hve-core · .github/skills/experimental/tts-voiceover · commit f425e94

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download tts-voiceover.zip