Home
Softono
podvoice

podvoice

Open source MIT Python
GitHub
33
Stars
14
Forks
1
Issues
10
Watchers
2 months
Last Commit
Podcast Tools

About podvoice

Local-first CLI that turns Markdown scripts into multi-speaker podcast-style audio using Coqui XTTS v2.

Platforms

Web Self-hosted

Languages

Python

Links

Source Code
a
Published by
aman179102
Visit View Profile

README.md

View on GitHub

🧠 Podvoice

Podvoice is a local-first AI podcast generator that converts simple Markdown scripts into multi-speaker audio.

Originally built as a CLI tool, Podvoice now includes PodVoice Studio — a modern web-based GUI for creating, previewing, and generating AI audio visually.

No cloud APIs. No subscriptions. Fully offline.

Runs on Linux, Windows, macOS, and FreeBSD.

Why Podvoice?

Most AI audio tools:

  • Require paid APIs
  • Depend on cloud services

Podvoice is:

  • Local-first
  • Fully offline
  • Developer-friendly
  • Now with a visual GUI (PodVoice Studio)

Features

  • Markdown-based scripts
  • Multiple logical speakers
  • Deterministic voice assignment
  • Single stitched output file
  • WAV or MP3 export
  • Local-only inference
  • CPU-first (GPU optional)
  • Cross-platform support
  • 🎙️ Studio Web UI — Modern single-page interface for voice selection, preview, and generation
  • 🔊 Built-in multi-speaker models — VCTK vits and others with cached voice demos
  • ⚡ AJAX-based generation — No page reloads, instant audio playback
  • 🎨 Modern dark theme — Clean sidebar layout with zero scrolling
  • 📁 Profile management — YAML-based speaker profiles with reference audio support
  • 🔄 Multi-reference audio — Concatenate multiple clips for better voice conditioning

Supported platforms

Platform Status Notes
Linux ✅ Fully supported Primary dev platform
macOS ✅ Fully supported Intel + Apple Silicon
Windows ✅ Fully supported PowerShell
FreeBSD ✅ Supported Requires ffmpeg
WSL2 ✅ Supported Recommended on Windows

Input format

Podvoice consumes Markdown files with speaker blocks:

[Host | calm]
Welcome to the show.

[Guest | warm]
If this sounds useful, try writing your own script
and see how easily Markdown becomes audio.

Rules:

  • Speaker name is required
  • Emotion tag is optional
  • Text continues until the next speaker block
  • Blank lines are allowed

▶️ Demo Video of Podvoice Studio (GUI USAGE)

🎧 Demo Audio

▶️ Demo Video of Podvoice (CLI USAGE)

---

Quick start (ALL operating systems)

1️⃣ System requirements (common)

Required everywhere:

  • Python 3.10.x
  • ffmpeg
  • espeak or espeak-ng (required for Studio with built-in multi-speaker models)
  • Internet access only for first run
  • ~5–8 GB free disk space (model cache)

2️⃣ Install system dependencies

🐧 Linux (Ubuntu / Debian)

sudo apt update
sudo apt install -y python3.10 python3.10-venv ffmpeg git espeak

🍎 macOS (Homebrew)

brew install [email protected] ffmpeg git

🪟 Windows (PowerShell)

winget install Python.Python.3.10
winget install ffmpeg
winget install Git.Git

Restart the terminal after installing Python.

🐡 FreeBSD

pkg install python310 ffmpeg git

3️⃣ Clone the repository

git clone https://github.com/aman179102/podvoice.git
cd podvoice

Setup (recommended path)

🐧 Linux / 🍎 macOS / 🐡 FreeBSD

chmod +x bootstrap.sh
./bootstrap.sh

This script will:

  • Verify Python 3.10
  • Create a local .venv
  • Install fully pinned dependencies from requirements.lock
  • Install podvoice in editable mode

🪟 Windows (PowerShell)

One-time: allow local scripts

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Run bootstrap

.\bootstrap.ps1

Activate the environment

Linux / macOS / FreeBSD

source .venv/bin/activate

Windows

.venv\Scripts\Activate.ps1

Run the demo

podvoice examples/demo.md --out demo.wav

