Metadata-Version: 2.5
Name: sase-listen
Version: 0.1.1
Summary: Turn Markdown into chaptered, loudness-normalized MP3 audio editions for the commute
Project-URL: Homepage, https://sase-org.github.io/sase-listen/
Project-URL: Documentation, https://sase-org.github.io/sase-listen/
Project-URL: Repository, https://github.com/sase-org/sase-listen
Project-URL: Issues, https://github.com/sase-org/sase-listen/issues
Project-URL: Changelog, https://github.com/sase-org/sase-listen/blob/master/CHANGELOG.md
Author: Bryan Bugyi
Maintainer: Bryan Bugyi
License-Expression: MIT
License-File: LICENSE
Keywords: audiobook,cli,gemini,markdown,podcast,sase,text-to-speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: curl-cffi>=0.10
Requires-Dist: google-genai>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: lxml>=5
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: mutagen>=1.47
Requires-Dist: numpy>=1.26
Requires-Dist: pdfminer-six>=20250506
Requires-Dist: pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich-argparse>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: segno>=1.6
Requires-Dist: trafilatura>=2.0
Description-Content-Type: text/markdown

# sase-listen

[![CI](https://github.com/sase-org/sase-listen/actions/workflows/ci.yml/badge.svg)](https://github.com/sase-org/sase-listen/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sase-listen.svg)](https://pypi.org/project/sase-listen/)
[![Python](https://img.shields.io/pypi/pyversions/sase-listen.svg)](https://pypi.org/project/sase-listen/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://sase-org.github.io/sase-listen/)

Turn Markdown into chaptered, loudness-normalized MP3 audio editions — narrated
by Gemini TTS, built for listening to SASE research on a commute or walk.

```bash
uv tool install sase-listen
sase-listen doctor
sase-listen render report_narration.md -o episode.mp3
```

Each episode is a mono 24 kHz, 64 kb/s MP3 at −16 LUFS with one ID3 chapter
per `##` heading, an embedded cover, and a spoken AI-disclosure intro. Episodes
reach your phone through Telegram's music player or a private podcast feed for
AntennaPod. Full docs: <https://sase-org.github.io/sase-listen/>.

## How it works

1. **Write a narration script** — by hand for research reports
   (`sase-listen guide` prints the authoring rules, brief by default,
   `sase-listen lint` checks them), deterministically from any Markdown
   (`sase-listen script`), or from an article or PDF URL or local PDF file
   (`sase-listen script https://example.com/article`,
   `sase-listen render paper.pdf -e full`).
2. **Render it** — `sase-listen render` synthesizes each chapter, gates quality
   chunk by chunk, masters to a loudness-normalized MP3, and commits the episode
   to a local library with a manifest.
3. **Listen** — publish to your private feed (`sase-listen publish`) or get the
   MP3 delivered over Telegram.

See [Getting started](https://sase-org.github.io/sase-listen/getting-started/)
and [How it works](https://sase-org.github.io/sase-listen/architecture/).

## Status notes

These commands are not implemented yet and exit 1 with a stub message:

- `sase-listen audition`, `sase-listen ls`, `sase-listen cache`
- `sase-listen doctor --online` (offline checks work; the one-word live synth
  check is still a stub)

Everything else in `sase-listen --help` works. The
[CLI reference](https://sase-org.github.io/sase-listen/cli/) marks each stub.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome; keep
Conventional Commit titles so release-please can cut releases.

## Background

sase-listen implements the
[commute-audio research](https://github.com/sase-org/sase--research/blob/617bce562f5a01dfae5999fc0caf3f6a12baf1aa/202610/commute_audio_from_markdown/commute_audio_from_markdown.md)
via epic `sase-1e3`. Details and provenance links:
[Background](https://sase-org.github.io/sase-listen/background/).
