narra 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- narra-0.0.1/.gitignore +31 -0
- narra-0.0.1/CLAUDE.md +83 -0
- narra-0.0.1/LICENSE +21 -0
- narra-0.0.1/PKG-INFO +113 -0
- narra-0.0.1/README.md +69 -0
- narra-0.0.1/SPEC.md +301 -0
- narra-0.0.1/generate_podcast.py +168 -0
- narra-0.0.1/pyproject.toml +158 -0
- narra-0.0.1/src/narra/__init__.py +3 -0
- narra-0.0.1/src/narra/__main__.py +8 -0
- narra-0.0.1/src/narra/cli.py +189 -0
- narra-0.0.1/src/narra/config.py +231 -0
- narra-0.0.1/src/narra/core.py +162 -0
- narra-0.0.1/src/narra/formats.py +99 -0
- narra-0.0.1/src/narra/script.py +100 -0
- narra-0.0.1/src/narra/serve.py +50 -0
- narra-0.0.1/src/narra/serve_page.html +46 -0
- narra-0.0.1/src/narra/speakers.py +82 -0
- narra-0.0.1/src/narra/tts/__init__.py +49 -0
- narra-0.0.1/src/narra/tts/base.py +61 -0
- narra-0.0.1/src/narra/tts/edge.py +22 -0
- narra-0.0.1/src/narra/tts/gemini.py +25 -0
- narra-0.0.1/src/narra/tts/kokoro.py +22 -0
- narra-0.0.1/src/narra/tts/openai_compat.py +24 -0
- narra-0.0.1/src/narra/tts/piper.py +23 -0
- narra-0.0.1/src/narra/writers/__init__.py +43 -0
- narra-0.0.1/src/narra/writers/base.py +63 -0
- narra-0.0.1/src/narra/writers/gemini.py +25 -0
- narra-0.0.1/src/narra/writers/ollama.py +22 -0
- narra-0.0.1/src/narra/writers/openai_compatible.py +24 -0
- narra-0.0.1/tests/test_narra.py +126 -0
- narra-0.0.1/uv.lock +3798 -0
narra-0.0.1/.gitignore
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.venv/
|
|
6
|
+
build/
|
|
7
|
+
dist/
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
.ruff_cache/
|
|
10
|
+
.coverage
|
|
11
|
+
htmlcov/
|
|
12
|
+
|
|
13
|
+
# AppleDouble files on exFAT
|
|
14
|
+
._*
|
|
15
|
+
|
|
16
|
+
# Local config and output
|
|
17
|
+
narra.yaml
|
|
18
|
+
.narra.yaml
|
|
19
|
+
podcasts/
|
|
20
|
+
output/
|
|
21
|
+
*.mp3.tmp
|
|
22
|
+
|
|
23
|
+
# Tauri / Rust
|
|
24
|
+
desktop/src-tauri/target/
|
|
25
|
+
desktop/src-tauri/gen/
|
|
26
|
+
|
|
27
|
+
# OS
|
|
28
|
+
.DS_Store
|
|
29
|
+
|
|
30
|
+
# Node (Tauri CLI)
|
|
31
|
+
node_modules/
|
narra-0.0.1/CLAUDE.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Narra — agent handover
|
|
2
|
+
|
|
3
|
+
`SPEC.md` is the source of truth. This file is the short working note.
|
|
4
|
+
|
|
5
|
+
## What it is
|
|
6
|
+
|
|
7
|
+
A privacy-first **source → podcast episode** tool. Point it at a PDF or text
|
|
8
|
+
file, choose a format (deep-dive, brief, critique, debate, or a custom
|
|
9
|
+
briefing), a *writer* (the LLM that writes the script) and a *voice* (TTS, one
|
|
10
|
+
per speaker). Get an MP3. Same shape as Limn and Canturía: Python core + Typer
|
|
11
|
+
CLI + FastAPI single page + Tauri v2 shell. PyPI package and CLI: `narra`.
|
|
12
|
+
|
|
13
|
+
Two provider abstractions, chosen independently:
|
|
14
|
+
- **writer** — `gemini` (default), `openai-compatible` (BYOK), `ollama` (local)
|
|
15
|
+
- **voice** — `edge` (default, free), `openai` / `openai-compatible`
|
|
16
|
+
(`/v1/audio/speech`), `gemini` (native), `piper` (local CPU), `kokoro`
|
|
17
|
+
(local CPU / Speaches)
|
|
18
|
+
|
|
19
|
+
## Status (0.0.1 — skeleton)
|
|
20
|
+
|
|
21
|
+
- Package frame only: installs, imports, `narra --version` / `narra --help` /
|
|
22
|
+
`narra init-config` work.
|
|
23
|
+
- `config.py` (layered, `${VAR}`), `formats.py`, `speakers.py`, `script.py`
|
|
24
|
+
(read_source only) are real.
|
|
25
|
+
- Every writer, every voice, `core.generate()`, and `serve` are **stubs** that
|
|
26
|
+
raise `NotImplementedError` with a TODO.
|
|
27
|
+
- No infographic / show-notes card — that is a separate tool.
|
|
28
|
+
- Next: M1 (see SPEC §10).
|
|
29
|
+
|
|
30
|
+
## Local commands
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/narra" # repo is on exFAT
|
|
34
|
+
uv sync --all-groups
|
|
35
|
+
uv run --no-sync ruff check src tests
|
|
36
|
+
uv run --no-sync basedpyright
|
|
37
|
+
uv run --no-sync pytest
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Publish (skeleton → PyPI)
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
uv build
|
|
44
|
+
twine upload dist/narra-0.0.1* # uses ~/.pypirc
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
CI `publish.yml` also builds on `v*` tags via `pypa/gh-action-pypi-publish`, but
|
|
48
|
+
it needs a `PYPI_API_TOKEN` repo secret; the manual twine path is the reliable
|
|
49
|
+
one until that secret is set.
|
|
50
|
+
|
|
51
|
+
## Machine gotchas
|
|
52
|
+
|
|
53
|
+
- The repo is on an exFAT drive. Keep the venv on the internal disk via
|
|
54
|
+
`UV_PROJECT_ENVIRONMENT`; macOS writes AppleDouble `._*` files that break
|
|
55
|
+
`uv sync` otherwise. `.gitignore` and the build exclude `._*`.
|
|
56
|
+
- Source material lives in `../` siblings: `generate_podcast.py` (this folder,
|
|
57
|
+
truncated at the Gemini TTS branch) and `~/Downloads/generate_notebook.py`
|
|
58
|
+
(the complete original it was split from — use it to reconstruct the Gemini
|
|
59
|
+
voice path).
|
|
60
|
+
|
|
61
|
+
## Decisions
|
|
62
|
+
|
|
63
|
+
- Two providers (writer + voice), like Canturía's lyricist + ACE-Step split.
|
|
64
|
+
- Ship edge as the free default voice; Gemini writer as the default writer to
|
|
65
|
+
match the original script's behaviour.
|
|
66
|
+
- Formats are a registry, not hardcoded; the four shipped presets came from the
|
|
67
|
+
original `STYLE_PROMPTS`.
|
|
68
|
+
- 1–N speakers with per-speaker voice override (open-notebook idea); Alex/Sam
|
|
69
|
+
are the two defaults.
|
|
70
|
+
- Default serve port 5372 ("NARR").
|
|
71
|
+
- Attribution retained for GroqCasters (J. Gravelle, MIT) and Open Notebook
|
|
72
|
+
(MIT) — see SPEC §8.
|
|
73
|
+
- Build order: skeleton → M1 CLI/web → M2 → M3 local voices → M4 desktop.
|
|
74
|
+
|
|
75
|
+
## Reference
|
|
76
|
+
|
|
77
|
+
- Original script: `generate_podcast.py` (this dir) and the complete
|
|
78
|
+
`~/Downloads/generate_notebook.py`.
|
|
79
|
+
- Pattern siblings: `../limn` (providers, serve, Tauri), `../song-gen`
|
|
80
|
+
(canturía — lyricists, serve, pyproject, workflows), `../talk-buddy`
|
|
81
|
+
(Piper bridge, sha256 model install).
|
|
82
|
+
- External ideas: https://github.com/jgravelle/GroqCasters,
|
|
83
|
+
https://github.com/lfnovo/open-notebook.
|
narra-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Michael Borck
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
narra-0.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: narra
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: A small, privacy-first source-to-podcast tool: a PDF or text file in, a multi-speaker episode out. Bring your own writer and voice.
|
|
5
|
+
Project-URL: Homepage, https://github.com/michael-borck/narra
|
|
6
|
+
Project-URL: Repository, https://github.com/michael-borck/narra
|
|
7
|
+
Project-URL: Issues, https://github.com/michael-borck/narra/issues
|
|
8
|
+
Author-email: Michael Borck <michael.borck@curtin.edu.au>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ai,audio,cli,notebooklm,podcast,text-to-speech,tts
|
|
12
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: pydantic>=2.0.0
|
|
26
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
27
|
+
Requires-Dist: requests>=2.31.0
|
|
28
|
+
Requires-Dist: rich>=13.0.0
|
|
29
|
+
Requires-Dist: typer>=0.9.0
|
|
30
|
+
Provides-Extra: audio
|
|
31
|
+
Requires-Dist: pydub>=0.25.1; extra == 'audio'
|
|
32
|
+
Provides-Extra: edge
|
|
33
|
+
Requires-Dist: edge-tts>=6.1.0; extra == 'edge'
|
|
34
|
+
Provides-Extra: gemini
|
|
35
|
+
Requires-Dist: google-genai>=0.3.0; extra == 'gemini'
|
|
36
|
+
Provides-Extra: local
|
|
37
|
+
Requires-Dist: kokoro-onnx>=0.4.0; extra == 'local'
|
|
38
|
+
Requires-Dist: numpy>=1.24.0; extra == 'local'
|
|
39
|
+
Requires-Dist: piper-tts>=1.2.0; extra == 'local'
|
|
40
|
+
Provides-Extra: serve
|
|
41
|
+
Requires-Dist: fastapi>=0.110.0; extra == 'serve'
|
|
42
|
+
Requires-Dist: uvicorn>=0.29.0; extra == 'serve'
|
|
43
|
+
Description-Content-Type: text/markdown
|
|
44
|
+
|
|
45
|
+
# Narra — tell it into a podcast
|
|
46
|
+
|
|
47
|
+
> *narra (Spanish): "tell!" / "narrate!"*
|
|
48
|
+
|
|
49
|
+
A small, privacy-first tool that turns a source document into a two (or more)
|
|
50
|
+
speaker podcast episode. Give it a PDF or text file, pick a format, choose who
|
|
51
|
+
writes the script and which voices speak it, and get an MP3. No account, no
|
|
52
|
+
telemetry, bring your own providers.
|
|
53
|
+
|
|
54
|
+
## Install
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install "narra[edge,audio]" # core + free edge-tts voice + pydub
|
|
58
|
+
export GEMINI_API_KEY=... # default writer
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Use
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
narra "paper.pdf" --format deep-dive --out episode.mp3
|
|
65
|
+
narra "notes.txt" --format brief --voice edge
|
|
66
|
+
narra init-config # write an example narra.yaml
|
|
67
|
+
narra serve # local web UI (pip install "narra[serve]")
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Or as a library:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from narra.config import load_config
|
|
74
|
+
from narra import core
|
|
75
|
+
|
|
76
|
+
settings = load_config()
|
|
77
|
+
episode = core.generate("paper.pdf", settings, format="deep-dive")
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Providers
|
|
81
|
+
|
|
82
|
+
- **Writer** (writes the script): `gemini` (default), `openai-compatible` (BYOK,
|
|
83
|
+
any `/v1/chat/completions`), `ollama` (local).
|
|
84
|
+
- **Voice** (speaks each line): `edge` (free, default), `openai` /
|
|
85
|
+
`openai-compatible` (OpenAI standard `/v1/audio/speech`), `gemini` (native
|
|
86
|
+
TTS), `piper` (local CPU), `kokoro` (local CPU).
|
|
87
|
+
|
|
88
|
+
Keys live in `~/.narra.yaml` (or `${VAR}` references), never in the browser.
|
|
89
|
+
|
|
90
|
+
## Status
|
|
91
|
+
|
|
92
|
+
**0.0.1 — skeleton.** The package installs, imports, and `narra --version` works;
|
|
93
|
+
providers and `narra generate` are stubbed and raise "not implemented yet". See
|
|
94
|
+
`SPEC.md` for the full design and milestones.
|
|
95
|
+
|
|
96
|
+
## Privacy
|
|
97
|
+
|
|
98
|
+
No account. No telemetry. The only network egress is the request to the writer
|
|
99
|
+
and voice providers you configure. Piper and Kokoro run locally; Ollama is
|
|
100
|
+
local. Audio saves to `~/Podcasts/Narra` with a JSON sidecar.
|
|
101
|
+
|
|
102
|
+
## Credits
|
|
103
|
+
|
|
104
|
+
Narra borrows ideas, with acknowledgment, from
|
|
105
|
+
[GroqCasters](https://github.com/jgravelle/GroqCasters) (J. Gravelle, MIT),
|
|
106
|
+
[Open Notebook](https://github.com/lfnovo/open-notebook) (MIT), and the author's
|
|
107
|
+
own [limn](https://github.com/michael-borck/limn),
|
|
108
|
+
[canturía](https://github.com/michael-borck/canturia), and
|
|
109
|
+
[talk-buddy](https://github.com/michael-borck/talk-buddy).
|
|
110
|
+
|
|
111
|
+
## Licence
|
|
112
|
+
|
|
113
|
+
MIT © Michael Borck.
|
narra-0.0.1/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Narra — tell it into a podcast
|
|
2
|
+
|
|
3
|
+
> *narra (Spanish): "tell!" / "narrate!"*
|
|
4
|
+
|
|
5
|
+
A small, privacy-first tool that turns a source document into a two (or more)
|
|
6
|
+
speaker podcast episode. Give it a PDF or text file, pick a format, choose who
|
|
7
|
+
writes the script and which voices speak it, and get an MP3. No account, no
|
|
8
|
+
telemetry, bring your own providers.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install "narra[edge,audio]" # core + free edge-tts voice + pydub
|
|
14
|
+
export GEMINI_API_KEY=... # default writer
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Use
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
narra "paper.pdf" --format deep-dive --out episode.mp3
|
|
21
|
+
narra "notes.txt" --format brief --voice edge
|
|
22
|
+
narra init-config # write an example narra.yaml
|
|
23
|
+
narra serve # local web UI (pip install "narra[serve]")
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Or as a library:
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from narra.config import load_config
|
|
30
|
+
from narra import core
|
|
31
|
+
|
|
32
|
+
settings = load_config()
|
|
33
|
+
episode = core.generate("paper.pdf", settings, format="deep-dive")
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Providers
|
|
37
|
+
|
|
38
|
+
- **Writer** (writes the script): `gemini` (default), `openai-compatible` (BYOK,
|
|
39
|
+
any `/v1/chat/completions`), `ollama` (local).
|
|
40
|
+
- **Voice** (speaks each line): `edge` (free, default), `openai` /
|
|
41
|
+
`openai-compatible` (OpenAI standard `/v1/audio/speech`), `gemini` (native
|
|
42
|
+
TTS), `piper` (local CPU), `kokoro` (local CPU).
|
|
43
|
+
|
|
44
|
+
Keys live in `~/.narra.yaml` (or `${VAR}` references), never in the browser.
|
|
45
|
+
|
|
46
|
+
## Status
|
|
47
|
+
|
|
48
|
+
**0.0.1 — skeleton.** The package installs, imports, and `narra --version` works;
|
|
49
|
+
providers and `narra generate` are stubbed and raise "not implemented yet". See
|
|
50
|
+
`SPEC.md` for the full design and milestones.
|
|
51
|
+
|
|
52
|
+
## Privacy
|
|
53
|
+
|
|
54
|
+
No account. No telemetry. The only network egress is the request to the writer
|
|
55
|
+
and voice providers you configure. Piper and Kokoro run locally; Ollama is
|
|
56
|
+
local. Audio saves to `~/Podcasts/Narra` with a JSON sidecar.
|
|
57
|
+
|
|
58
|
+
## Credits
|
|
59
|
+
|
|
60
|
+
Narra borrows ideas, with acknowledgment, from
|
|
61
|
+
[GroqCasters](https://github.com/jgravelle/GroqCasters) (J. Gravelle, MIT),
|
|
62
|
+
[Open Notebook](https://github.com/lfnovo/open-notebook) (MIT), and the author's
|
|
63
|
+
own [limn](https://github.com/michael-borck/limn),
|
|
64
|
+
[canturía](https://github.com/michael-borck/canturia), and
|
|
65
|
+
[talk-buddy](https://github.com/michael-borck/talk-buddy).
|
|
66
|
+
|
|
67
|
+
## Licence
|
|
68
|
+
|
|
69
|
+
MIT © Michael Borck.
|
narra-0.0.1/SPEC.md
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
# Narra — specification
|
|
2
|
+
|
|
3
|
+
> *narra (Spanish): "tell!" / "narrate!" — the second-person command to tell a story.*
|
|
4
|
+
|
|
5
|
+
A small, privacy-first tool that turns a source document into a two (or more)
|
|
6
|
+
speaker podcast episode. Give it a PDF or text file, pick a format, choose who
|
|
7
|
+
writes the script and which voices speak it, and get an MP3. No account, no
|
|
8
|
+
telemetry, bring your own providers.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. Vision
|
|
13
|
+
|
|
14
|
+
Most "NotebookLM-style" audio tools are a single locked-in web service (an
|
|
15
|
+
account, your documents on their servers) or a heavy research platform
|
|
16
|
+
(notebooks, embeddings, chat, Docker). **Narra sits deliberately in between:**
|
|
17
|
+
the simplest possible "source → podcast episode" surface that you own.
|
|
18
|
+
|
|
19
|
+
- **Give it a source → get an episode.** That's the whole interaction.
|
|
20
|
+
- **No account, no lock-in, privacy by default.** Your documents and audio are
|
|
21
|
+
yours. On the desktop nothing leaves your machine except the request to the
|
|
22
|
+
writer and voice providers *you* configure.
|
|
23
|
+
- **Bring your own providers.** A *writer* (an LLM that turns source text into a
|
|
24
|
+
script) and a *voice* (text-to-speech), each configured independently. Use a
|
|
25
|
+
cloud key, an OpenAI-compatible endpoint, or a local CPU model.
|
|
26
|
+
- **Minimal by design.** Format, speakers, and one Generate button. Advanced
|
|
27
|
+
knobs live in the providers and the config, not in the main flow.
|
|
28
|
+
|
|
29
|
+
## 2. Principles
|
|
30
|
+
|
|
31
|
+
1. **Simple beats powerful.** One source in, one episode out. Advanced options
|
|
32
|
+
stay in config.
|
|
33
|
+
2. **Local-first & private.** No account, no telemetry, no server-side storage
|
|
34
|
+
of sources or audio. The web UI keeps its session gallery in memory; nothing
|
|
35
|
+
is written to disk unless you press Save.
|
|
36
|
+
3. **Provider-shaped, not provider-locked.** The core does not depend on any one
|
|
37
|
+
writer or voice. Writers and voices are thin modules behind one interface.
|
|
38
|
+
4. **Progressive surfaces.** The same core powers a CLI, a web UI, and a desktop
|
|
39
|
+
app. Each is optional.
|
|
40
|
+
5. **Fail visibly.** A provider error stops the run with a clear message; no
|
|
41
|
+
silent fallback to a different provider.
|
|
42
|
+
|
|
43
|
+
## 3. Surfaces
|
|
44
|
+
|
|
45
|
+
### v1 — CLI
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
narra "paper.pdf" --format deep-dive --out episode.mp3
|
|
49
|
+
narra "notes.txt" --format brief --writer openai-compatible --voice edge
|
|
50
|
+
narra init-config # write an example narra.yaml
|
|
51
|
+
narra compare "paper.pdf" --voice edge --voice gemini # A/B two voices
|
|
52
|
+
narra serve # local web UI
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Options: `--format`, `--writer`, `--voice`, `--speakers`, `--out`, `--out-dir`,
|
|
56
|
+
`--config`, `--base-url`, `--api-key`, `--model`, `--voice-model`, `--timeout`.
|
|
57
|
+
|
|
58
|
+
### v2 — Web UI (`narra serve`)
|
|
59
|
+
|
|
60
|
+
A single page (FastAPI + a self-contained HTML page, no CDNs):
|
|
61
|
+
|
|
62
|
+
- A **source** box (paste text or pick a file).
|
|
63
|
+
- A **format** selector: your shipped presets as chips, plus a custom briefing.
|
|
64
|
+
- A **speaker strip**: 1–N speakers, each with a name, a persona, and a voice
|
|
65
|
+
picked from any configured voice provider.
|
|
66
|
+
- **Generate** → a pending card (writing script, then voicing lines) → an audio
|
|
67
|
+
card with a player.
|
|
68
|
+
- **Preview script** before committing audio: edit the lines, then **Speak
|
|
69
|
+
this script**.
|
|
70
|
+
- In-memory session gallery (capped) with **Save / Download / Again / Delete**.
|
|
71
|
+
- A **Help** sheet: what each format does, where the script comes from, BYOK,
|
|
72
|
+
local voices, and where files are saved.
|
|
73
|
+
|
|
74
|
+
Binds `127.0.0.1` by default; an optional shared password gates hosted
|
|
75
|
+
instances. Keys live in config, never in the browser.
|
|
76
|
+
|
|
77
|
+
### v3 — Desktop (Tauri v2 + Python sidecar)
|
|
78
|
+
|
|
79
|
+
A native, installable app. Tauri v2 uses the OS webview. On first launch it
|
|
80
|
+
bootstraps a private runtime with `uv`, creates a venv in the app-data
|
|
81
|
+
directory, installs `narra[serve]==<pin>`, runs `narra serve` on a random
|
|
82
|
+
localhost port, and shows the served UI. A Settings sheet reads/writes
|
|
83
|
+
`~/.narra.yaml` (merge-preserving, chmod 600) — the same file the CLI uses.
|
|
84
|
+
Saves land in `~/Podcasts/Narra`. Distributed as a signed installer; not on the
|
|
85
|
+
Mac App Store (runtime-download rules).
|
|
86
|
+
|
|
87
|
+
### Demo — "try before install" (later)
|
|
88
|
+
|
|
89
|
+
A hosted instance that is rate-limited and non-storing: generate a couple of
|
|
90
|
+
episodes, nothing saved server-side, with a banner inviting users to install
|
|
91
|
+
locally for full control and privacy.
|
|
92
|
+
|
|
93
|
+
## 4. The pipeline
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
source (pdf/txt)
|
|
97
|
+
│ read_source()
|
|
98
|
+
▼
|
|
99
|
+
writer (LLM) ──► script: [DialogueLine] (outline → expand → dialogue)
|
|
100
|
+
│
|
|
101
|
+
▼
|
|
102
|
+
speakers: each line assigned a speaker → a voice from a voice provider
|
|
103
|
+
│
|
|
104
|
+
▼
|
|
105
|
+
voices (TTS) ──► per-line audio ──► concatenate (pauses) ──► episode.mp3
|
|
106
|
+
│
|
|
107
|
+
▼
|
|
108
|
+
save + <episode>.json sidecar
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Formats (writer styles)
|
|
112
|
+
|
|
113
|
+
`formats.py` is a registry mapping a format key to a prompt fragment. Shipped:
|
|
114
|
+
|
|
115
|
+
| Key | Shape |
|
|
116
|
+
|---|---|
|
|
117
|
+
| `deep-dive` | 18–24 lines, two hosts (Alex storyteller, Sam skeptic) |
|
|
118
|
+
| `brief` | 6–8 short lines, single host (Alex), under 90 s |
|
|
119
|
+
| `critique` | 16–20 lines, candid domain reviewers (Alex + Sam) |
|
|
120
|
+
| `debate` | 18–22 lines, optimistic pro vs tough skeptic |
|
|
121
|
+
|
|
122
|
+
A format may also be a **custom briefing** (free text) for open-notebook-style
|
|
123
|
+
"episode profiles". Writer rules are appended to every format: cold open (no
|
|
124
|
+
"welcome back"), cite concrete facts, avoid AI clichés, no stage directions.
|
|
125
|
+
|
|
126
|
+
### Writers (write the script)
|
|
127
|
+
|
|
128
|
+
| Name | What | Auth |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| `gemini` | Google Gemini (`google-genai`), default `gemini-3.5-flash` | `GEMINI_API_KEY` |
|
|
131
|
+
| `openai-compatible` | Any `/v1/chat/completions`: OpenAI, LM Studio, llama.cpp, OpenRouter | Bearer key (optional locally) |
|
|
132
|
+
| `ollama` | Local Ollama chat model | none |
|
|
133
|
+
|
|
134
|
+
The writer receives the source text plus the format and returns structured
|
|
135
|
+
`[DialogueLine]`. Gemini uses a typed schema; the OpenAI-compatible writer asks
|
|
136
|
+
for JSON and validates.
|
|
137
|
+
|
|
138
|
+
### Voices (speak each line)
|
|
139
|
+
|
|
140
|
+
`tts/` exposes one interface, `synthesize(text, voice, opts) -> audio bytes`.
|
|
141
|
+
Shipped:
|
|
142
|
+
|
|
143
|
+
| Name | What | Auth / notes |
|
|
144
|
+
|---|---|---|
|
|
145
|
+
| `edge` | edge-tts neural voices, free | none (default) |
|
|
146
|
+
| `openai` / `openai-compatible` | OpenAI standard `POST {base}/audio/speech` (`model`, `input`, `voice`, `response_format`, `speed`) | Bearer key (optional for local Speaches/LocalAI) |
|
|
147
|
+
| `gemini` | Gemini native TTS (single- or multi-speaker), 24 kHz PCM | `GEMINI_API_KEY` |
|
|
148
|
+
| `piper` | Local CPU, tiny ONNX voices, ~0.05× realtime | sha256-verified first-run download |
|
|
149
|
+
| `kokoro` | Local CPU via `kokoro-onnx` (~120 MB), or a Speaches server | local or server URL |
|
|
150
|
+
|
|
151
|
+
Two concatenation strategies must be supported: **per-line** (edge, piper,
|
|
152
|
+
kokoro, openai-compatible — synthesize each line, stitch with 180–420 ms pauses)
|
|
153
|
+
and **single-call** (gemini native multi-speaker — one request returns the whole
|
|
154
|
+
dialogue).
|
|
155
|
+
|
|
156
|
+
### Speakers
|
|
157
|
+
|
|
158
|
+
A `Speaker` has a `name`, an optional `persona` (fed to the writer), and a
|
|
159
|
+
`voice` reference `{provider, voice_id, model}`. Two defaults ship: **Alex**
|
|
160
|
+
(male) and **Sam** (female). A format that is single-host uses Alex only. The
|
|
161
|
+
web UI and config can define 1–N speakers; each may point at a *different* voice
|
|
162
|
+
provider (open-notebook's per-speaker override).
|
|
163
|
+
|
|
164
|
+
## 5. Config
|
|
165
|
+
|
|
166
|
+
Layered, later wins (mirrors limn/canturía):
|
|
167
|
+
|
|
168
|
+
1. Built-in defaults.
|
|
169
|
+
2. `~/.narra.yaml` — your providers + keys, set once.
|
|
170
|
+
3. `./narra.yaml` (or `--config FILE`).
|
|
171
|
+
4. CLI flags / environment.
|
|
172
|
+
|
|
173
|
+
```yaml
|
|
174
|
+
writer: gemini # gemini | openai-compatible | ollama
|
|
175
|
+
voice: edge # edge | openai-compatible | gemini | piper | kokoro
|
|
176
|
+
format: deep-dive
|
|
177
|
+
|
|
178
|
+
writers:
|
|
179
|
+
gemini:
|
|
180
|
+
model: gemini-3.5-flash
|
|
181
|
+
api_key: "${GEMINI_API_KEY}"
|
|
182
|
+
openai-compatible:
|
|
183
|
+
base_url: https://api.openai.com/v1
|
|
184
|
+
model: gpt-4o-mini
|
|
185
|
+
api_key: "${OPENAI_API_KEY}"
|
|
186
|
+
ollama:
|
|
187
|
+
base_url: http://127.0.0.1:11434
|
|
188
|
+
model: qwen3.5:4b
|
|
189
|
+
|
|
190
|
+
voices:
|
|
191
|
+
edge: {}
|
|
192
|
+
openai-compatible:
|
|
193
|
+
base_url: https://api.openai.com/v1
|
|
194
|
+
model: gpt-4o-mini-tts
|
|
195
|
+
api_key: "${OPENAI_API_KEY}"
|
|
196
|
+
gemini:
|
|
197
|
+
model: gemini-3.8-flash-tts
|
|
198
|
+
api_key: "${GEMINI_API_KEY}"
|
|
199
|
+
piper:
|
|
200
|
+
voice: en_GB-alan-low
|
|
201
|
+
kokoro:
|
|
202
|
+
voice: bm_george
|
|
203
|
+
|
|
204
|
+
speakers:
|
|
205
|
+
- name: Alex
|
|
206
|
+
persona: Storyteller who sees the big picture.
|
|
207
|
+
voice: { provider: edge, voice_id: en-US-AndrewNeural }
|
|
208
|
+
- name: Sam
|
|
209
|
+
persona: Curious skeptic who asks sharp follow-ups.
|
|
210
|
+
voice: { provider: edge, voice_id: en-US-AvaNeural }
|
|
211
|
+
|
|
212
|
+
serve:
|
|
213
|
+
host: 127.0.0.1
|
|
214
|
+
port: 5372
|
|
215
|
+
password: "${NARRA_SERVE_PASSWORD}"
|
|
216
|
+
out_dir: ~/Podcasts/Narra
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Secrets are referenced as `${VAR}` so no plaintext keys live in files. Default
|
|
220
|
+
serve port **5372** ("NARR" on a phone keypad).
|
|
221
|
+
|
|
222
|
+
## 6. Architecture
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
narra/
|
|
226
|
+
config.py layered config + ${VAR} expansion
|
|
227
|
+
formats.py format registry + writer rules
|
|
228
|
+
speakers.py Speaker dataclass, defaults, voice refs
|
|
229
|
+
writers/
|
|
230
|
+
base.py Writer ABC, ScriptRequest/ScriptResult
|
|
231
|
+
gemini.py openai_compatible.py ollama.py
|
|
232
|
+
tts/
|
|
233
|
+
base.py VoiceProvider ABC, SpeakRequest
|
|
234
|
+
edge.py openai_compat.py gemini.py piper.py kokoro.py
|
|
235
|
+
script.py read_source(), outline→dialogue, text cleanup
|
|
236
|
+
core.py generate(): script → per-line audio → episode + sidecar
|
|
237
|
+
cli.py Typer CLI
|
|
238
|
+
serve.py FastAPI app factory [serve extra]
|
|
239
|
+
serve_page.html self-contained web UI (package data)
|
|
240
|
+
desktop/ Tauri v2 shell + uv-bootstrapped sidecar
|
|
241
|
+
tests/
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- **Python 3.10+**, `typer`, `rich`, `requests`, `pyyaml`, `pydantic`.
|
|
245
|
+
- **Extras:** `audio=[pydub]`, `edge=[edge-tts]`, `gemini=[google-genai]`,
|
|
246
|
+
`local=[piper-tts, kokoro-onnx, numpy]`, `serve=[fastapi, uvicorn]`.
|
|
247
|
+
- **Packaging:** hatchling; `pip install narra`, publish to PyPI.
|
|
248
|
+
|
|
249
|
+
## 7. Privacy and storage
|
|
250
|
+
|
|
251
|
+
- No account, no telemetry, no logging of sources or scripts.
|
|
252
|
+
- The only egress is the request to the writer and voice providers you
|
|
253
|
+
configure. Piper and Kokoro run locally; Ollama is local.
|
|
254
|
+
- The web session gallery is in memory, capped, and dies with the process.
|
|
255
|
+
- Save writes the audio plus a `<episode>.json` sidecar (writer, voice,
|
|
256
|
+
format, source hash, settings) into `~/Podcasts/Narra` (configurable). Save
|
|
257
|
+
never overwrites.
|
|
258
|
+
- Keys are never exposed to the browser.
|
|
259
|
+
|
|
260
|
+
## 8. Attribution
|
|
261
|
+
|
|
262
|
+
Narra borrows ideas, with acknowledgment, from:
|
|
263
|
+
|
|
264
|
+
- **GroqCasters** by J. Gravelle (MIT) — the outline → expand → dialogue
|
|
265
|
+
pipeline, host personas, and voice cloning from a short sample. © J. Gravelle;
|
|
266
|
+
a mention is retained per the licence.
|
|
267
|
+
- **Open Notebook** by lfnovo and contributors (MIT) — episode profiles,
|
|
268
|
+
per-speaker voice-model overrides, the "what each model sees" privacy framing,
|
|
269
|
+
and background-job retry.
|
|
270
|
+
- The author's own **limn**, **canturía**, and **talk-buddy** — the
|
|
271
|
+
provider/config/serve architecture, the `compare` workflow, and the
|
|
272
|
+
sha256-verified first-run model download for Piper.
|
|
273
|
+
|
|
274
|
+
## 9. Non-goals
|
|
275
|
+
|
|
276
|
+
- Not a research notebook, chat, or embeddings tool. Narra makes one thing:
|
|
277
|
+
an episode from a source.
|
|
278
|
+
- Not a DAW or audio editor.
|
|
279
|
+
- Not a model host — Narra calls the providers you point it at.
|
|
280
|
+
- No infographic / show-notes card in v1 (a separate tool handles that).
|
|
281
|
+
|
|
282
|
+
## 10. Milestones
|
|
283
|
+
|
|
284
|
+
1. **M1 — Core + CLI.** `narra "source" --format ... --out ...`; Gemini writer +
|
|
285
|
+
OpenAI-compatible writer; edge + OpenAI-compatible voices; layered config;
|
|
286
|
+
PyPI publish.
|
|
287
|
+
2. **M2 — Web UI.** `narra serve` with source box, format chips, speaker strip,
|
|
288
|
+
preview/edit script, session gallery with Save/Download/Again/Delete, password
|
|
289
|
+
gate, Help sheet.
|
|
290
|
+
3. **M3 — Local + BYOK voices.** Piper + Kokoro (CPU) with sha256 model
|
|
291
|
+
download, Gemini native TTS (single + multi-speaker), per-speaker voice
|
|
292
|
+
override, `narra compare` voices.
|
|
293
|
+
4. **M4 — Desktop + landing.** Tauri shell, first-run uv runtime, Settings
|
|
294
|
+
sheet, CI installers, demo mode, landing page.
|
|
295
|
+
|
|
296
|
+
## 11. Skeleton (0.0.1)
|
|
297
|
+
|
|
298
|
+
The first PyPI upload is a frame, not a product: it installs, imports,
|
|
299
|
+
`narra --version` and `narra init-config` work, and every provider plus
|
|
300
|
+
`generate()` raise a clear "not implemented yet" error. This exists so the
|
|
301
|
+
package name, repo, CI, and packaging are proven before M1 fills the modules.
|