Or export MP3:

podvoice examples/demo.md --out demo.mp3

On first run, Coqui XTTS v2 model weights will be downloaded and cached locally. Subsequent runs reuse the cache.

🎙️ Studio Web UI

Podvoice includes a modern, single-page web interface for interactive voice generation.

Launch Studio

podvoice studio --host 127.0.0.1 --port 8000

Then open: http://127.0.0.1:8000

Studio Features

Feature Description
Sidebar Voice Gallery All built-in speakers displayed with human-friendly labels
Instant Preview Click any voice to hear a demo instantly (cached after first play)
Single TTS Type text, select voice, generate audio — no page reloads
Multi TTS (Podcast) Paste Markdown scripts with speaker mapping
AJAX Generation Audio generates and plays without leaving the page
Modern Dark Theme Clean aesthetic with CSS variables, no scrolling

Studio Endpoints

  • / or /single — Single TTS page
  • /multi — Multi-speaker podcast page
  • /demo_wav?voice=p240 — Get cached demo audio for a voice
  • /health — Health check endpoint

Using a Different Model

Studio defaults to tts_models/en/vctk/vits (built-in multi-speaker). To use XTTS v2 instead:

podvoice studio --model-name tts_models/multilingual/multi-dataset/xtts_v2

CLI usage

podvoice SCRIPT.md --out OUTPUT

Examples:

podvoice examples/demo.md --out output.wav
podvoice examples/demo.md --out podcast.mp3 --language en --device cpu

Options

Option Description
SCRIPT Input Markdown file
--out, -o Output .wav or .mp3
--language, -l XTTS language code
--device, -d cpu (default) or cuda

GPU usage (optional)

If you have a compatible NVIDIA GPU:

podvoice examples/demo.md --device cuda

If CUDA is unavailable, Podvoice safely falls back to CPU.

📁 Profile Management

Podvoice supports YAML-based speaker profiles for advanced use cases.

Profile Directory

Default: ./podvoice_profiles/profiles.yaml

Profile Format

profiles:
  my_custom_voice:
    builtin_speaker: p240
  cloned_voice:
    reference_audio: ./samples/voice.wav
  multi_sample_voice:
    reference_audios:
      - ./samples/clip1.wav
      - ./samples/clip2.wav
      - ./samples/clip3.wav

Using Profiles

Profiles are automatically loaded and can be referenced in your Markdown scripts by speaker name.

Performance notes

You may see warnings like:

Could not initialize NNPACK! Reason: Unsupported hardware.

✔️ These are harmless ✔️ Audio generation will still complete ❌ No action required

How voices are assigned

Podvoice does not train voices.

Instead:

  • Uses built-in XTTS v2 speakers
  • Hashes speaker names deterministically
  • Maps each logical speaker to a stable voice

Implications:

  • Same speaker name → same voice
  • Rename speaker → possibly different voice
  • XTTS update → mapping may change

Fallback: default XTTS voice.

Project structure

podvoice/
├── podvoice/
│   ├── cli.py            # CLI entrypoint
│   ├── parser.py         # Markdown parser
│   ├── tts.py            # XTTS inference
│   ├── audio.py          # Audio stitching
│   ├── studio.py         # FastAPI web UI
│   ├── profiles.py       # YAML profile management
│   ├── preprocessing.py  # Audio preprocessing
│   └── utils.py
│
├── examples/
│   └── demo.md
│
├── podvoice_profiles/    # Voice profiles directory
│
├── bootstrap.sh
├── bootstrap.ps1
├── pyproject.toml
└── README.md

Responsible use

Podvoice generates natural-sounding speech.

Do not:

  • Impersonate real people without consent
  • Use generated audio for fraud or deception

Always disclose synthesized content where appropriate.

You are responsible for compliance with all applicable laws and licenses, including those of Coqui XTTS v2.

Contributing

Podvoice is intentionally simple.

Good contributions:

  • Bug reports with minimal reproduction scripts
  • CLI UX improvements
  • Documentation clarity
  • Cross-platform fixes

Non-goals:

  • Cloud dependencies
  • Training pipelines
  • Over-engineering

Goal: local, boring, reliable software.