Project Podcast Skill

Turn a private local software project into a grounded podcast you can carry on your phone.

Project Podcast is a local-first Codex Skill that reads a repository with README.md as its narrative backbone, checks important claims against a bounded set of project files, writes a listening-first script, and exports one phone-friendly MP3 or one cover video with burned subtitles.

Why Project Podcast

Long READMEs and architecture notes are useful at a desk but awkward on a walk, commute, or before sleep. Project Podcast turns that material into an explanation rather than reading Markdown syntax aloud. It preserves a transcript and evidence cards so the result remains reviewable.

The Skill is designed for private and unpublished repositories:

project sources, facts, scripts, subtitles, and media stay local by default;
suspicious files are skipped before their contents are read;
local failures stop with an actionable error—there is no silent fallback to another engine or cloud TTS;
dependencies and model weights are never downloaded without explicit approval.

What it produces

The default deliverable is one 112 kbps spoken-word MP3 with normalized loudness, cover art, and metadata. If the user explicitly asks for subtitles or video, the deliverable becomes one 1280×720 H.264/AAC MP4 with always-visible burned subtitles.

Each run also keeps review artifacts in the project:

scan.json: bounded, privacy-filtered source inventory;
facts.json: claims with sources, confidence, and evidence type;
script.json and transcript.md: synthesis input and readable transcript;
synthesis.json: engine route, cache keys, and segment paths;
segments/: resumable WAV files;
captions.srt: internal subtitle audit file for MP4 runs;
cover.png and latest.txt.

Only the selected final MP3 or MP4 needs to be copied to a phone.

Key features

README-led explanations grounded in a bounded set of repository files
.podcastignore plus built-in exclusions for secrets, datasets, caches, builds, archives, binaries, and model weights
five program presets with independent content, style, solo/dialogue, voice, speed, and output controls
automatic 8–30 minute targeting without padding sparse projects
local Kokoro Mandarin speech and local MeloTTS Chinese-English mixed speech
optional Kokoro Chinese/English voice switching for maximum English clarity
reusable per-user runtimes and model caches shared by every project
deterministic segment caching for partial regeneration after voice, speed, or pronunciation changes
locally timed burned subtitles derived from the verified script and actual WAV duration
explicit failure boundaries: no automatic package install, model download, cloud upload, or silent engine switch

Program presets

Defaults reduce setup friction; they never remove the user's right to choose.

Preset	Content	Style	Format	Speed
Bedtime overview (default)	accessible / automatic	calm	solo	`0.80`
Commute briefing	quick	energetic	dialogue	`1.0`
Project handoff	complete	rigorous	solo	`1.0`
Technical deep dive	professional	rigorous / documentary	dialogue	`1.0`
Light tour	accessible	humorous	dialogue	`1.0`

Advanced controls:

content: auto, quick, accessible, complete, professional
style: calm, friendly, humorous, rigorous, energetic, documentary
format: solo, dialogue
speed: 0.7–1.2
output: MP3 by default, or an explicitly requested burned-subtitle MP4
voice: every installed local voice and curated dialogue pairs

Speech strategies

Strategy	Recommended use	Behavior	Trade-off
`auto`	general use	pure Chinese uses Kokoro; mixed Chinese-English uses MeloTTS	the selected engine must be installed and healthy
`melo-mixed`	same-voice bilingual speech	one MeloTTS `ZH` voice speaks both Chinese and English	smooth continuity; English is below dedicated English Kokoro
`kokoro-bilingual`	maximum English clarity	switches between a Chinese and an English Kokoro voice	a slight voice or accent change can occur at language boundaries
`kokoro-zh`	pure Chinese	uses a Kokoro Mandarin voice	not intended for mixed English phrases

The default Mandarin voice is zm_yunyang. The default English Kokoro voice is af_heart. MeloTTS currently exposes the verified mixed-language voice ZH.

Privacy

Scanning is bounded to the resolved project root. The Skill applies privacy filters before opening candidate files and never reads outside that root.

Built-in exclusions cover:

.env*, credentials, certificates, key files, and secret directories;
datasets, databases, uploads, and generated podcast output;
dependency folders, caches, build products, and version-control internals;
archives, binaries, media, and model weights.

Add project-specific rules to .podcastignore using gitignore-style syntax:

docs/internal/**
benchmarks/private-results.csv
customer-demos/**

The script validator also rejects secret-like assignments such as API keys. A future cloud adapter may receive final spoken lines only after explicit selection; it must never receive raw README files, source code, source paths, or facts.json. No cloud adapter ships in this repository.

Requirements

Windows 10/11 for the currently verified end-to-end path
Codex with local Skill support
Git for cloning the repository
Python 3.11+ for repository development and deterministic helpers
a Python 3.12 interpreter for the shared Kokoro setup path
Conda available when installing the isolated MeloTTS Python 3.9 runtime
enough disk space for runtimes and approved model files

This project is Windows-first. Linux and macOS may work with adaptation, but they have not received equivalent native end-to-end smoke testing. MeloTTS upstream recommends Docker on Windows; this repository instead uses a tested isolated native worker and does not install Docker or WSL.

Installation

Clone the repository and copy only the installable Skill directory into your current-user Codex Skills folder:

The installable source directory in the repository is skill/project-podcast.

git clone https://github.com/YOUR-ACCOUNT/project-podcast-skill.git
Set-Location project-podcast-skill

$skillDestination = Join-Path $env:USERPROFILE '.codex\skills\project-podcast'
New-Item -ItemType Directory -Force (Split-Path $skillDestination) | Out-Null
Copy-Item -LiteralPath 'skill\project-podcast' -Destination $skillDestination -Recurse -Force

If the destination already exists, remove or archive that exact project-podcast directory before copying a clean replacement. Do not copy .models/, voice-previews/, tests, or development plans into the Skills folder.

Installing the Skill does not install speech engines or download model weights.

Runtime and model setup

Every project reuses one current-user runtime root:

%LOCALAPPDATA%\ProjectPodcast

Approved model downloads are stored below that root and are not committed to this repository:

Engine	Model	Pinned revision	Approx. download	License	Destination
Kokoro	`hexgrad/Kokoro-82M`	`f3ff3571791e39611d31c381e3a41a3af07b4987`	331 MB	Apache-2.0	`models/huggingface/`
MeloTTS	`myshell-ai/MeloTTS-Chinese`	`af5d207a364ea4208c6f589c89f57f88414bdd16`	208 MB	MIT	`models/melo/MeloTTS-Chinese/`
MeloTTS frontend	`google-bert/bert-base-multilingual-uncased`	`d11aae01352cff41b1deab96882a87b9e4d13862`	675 MB	Apache-2.0	`models/melo/bert-base-multilingual-uncased/`

Sizes are approximate manifest values. Upstream licenses and terms remain authoritative.

Check it from any directory:

python "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py" runtime-status

When an engine reports ready, reuse it offline without asking for installation again. When it reports missing or broken, first run the setup command without approval flags to review its manifest. Dependency installation and model download are separate approvals.

Kokoro dependency setup after review:

python "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py" setup-runtime `
  --base-python "C:\path\to\python.exe" `
  --allow-network

Kokoro model setup requires a separate approved invocation, either with a reviewed local model source or --allow-model-download.

MeloTTS dependency and model gates are also separate:

python "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py" setup-melo-runtime `
  --allow-dependencies `
  --conda-executable conda

python "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py" setup-melo-runtime `
  --allow-model-download

The setup commands print sources, revisions, approximate sizes, licenses, and destinations before an approval is granted. They do not install into the current project as a fallback.

Quick start

The normal interface is natural language in Codex. Examples:

Use project-podcast to turn this repository into an audio podcast.

Make a calm solo bedtime overview at 0.80 speed. Keep everything local.

Create a complete professional MP4 with burned subtitles. Use MeloTTS for mixed Chinese-English terms.

English pronunciation matters most. Use Kokoro bilingual voice switching and let me preview the voices first.

If no dimension is specified, the Skill announces the bedtime default and reminds the user that preset, content, style, format, voice, speed, and output can all be changed.

Voice previews

Ask Codex for an audio preview before full synthesis. The mixed-language sample includes representative terms such as OverLock Spiking Transformer, Temporal Query, and Q/K/V.

Advanced direct invocation:

python "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py" preview `
  --backend melo `
  --language mixed-zh-en `
  --project-name Demo `
  --output-root "$env:LOCALAPPDATA\ProjectPodcast\voice-previews\melo"

Configuration

Project defaults may be stored in .project-podcast.yml:

preset: bedtime
content: auto
style: calm
format: solo
duration:
  mode: auto
  min_minutes: 8
  max_minutes: 30
tts:
  mode: local
  speech_strategy: auto
  speed: 0.80
  voice: zm_yunyang
  english_voice: af_heart
  melo_voice: ZH
output:
  format: mp3

Precedence is: current natural-language request → project configuration → remembered user preference → Skill default.

Project-specific pronunciation replacements use .podcast-pronunciations.yml:

SCTFormer: "S C T Former"
Nomniglot: "Nom-ni-glot"

The readable transcript keeps the original term; only the TTS input receives the replacement.

Generated files

Runs are placed under the source project, not under the shared runtime:

<project>/project-podcast/
└── YYYY-MM-DD-project-name-solo/
    ├── project-name-solo.mp3       # or one final .mp4
    ├── latest.txt
    ├── transcript.md
    ├── sources.md
    ├── scan.json
    ├── facts.json
    ├── script.json
    ├── synthesis.json
    ├── cover.png
    ├── captions.srt                # MP4 audit artifact
    └── segments/

Changing only a voice, speed, or pronunciation invalidates affected audio segments instead of rescanning the project. Changing style regenerates the script and audio while preserving the scan. Valid upstream artifacts survive failures.

CLI reference

The deterministic helper is primarily for Codex orchestration and diagnostics:

$projectPodcast = "$env:USERPROFILE\.codex\skills\project-podcast\scripts\project_podcast.py"

python $projectPodcast runtime-status
python $projectPodcast options
python $projectPodcast scan --project-root . --output-root .\project-podcast\manual-run
python $projectPodcast validate-facts --scan .\project-podcast\manual-run\scan.json --facts .\project-podcast\manual-run\facts.json
python $projectPodcast validate-script --script .\project-podcast\manual-run\script.json --format solo

Run subcommands with --help for their full arguments. The fake backend is test-only and must not be used as a production voice.

Troubleshooting

The Skill asks to install speech packages in every project

Run runtime-status through the installed wrapper. A healthy current-user runtime must be reused; project-local installation is not a fallback.

Chinese is fine but English technical terms sound wrong

Use melo-mixed for one consistent mixed-language voice, or kokoro-bilingual when maximum English clarity matters more than a slight voice change. Generate a preview first.

MeloTTS reports missing models

Confirm both MeloTTS-Chinese and bert-base-multilingual-uncased exist under the shared Melo model directory. Do not substitute chinese-roberta-wwm-ext-large; Melo's mixed frontend requires multilingual BERT.

MP4 export fails

The exporter requires FFmpeg and a supported Chinese font such as Microsoft YaHei or SimHei. WAV segments, transcript, and SRT are preserved after failure.

The output is too fast

Request a speed from 0.7 to 1.2. The bedtime preset defaults to 0.80.

A cached segment is stale

Change the pronunciation version, strategy, voice, or speed. Those values are included in deterministic cache keys.

Development

Create a development environment from the repository root:

python -m venv .venv
& '.\.venv\Scripts\python.exe' -m pip install -e '.[dev]'
& '.\.venv\Scripts\python.exe' -m pytest

Validate the installable Skill:

$env:PYTHONUTF8 = '1'
python "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" skill\project-podcast

Contributions should preserve local-first behavior, add tests before behavior changes, avoid vendoring models or generated media, and document any new external dependency or license.

Limitations and roadmap

Current limitations:

Windows-first native runtime setup
no automatic phone delivery, RSS feed, or scheduled generation
no web UI, background music, or voice cloning
no bundled cloud TTS adapter
no claim that generated explanations replace a code or security review

Potential future work includes tested Linux/macOS setup, additional offline voices, pronunciation tooling, optional phone delivery integrations, and more efficient long-running MeloTTS worker reuse.

License and third-party components

Repository code and documentation are available under the MIT License. Speech packages, model weights, FFmpeg builds, and transitive dependencies retain their own licenses and terms. See THIRD_PARTY_NOTICES.md before redistribution.

Models and runtimes are downloaded only after explicit approval and are not included in this Git repository.

Name		Name	Last commit message	Last commit date
docs/superpowers		docs/superpowers
skill/project-podcast		skill/project-podcast
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Project Podcast Skill

Why Project Podcast

What it produces

Key features

Program presets

Speech strategies

Privacy

Requirements

Installation

Runtime and model setup

Quick start

Voice previews

Configuration

Generated files

CLI reference

Troubleshooting

The Skill asks to install speech packages in every project

Chinese is fine but English technical terms sound wrong

MeloTTS reports missing models

MP4 export fails

The output is too fast

A cached segment is stale

Development

Limitations and roadmap

License and third-party components

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Project Podcast Skill

Why Project Podcast

What it produces

Key features

Program presets

Speech strategies

Privacy

Requirements

Installation

Runtime and model setup

Quick start

Voice previews

Configuration

Generated files

CLI reference

Troubleshooting

The Skill asks to install speech packages in every project

Chinese is fine but English technical terms sound wrong

MeloTTS reports missing models

MP4 export fails

The output is too fast

A cached segment is stale

Development

Limitations and roadmap

License and third-party components

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages