🎵 MusicLe CLI

A terminal-based music player with Spotify-inspired UI, audio visualization, and multi-platform support. Built with Go and Bubble Tea.

English · Türkçe

✨ Features

🎨 Spotify-Inspired UI — Clean, modern terminal interface with album art, song list, and player bar
📊 Audio Visualization — Real-time volume bars using CP437 characters (░▒▓█) — works in every terminal
📋 Playlist Management — Create, edit, delete playlists; reorder songs
🎵 Multiple Sources — Add music from Spotify, YouTube Music, or local files
🖼️ Album Art — ANSI half-block rendering of cover images
🌐 Bilingual — Full English and Turkish interface support
🎨 Themes — Light, Dark, and custom color themes
⚡ Blazing Fast — Written in Go, launches in milliseconds
🔊 Audio Engine — Embedded yt-dlp + FFmpeg downloads MP3 320k with album art, auto-advances on completion
🔄 Auto-Advance — Automatic next track with configurable delay
🔍 Search — Quick filtering across your library
🎛️ Equalizer-like Bars — Real-time audio spectrum visualization in the player bar

📦 Installation

Windows

Archive (zip) Install Steps

Architecture	File
x86_64	`musicle-cli_Windows_x86_64.zip`
x86 (32-bit)	`musicle-cli_Windows_x86.zip`
arm64	`musicle-cli_Windows_arm64.zip`

Download the .zip for your architecture from Releases
Extract the archive
Run musicle-cli.exe

No dependencies required.

macOS

Archive (tar.gz) Install Steps

Architecture	File
Intel (x86_64)	`musicle-cli_macOS_x86_64.tar.gz`
Apple Silicon (arm64)	`musicle-cli_macOS_arm64.tar.gz`

Download the .tar.gz for your architecture from Releases
Extract: tar xzf muscle-cli_macOS_*.tar.gz
Run: ./musicle-cli

No dependencies required.

Linux

Format Install Steps

tar.gz
musicle-cli_Linux_x86_64.tar.gz

deb (Debian/Ubuntu)
musicle-cli_Linux_x86_64.deb

rpm (Fedora/RHEL)
musicle-cli_Linux_x86_64.rpm

tar.gz:

tar xzf muscle-cli_Linux_x86_64.tar.gz
cd muscle-cli_Linux_x86_64
./musicle-cli

deb:

sudo dpkg -i muscle-cli_Linux_x86_64.deb
musicle-cli

rpm:

sudo rpm -ivh muscle-cli_Linux_x86_64.rpm
musicle-cli

No dependencies required.

Build from Source

The download engine (standalone yt-dlp + a static FFmpeg) is embedded into the binary via go:embed (-tags engine_assets), so the released binary is fully self-contained — end users never download anything extra and no Python is required. The engine assets themselves are not committed to the repo; they are fetched at build time by scripts/prepare-engine.sh.

git clone https://github.com/alperencolgecen/musicle-cli.git
cd musicle-cli

# Recommended: downloads the embedded engine, then bakes it into the binary
make build

# …or manually:
make engine                 # downloads yt-dlp + ffmpeg into internal/engine/engine_bin
CGO_ENABLED=1 go build -tags engine_assets -o musicle-cli .

Note: the audio player backend (oto) needs CGO + ALSA dev headers, so the build is CGO_ENABLED=1 by default. On Fedora: sudo dnf install gcc alsa-lib-devel. A plain go build (without -tags engine_assets) still compiles, but the embedded engine is omitted and the downloader falls back to the legacy method at runtime. scripts/prepare-engine.sh compresses FFmpeg with UPX when available (77 MB → ~25 MB) to keep the final binary small. To re-fetch the engine (e.g. after bumping versions in assets/engine/manifest.yaml), run make engine again before building.

🚀 Quick Start

Launch: ./musicle-cli (or double-click the binary)
First Run Wizard: Choose music directory, language, create a profile and playlist
Add Music:
- Paste a Spotify or YouTube Music URL in the sidebar
- Or use + Add Local Music to browse local files
Play: Select a song and press Space or click ▶ Play

🎮 Keybindings

