Metadata-Version: 2.4
Name: navig-audio
Version: 0.3.0
Summary: Speak text, transcribe audio, generate music and sound effects, analyse beats and render podcasts — its own navig-audio command, with your own provider keys; also `navig audio` / `navig voice` inside navig.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,audio,tts,stt,voice,transcription
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.14.0
Requires-Dist: navig-generate>=0.2.1
Requires-Dist: navig-vault>=0.7.0
Requires-Dist: edge-tts>=6.1.9
Requires-Dist: openai>=1.0.0
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# navig-audio

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Speak text, transcribe audio, generate music and sound effects, analyse beats and render podcasts — its own navig-audio command, with your own provider keys; also `navig audio` / `navig voice` inside navig.

**Works on its own** — its own CLI, no navig required · v0.3.0 · [PyPI](https://pypi.org/project/navig-audio/)

**On its own** (no navig needed)

```bash
pip install navig-audio
navig-audio --help   # no navig needed
```

**With navig**

```bash
pip install "navig[voice]"
navig audio --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig audio beat analyse` | 🔍 What is this beat — tempo, key, structure, spectrum, and a style brief derived from them. |
| `navig audio beat gen` | 🎛  Render beats from a style — bar-exact sections, no vocals, tempo and key checked afterwards. |
| `navig audio beat plan` | 🧮 The arrangement a render would use — section by section, in seconds. Spends nothing. |
| `navig audio beat styles` | 📚 The beat styles available — built-in genres plus any file you pass. |
| `navig audio check` | Show whether AI audio generation is configured (a provider key resolves). |
| `navig audio clone` | 👤 Clone a voice from your own recordings and print its id. |
| `navig audio draft` | 📝 Turn rough notes into a strict scenario you can review before rendering. |
| `navig audio gen` | Generate audio from a text prompt and save it locally. |
| `navig audio plan` | 🧮 What this episode will cost, before it costs it. Spends nothing. |
| `navig audio publish` | 📤 Show exactly what would be uploaded to NobiCast. Uploads nothing yet. |
| `navig audio render` | 🎧 Build the episode — one mp3 per track, plus subtitles, transcript and a master. |
| `navig audio slowed` | 🐢 The "slowed" sound — pitch drops with the speed, plus optional reverb. |
| `navig audio speed` | ⏩ Change speed, keeping pitch — a lecture at 1.5x still sounds like the speaker. |
| `navig audio translate` | 🌍 Translate the spoken lines, keeping the album structure identical. |
| `navig audio voices` | 🗣  List the voices this key can speak with — your clones first. |
| `navig voice list-voices` | List available voices for a provider. |
| `navig voice speak` | Synthesize speech from text. |
| `navig voice transcribe` | Transcribe audio file to text. |

</details>

<!-- navig:plugin-card:end -->

NAVIG **Audio**: speak text, transcribe audio, generate music and sound effects, make beats to
rap on and render podcast episodes, with **your own provider keys**. It runs on its own as
`navig-audio`, and inside navig as `navig audio` and `navig voice`.

## On its own

```bash
pip install navig-audio                        # adds the `navig-audio` command
navig-audio voice speak "hello" -o hello.mp3   # edge-tts works with no key at all
navig-audio voice transcribe interview.m4a     # local Whisper; or OPENAI_API_KEY / DEEPGRAM_API_KEY
export ELEVENLABS_API_KEY=…                    # music, sound effects, cloned voices
navig-audio gen "lo-fi rain loop" --kind music
navig-audio beat analyse ref.mp3               # tempo · key · structure · spectrum → a style brief
navig-audio speed lecture.mp3 --rate 1.5       # ffmpeg on PATH for edits and beats
navig-audio draft notes.md                     # podcast scenario from rough notes (needs an AI, below)
```

Keys come from the environment or the shared encrypted vault (`navig-vault`), the same vault
navig reads. `draft` and `translate` need an AI: navig's own when navig is installed, otherwise
any key navig-sdk finds (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `GROQ_API_KEY`,
`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`…), `NAVIG_AI_BASE_URL` for any OpenAI-compatible server,
or a local Ollama. With none, they say how to set one up and exit 1.

Beats and audio edits run on navig-generate's media engine, which is installed with this.

## Inside navig

The same commands are `navig audio …` and `navig voice speak|transcribe|list-voices`. navig
also uses these engines for Telegram voice notes, agent voice input and inbox transcription;
core's `navig.voice.*` modules re-export `navig_audio.voice.*`. The wake-word voice pipeline
runs inside navig's gateway and needs navig.

## Beats

```
navig-audio beat analyse ref.mp3 --card ref.md      tempo · key · structure · spectrum → a style brief
navig-audio beat styles [--styles house.yaml]       built-in genres + your own presets (a style may `extends:` another)
navig-audio beat plan --style boom-bap-dark --bpm 76   the arrangement in seconds — costs nothing
navig-audio beat gen  --style boom-bap-dark --bpm 76 --key Em -n 3 --out ./beats
```

`gen` renders from a **composition plan** whose sections are whole bars at the tempo you asked
for (`--structure intro:4,verse:16,hook:8,…`), always instrumental, and then **measures** each
file: the `.json` sidecar and the folder's `INDEX.md` carry target → measured tempo and key,
with an off-tempo render flagged `⚠`. `--dry-run` shows the exact request and sends nothing;
`--seed` makes a keeper re-renderable.
