podcast-generator 0.3.0__tar.gz

podcast_generator-0.3.0/.env.example

@@ -0,0 +1,15 @@
+# Copy this file to .env in the home folder to change where podcast-generator
+# looks for scripts and writes audio. The home folder is podcast_generator in
+# your Documents folder after a pip install, or the repo folder for a source
+# checkout (or PODCAST_GENERATOR_HOME, if set). The Podcast Watch app
+# (podcast-watch) can also edit these for you. All settings are optional; if
+# unset, the home folder's own inputs/, outputs/ and script_archive/ are used.
+# The same folders are used for manual and scheduled runs.
+
+PODCAST_INPUTS_DIR=C:\Users\yourname\Sync\podcasts\inputs
+PODCAST_OUTPUTS_DIR=C:\Users\yourname\Sync\podcasts\outputs
+PODCAST_ARCHIVE_DIR=C:\Users\yourname\Sync\podcasts\script_archive
+
+# Used by the Podcast Watch app (scripts/podcast-watch.ps1): on or off forces
+# the watch task to that state whenever the app opens. Unset = leave it as is.
+# PODCAST_WATCH_ON_OPEN=on

podcast_generator-0.3.0/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-02
+
+First public release, and the first on PyPI (`pip install podcast-generator`).
+
+### Added
+
+- Packaged for PyPI as `podcast-generator`, with three commands:
+  `podcast-generator` (convert scripts; also `python -m podcast_generator`),
+  `podcast-generator-mcp` (the MCP server, with the `[mcp]` extra) and
+  `podcast-watch` (the Podcast Watch app; `podcast-watch --shortcut` makes
+  the desktop shortcut).
+- A home folder for settings and the default folders: `podcast_generator`
+  in Documents for a pip install, the repo for a source checkout, or
+  `PODCAST_GENERATOR_HOME`. The first batch run creates the inputs folder.
+- MCP server: Claude Desktop or another MCP client can list voices, queue a
+  script (validated up front), start a conversion in the background, check
+  a podcast's status, list recent podcasts, and turn the watch on or off.
+- Podcast Watch app (Windows): one window to set up the
+  `PodcastGeneratorWatch` scheduled task (current user, no admin rights,
+  `pythonw.exe` so no window flashes up), turn it on or off, set how often
+  it checks, choose what happens when the app opens
+  (`PODCAST_WATCH_ON_OPEN`), and pick the inputs/outputs/archive folders.
+  Its **About** menu shows the version and author.
+- Only one conversion runs at a time on a machine; a run that finds
+  another in progress leaves the queue to it. Under `pythonw.exe`, output
+  goes to `generator.log` (rotated at 1 MB).
+- Tests, GitHub Actions CI, and a tag-triggered workflow that publishes to
+  PyPI and creates the GitHub release.
+- MANUAL.md: sections on the Podcast Watch app, the home folder, offline
+  use, and troubleshooting the app, the watch and the MCP server.
+
+### Changed
+
+- Speech synthesis comes from [`voxport`](https://pypi.org/project/voxport/)
+  0.5.0+ on PyPI (the renamed `vox_bridge`), with its `kokoro` extra. Its
+  progress messages (model loads, each segment) are shown through logging.
+- The code moved into the `podcast_generator` package. `generator.py` and
+  `mcp_server.py` at the repo root remain as thin wrappers, so scheduled
+  tasks and MCP configs made before this release keep working.
+- Offline use: point `HF_HOME` at a copied Hugging Face cache in `.env`,
+  instead of voxport's repo `hf_cache/` folder.
+- `instructions_creating_podcast_generator.md` brought up to date (v6.0).
+
+### Removed
+
+- `requirements.txt` (dependencies are in `pyproject.toml`) and `VERSION`
+  (the version lives in `podcast_generator/__init__.py`).
+- `scripts/watch-on.ps1` / `scripts/watch-off.ps1` and their two desktop
+  shortcuts, replaced by the Podcast Watch app.
+
+## Earlier versions
+
+*Versions 0.1.0 to 0.2.1 predate this public repository, which starts
+from a fresh history, so they have no tags or releases here.*
+
+## 0.2.1 - 2026-10-31
+
+### Fixed
+
+- `generator.py --version` reported `0.1.0` in the v0.2.0 release.
+
+### Changed
+
+- README: new Installation and Usage sections. MANUAL.md now describes
+  how italic-only lines at the top of a script are handled.
+
+## 0.2.0 - 2026-10-31
+
+### Added
+
+- `scripts/watch-on.ps1` / `scripts/watch-off.ps1` and matching desktop
+  shortcuts ("Podcast Watch - Turn ON/OFF") that enable/disable the
+  `PodcastGeneratorWatch` scheduled task with a confirmation popup, so
+  toggling the folder-watch schedule doesn't need PowerShell or Task
+  Scheduler's GUI.
+- `MANUAL.md`, a full user manual: script-writing guide, CLI reference,
+  voice catalog, and troubleshooting.
+
+### Removed
+
+- The `reference/` folder and the obsolete in-repo `inputs/`/`outputs/`
+  folders.
+
+### Fixed
+
+- An all-italic line near the top of a script (e.g. `*Source: ...*`) was
+  treated as the end-of-script marker, so the whole script stripped to
+  nothing and failed with "no spoken text found". Italic-only lines now end
+  the script only after spoken prose has started; before that they're
+  skipped as front matter.
+
+## 0.1.0 - 2026-09-19
+
+### Added
+
+- `generator.py`: rebuilt as a consumer of the shared
+  [`vox_bridge`](../vox_bridge) toolkit's `KokoroDirectTTS`, replacing the
+  original standalone `tts_podcast.py` (which called Kokoro directly).
+  Behavior preserved: same CLI flags (`--voice`, `--speed`, `--format`,
+  `--output`), same markdown stripping, same per-script `**Voice:**`
+  metadata handling and precedence rules.
+- Configurable folder locations (`PODCAST_INPUTS_DIR`,
+  `PODCAST_OUTPUTS_DIR`, `PODCAST_ARCHIVE_DIR` via `.env`), defaulting to
+  local script-relative folders when unset. The same folders and the same
+  command (`python generator.py`) serve both interactive use and scheduled/
+  unattended runs — there is no separate watch-mode script.
+- Archive-on-success: a successfully-converted script moves out of the
+  inputs folder into the archive folder (collision-safe renamed if
+  needed), so a rerun — manual or scheduled — never reprocesses it.
+- Archive-on-failure: a script that fails to convert moves to
+  `<archive>/failed/` with a `.error.txt` note, instead of being retried
+  forever by a scheduled run.
+- Job discovery happens before any heavy import (`vox_bridge`/`torch`/
+  `kokoro`), so an empty inputs folder exits in a fraction of a second
+  instead of paying model-load cost for nothing — the difference that
+  makes polling this on a schedule cheap.
+- `--version` flag.
+- `LICENSE` (MIT).
+
+### Changed
+
+- Default voice changed from `am_onyx` to `af_heart` (actual usage:
+  `af_heart` for most podcasts, `am_echo` via per-script `**Voice:**` for
+  the military fellows program).
+- An empty inputs queue now exits with code `0`, not `1` — it's the normal
+  steady state for a scheduled/watched run, not an error. A genuinely
+  missing inputs directory (misconfiguration) still exits `1`.
+
+### Fixed
+
+- Voice connect/permission and text/voice ordering issues live-tested and
+  fixed on the `vox_bridge`/`loremaster` side of this work are recorded in
+  those repos' own changelogs, not here — this file covers only
+  `podcast_generator`.
+
+[Unreleased]: https://github.com/brienalkire/podcast_generator/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/brienalkire/podcast_generator/releases/tag/v0.3.0

podcast_generator-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brien Alkire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

podcast_generator-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+include CHANGELOG.md MANUAL.md .env.example

podcast_generator-0.3.0/MANUAL.md

@@ -0,0 +1,393 @@
+# podcast_generator — User Manual
+
+A companion to [README.md](README.md) — that file gets you running in five
+minutes; this one covers everything else: how to write a script, the full
+CLI reference, the voice catalog, the Podcast Watch desktop app, using it
+from Claude Desktop (MCP), and troubleshooting.
+
+## What this does
+
+`podcast-generator` takes a markdown file — a podcast script — and turns it
+into an audio file (MP3 or WAV) using [Kokoro](https://github.com/hexgrad/kokoro),
+a free, open-source text-to-speech model that runs entirely on your own
+machine via [`voxport`](https://github.com/brienalkire/voxport). No API key, no per-use cost, and
+(once the model is cached) no internet connection required.
+
+## Writing a script
+
+Any markdown file works, but a few conventions control exactly what gets
+spoken aloud versus stripped out before synthesis:
+
+- **Headers** (`#`, `##`, `###`, ...) are removed entirely — including
+  their text. If you use headers as section labels (`## OPENING`,
+  `## CLOSING`), those labels are *not* spoken.
+- **Metadata lines** matching `**Key:** value` (e.g. `**Author:** ...`,
+  `**Date:** ...`) are removed. This is also how `**Voice:** af_heart`
+  works — see below.
+- **Horizontal rules** (`---`, `***`, `___`) are removed.
+- **An entirely-italic line** (e.g. `*Source: ...*` or `*End of script.*`)
+  is a production note. Before any spoken prose it's skipped as front
+  matter. After prose has started it's the end-of-script marker, and
+  **everything from that line to the end of the file is dropped, not just
+  that line.** This is meant for a trailing citation or production note,
+  but it's a common gotcha: if a normal sentence in the middle of your
+  script happens to be wrapped entirely in `*asterisks*`, everything after
+  it will silently go unspoken. Keep italic-only lines for the very top or
+  very end of the file only.
+- **Inline formatting** — `**bold**`, `*italic*`, `` `code` ``,
+  `[link text](url)` — has its markup stripped but the text itself is
+  kept and spoken normally.
+- Blank lines are preserved as paragraph breaks; runs of 3+ blank lines
+  collapse to one.
+
+Everything else — plain paragraphs — is spoken as-is. A minimal script:
+
+```markdown
+# My Episode Title
+
+**Voice:** af_heart
+
+## OPENING
+
+Welcome back to the show. Today we're talking about...
+
+## CLOSING
+
+That's all for this episode. Thanks for listening.
+
+---
+
+*Source: some-article.com, September 2026.*
+```
+
+Only "Welcome back to the show..." and "That's all for this episode..."
+get spoken — the title, section labels, voice metadata, and trailing
+source note are all stripped.
+
+### Choosing a voice
+
+Precedence, highest to lowest:
+
+1. `--voice` on the command line — applies to every script in that run.
+2. A `**Voice:**` line in the script's own header.
+3. The built-in default (`af_heart`).
+
+This lets you set a default for most episodes while overriding specific
+ones — e.g. a recurring segment that always uses a different voice.
+
+## Full CLI reference
+
+```
+podcast-generator [input_script.md] [options]
+```
+
+| Argument | Meaning |
+|---|---|
+| `input_script.md` (positional, optional) | Convert just this one file instead of batch-processing the inputs folder. |
+| `--voice VOICE` | Kokoro voice for the whole run (see catalog below). Overrides any `**Voice:**` line. |
+| `--lang CODE` | Accent code (`a` American, `b` British). Defaults to the chosen voice's first letter — you'd only override this for an edge case. |
+| `--speed FLOAT` | Speaking rate multiplier (default `1.0`; `0.9` slower, `1.1` faster). |
+| `--format {mp3,wav}` | Output format (default `mp3`). |
+| `--output PATH` | Output file path. Only used in single-file mode; ignored in batch mode. |
+| `--version` | Print the installed version and exit. |
+
+`python -m podcast_generator` does the same thing.
+
+**Batch mode** (no positional argument): every `.md` file in the inputs
+folder is converted, written to the outputs folder as
+`<script-name>.<format>`, and (on success) moved to the archive folder.
+
+**Single-file mode**: pass a path directly. `--output` only applies here.
+Archiving still happens if the file you named happens to live in the
+inputs folder; a file from anywhere else is left where it is.
+
+## Voice catalog
+
+Kokoro's voice names encode accent and gender in the first two letters
+(`a`=American/`b`=British, `m`=male/`f`=female). These are the voices this
+tool validates against and shows in `--help`:
+
+| American male | American female | British male | British female |
+|---|---|---|---|
+| `am_onyx` | `af_heart` | `bm_george` | `bf_emma` |
+| `am_adam` | `af_bella` | `bm_lewis` | `bf_isabella` |
+| `am_echo` | `af_nova` | `bm_daniel` | `bf_alice` |
+| `am_eric` | `af_sarah` | `bm_fable` | `bf_lily` |
+| `am_fenrir` | `af_sky` | | |
+| `am_liam` | `af_nicole` | | |
+| `am_michael` | `af_aoede` | | |
+| `am_puck` | `af_kore` | | |
+
+We don't have authoritative per-voice character descriptions beyond the
+defaults chosen for this project (`af_heart` for most episodes, `am_echo`
+for one recurring series) — try a few on a short script and pick what
+sounds right for your content. Kokoro supports more voices than this list
+(including other languages); this tool's `--voice` choices are
+deliberately limited to a curated English subset. If you need one outside
+this list, it'll need adding to `VOICE_CHOICES` in
+`podcast_generator/generator.py`.
+
+**Only voices already in the local Hugging Face cache work on a machine
+with `HF_HUB_OFFLINE=1` set.** On a machine with normal internet access, an
+uncached voice just downloads on first use. See "Offline use" below.
+
+## Scheduled ("drop folder") mode
+
+Running `podcast-generator` on a schedule turns the inputs folder into a
+drop folder. Each run converts whatever scripts have arrived since the last
+one and archives them, so nothing is processed twice. Point the folders at
+a cloud-synced location and you can drop a script in from any device and
+get the finished audio back out, with no manual run.
+
+The schedule is a Windows scheduled task named `PodcastGeneratorWatch`
+that runs every few minutes. Create it once with the **Set up watch**
+button in the Podcast Watch app below, then use the same app to control
+it. On macOS or Linux, schedule `podcast-generator` with cron or similar
+instead; the app and the scheduled task are Windows-only.
+
+Only one conversion runs at a time on a machine. If a run starts while
+another is still converting, for example a scheduled check during a long
+script, it leaves the queue to the run already going and exits.
+
+## The Podcast Watch app
+
+A small window for day-to-day control of the drop folder. Open it with
+the `podcast-watch` command, or from a desktop shortcut that
+`podcast-watch --shortcut` creates for you. It's a Windows PowerShell
+script shipped inside the package (`podcast_generator/podcast-watch.ps1`),
+so there's nothing else to install.
+
+![The Podcast Watch window, showing the watch turned on and the three folders](docs/images/podcast-watch.png)
+
+The **About** menu at the top shows the version number and the author.
+
+### Folder watch
+
+- **Watch is ON / OFF** shows whether the scheduled task is enabled. When
+  it's on, the line underneath gives the check interval.
+- **Turn ON / Turn OFF** enables or disables the task. Turning it off only
+  stops the schedule. Scripts already in the inputs folder stay there and
+  are converted when you turn it back on. Manual `podcast-generator` runs
+  work either way.
+- **When this app opens** decides what happens to the watch each time you
+  open the window:
+  - *Leave watch as it was* (the default) changes nothing.
+  - *Turn watch ON* always switches it on, so opening the app is enough to
+    start the watch.
+  - *Turn watch OFF* always switches it off.
+
+  The choice is saved immediately to `.env` as `PODCAST_WATCH_ON_OPEN`.
+- **Check every** sets how often the watch looks for new scripts (5 to 60
+  minutes). The change applies to the scheduled task straight away and
+  doesn't turn the watch on or off.
+
+#### Setting up the watch
+
+On a machine where the watch has never been set up, the window says
+**Watch not set up** and the button reads **Set up watch**. Pick an
+interval under **Check every**, then click the button. The app registers
+the `PodcastGeneratorWatch` scheduled task and turns it on. The task:
+
+- runs under your own Windows account, with no admin rights or stored
+  password, and only while you're logged in;
+- runs on battery power as well as when plugged in;
+- runs `pythonw.exe -m podcast_generator` from the Python environment you
+  started the app from, so no console window flashes up on each check.
+  Each run's output is appended to `generator.log` in the home folder
+  (see "Where settings are stored" below).
+
+If you later move or recreate that environment, delete the task and set it
+up again from the new one.
+
+To remove the task, run
+`Unregister-ScheduledTask -TaskName PodcastGeneratorWatch` in PowerShell
+or delete it in Task Scheduler. The app then offers **Set up watch** again.
+
+### Folders
+
+The three folders `podcast-generator` uses, whether it runs on the schedule or
+by hand:
+
+| Folder | What goes there |
+|---|---|
+| **Inputs** | Scripts (`.md` files) waiting to be converted. |
+| **Outputs** | Finished audio, named after the script (`my-episode.mp3`). |
+| **Archive** | Scripts after conversion. Scripts that failed go to `failed/` inside it, each with a `.error.txt` note. |
+
+For each folder:
+
+- **Browse...** picks a different folder and saves it to `.env`.
+- **Open** opens the folder in File Explorer, creating it first if it
+  doesn't exist yet.
+- **Use default** removes your choice from `.env`, so the folder goes back
+  to the one inside the home folder (`inputs/`, `outputs/`, or
+  `script_archive/`). The label then reads "(default)" and the button is
+  greyed out.
+
+Changes take effect on the next run. There's nothing to restart.
+
+### Where settings are stored
+
+Settings live in `.env` in the **home folder**, which also holds the
+default `inputs/`, `outputs/` and `script_archive/` folders and
+`generator.log`. The home folder is:
+
+- `podcast_generator` in your Documents folder, for a `pip install`;
+- the repo folder, when running from a source checkout;
+- or whatever `PODCAST_GENERATOR_HOME` points to, if you set that
+  environment variable (it can't go in `.env` itself).
+
+Everything the app saves goes into that `.env`, the same file
+`podcast-generator` reads:
+
+```
+PODCAST_INPUTS_DIR=C:\Users\yourname\Sync\podcasts\inputs
+PODCAST_OUTPUTS_DIR=C:\Users\yourname\Sync\podcasts\outputs
+PODCAST_ARCHIVE_DIR=C:\Users\yourname\Sync\podcasts\script_archive
+PODCAST_WATCH_ON_OPEN=on
+```
+
+The app changes only these lines and leaves the rest of the file,
+including comments, as it was. You can still edit `.env` by hand;
+[`.env.example`](.env.example) documents every setting. Each machine keeps
+its own `.env`.
+
+## Using it from Claude Desktop (MCP)
+
+`podcast-generator-mcp` lets an AI app that supports the
+[Model Context Protocol](https://modelcontextprotocol.io), such as Claude
+Desktop, make podcasts for you. You can ask, for example, "write a
+10-minute episode explaining how tides work, read by a British voice", and
+the app writes the script, queues it, converts it, and tells you where the
+MP3 is. Everything still runs on your machine, using the same folders and
+`.env` as the command line and the Podcast Watch app.
+
+### Setting it up
+
+1. Install with the `mcp` extra: `pip install "podcast-generator[mcp]"`.
+2. In Claude Desktop, open Settings → Developer → Edit Config. Add this to
+   `claude_desktop_config.json`, with the full path to the command in your
+   environment (Claude Desktop doesn't see a virtual environment's `PATH`):
+
+   ```json
+   {
+     "mcpServers": {
+       "podcast-generator": {
+         "command": "C:\\path\\to\\.venv\\Scripts\\podcast-generator-mcp.exe"
+       }
+     }
+   }
+   ```
+
+   If the file already has an `mcpServers` section, add the
+   `"podcast-generator"` entry inside it.
+3. Restart Claude Desktop. The tools appear under the tools (hammer or
+   plug) menu in the chat box.
+
+Other MCP clients that can start a local (stdio) server use the same
+command.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `list_voices` | Lists the voices a script can use. |
+| `queue_podcast` | Saves a script to the inputs folder under a name you choose, optionally setting its voice. It checks the script first: an unknown voice, a script with nothing to speak, or a name that's already taken is reported straight away, not after a failed conversion. Returns the word count and an estimated length. |
+| `generate_now` | Starts converting everything queued, in the background, and returns at once. Does nothing if a conversion is already running. |
+| `podcast_status` | Reports whether a podcast is queued, converting, done (with the file path, size, and length), or failed (with the reason). |
+| `list_podcasts` | Shows the folders, whether the watch is on, what's queued, and recent audio and failures. |
+| `set_watch` | Turns the scheduled watch on or off. |
+
+Conversion never happens inside a tool call, because a long script takes
+minutes. If the watch is on, a queued script is picked up on the next
+check. Otherwise the AI calls `generate_now`. Either way, it checks back
+with `podcast_status`. Output from conversions started this way goes to
+`generator.log`.
+
+## Offline use
+
+Kokoro downloads its model weights, and each voice pack (e.g.
+`af_heart.pt`), from Hugging Face the first time each is used. They're
+cached in Hugging Face's standard location (`~/.cache/huggingface`), or
+wherever `HF_HOME` points. To run on a machine that can't reach
+huggingface.co:
+
+1. On a machine with internet access, add `HF_HOME=<some folder>` to the
+   home folder's `.env`, then convert a short script once with each voice
+   you'll need. The model and those voices land in that folder.
+2. Copy the folder to the offline machine and add `HF_HOME=<where you put
+   it>` to that machine's `.env`.
+3. Add `HF_HUB_OFFLINE=1` to the offline machine's `.env`. Only cached
+   voices work there.
+4. Install spaCy's English model while you have a network connection,
+   since `HF_HUB_OFFLINE` doesn't cover it:
+   `python -m spacy download en_core_web_sm`.
+
+If the network is reachable but an SSL-inspecting corporate proxy breaks
+the downloads (`CERTIFICATE_VERIFY_FAILED`), `pip install pip-system-certs`
+often fixes it by trusting Windows' certificate store.
+
+## Troubleshooting
+
+**Podcast Watch says "Watch not set up"**: The `PodcastGeneratorWatch`
+scheduled task doesn't exist on this machine yet. Click **Set up watch**
+(see "Setting up the watch" above).
+
+**"Could not set up the podcast watch"**: Windows refused to create the
+task, and the message gives Windows' reason. Some work computers block
+scheduled tasks for ordinary users; if so, run `podcast-generator` by
+hand or ask your IT department.
+
+**The podcast-generator tools don't appear in Claude Desktop**: Check that
+the command path in `claude_desktop_config.json` exists, that backslashes
+are doubled, and that you restarted Claude Desktop. Claude Desktop's MCP
+log (Settings → Developer) shows the server's startup errors. A common one
+is "podcast-generator-mcp needs the MCP SDK", fixed by
+`pip install "podcast-generator[mcp]"` in that environment.
+
+**"Could not turn the podcast watch on/off"**: Windows refused to change
+the scheduled task, and the message gives Windows' reason. If the task was
+registered by another user or by an administrator, you may need to enable
+or disable it in Task Scheduler instead.
+
+**Nothing happens when the watch is on**: Check that a run has had time to
+happen (the app shows the interval), that the script ends in `.md`, and
+that it's in the inputs folder the app shows. If the script was picked up
+but failed, it's in the archive folder's `failed/` subfolder with a
+`.error.txt` note explaining why. Otherwise, look at the end of
+`generator.log` in the home folder for the latest run's output.
+
+**"Another conversion run is already in progress"**: Not an error. Only one
+conversion runs at a time; the run already going converts the queue. In
+single-file mode, try again when it finishes.
+
+**"No .md scripts found in ..."** — Not an error (exit code 0). The
+inputs folder is just empty right now. Normal for a scheduled run between
+drops.
+
+**"script requests unknown voice '...'"** — A `**Voice:**` line names
+something not in the catalog above. Check spelling (underscore, not
+hyphen: `af_heart` not `af-heart`).
+
+**"no spoken text found after stripping the markdown"** — Usually means
+an italic-only line partway through the script triggered the
+end-of-script cutoff (see "Writing a script" above) and everything after
+it — possibly the entire rest of the file — got dropped. Check for a
+stray `*line wrapped entirely in asterisks*` before the content you
+expected to hear.
+
+**MP3 write fails, mentions ffmpeg** — Your `soundfile`/libsndfile build
+doesn't have native MP3 support and `ffmpeg` isn't on `PATH`. Either
+install `ffmpeg`, or use `--format wav` (needs neither).
+
+**First run on a new machine hangs or fails trying to reach the
+network** — A fresh Python environment downloads a small spaCy model (`en_core_web_sm`) on first use, separately from the
+Kokoro model itself. On a firewalled machine, run
+`python -m spacy download en_core_web_sm` ahead of time, while you still
+have a network connection somewhere.
+
+**A voice fails with a Hub connection error instead of downloading** —
+`HF_HUB_OFFLINE=1` is set (intentionally, on a firewalled machine) and
+that voice isn't in the local Hugging Face cache. Either populate the cache with
+that voice's `.pt` file from a machine that can reach huggingface.co, or
+unset `HF_HUB_OFFLINE` if this machine actually has internet access.