Key	Action	Description
`Space`	⏯ Play/Pause	Toggle playback
`→` / `←`	⏩⏪ Seek	5 seconds forward/back
`↑` / `↓`	🔊🔉 Volume	Increase/decrease volume
`Tab`	🔄 Cycle Focus	Switch between sidebar, songs, editor, console
`F1`	🔁 Cycle Sections	Cycle focus through all sections including console
`F3`	⚙️ Switch Settings Tab	Cycle through the General page tabs (Theme, Language, …)
`Ctrl+U`	📋 Update Playlist	Save the current playlist
`n`	⏭ Next Song	Skip to next track
`Ctrl+C` / `Esc`	❌ Quit	Exit the application
`Enter`	✏️ Edit Song	Open edit modal for selected song

🖥️ Interface

┌─────────────────────────────────────────────────────────────────┐
│  MusicLe      [Home]  [Settings]                                │  ← Header
├──────────────┬──────────────────────────────────────────────────┤
│              │  [Playlist ▼]                                    │
│  MUSIC       │  ┌──────┐  Playlist Name                         │
│  DOWNLOAD    │  │ Art  │  Description / Bio                     │
│              │  └──────┘                                        │
│  [Spotify…]  │  [🔒 Lock] [🔀 Shuffle] [▶ Play] [⬇ Download]  │
│  [YouTube…]  │  ────────────────────────────────────────────    │
│  [+Local]    │  #  Title               Artist     Album   Dur   │
│  [Playlist▼] │  ────────────────────────────────────────────    │
│              │  1  Bohemian Rhapsody   Queen      A Night 05:55 │
│  (~25%)      │  2  Stairway to Heaven  Led Zepp  IV      08:02 │
│              │  3  …                                           │
├──────────────┴──────────────────────────────────────────────────┤
│  ░▒▓███████  Bohemian Rhapsody — Queen    ░▒▓███░  01:23/05:55 │  ← Player Bar
└─────────────────────────────────────────────────────────────────┘

Sections

Section	Description
Sidebar	Music download (Spotify/YouTube/local) + playlist selector
Playlist Info	Album art, name, description, action buttons
Songs Table	Song list with title, artist, album, duration columns
Player Bar	Volume visualization, now-playing info, progress, metadata
Console	Log output and debug information
Edit Modal	Inline editing of song title, artist, album, and date

⚙️ Configuration

Config file: %APPDATA%/musicle/config.json (Windows) or ~/.config/musicle/config.json (Linux/macOS)

{
  "language": "en",
  "theme": "dark",
  "musicDir": "~/Music",
  "player": {
    "volume": 80,
    "autoAdvance": true,
    "autoAdvanceDelay": 2
  }
}

Themes

dark — Dark background with vibrant accents (default)
light — Light background
custom — User-defined color scheme

🧩 Project Structure

musicle-cli/
├── main.go                 # Application entry point
├── model.go                # Main TUI model
├── home.go                 # Home screen logic (player, songs, sidebar)
├── settings.go             # Settings screen
├── state/
│   ├── state.go            # Global application state
│   ├── config.go           # Configuration management
│   └── profile.go          # Profile data structures
├── ui/
│   ├── styles.go           # Lipgloss styles, theme system
│   ├── keys.go             # Keybinding definitions
│   └── help.go             # Help view
├── bridge/
│   ├── bridge.go           # Main dispatcher (player, playlist, metadata, download)
│   ├── player.go           # Audio playback engine (oto + beep + gonum FFT)
│   ├── metadata.go         # Metadata extraction (dhowden/tag)
│   ├── playlist.go         # Playlist CRUD + local file import
│   ├── download.go         # YouTube/Spotify download via embedded engine dispatcher
├── internal/engine/        # Embedded download engine (go:embed yt-dlp + ffmpeg)
│   ├── ytwrap.go           # yt-dlp/ffmpeg orchestration -> MP3 320k + APIC cover
│   ├── spotify.go          # API-free Spotify resolution (embed scrape -> ytsearch1)
│   ├── extract.go          # Extract embedded tools to the user cache
│   └── engine_bin/         # (not committed) prepared by scripts/prepare-engine.sh
├── maximize_windows.go     # Terminal maximize (Windows)
├── maximize_unix.go        # Terminal maximize (Linux/macOS)
├── .goreleaser.yaml        # Release build config

🔧 Technical Details

