pdftts 0.2.0__tar.gz

pdftts-0.2.0/.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.venv
+dist
+build
+*.egg-info
+__pycache__
+.pytest_cache
+tests
+uv.lock
+*.wav
+*.m4a
+*.m4b
+*.mp3
+*.pdf
+*.epub

pdftts-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+# Publish to PyPI on a tagged release, using a Trusted Publisher — no token is
+# stored anywhere. Inert until the project is claimed on PyPI and this workflow
+# is registered as its publisher; until then, tagging simply does nothing.
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # what Trusted Publishing authenticates with
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: the wheel carries its assets
+        run: |
+          uv run --no-project python - <<'PY'
+          import glob, zipfile, sys
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          missing = [p for p in ("pdftts/web/index.html", "pdftts/web/sw.js",
+                                 "pdftts/vendor/ocrpdf.swift") if p not in names]
+          sys.exit(f"missing from wheel: {missing}" if missing else 0)
+          PY
+      - uses: pypa/gh-action-pypi-publish@release/v1

pdftts-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,98 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # Both platforms matter: OCR is macOS-only, so Linux proves the rest of the
+    # pipeline does not quietly depend on it.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - uses: actions/setup-node@v4
+        with: { node-version: "22" }      # the dashboard-script test executes the page
+      - run: uv sync --locked
+      - run: uv run pytest -q
+
+  build:
+    # A wheel that omits the dashboard or the OCR helper installs fine and fails
+    # at runtime, so check the assets are actually inside it.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: the wheel carries its assets
+        run: |
+          uv run --no-project python - <<'PY'
+          import glob, zipfile, sys
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          missing = [p for p in ("pdftts/web/index.html", "pdftts/web/sw.js",
+                                 "pdftts/vendor/ocrpdf.swift") if p not in names]
+          sys.exit(f"missing from wheel: {missing}" if missing else 0)
+          PY
+      - name: it installs and runs from the wheel alone
+        run: |
+          uv venv /tmp/probe
+          VIRTUAL_ENV=/tmp/probe uv pip install dist/*.whl
+          /tmp/probe/bin/pdftts --list-languages
+
+  docker:
+    # This image cannot be built on the machine I develop on — no Docker daemon
+    # there — so CI is what proves it works, not a claim in the README.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: pdftts:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: the phonemiser model is baked in, not downloaded at runtime
+        run: |
+          docker run --rm --entrypoint python pdftts:ci -c \
+            "import spacy.util; assert spacy.util.is_package('en_core_web_sm')"
+      - name: it runs, and knows what it can do
+        run: |
+          docker run --rm pdftts:ci --list-languages
+          docker run --rm pdftts:ci --list-engines
+      - name: it narrates a file and writes a tagged m4b
+        run: |
+          mkdir -p books
+          printf 'The first sentence. A second one follows it. And a third.\n' > books/sample.txt
+          docker run --rm --user "$(id -u):$(id -g)" \
+            -v "$PWD/books:/books" pdftts:ci /books/sample.txt --m4a --srt
+          ls -l books/
+          test -s books/sample.wav
+          test -s books/sample.m4a
+          test -s books/sample.srt
+          test "$(stat -c %u books/sample.wav)" = "$(id -u)"   # written as the caller
+      - name: the dashboard answers over a published port
+        run: |
+          docker run -d --name dash -p 8765:8765 pdftts:ci --serve --lan
+          for i in $(seq 1 60); do
+            curl -sf http://127.0.0.1:8765/api/engines >/dev/null && break || sleep 2
+          done
+          curl -sf http://127.0.0.1:8765/ | grep -q "Drop a document here"
+          curl -sf "http://127.0.0.1:8765/api/voices?engine=kokoro" | grep -q af_heart
+          docker rm -f dash

pdftts-0.2.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# Audio output and working files
+*.wav
+*.m4a
+*.mp3
+narration.*
+
+# Source documents: never commit copyrighted readings
+samples/*.pdf
+*.pdf
+
+# OS
+.DS_Store

pdftts-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

pdftts-0.2.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## 0.2.0
+
+### Added
+- **Resume after an interruption.** Every finished chunk is cached by exactly the
+  inputs that determine its audio, so a book that dies at chunk 900 of 1000
+  synthesizes 100 chunks on the next run, not 1000. `--no-cache` opts out,
+  `--clear-cache` empties it, and the dashboard reports and clears it too.
+- **Folder conversion.** `pdftts shelf/` converts everything readable in a
+  directory, `-r` descends into sub-folders, and one unreadable file costs only
+  itself — the queue finishes and the failures are listed at the end.
+- **Nine languages, 54 voices.** American and British English, Spanish, French,
+  Hindi, Italian and Brazilian Portuguese work on the base install; Japanese and
+  Mandarin need one extra each and say so instead of failing at synthesis time.
+  `--lang` picks one, `--list-languages` shows them, and the dashboard groups the
+  voice picker by language.
+- **Cover art and book metadata in the m4b.** The EPUB jacket is attached as
+  cover art, and title, author, language and publication date are written as tags.
+- **Kindle input.** `.mobi`, `.azw`, `.azw3` and `.prc` are unpacked into the
+  same XHTML an EPUB holds, so chapters, metadata and cover art come through one
+  code path. Pure Python — no Calibre, no external tools.
+- **A Docker image**, built and smoke-tested in CI because the machine I develop
+  on has no daemon: it narrates a file and answers on a published port before
+  the build is called green. No OCR inside it — Vision is macOS-only.
+- Continuous integration on Linux and macOS, including a check that the built
+  wheel actually contains the dashboard and the OCR helper.
+- A release workflow that publishes to PyPI through a Trusted Publisher, so no
+  token is ever stored.
+
+- **`--tunnel`: a phone on cellular, with nothing installed on it.** Publishes a
+  temporary `trycloudflare.com` address for the run and shows it as a QR on the
+  Phone tab. The address points at your own machine and dies with the process, so
+  two people running `pdftts` get two separate addresses to their own machines
+  rather than sharing anyone's server. It refuses to publish without a password,
+  generating one if you did not set it, and it ignores any `~/.cloudflared`
+  config it finds — otherwise it silently runs *that* tunnel instead.
+- **A password for the dashboard.** `--password` (or `PDFTTS_PASSWORD`) gates
+  every route, not just the page — the audio, the library and the service worker
+  included. Any username is accepted; the password is what is checked, because a
+  single-user dashboard does not need a user list.
+- **`--public-url`**, for when the dashboard sits behind a tunnel or reverse
+  proxy: the machine cannot discover its own public hostname, so it is told, and
+  the Phone tab offers it as the QR that works on cellular.
+
+### Fixed
+- **New did not start a new session.** The finished narration and its player
+  stayed on screen, and appeared under the pairing QR code on the Phone tab too.
+  New now clears the last render — it is already saved under Past — and the
+  player is scoped to the views it belongs to. A long paste is deliberately kept.
+- **The pairing QR handed out a VPN address.** Asking the routing table for "my
+  address" returns the tunnel when a VPN owns the default route, which a phone on
+  the same wifi cannot reach. The LAN address and the mesh address are now told
+  apart and offered separately — the first for a phone in the house, the second
+  for one out on cellular.
+- **The dashboard was dead in every browser.** The service-worker registration
+  referenced `refreshOffline` twelve lines before its `const` declaration, which
+  throws `ReferenceError` in the temporal dead zone and aborts the entire script:
+  no engine list, no voice list, and every button on the page inert. It looked
+  like a slow network. The callback is now a hoisted function declaration, and
+  the script is executed in a browser-shaped environment in the test suite so
+  this class of error cannot ship again.
+- EPUB content is XHTML and was being parsed with the HTML parser, which warned
+  on every book and is the less reliable of the two.
+- A Piper-style voice id passed to Kokoro selected a pipeline from its first
+  letter alone, so `en_US-amy-medium` narrated English text through the Spanish
+  phonemizer instead of being rejected.
+- `language` was written as a container tag, where MP4 ignores it, and as a
+  two-letter code, which MP4 does not accept. It is now an ISO 639-2 code on the
+  audio stream.
+- Chapter titles were taken from the first line of body text, so an illustrated
+  edition put eighty characters of prose — or a plate's caption — in the player's
+  chapter menu. They now come from the chapter's own heading, with any caption
+  ahead of the chapter marker trimmed off.
+- Tables of contents and lists of illustrations were narrated as prose, arriving
+  mid-book as "Chapter: one, two, three, four...". They are recognised and
+  skipped.
+- The dashboard re-probed the hardware on every page load — about a second of
+  "Checking what this machine can run…" before it could offer a choice. The
+  survey is computed once and warmed at startup.

pdftts-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Bug reports and patches are welcome. This is a small project, so the bar is
+simple: it should keep working on a laptop with no GPU and no network.
+
+## Getting set up
+
+```sh
+git clone https://github.com/JosiahMcj/pdftts.git && cd pdftts
+uv sync
+uv run pytest
+```
+
+That is the whole loop. There is no build step and nothing to configure.
+
+## What I look for in a change
+
+- **A test that fails without it.** The tests here are mostly small and
+  text-only; they run in a couple of seconds and do not synthesize audio. If a
+  change needs a real engine to test, fake the engine — `tests/test_cache.py` has
+  one that counts calls.
+- **Measurements over adjectives.** If a change makes something faster, say how
+  much faster on what hardware. I would rather ship a blank number than an
+  estimate presented as a measurement; the README leaves MisoTTS's speed empty
+  for exactly this reason.
+- **No new required dependency** for something that only some users need. Put it
+  behind an extra, like `piper`, `chatterbox`, `ja` and `zh` already are, and
+  make the failure message name the extra.
+- Comments that explain *why*. The code says what it does.
+
+## Things that are deliberate, not oversights
+
+- **OCR is macOS-only.** It calls Apple's Vision framework through a small Swift
+  helper. On other platforms a scanned PDF is refused with a clear message rather
+  than silently producing an empty file. A Tesseract path would be welcome as
+  long as it stays optional.
+- **Column detection assumes one body column.** True two-column journal layouts
+  extract in visual order. Fixing that properly means real reading-order
+  detection, not a heuristic.
+- **The dashboard has no authentication.** It binds to `127.0.0.1` by default and
+  `--lan` says plainly what it exposes. Adding accounts would be a bigger project
+  than this is.
+
+## Reporting a bug in the audio
+
+Extraction bugs are hard to see and easy to hear. If something reads wrong,
+`pdftts yourfile.pdf --dry-run` prints the exact text that would have been
+spoken — that output, plus the page it came from, is the most useful bug report.

pdftts-0.2.0/Dockerfile

@@ -0,0 +1,78 @@
+# The dashboard and CLI, minus OCR.
+#
+# OCR calls Apple's Vision framework through a Swift helper, so it cannot cross
+# to Linux; a scanned PDF in this image is refused with a clear message rather
+# than silently producing nothing. Everything else — every input format, every
+# output format, Kokoro and Piper, the resume cache, the phone connector — works.
+#
+#   docker build -t pdftts .
+#   docker run --rm -p 8765:8765 -v "$PWD:/books" pdftts --serve --lan
+#   docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/books" pdftts /books/novel.epub --m4b
+#
+# `--user` matters whenever output is written back to a bind mount: the files
+# belong to whoever runs the container, and without it they are written as this
+# image's own user — which usually cannot write to your directory at all.
+#
+# Models and finished chunks live in named volumes, so a rebuilt container does
+# not re-download Kokoro or re-synthesize what it already has:
+#   docker run --rm --user "$(id -u):$(id -g)" \
+#              -v pdftts-models:/cache/huggingface -v pdftts-cache:/cache/pdftts \
+#              -v "$PWD:/books" pdftts /books/novel.epub
+
+FROM python:3.12-slim AS build
+
+# Torch ships a CUDA build by default and it is gigabytes of driver this image
+# will never use. The CPU index keeps the layer to a fraction of that.
+ENV UV_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu \
+    UV_INDEX_STRATEGY=unsafe-best-match \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /src
+COPY pyproject.toml README.md ./
+COPY src ./src
+COPY web ./web
+COPY vendor ./vendor
+RUN uv venv /opt/venv \
+ && VIRTUAL_ENV=/opt/venv uv pip install --no-cache . \
+ # Kokoro's English phonemiser calls spacy.cli.download() the first time it runs,
+ # which needs pip or uv and a network. Neither belongs in the runtime image, so
+ # the model is baked in here and the download never happens.
+ && VIRTUAL_ENV=/opt/venv uv run --no-project python -m spacy download en_core_web_sm \
+ && VIRTUAL_ENV=/opt/venv uv run --no-project python -c \
+      "import spacy.util, sys; sys.exit(0 if spacy.util.is_package('en_core_web_sm') else 'spacy model missing')" \
+ && find /opt/venv -name '__pycache__' -type d -prune -exec rm -rf {} +
+
+
+FROM python:3.12-slim
+
+# espeak-ng is Kokoro's fallback phonemiser; ffmpeg is needed for anything that
+# is not a WAV. Both are small next to the model weights.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ffmpeg espeak-ng \
+ && rm -rf /var/lib/apt/lists/*
+
+# Not root: this container is handed a directory of the user's own books.
+# The caches sit outside any home directory and are world-writable, so the image
+# still works when it is run as the caller's own uid — which is how anyone
+# writing output back to a bind mount has to run it.
+RUN useradd --create-home --uid 1000 reader \
+ && mkdir -p /cache/huggingface /cache/pdftts /data \
+ && chmod 1777 /cache /cache/huggingface /cache/pdftts /data
+COPY --from=build /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH" \
+    HF_HOME=/cache/huggingface \
+    XDG_CACHE_HOME=/cache \
+    XDG_DATA_HOME=/data \
+    HOME=/cache
+
+USER reader
+WORKDIR /books
+EXPOSE 8765
+
+# --serve alone binds 127.0.0.1, which is unreachable from outside a container.
+# --lan is what makes a published port work, and it says what it exposes.
+ENTRYPOINT ["pdftts"]
+CMD ["--serve", "--lan"]

pdftts-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josiah McJunkin
+
+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.