csongs

A terminal music player for a local ~/Music library.

Requirements

• Node.js 16 or newer
• npm
• ffplay and ffprobe from FFmpeg
• cava for the visualizer
• A Music directory in your home folder with .mp3 files

If ~/Music does not exist, csongs will prompt you to create it on launch.

Install

Global install

npm install --global @vardhanbattula7/csongs
csongs --list

From source

git clone https://codeberg.org/Vardhanb07/csongs.git
cd csongs
npm install
npm run build

Development

npm install
npm run dev

Run

After installing or building, run:

csongs

By default the app opens the song list view. Use --play to start playback immediately.

CLI

csongs --help

Usage
  csongs [options]

Options
  --list  Open the song list view
  --play  Start playing from the first song

Examples
  csongs --list
  csongs --play

Flags

• --list opens the library browser.
• --play starts playback from the first song in ~/Music.
• If both are provided, --list wins.

Keyboard Commands

Library view

• ↑ / ↓: move selection
• g: jump to the first song
• G: jump to the last song
• Enter: play the selected song
• q / Esc: exit the app

Player view

• Space: play or pause
• l: loop the current song
• L: loop the full playlist
• n / Right Arrow: next song
• p / Left Arrow: previous song
• q / Esc: stop playback and exit
• When a song ends, playback automatically moves to the next song.
• When the final song ends and playlist loop is off, player returns to home.

How It Works

• csongs reads audio files from ~/Music
• Only .mp3 files are shown and played
• The player uses ffplay
• Track duration is read with ffprobe
• The animated visualizer uses cava
• CAVA signal-based exits during song transitions are treated as expected cleanup.

Commands During Setup

If you are setting up the project from source, these are the main commands:

npm install
npm run dev
npm run build