Audio Engine

Go powers everything: TUI (Bubble Tea + Lipgloss), audio playback (oto + beep), metadata (dhowden/tag), and FFT spectrum (gonum)
No Python required — single binary, zero runtime dependencies
Audio decoding supports MP3, FLAC, and WAV

Visualization

Real-time 16-band FFT spectrum computed with gonum/dsp/fourier
Rendered as CP437 block characters ( ░▒▓█) — guaranteed in every terminal
40-character bar width for consistent rendering in the player bar

Release Artifacts

Platform	Arch	Format
Windows	x86_64	zip
Windows	x86	zip
Windows	arm64	zip
Linux	x86_64	tar.gz, deb, rpm
Linux	arm64	tar.gz, deb, rpm
Linux	x86	tar.gz, deb, rpm
macOS	x86_64	tar.gz
macOS	arm64	tar.gz

📄 Changelog

v1.1.0

✨ Pure Go rewrite — no Python, no venv, single self-contained binary
🔽 Embedded download engine — standalone yt-dlp + static FFmpeg baked in via go:embed; YouTube & Spotify (API-free) → MP3 320k with embedded cover
📦 Self-contained — download, extract, run. Zero runtime dependencies
🔊 Audio engine — oto + beep for playback, gonum FFT for spectrum
🏷️ Native metadata — dhowden/tag for ID3/FLAC/MP4/AAC
🐧 Linux arm64 + 386 — added alongside x86_64
📊 16-band real-time FFT spectrum visualization
🎨 Album art ANSI rendering

v1.0.0

🎵 Initial release (Python engine)
Spotify and YouTube Music integration
Playlist management
Modern terminal UI
Windows, macOS, Linux support

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines.

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes
Push and open a Pull Request

📬 Contact

Developer: Alperen Çölgeçen — alperencolgecen@gmail.com
GitHub: @alperencolgecen
Issues: github.com/alperencolgecen/musicle-cli/issues

📜 License

This project is licensed under the Apache License 2.0. See LICENSE for details.

The binary also bundles third-party components that are extracted at runtime into the user cache directory and invoked directly (no Python):

yt-dlp — The Unlicense
FFmpeg — LGPL-2.1+ (with GPL components)

It additionally depends on the Go libraries listed in go.mod (bubbletea, lipgloss, oto, gopxl/beep, ncruces/zenity, and their transitive dependencies).

Full license texts and disclaimers are in THIRD_PARTY_NOTICES.md.

🎵 The most elegant way to enjoy music from your terminal.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
bridge		bridge
components		components
internal		internal
scripts		scripts
state		state
test		test
ui		ui
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMMUNITY.md		COMMUNITY.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
build.sh		build.sh
components.go		components.go
connect.go		connect.go
downloads.go		downloads.go
go.mod		go.mod
go.sum		go.sum
home.go		home.go
language.go		language.go
logos_embed.go		logos_embed.go
main.go		main.go
maximize_unix.go		maximize_unix.go
maximize_windows.go		maximize_windows.go
model.go		model.go
playlist.go		playlist.go
profile.go		profile.go
rsrc_windows_386.syso		rsrc_windows_386.syso
rsrc_windows_amd64.syso		rsrc_windows_amd64.syso
settings.go		settings.go
settings_content.go		settings_content.go
setup.go		setup.go

Navigation Menu

Repository files navigation

🎵 MusicLe CLI

✨ Features

📦 Installation

Windows

macOS

Linux

Build from Source

🚀 Quick Start

🎮 Keybindings

🖥️ Interface

Sections

⚙️ Configuration

Themes

🧩 Project Structure

🔧 Technical Details

Audio Engine

Visualization

Release Artifacts

📄 Changelog

v1.1.0

v1.0.0

🤝 Contributing

📬 Contact

📜 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎵 MusicLe CLI

✨ Features

📦 Installation

Windows

macOS

Linux

Build from Source

🚀 Quick Start

🎮 Keybindings

🖥️ Interface

Sections

⚙️ Configuration

Themes

🧩 Project Structure

🔧 Technical Details

Audio Engine

Visualization

Release Artifacts

📄 Changelog

v1.1.0

v1.0.0

🤝 Contributing

📬 Contact

📜 License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages