edge-tts（边缘 tts）

PowerShell / Terminal TTS Skill (edge-tts)

Use edge-tts — free, neural-quality voices (400+), works from any terminal. No Windows API nonsense. Sounds like a real human. 🎉

Step 1 — Check & Install

Always check if installed first:

Get-Command edge-tts -ErrorAction SilentlyContinue

Install with uv (preferred):

uv tool install edge-tts

Fallback with pip:

pip install edge-tts

This installs two executables: edge-tts (generate audio) and edge-playback (speak aloud).

Step 2 — Basic Usage

Speak aloud (use edge-playback, NOT edge-tts --play):

edge-playback --text "Hello world"

Save to MP3:

edge-tts --text "Hello world" --write-media output.mp3

⚠️ --play flag does NOT exist on Windows. Always use edge-playback to speak aloud.

Step 3 — Voices

List ALL voices (400+):

edge-tts --list-voices

Filter voices by language in PowerShell:

edge-tts --list-voices | Select-String "en-US"
edge-tts --list-voices | Select-String "Female"

Recommended English neural voices:

Use a specific voice:

edge-playback --voice "en-US-AriaNeural" --text "Hi, I'm Aria!"
edge-tts --voice "en-US-AriaNeural" --text "Hi" --write-media aria.mp3

Step 4 — Rate, Volume, Pitch

All adjustments use +X% or -X% string format:

# Rate: default is +0%, range roughly -50% to +100%
edge-playback --voice "en-US-AriaNeural" --rate "+20%" --text "Faster speech"
edge-playback --voice "en-US-AriaNeural" --rate "-30%" --text "Slower speech"

# Volume: default +0%
edge-playback --voice "en-US-AriaNeural" --volume "+50%" --text "Louder"

# Pitch: default +0Hz
edge-playback --voice "en-US-AriaNeural" --pitch "+10Hz" --text "Higher pitch"

The Complete Say.ps1 Script

When the user wants a full CLI wrapper script, generate this:

<#
.SYNOPSIS
    TTS CLI wrapper around edge-tts / edge-playback.

.DESCRIPTION
    Speaks text aloud or saves to MP3. Supports pipeline input,
    voice selection, rate/volume/pitch control, and voice listing/search.

.EXAMPLE
    .\Say.ps1 "Hello world"
    .\Say.ps1 -Text "Hello" -Voice "en-US-AriaNeural" -Rate "+20%"
    .\Say.ps1 -Text "Hello" -OutFile speech.mp3
    .\Say.ps1 -List
    .\Say.ps1 -Search "en-GB"
    "Hello from pipeline" | .\Say.ps1
#>

[CmdletBinding(DefaultParameterSetName = 'Speak')]
param(
    [Parameter(ParameterSetName='Speak', Position=0, ValueFromPipeline=$true)]
    [string]$Text,

    [Parameter(ParameterSetName='Speak')]
    [string]$Voice = 'en-US-AriaNeural',

    # Rate adjustment e.g. "+20%", "-10%"
    [Parameter(ParameterSetName='Speak')]
    [string]$Rate = '+0%',

    # Volume adjustment e.g. "+50%", "-20%"
    [Parameter(ParameterSetName='Speak')]
    [string]$Volume = '+0%',

    # Pitch adjustment e.g. "+5Hz", "-10Hz"
    [Parameter(ParameterSetName='Speak')]
    [string]$Pitch = '+0Hz',

    # Save to MP3 file (speaks aloud if omitted)
    [Parameter(ParameterSetName='Speak')]
    [string]$OutFile,

    # Also speak aloud when saving to file
    [Parameter(ParameterSetName='Speak')]
    [switch]$Also,

    [Parameter(ParameterSetName='List', Mandatory)]
    [switch]$List,

    [Parameter(ParameterSetName='Search', Mandatory)]
    [string]$Search
)

begin {
    # Check edge-tts is installed
    if (-not (Get-Command edge-tts -ErrorAction SilentlyContinue)) {
        Write-Error "edge-tts not found. Install with: uv tool install edge-tts"
        exit 1
    }

    # LIST mode
    if ($PSCmdlet.ParameterSetName -eq 'List') {
        edge-tts --list-voices
        return
    }

    # SEARCH mode
    if ($PSCmdlet.ParameterSetName -eq 'Search') {
        Write-Host "Voices matching '$Search':" -ForegroundColor Cyan
        edge-tts --list-voices | Select-String $Search
        return
    }
}

process {
    if ($PSCmdlet.ParameterSetName -ne 'Speak') { return }
    if (-not $Text) { return }

    $baseArgs = @(
        '--voice',  $Voice,
        '--rate',   $Rate,
        '--volume', $Volume,
        '--pitch',  $Pitch,
        '--text',   $Text
    )

    if ($OutFile) {
        & edge-tts @baseArgs --write-media $OutFile
        Write-Host "Saved to: $OutFile" -ForegroundColor Green
        if ($Also) {
            & edge-playback @baseArgs
        }
    } else {
        & edge-playback @baseArgs
    }
}

Pipeline Examples

# Simple string
"Good morning!" | .\Say.ps1

# From file
Get-Content notes.txt | .\Say.ps1 -Voice "en-GB-SoniaNeural"

# Command output
(Get-Date -Format "dddd, MMMM d") | .\Say.ps1

# Save to file
"Hello" | .\Say.ps1 -OutFile hello.mp3

# Speak AND save
.\Say.ps1 -Text "Hello" -OutFile hello.mp3 -Also

Common Gotchas

• --play doesn't exist on Windows — always use edge-playback executable instead
• Rate/Volume/Pitch need +X% / +XHz format — not plain numbers
• Requires internet — edge-tts calls Microsoft's servers for synthesis
• Output is MP3 not WAV — use ffmpeg if WAV needed: ffmpeg -i out.mp3 out.wav
• Voice names are case-sensitive — en-US-AriaNeural not en-us-arianeural
• uv tool install puts executables in uv's tool bin — make sure it's on PATH