navig-audio

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.6.0 · PyPI

On its own (no navig needed)

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

With navig

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

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

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 packs list                   # offline packs: fr/ru/en Piper voices, size + license
navig-audio voice packs install en_US-ljspeech-medium   # download + SHA-256 verify (~67 MB)
navig-audio voice speak "hello" -p local       # sherpa-onnx on-device (pip install "navig-audio[local-tts]")
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.

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.