term-audio

A terminal-based audio player with a file browser UI. Navigate your music library, select files, and control playback — all from the command line. Built with OpenTUI and backed by mpv via node-mpv.

Prerequisites

Must be installed on your system before using term-audio:

• Bun — the JavaScript runtime (curl -fsSL https://bun.sh/install | bash)
• mpv — the media playback engine
  • macOS: brew install mpv
  • Ubuntu/Debian: sudo apt install mpv
  • Windows: scoop install mpv or download from mpv.io

Install

npm install -g term-audio

Or with Bun:

bun install -g term-audio

Usage

Play a file directly

term-audio ~/music/album/song.mp3

Supports common formats: mp3, wav, flac, ogg, m4a, aac, opus, wma, aiff.

Browse and select

Run without arguments to open the file browser:

term-audio

Use arrow keys to navigate directories and select an audio file. Only audio files are shown.

Controls (when a file is playing)

| Key | Action | |-----|--------| | Space | Play / Pause | | → / l | Seek forward 5s | | ← / j | Seek backward 5s | | ↑ | Volume up | | ↓ | Volume down | | Esc | Go back to file browser | | q | Quit |

Examples

# Open a specific file
term-audio ~/Music/album.mp3

# Pass relative paths
term-audio ./downloads/track.flac

# Browse your music directory
cd ~/Music && term-audio

Development

git clone https://github.com/<your-username>/term-audio
cd term-audio
bun install
bun dev        # watch mode, restarts on changes
bun start      # run once
bun run build  # bundle for distribution

What it looks like

A terminal UI with two modes:

• File browser — navigate directories, preview files, select an audio file
• Player — shows playback progress, time elapsed / remaining, volume level, and file name