Metadata-Version: 2.4
Name: navig-audio
Version: 0.5.1
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.4.0
Requires-Dist: navig-media-core>=0.2.0
Requires-Dist: navig-vault>=0.7.0
Requires-Dist: edge-tts>=7.3.1
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: numpy>=1.24.0
Requires-Dist: num2words>=0.5.13
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Provides-Extra: master
Requires-Dist: matchering>=2.0; extra == "master"
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.5.1 · [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 ambience` | 🌧 Rain, static or city weather under a cut — deterministic, seeded by kind. |
| `navig audio beat analyse` | 🔍 What is this beat — tempo, key, structure, spectrum, and a style brief derived from them. |
| `navig audio beat demo` | 🎤 A 30-second guide-vocal demo: the hook spoken in character voices on its bars. GUIDE ONLY. |
| `navig audio beat fit` | 📏 Does a lyric sit on the beat? (alias of `navig text lyrics fit`) |
| `navig audio beat gen` | 🎛  Render beats from a style — bar-exact sections, no vocals, tempo and key checked afterwards. |
| `navig audio beat grid` | 📐 Beat times for a bed — the grid a cut lands on, cached per (file, offset, length). |
| `navig audio beat layer` | 🎚  Layer sound effects onto a beat — on bars, with fades. The dry beat is never touched. |
| `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 bed assign` | 🎼 (Re)use the episode's track — stable across renders, unique per episode. |
| `navig audio check` | Show whether AI audio generation is configured (a provider key resolves). |
| `navig audio clean-video` | 🎬 Clean the dialogue in a video and put it back in sync (picture copied untouched). |
| `navig audio clone` | 👤 Clone a voice from your own recordings and print its id. |
| `navig audio delivery` | 📡 Check loudness against a platform's delivery spec — and fix it to fit. |
| `navig audio draft` | 📝 Turn rough notes into a strict scenario you can review before rendering. |
| `navig audio dub` | 🌍 Dub into other languages — the same voices, the timing kept. |
| `navig audio enhance` | 🎛 Restore and master a recording — measured, explained, verified, never overwritten. |
| `navig audio enhance-presets` | 🎚 The enhancement presets (Preserve Original, Clean SFX, Studio Polish, …). |
| `navig audio gen` | Generate audio from a text prompt and save it locally. |
| `navig audio isolate` | 🎤 Strip background noise, keep the voice — the ElevenLabs voice isolator. |
| `navig audio loop` | 🌧 A seamless, loopable ambience bed at any length (rain, room tone, server room, …). |
| `navig audio loudness` | 📏 Integrated loudness (LUFS), loudness range and true peak — how a master is judged. |
| `navig audio master` | 🎚️ Mix a vocal over a beat and master it — a finished song at a measured loudness. |
| `navig audio match` | 🎚 Match a reference's tonal balance and loudness (dynamics kept unless asked). |
| `navig audio plan` | 🧮 What this episode will cost, before it costs it. Spends nothing. |
| `navig audio podcast-edit` | ✂️ Find fillers, long pauses and repeats — review the cut list, then apply it. |
| `navig audio publish` | 📤 Show exactly what would be uploaded to NobiCast. Uploads nothing yet. |
| `navig audio read` | 📖 Read a text aloud, like a book — numbered ten-minute parts, quiet and unhurried. |
| `navig audio regenerate` | 🧪 Make NEW audio from a recording with AI — new voice, variations, or a replaced stem. |
| `navig audio render` | 🎧 Build the episode — one mp3 per track, plus subtitles, transcript and a master. |
| `navig audio score` | 🎼 Compose music that follows the cuts of a video, mixed under its dialogue. |
| `navig audio similar` | 🔎 Find sounds that sound like this one — local fingerprints, cached. |
| `navig audio slowed` | 🐢 The "slowed" sound — pitch drops with the speed, plus optional reverb. |
| `navig audio songs card` | 🪪 Create or refresh a song card (README.md front matter + facts read from the folder). |
| `navig audio songs catalog` | 📚 Build the catalog from every song card under ROOT. |
| `navig audio songs check` | 🩺 Duplicate ids, unknown status, a recorded song with no audio. Exit 1 when anything is wrong. |
| `navig audio speed` | ⏩ Change speed, keeping pitch — a lecture at 1.5x still sounds like the speaker. |
| `navig audio spoken` | 🔢 Display text → the words a voice should actually speak (cases, ordinals, years). |
| `navig audio stems` | 🎛 Split a song into parts once, then mute / solo / re-balance them locally. |
| `navig audio translate` | 🌍 Translate the spoken lines, keeping the album structure identical. |
| `navig audio voice-line` | 🗣 One narration line with word timings — the kinetic renderer reads the same cache. |
| `navig audio voice-stats` | 📊 What the shared voice cache holds — counts, size, orphans, age. |
| `navig audio voices` | 🗣  List the voices this key can speak with — your clones first. |
| `navig voice budget` | Show or set the daily budget for paid read-aloud voices. |
| `navig voice list-voices` | List available voices for a provider. |
| `navig voice policy` | Show or set which voices read-aloud may use. |
| `navig voice speak` | Synthesize speech from text. |
| `navig voice transcribe` | Transcribe audio file to text. |
| `navig voice usage` | Paid read-aloud characters per day, against the daily budget. |

</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.

## Mixing and mastering

```
navig-audio loudness song.mp3 ref.mp3                       LUFS · loudness range · true peak
navig-audio master vocal.wav --beat beat.mp3                vocal over the beat, mastered (preset ritual, -9 LUFS)
navig-audio master vocal.wav --beat beat.mp3 --preset boom-bap --offset 4.2 --wav
navig-audio master vocal.wav --beat beat.mp3 --ref ref.mp3  match a reference track (pip install navig-audio[master])
navig-audio master vocal.wav --beat beat.mp3 --dry-run      the chain and the input loudness; writes nothing
```

The vocal is levelled, cleaned (low cut, light denoise), de-boxed (~280 Hz), compressed,
de-essed, given presence (~3 kHz), air and the preset's space. The beat makes room at
2–4 kHz, is set a preset number of LU under the **measured** processed vocal (`--balance`)
and ducks while the voice speaks (`--duck`). The mix is glued, then pushed to the loudness
target by gain + limiter and **measured** each round until it lands (±0.4 LU), and written as
mp3 320k (`--wav` adds 24-bit) with a sidecar JSON holding the graph and every number.

| Preset | For | LUFS | Vocal |
|---|---|---|---|
| `ritual` | dense rave / jungle / ritual hip-hop | −9 | close and dry, slapback + short plate |
| `boom-bap` | dusty boom bap | −10 | dry, up front, a small room |
| `collage` | sample-collage breakbeat | −10 | forward, a short plate |
| `clean` | demos, guides, podcasts | −14 | transparent |

## Enhancing a recording

```
navig audio enhance take.wav --analyze             what is measurably wrong; writes nothing
navig audio enhance take.wav                       Preserve Original: fix only measured defects
navig audio enhance take.wav --dry-run             the plan, step by step, with the reason for each
navig audio enhance take.wav --mode studio -f wav,flac -o D:\clean
navig audio enhance take.wav --preset audio-enhance/voice-restoration
navig audio enhance-presets                        the enhancement presets
```

Improves an existing recording without turning it into a different one. It **measures**
first (ffmpeg + numpy: clipping, DC offset, true peak, loudness, noise floor between events
and whether that noise is broadband or tonal, mains hum, clicks, edge silence, bandwidth,
stereo phase, every event's onset) and only then plans. **Preserve Original** (the default)
adds a step only when a measurement asks for it, so a clean file gets *"already clean —
nothing to fix"* and no output. **Studio** adds gentle tone, light compression where the
material suits it (never on a sound effect) and loudness for its category; **Cinematic** is
labelled creative; **Custom** takes every setting.

Every candidate is **verified against the original** before it is kept: same length,
sample-aligned (some ffmpeg denoisers delay their output 8–25 ms; that is measured and
compensated), every event still there and none invented, no pitch change, the tone of the
sound itself unchanged, no energy appearing in bands that were empty, no new clipping, peaks
under the ceiling. A failed candidate is retried without its riskiest step, then rejected;
the original is never written (it is hashed before and after). Outputs are
`<name>.enhanced.wav` (24-bit; `wav16`, `flac`, `mp3` on request) plus a `.enhance.json`
sidecar with the report, plan, filter graph, checks and the gain that loudness-matches the
A/B. A lossy source stays lossy-derived: exports never claim recovered detail.

**DeepFilterNet (optional, local).** Put `deep-filter.exe` (v0.5.6, from the DeepFilterNet
GitHub releases) in `~/.navig/bin/` — or point `NAVIG_DEEPFILTER` at it — and speech noise is
cleaned by that network instead of ffmpeg's denoiser. It runs on the CPU, filters rather than
generates, and its output goes through the same verification. `--set engine=local` keeps ffmpeg.

The ElevenLabs voice isolator can run first for **speech only**, and only with
`--allow-cloud` (it uploads the file; about $0.12/min). Nothing else leaves the machine.

## Making new versions with AI

```
navig audio regenerate take.wav --op voice --voice <voice-id> --allow-cloud
navig audio regenerate money.mp3 --op variations -d "heavier, 8-bit arcade" -n 3 --allow-cloud
navig audio regenerate song.mp3 --op replace --stem drums --with "lo-fi brushed kit" --allow-cloud
navig audio regenerate song.mp3 --op replace --stem vocals --voice <voice-id> --allow-cloud
navig audio regenerate money.mp3 --op variations --dry-run      what would be sent and billed
```

This is the opposite of `enhance`: it **generates new audio** (ElevenLabs) from the recording,
and says so on every output. `voice` keeps the words, timing and emotion in another voice;
`variations` sends only a text description (measured locally, or heard by an AI with
`--describe-with-ai`, which uploads the clip) plus your direction; `replace` splits the mix
into stems and changes one. Nothing runs without `--allow-cloud`; the original is never
written; each take gets a `.regen.json` with the prompt, provider and a closeness reading.

## Audio Lab

```
navig audio delivery mix.wav --target all                    every platform's loudness spec, pass/fail
navig audio delivery mix.wav --target spotify --fix          a levelled copy that fits
navig audio clean-video interview.mp4                        clean dialogue, picture untouched, in sync
navig audio match mix.wav --ref reference.mp3                tone + loudness like a reference
navig audio loop rain --seconds 600                          a seamless, loopable bed (local)
navig audio enhance tape.wav --preset audio-enhance/cassette also vinyl · phone-call · voice-memo
navig audio podcast-edit episode.mp3                         fillers, long pauses, repeats → a cut list
navig audio podcast-edit episode.cuts.json --apply           apply it after review
navig audio stems song.mp3 --allow-cloud                     split once (ElevenLabs) …
navig audio stems song.stems --preset karaoke                … remix locally as often as you like
navig audio similar door.wav --in D:/sfx                     find sounds that sound like this one
navig audio dub talk.mp4 --to fr --to es --allow-cloud       same voices, other languages, timing kept
navig audio score trailer.mp4 --style "dark synth" --allow-cloud   music that turns on the cuts
```

Local unless it says `--allow-cloud`. Podcast editing transcribes on this machine
(faster-whisper); sound-alike search fingerprints locally and caches per folder. Dubbing
uploads only the sound — a dubbed video keeps its picture bit for bit, with the original
sound as a second track. Score-to-picture sends only a music plan (no media). Dubs and
scores are labelled AI-generated in their `.json` sidecars.

## 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
navig-audio beat analyse beat.mp3 --bpm 76 --bars    the arrangement bar by bar: where the beat enters, drops out, ends
navig-audio beat fit lyrics.md --beat beat.mp3        does each line fit its bar? — alias of `navig text lyrics fit` (navig-text)
navig-audio beat layer beat.mp3 --sheet fx.yaml       sound effects on bars, with fades → beat-layered.mp3 (dry beat kept)
navig-audio beat demo beat.mp3 --sheet hook.yaml --voices voices.yaml   30 s guide vocal in pitched character voices
```

**The file, not the plan.** A generated beat does not always follow the sections it was asked
for. `--bars` measures one loudness value per bar (phase-aligned to the downbeat) and groups
the bars into `build / full / mid / drop / tail` blocks with their bar numbers and timecodes;
every `gen` stores that map in the sidecar. `layer` and `demo` place things on those measured
bars (`at_bar: 25`, `block: drop`, `block: full:2`), so an effect meant for the drop lands on
the drop the file actually has.

`fit` (an alias of `navig text lyrics fit` — install navig-text) counts syllables per line
(Russian by vowel, English/French by vowel group) against the time one bar gives — about 3.2–5.1 syllables a second — and says which lines to split, fill or
keep as a punch, and which tempo the text naturally wants. `--all DIR --report FIT.md` does a
whole library. `demo` speaks each hook line with a stock voice, shapes it per character
(`rubberband` pitch with `formant: keep|shift`, room/hall/grit/robot/radio/tape/double), ducks
the beat under it and cuts 30 s tagged `GUIDE — NOT FOR RELEASE`. Generated effects and speech
are cached (`.sfx/`, `.tts/` beside the beat) so a re-mix spends nothing.

`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.
