nu_plugin_audio
A Nushell plugin to generate and play sounds. It supports tone generation, metadata manipulation, and playback for multiple audio formats.
Origins and Attribution
This project is a continuation and expansion of the original nu_plugin_audio_hook created by fmotalleb. Due to real-world circumstances, the original author plans to archive their repository and step away from development. They gave explicit permission to fork the project and keep the code alive. I am incredibly grateful for their hard work in laying the foundation for this tool.
Features
sound beep- Play a simple beep sound.sound make- Generate a noise with a given frequency and duration.sound meta- Retrieve metadata (duration, artist, album, etc.) from an audio file.sound meta set- Modify metadata tags in an audio file using format-agnostic key names.sound play- Play an audio file with a live progress display and interactive controls. By default, it supports FLAC, WAV, MP3, OGG, AAC, and MP4 playback. Use theall-decodersfeature for an expanded set like minimp3 or 64-bit support.
Usage
Generate a simple noise
Generate a noise sequence
[ |
Generate a noise with 50% volume
Save a generated tone to a file
|
Play an audio file (first 3 seconds only)
Play an audio file starting at 2x volume
Play an audio file starting at 50% volume
Play silently (no terminal output for scripts or background tasks)
Play with Nerd Font icons
Retrieve metadata from an audio file
Example output:
╭───────────────┬────────────────────────────╮
│ size │ 6.4 MiB │
│ format │ mp3 │
│ bitrate │ 320 │
│ audio_bitrate │ 320 │
│ artist │ SINGER │
│ title │ TITLE │
│ album │ ALBUM │
│ albumartist │ SINGER │
│ comment │ Tagged with MusicBrainz │
│ date │ 2024-03-15 │
│ genre │ Rock │
│ track_no │ 1 │
│ total_tracks │ 12 │
│ artwork │ [list 1 item] │
│ duration │ 4:05 │
│ sample_rate │ 44100 │
│ channels │ 2 │
╰───────────────┴────────────────────────────╯
The artwork field is a list of records, one per embedded image:
sound meta audio.mp3 | get artwork
# ╭───┬───────────────┬────────────┬──────────╮
# │ # │ pic_type │ mime_type │ size │
# ├───┼───────────────┼────────────┼──────────┤
# │ 0 │ CoverFront │ image/jpeg │ 127.3 KB │
# ╰───┴───────────────┴────────────┴──────────╯
FLAC and lossless files additionally expose bit_depth:
sound meta audio.flac | select size format bitrate bit_depth
# ╭───────────┬──────────╮
# │ size │ 42.3 MiB │
# │ format │ flac │
# │ bitrate │ 1411 │
# │ bit_depth │ 24 │
# ╰───────────┴──────────╯
Modify metadata (change the artist tag)
Key names are case-insensitive. artist, Artist, and ARTIST all work. Key names are format-agnostic. The same key works across MP3, FLAC, OGG, and MP4 files. Use sound meta --all to list every available key name.
Set a comment tag
Set ReplayGain values
List all available metadata key names
Key names are normalised to lowercase before lookup, so Artist, ARTIST, and artist are all accepted. The table below shows every supported key grouped by category.
Core identity
| Key | Maps to |
|---|---|
album |
Album title |
albumartist |
Album-level artist |
albumsortorder |
Album title sort order |
artist |
Track artist |
artistsortorder |
Track artist sort order |
title |
Track title |
titlesortorder |
Track title sort order |
subtitle |
Track subtitle |
setsubtitle |
Set/disc subtitle |
People & roles
| Key | Maps to |
|---|---|
composer |
Composer |
composersortorder |
Composer sort order |
conductor |
Conductor |
label |
Record label |
lyricist |
Lyricist |
movement |
Movement name |
movementnumber |
Movement number |
movementtotal |
Total movements |
organization |
Publisher |
producer |
Producer |
publisher |
Publisher (alias for organization) |
remixer |
Remixer / mix artist |
work |
Work title |
Dates
| Key | Maps to |
|---|---|
date |
Recording date (ISO 8601, e.g. 2024-03-15) |
originalyear |
Original release date |
releasedate |
Release date |
year |
Release year (bare integer) |
Identifiers
| Key | Maps to |
|---|---|
barcode |
Release barcode (EAN/UPC) |
cataloguenumber |
Catalogue number |
isrc |
ISRC |
Style & content
| Key | Maps to |
|---|---|
bpm |
BPM (decimal string) |
comment |
Comment |
compilation |
Compilation flag (1 / 0) |
copyright |
Copyright message |
discnumber |
Disc number |
encodedby |
Encoded by |
encodingsettings |
Encoder settings |
genre |
Genre |
grouping |
Content group / grouping |
initialkey |
Initial key (e.g. Am) |
language |
Language |
lyrics |
Lyrics text |
mood |
Mood |
originalalbum |
Original album title |
originalartist |
Original artist |
script |
Script (e.g. Latin) |
track |
Track number |
ReplayGain
| Key | Maps to |
|---|---|
replaygain_album_gain |
Album gain (dB string, e.g. -6.5 dB) |
replaygain_album_peak |
Album peak (float string, e.g. 0.998) |
replaygain_track_gain |
Track gain |
replaygain_track_peak |
Track peak |
Live Playback Display
When you play a file, sound play renders a live progress bar to stderr:
▶ 0:42 / 4:05 [██████████░░░░░░░░░░░░░░░░░░░░] 17% 🔊 [████████░░░░░░] 100%
Because the display writes to stderr, stdout remains clean. Piping the result of sound play to another command works without any garbled output. Use --no-progress (-q) to suppress the display entirely.
Nerd Font mode
If you have a Nerd Font installed and configured in your terminal, pass --nerd-fonts (-n) or set NERD_FONTS=1 in your environment for richer icons:
0:42 / 4:05 [██████████░░░░░░░░░░░░░░░░░░░░] 17% [████████░░░░░░] 100%
To enable permanently, add this to your env.nu:
$env.NERD_FONTS = "1"
Interactive Controls
For files longer than 1 minute, interactive keyboard controls are enabled automatically:
| Key | Action |
|---|---|
Space |
Play / pause |
→ or l |
Seek forward 5 seconds |
← or h |
Seek backward 5 seconds |
↑ or k |
Volume up 5% |
↓ or j |
Volume down 5% |
m |
Toggle mute |
q or Esc |
Stop and quit |
The control hint is shown inline on the progress bar and updates live to reflect the current state:
▶ 0:42 / 4:05 [██████████░░░░░░░░░░░░░░░░░░░░] 17% 🔊 [████████░░░░░░] 100% « [SPACE/pause] » [↑↓/kj] vol [m] mute [q] quit
Use --no-progress to disable terminal output and controls. This is recommended when you run tasks in the background or pipe output.
Installation
Linux requirements (ALSA)
Before installing on Linux, make sure the ALSA development package is present:
| Distro | Command |
|---|---|
| Debian / Ubuntu | sudo apt install libasound2-dev pkg-config |
| Fedora / RHEL | sudo dnf install alsa-lib-devel pkgconf-pkg-config |
| Arch | sudo pacman -S alsa-lib pkgconf |
| openSUSE | sudo zypper install alsa-lib-devel pkg-config |
Using nupm (Recommended)
git clone https://github.com/SuaveIV/nu_plugin_audio.git
nupm install --path nu_plugin_audio -f
Shell Installer (Linux / macOS)
No Rust toolchain required. Run this in your terminal, then register the plugin in Nushell:
|
plugin add ~/.cargo/bin/nu_plugin_audio
Note: The shell installer covers x86_64 Linux, x86_64 macOS, and ARM64 macOS (Apple Silicon). ARM64 Linux (
aarch64-unknown-linux-gnu) is not included in the installer — use the Manual Download orcargo installmethod instead.
PowerShell Installer (Windows)
No Rust toolchain required. Run this in PowerShell, then register the plugin in Nushell:
irm https://github.com/SuaveIV/nu_plugin_audio/releases/latest/download/nu_plugin_audio-installer.ps1 | iex
plugin add ($env.USERPROFILE | path join ".cargo" "bin" "nu_plugin_audio.exe")
cargo-binstall
Installs a prebuilt binary from the GitHub release, falling back to a source build automatically:
cargo binstall nu_plugin_audio
plugin add ~/.cargo/bin/nu_plugin_audio
cargo install
Builds from source using the published crate on crates.io:
cargo install nu_plugin_audio --locked
plugin add ~/.cargo/bin/nu_plugin_audio
Manual Download
Download the prebuilt binary for your platform from the Releases page, extract it, and register it:
plugin add path/to/nu_plugin_audio
Prebuilt binaries are available for the following targets:
| Target | Notes |
|---|---|
x86_64-unknown-linux-gnu |
x86_64 Linux |
aarch64-unknown-linux-gnu |
ARM64 Linux — built with --features=all-decoders |
x86_64-apple-darwin |
x86_64 macOS |
aarch64-apple-darwin |
ARM64 macOS (Apple Silicon) |
x86_64-pc-windows-msvc |
x86_64 Windows |
Each archive has a matching .sha256 checksum file on the release page.
Compile from Source
Only needed if you want custom feature flags:
git clone https://github.com/SuaveIV/nu_plugin_audio.git
cd nu_plugin_audio
cargo build -r --locked --features=all-decoders
plugin add target/release/nu_plugin_audio
Supported formats
Default install
Enabled out of the box with no extra flags (includes all Symphonia codecs):
| Format | Feature flag | Notes |
|---|---|---|
| MP3 | symphonia-all |
Via Symphonia; better accuracy than minimp3 |
| FLAC | symphonia-all |
Lossless compression |
| OGG Vorbis | symphonia-all |
Open lossy format |
| WAV | symphonia-all |
Uncompressed PCM |
| AAC | symphonia-all |
Used by Apple, YouTube, most streaming services |
| MP4 / M4A | symphonia-all |
Container for AAC and ALAC |
| ALAC | symphonia-all |
Apple Lossless |
| ADPCM | symphonia-all |
Adaptive PCM; common in games |
| CAF | symphonia-all |
Core Audio Format; Apple professional audio |
| MKV / WebM (Opus) | symphonia-all |
Open container with Opus codec |
With --features=all-decoders
Everything above plus expanded capabilities:
| Format | Feature flag | Notes |
|---|---|---|
| MP3 (minimp3) | minimp3 |
Lightweight alternative MP3 decoder |
| 64-bit precision | 64bit |
f64 sample precision |
Note: The
defaultfeature includesrodio/symphonia-all, providing support for almost every common audio format out of the box.
Compile with specific formats only
Users who want a smaller binary can build with the lite feature, which only includes a minimal set of decoders:
Note:
cargo installalways uses thedefaultfeature set. Custom features require a source build.
Contributors
See CONTRIBUTORS.md for the full list of contributors.