The Problem
Organizations that need to repurpose written content (reports, white‑papers, blog posts) into audio often rely on cloud TTS services. Those services introduce latency, cost, and data‑privacy concerns, especially when the source material is confidential. A self‑hosted pipeline that runs on commodity hardware can eliminate these barriers.
What This Does
document-to-podcast is a lightweight Python blueprint that converts a document (PDF, DOCX, MD, HTML) into a two‑speaker podcast. The core logic lives in src/documenttopodcast/:
CLI – src/documenttopodcast/cli.py parses arguments (--inputfile, --outputfolder, model selectors) and orchestrates the workflow. Configuration – src/documenttopodcast/config.py reads the user‑supplied config.yaml (example in exampledata/config.yaml). Pre‑processing – src/documenttopodcast/preprocessing/ cleans and loads text from the supported formats. Inference – src/documenttopodcast/inference/ contains model loaders (modelloaders.py) and two back‑ends: texttotext.py (summarization) and texttospeech.py (voice synthesis) built on local GGUF models (e.g., Qwen2.5).
A minimal graphical front‑end is provided in demo/app.py, which runs a Flask/Streamlit‑style UI inside the container defined by demo/Dockerfile.
How To Use It
Setup
Install the package from PyPI (or from source) pip install document-to-podcast
Or, build the local Docker image for an isolated environment docker build -f demo/Dockerfile -t doc2podcast .
Configuration
Create or edit a config.yaml (see exampledata/config.yaml) to specify model paths, speaker voices, and optional chunk‑size parameters. The file is loaded by src/documenttopodcast/config.py.
Run the CLI
document-to-podcast \ --inputfile "exampledata/Mozilla-TrustworthyAI.pdf" \ --outputfolder "exampledata" \ --texttotextmodel "Qwen/Qwen2.5-1.5B-Instruct-GGUF/qwen2.5-1.5b-instruct-q80.gguf"
The command produces a folder containing the generated audio files and a transcript.
Run the UI (Docker)
docker run --rm -p 8501:8501 doc2podcast
Navigate to http://localhost:8501 to upload a document and select models via the web interface defined in demo/app.py.
Real‑World Use
A compliance team can embed the pipeline into an internal CI job to publish weekly policy updates as audio newsletters:
.github/workflows/podcast.yaml name: Generate podcast run: | document-to-podcast \ --inputfile "reports/q3policy.pdf" \ --outputfolder "artifacts/q3podcast" \ --texttotextmodel "path/to/summarizer.gguf" \ --texttospeechmodel "path/to/ttsspeaker1.gguf" name: Publish artifact uses: actions/upload-artifact@v4 with: name: q3-podcast path: artifacts/q3podcast
The generated MP3 files can then be distributed via internal channels without exposing the original PDF to external services.
Code Health & Issues
Low – Missing lockfile – pyproject.toml lists dependencies but no poetry.lock or requirements.txt; reproducible builds depend on external package versions. Low – Limited version pinning – Some dependencies are specified with broad version ranges, increasing the risk of breakage on future releases. Medium – Input validation – CLI arguments are passed directly to internal functions; malformed files or unsupported formats could raise uncaught exceptions (e.g., in src/documenttopodcast/preprocessing/data_loaders.py). Low – Test coverage – Tests exist for data loading, model loading, and end‑to‑end flow, but no explicit tests for the Flask UI (demo/app.py). Low – Documentation gaps – The README shows CLI usage but does not document required keys in config.yaml or environment variables for GPU/CPU selection. None – Licensing – Apache‑2.0 license is present (LICENSE). None – CI – GitHub Actions workflows cover linting, testing, and documentation builds, indicating a functional CI pipeline.
The Bottom Line
document-to-podcast delivers a functional, locally‑run pipeline for turning text documents into two‑speaker audio, backed by real tests and CI. It is well‑suited for teams that need privacy‑preserving content repurposing and can tolerate modest setup effort (installing GGUF models, handling the missing lockfile). Organizations with strict reproducibility requirements should add a lockfile and tighten dependency versions before production deployment.