Package Exports

mox-cli
mox-cli/mox

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mox-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

mox - Terminal Music CLI

A powerful command-line music player with web UI, mpv backend, and extensive features

✨ Features

🎵 Multiple Sources: YouTube, SoundCloud, Bandcamp, local files, radio stations
🌐 Web Interface: Beautiful browser-based UI with real-time sync
📱 Terminal UI: Rich terminal interface with progress bars and visualizations
🎤 Lyrics Support: Real-time synced lyrics from lrclib.net
🎨 Album Art: Terminal album art display via chafa
📋 Playlists: Create, manage, and share playlists
🔀 Auto-DJ: Automatic queue refill from Last.fm recommendations
🔖 Bookmarks: Save and restore queue states with timestamps
📊 History: Track listening history with search and export
⚡ Fast Search: YouTube Data API v3 integration for instant results
🎛️ Audio Controls: Volume, speed, equalizer, crossfade support
🔄 Queue Management: Advanced queue operations and manipulation

🚀 Quick Install

npm (Recommended)

npm install -g mox-cli

Homebrew (macOS/Linux)

brew install KrishnaGupta653/tap/mox

Manual Installation

git clone https://github.com/KrishnaGupta653/mox.git
cd mox
./scripts/install.sh

📋 Requirements

Essential Dependencies

zsh - Shell interpreter
python3 (≥3.6) - For web UI server
mpv - Media player backend
curl - HTTP requests
jq - JSON processing

Optional (Recommended)

yt-dlp - YouTube/streaming support
fzf - Interactive fuzzy search
chafa - Terminal image display
ffmpeg - Audio metadata and conversion

Installation Commands

macOS (Homebrew):

brew install mpv curl jq python3 zsh yt-dlp fzf chafa ffmpeg

Ubuntu/Debian:

sudo apt update && sudo apt install mpv curl jq python3 zsh yt-dlp fzf chafa ffmpeg

Fedora/RHEL:

sudo dnf install mpv curl jq python3 zsh yt-dlp fzf chafa ffmpeg

Arch Linux:

sudo pacman -S mpv curl jq python zsh yt-dlp fzf chafa ffmpeg

WSL (Windows Subsystem for Linux):

# Install dependencies
sudo apt update && sudo apt install mpv curl jq python3 zsh yt-dlp fzf chafa ffmpeg

# Audio setup (choose one):
# Option 1: PulseAudio
sudo apt install pulseaudio
pulseaudio --start

# Option 2: Windows audio (experimental)
export PULSE_SERVER=tcp:localhost

🎯 Quick Start

# Search and play music
mox search "your favorite song"

# Open web interface
mox uxi

# Show help
mox help

# Play from URL
mox play "https://youtube.com/watch?v=..."

# Control playback
mox pause    # or mox pp
mox next     # or mox mn  
mox prev     # or mox mb
mox vol 80   # Set volume to 80%

# View current status
mox status   # or mox bar

🌐 Web Interface

Launch the web UI with:

mox uxi

The web interface provides:

🎵 Real-time player status and controls
📋 Queue management with drag & drop
🎤 Synchronized lyrics display
🎨 Album art and track information
🎛️ Volume and speed controls
🌓 Dark/light theme toggle

📖 Command Reference

Playback Control

mox play <url|query>     # Play music from URL or search
mox pause               # Toggle pause (alias: pp)
mox stop                # Stop playback
mox next                # Next track (alias: mn)
mox prev                # Previous track (alias: mb)
mox seek <time>         # Seek to position (e.g., +30, -10, 1:30)

Volume & Audio

mox vol <level>         # Set volume (0-100)
mox vol +/-<amount>     # Adjust volume relatively
mox speed <rate>        # Set playback speed (0.5-2.0)
mox eq                  # Open equalizer
mox norm                # Normalize audio

Queue Management

mox add <url|query>     # Add to queue
mox add-next <query>    # Add after current track
mox clear               # Clear queue
mox shuffle             # Shuffle queue
mox repeat              # Toggle repeat mode
mox queue               # Show current queue

Search & Discovery

mox search <query>      # Search for music
mox similar             # Find similar tracks
mox radio               # Start radio mode
mox autodj              # Toggle Auto-DJ mode

Playlists

mox save <name>         # Save current queue as playlist
mox load <name>         # Load playlist
mox playlists           # List all playlists
mox playlist <name>     # Show playlist contents

History & Likes

mox history             # Show listening history
mox like                # Like current track
mox likes               # Show liked tracks
mox export              # Export data to CSV

Information

mox status              # Current track info (alias: bar)
mox lyrics              # Show synchronized lyrics
mox art                 # Display album art in terminal
mox info                # Detailed track information

System

mox start               # Start mpv daemon
mox kill                # Stop mpv daemon
mox restart             # Restart mpv daemon
mox config              # Edit configuration
mox index               # Scan local music library

⚙️ Configuration

Configuration file: ~/music_system/config

# API Keys (recommended for full functionality)
LASTFM_API_KEY="your_lastfm_key"
YOUTUBE_API_KEY="your_youtube_key"
INVIDIOUS_HOST="https://invidious.snopyta.org"

# Audio Settings
DEFAULT_VOLUME=80
VOLUME_STEP=5
CROSSFADE_SECS=3

# Features
AUTODJ_ENABLED=1
LYRICS_ENABLED=1
NOTIFY_ENABLED=1

# Performance
CACHE_TTL=3600
SEARCH_RESULTS=20
BAR_REFRESH_MS=500

# Paths
LOCAL_MUSIC_DIR="$HOME/Music"
MUSIC_ROOT="$HOME/music_system"

📁 Directory Structure

~/music_system/
├── config              # Configuration file
├── socket/             # mpv IPC socket
├── cache/              # Cached metadata
├── playlists/          # Saved playlists
├── data/
│   ├── history         # Listening history
│   ├── likes           # Liked tracks
│   ├── bookmarks       # Saved queue states
│   └── local_index.tsv # Local music index
├── downloads/          # Downloaded files
└── logs/               # Application logs

🔧 Advanced Usage

Bookmarks

Save and restore complete queue states:

mox bookmark save "party-mix"    # Save current state
mox bookmark load "party-mix"    # Restore queue and position
mox bookmarks                    # List all bookmarks

Text File Playlists

Play from text files with URLs:

mox txt playlist.txt             # Play from text file
mox txt playlist.txt --resume    # Resume from last position

Local Music Library

Index and search your local music:

mox index                        # Scan ~/Music directory
mox local "artist name"          # Search local library

Keyboard Shortcuts (Web UI)

Space - Play/Pause
→ / ← - Next/Previous track
↑ / ↓ - Volume up/down
M - Mute toggle
L - Toggle lyrics
T - Toggle theme
F - Toggle fullscreen

🐛 Troubleshooting

Common Issues

mpv not starting:

mox kill && mox start    # Restart mpv daemon

Web UI not accessible:

# Check if port is available
lsof -i :7700
# Try different port
UXI_PORT=7701 mox uxi

Missing dependencies:

./scripts/install.sh        # Re-run installation script

Permission issues:

chmod +x mox.sh music_ui_server.py

Debug Mode

Enable verbose logging:

export DEBUG=1
mox <command>

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Test thoroughly
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

mpv - Powerful media player backend
yt-dlp - YouTube and streaming support
lrclib.net - Lyrics database
Last.fm - Music recommendations
fzf - Fuzzy search interface

🔗 Links

Enjoy your music! 🎶

Made with ❤️ for terminal music lovers.