Metadata-Version: 2.4
Name: mkdocs-piper-tts
Version: 0.1.0
Summary: MkDocs plugin for generating and serving Piper text-to-speech page audio
Author: Reto Weber
License-Expression: MIT
Project-URL: Homepage, https://github.com/risajef/mkdocs-piper-tts
Project-URL: Repository, https://github.com/risajef/mkdocs-piper-tts
Project-URL: Issues, https://github.com/risajef/mkdocs-piper-tts/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markupsafe>=2.1
Requires-Dist: mkdocs<2,>=1.6
Requires-Dist: piper-tts==1.2.0
Provides-Extra: cuda
Requires-Dist: onnxruntime-gpu[cuda,cudnn]==1.25.0; extra == "cuda"
Provides-Extra: tensorrt
Requires-Dist: onnx<2,>=1.16; extra == "tensorrt"
Requires-Dist: onnxruntime-gpu[cuda,cudnn]==1.25.0; extra == "tensorrt"
Requires-Dist: tensorrt-cu12<11,>=10.9; extra == "tensorrt"
Dynamic: license-file

# mkdocs-piper-tts

An MkDocs plugin that generates Piper text-to-speech audio for pages and adds
an HTML audio control through the `piper_tts_button` template helper.

## Install

```bash
pip install mkdocs-piper-tts
```

For CUDA synthesis, install the CUDA extra on a compatible CUDA 12 system:

```bash
pip install 'mkdocs-piper-tts[cuda]'
```

For TensorRT synthesis support, install:

```bash
pip install 'mkdocs-piper-tts[tensorrt]'
```

The plugin invokes `ffmpeg` to encode MP3 files, so `ffmpeg` must be available
on `PATH` when generating audio.

## Piper Version Policy

This package intentionally pins `piper-tts==1.2.0`. That release is MIT
licensed and is compatible with this package's MIT license. Do not upgrade
Piper without first reviewing the license of the target release and its
runtime dependencies.

## Configure

Store Piper `.onnx` models and their JSON configuration files outside the
published documentation source, then enable the plugin in `mkdocs.yml`:

```yaml
plugins:
  - piper-tts:
      model_dir: models/piper-tts
      asset_dir: assets/piper-tts
      audio_dir: audio
      use_cuda: true
      batch_size: 2
      languages:
        en:
          model: en_US-amy-medium.onnx
          label: Listen
        de:
          model: de_DE-thorsten-medium.onnx
          label: Vorlesen
```

Set `lang` in a page's front matter. The plugin caches generated MP3 files and
sidecar metadata under `<docs_dir>/<asset_dir>/<audio_dir>`. Cached files are
reused when both page source and plugin code are unchanged.

Render the control in an MkDocs template with:

```jinja2
{{ piper_tts_button(page) }}
```

## Releases

Tags named `v*` build and publish a wheel and source distribution with PyPI
trusted publishing. Before the first release, configure PyPI's pending trusted
publisher for the `risajef/mkdocs-piper-tts` repository and the
`publish-pypi.yml` workflow.
