Who nava is for#
Python developers adding audio alerts to CLI tools
Nava lets a CLI tool emit a sound on completion, error, or user prompt with two lines of Python and no new system dependencies. A script finishing a long batch job can play a WAV on any developer machine without requiring the developer to install anything beyond the package itself.
Skip if:
Skip if you need MP3 playback on Linux, or if you need to control volume or mix multiple audio streams simultaneously.
Automation engineers adding auditory notifications to pipelines
Scheduled scripts and data pipelines can use nava to play an alert when a pipeline fails, a threshold is crossed, or a long process finishes. The async_mode flag lets the notification play without blocking the script's remaining work.
Skip if:
Skip if your pipeline runs in a headless server environment with no audio hardware, where playback will fail or raise an error.
Python game developers prototyping simple sound effects
Nava's loop mode and async playback make it usable for simple audio feedback in early-stage Python games or simulations. Engine selection handles platform differences automatically, so prototype audio works on any developer's machine without per-platform setup.
Skip if:
Skip if your game needs audio mixing, multiple simultaneous channels, or MP3 on Linux. pygame.mixer is the better fit for those requirements.
The problem it solves#
Adding audio playback to a Python application typically means pulling in a large framework. pygame requires a full game engine installation alongside its audio module; pyaudio requires the PortAudio C library to be compiled or installed at the OS level; playsound has been effectively abandoned and breaks on modern Linux distributions. Cross-platform audio in Python has no single standard library: what plays a WAV on Windows (winsound) does nothing on macOS or Linux, leaving developers to write platform-detection boilerplate or take on a heavyweight dependency for a feature they need for a few seconds of audio.
The result is that basic audio feedback, test signals, and alert sounds end up either missing from Python tools or gated behind a fragile install process that breaks on fresh machines and CI containers. Developers maintaining CLI tools and automation scripts frequently skip audio altogether because the setup cost outweighs the value for a single library.
How it solves it#
Zero external dependencies
Nava plays sounds using each platform's built-in audio subsystem: ALSA on Linux, winsound and Windows MCI on Windows, and afplay on macOS. No PortAudio, no pygame, no system-level audio library installation needed. pip install is sufficient to run it on any Python 3 environment.
Automatic platform engine selection
The AUTO engine mode detects the host operating system and picks the correct backend without any configuration. On Linux it uses ALSA; on Windows it switches between winsound (WAV) and WINMM (WAV and MP3); on macOS it uses afplay. You can also specify the engine manually with the Engine parameter if you need a specific backend.
Async and loop playback modes
The play() function accepts async_mode=True to return a sound ID immediately while the audio continues playing in the background, letting your Python code continue running. Pair async_mode with loop=True for continuous looping audio, and call stop(sound_id) to halt playback at any point.
Command-line interface
Nava ships a CLI for playing sounds without writing Python: nava [--file FILE_PATH] [--loop] [--engine ENGINE] FILE_PATH. This makes it useful in shell scripts, cron jobs, and system notification pipelines where you want to trigger audio from a terminal command.
Typed exception handling
Playback failures raise NavaBaseError, a typed exception callers can catch rather than relying on generic OS error signals. This makes it straightforward to build fallback behavior in scripts that run in environments where audio hardware may not be present.
Strengths and trade-offs#
Strengths
- Genuinely zero-dependency installUnlike pygame (which installs a full game framework) or pyaudio (which requires compiling against the PortAudio C library), nava uses only Python standard library calls to invoke platform audio. The install footprint is the library itself. This makes it safe to add to any Python environment without risking transitive dependency conflicts.
- MIT licenseNava is MIT licensed, so you can use it in commercial projects, fork it, and modify it without restriction. There are no runtime licensing fees, no vendor agreements, and no clauses governing how you distribute software that includes it.
- CI-verified on all three platformsThe project runs separate CI pipelines for Linux, Windows, and macOS on every commit, tracking both main and dev branches. Platform regressions are caught before release, which matters for a library where platform differences are the central design concern.
- Python Software Foundation grant recipientVersions 0.8 and 0.9 of nava received a Python Software Foundation grant. PSF grants go through an external vetting process, which is a signal of project quality beyond community star counts alone.
Trade-offs
- -Linux playback limited to WAV formatThe ALSA engine on Linux only supports WAV files. MP3 playback on Linux is not available through nava's current engine set. Developers who need MP3 on Linux must convert their audio to WAV before using nava, or choose a different library.
- -Playback only, no audio processingNava's API covers play and stop. It does not expose volume control, audio mixing, channel management, pitch shifting, or format conversion. Developers who need those capabilities need a more complete audio library alongside or instead of nava.
nava vs alternatives#
nava vs pygame.mixer
Both nava and pygame.mixer play audio files in Python, but they address different scales of need. pygame.mixer is part of the pygame game development library, which brings rendering, event handling, and display management alongside its audio module. Installing pygame to play a single WAV file adds a large dependency and requires a display subsystem on some platforms.
| Feature | nava | pygame.mixer |
|---|---|---|
| License | MIT | LGPL |
| Dependencies | None | pygame (game framework) |
| MP3 on Linux | No | Yes (with SDL_mixer) |
| Audio mixing | No | Yes (multiple channels) |
| Volume control | No | Yes |
| Loop playback | Yes | Yes |
nava is the better pick when the goal is a simple, dependency-free pip install that plays a WAV or MP3 on any platform. pygame.mixer is the better pick when you are already using pygame for a game, or when you need audio mixing, volume control, or MP3 on Linux.
nava vs pyaudio
pyaudio is a lower-level audio library that wraps PortAudio, a cross-platform C library. It gives fine-grained access to audio streams, sample rates, and buffer sizes. The tradeoff is installation complexity: pyaudio requires PortAudio to be installed at the OS level via apt, brew, or manual compilation, which breaks frequently in Docker containers and CI pipelines.
| Feature | nava | pyaudio |
|---|---|---|
| License | MIT | MIT |
| Dependencies | None | PortAudio (C library) |
| Install complexity | pip only | pip + OS package |
| Audio streaming | No | Yes |
| Playback API | play/stop | raw stream buffers |
nava is the right choice when you need to play a sound file and move on. pyaudio is the right choice when you need to process audio streams, record microphone input, or work with raw audio buffers.
Install and self-host#
Install nava via pip; no system audio libraries are required.
```bash
pip install nava==0.9
```What it's built on#
- Languages
- Python
FAQ#
Does nava require any system-level audio libraries to be installed?
No. Nava uses the audio subsystems built into each operating system: ALSA on Linux, winsound and Windows MCI on Windows, and afplay on macOS. You install nava with pip and it works without any additional system packages. This is its primary advantage over libraries like pyaudio, which requires PortAudio to be installed at the OS level.
What audio file formats does nava support?
WAV is supported on all three platforms. MP3 is supported on Windows (via the WINMM engine) and macOS (via afplay). Linux is currently limited to WAV via ALSA. If you need MP3 playback on Linux, you would need to convert your files to WAV first or use a different library.
Can nava play audio in the background while my Python code continues running?
Yes. Pass async_mode=True to play() and it returns a sound ID immediately while the audio plays in a background thread. You can stop it at any time by calling stop(sound_id). Combine async_mode=True with loop=True for continuously looping audio that runs until you explicitly stop it.
Is nava suitable for production use in Python scripts and tools?
Nava is MIT licensed, has CI coverage on Linux, Windows, and macOS, and received Python Software Foundation grants for versions 0.8 and 0.9. For basic audio playback in production scripts or CLI tools, it is a reasonable choice. It is not suitable for high-performance audio applications that require mixing, multichannel output, or fine-grained buffer control, where a library like pyaudio or pygame.mixer would be more appropriate.
How does nava handle environments without audio hardware?
Nava raises a NavaBaseError when playback fails, which you can catch with a try/except block. On headless servers without audio hardware, the exception lets you handle the failure gracefully rather than crashing the script. This means you can write one code path that plays audio when available and silently skips it when not.
Similar open-source tools#
monocode
One desktop UI for all your AI coding agents.
crawl4ai
LLM-ready web crawling without API keys or rate limits
browser-use
Python library giving any LLM full browser control, MIT licensed
free-claude-code
Route 9 AI coding agents through 1.3B+ free monthly tokens
codex
OpenAI's terminal coding agent, Apache-2.0 licensed
kilocode
Open source AI coding agent. 500+ models at zero markup.