AMCLI is a Terminal User Interface (TUI) application for controlling Apple Music on macOS. It brings playback controls, album artwork, synchronized lyrics, and terminal-first customization into one focused interface.
- Complete playback controls for Apple Music
- 8-bit style album artwork rendering
- Real-time synchronized lyrics
- Lightweight Rust implementation
- Vim-style keybindings
- Theme and mosaic display customization
- Play, pause, skip, and go back
- Adjust volume and mute
- Seek forward and backward
- Cycle repeat mode
- Track progress with precise position display
- ASCII, Unicode, and TrueColor album artwork
- Current-track artwork first, with online lookup as a fallback
- Non-blocking background artwork loading
- Automatic retry after transient artwork failures
- Six built-in themes:
AMBER VFDGREEN VFDCYAN VFDRED ALERTMODERNCLEAN
- Optional mosaic mode for pixelated artwork
- Responsive terminal layout
- Millisecond-precision LRC playback sync
- Concurrent LRCLIB and Netease lookup on first fetch
- Candidate matching by title, artist, album, and duration
- Session-level source preference based on the faster provider
- LRU cache for repeated lyrics queries
- Centered auto-scrolling lyrics view
- LRC parser support for multiple timestamps and offset adjustments
AMCLI is designed to stay useful inside a real terminal workspace: compact controls, readable metadata, predictable keybindings, and visual feedback that works alongside other command-line tools.
- Interface language: English / Japanese
- Settings menu with
s - Live theme switching with
t - Mosaic mode toggle
- Configuration file at
~/.config/amcli/config.toml
Tip
Project status: Phases 1-3 are complete, covering the core TUI, album artwork, and LRCLIB + Netease lyrics integration.
Option 1: Build from Source
git clone https://github.com/juntaochi/amcli.git
cd amcli
cargo build --release
cargo install --path .Option 2: Download a Release
Download a pre-built binary from the Releases page.
Option 3: Homebrew tap
If the Homebrew tap has been published for the current release:
brew tap juntaochi/tap
brew install amcliMaintainers can use the template in homebrew/amcli.rb when preparing tap updates.
amcli
amcli --help
amcli --config ~/.config/amcli/config.tomlAMCLI creates ~/.config/amcli/config.toml on first run.
[general]
language = "en" # "en" or "jp"
[artwork]
enabled = true
cache_size = 100
mode = "auto" # auto, ascii, blocks, truecolor
mosaic = true
[ui]
color_theme = "default"
show_help_on_start = true| Action | Key |
|---|---|
| Play / Pause | Space |
| Next Track | ] |
| Previous Track | [ |
| Volume Up | = / + |
| Volume Down | - / _ |
| Mute | m |
| Seek Forward / Backward | . / , or → / ← |
| Navigate | h / j / k / l or arrow keys |
| Cycle Repeat Mode | r |
| Theme Switch | t |
| Settings | s |
| Help | ? |
| Quit | q |
See PROJECT_SPEC.md for the full design notes and planned keyboard system.
- PROJECT_SPEC.md - Full project specification, architecture, feature design, and roadmap
- LYRICS.md - Lyrics system internals, provider integration, parsing, and sync behavior
- CONTRIBUTING.md - Contribution guide
- Phase 1: Core foundation, TUI framework, and Apple Music control
- Phase 2: UI enhancements and album artwork
- Phase 3: Lyrics integration
- Phase 4: Playlist and music library features
- Phase 5: Plugin system and multi-player support
- Phase 6: Polish and release
- Language: Rust 1.75+
- TUI Framework: Ratatui
- Terminal Backend: Crossterm
- Async Runtime: Tokio
- macOS Integration: AppleScript / osascript
- Configuration: Serde + TOML + Clap
Contributions are welcome. See CONTRIBUTING.md for setup and workflow details.
AMCLI is licensed under the MIT License. See LICENSE for details.
- go-musicfox for design inspiration
- Ratatui for the TUI framework
Made for music lovers and terminal enthusiasts