https://github.com/a/musictl
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/a/musictl
- Owner: A
- Created: 2025-07-12T08:00:15.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-07-27T17:45:30.000Z (11 months ago)
- Last Synced: 2025-07-27T19:31:51.471Z (11 months ago)
- Language: Python
- Size: 30.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Musictl
Music control CLI for **MPD** + **beets**. Manage your library, playlists, and playback from the terminal.
## Prerequisites
- **Python ≥ 3.13**
- **MPD** — running and configured
- **beets** — with library database and custom fields (`folder`, `playlists`, `comments`)
- **YAD** — for interactive dialogs (`update`, `delete-current`)
- **FFmpeg** — for `cue-split`
### Beets Setup
Musictl expects these beets flexible attributes:
- `folder` — organizes tracks into directories (also synced to `genre`)
- `playlists` — comma-separated playlist names
- `comments` — synced to `playlists:$playlists` for external readers
Beets path config should include:
```yaml
paths:
"folder::.+": $folder/$artist - $album - $track - $title
default: inbox/$genre/$artist - $album - $track - $title
```
## Installation
```bash
# From PyPI
uv tool install musictl
# Or from source
git clone https://github.com/A/musictl
cd musictl
uv tool install -e .
```
## Commands
| Command | Description |
|---------|-------------|
| `musictl search ` | Search beets library, print relative paths |
| `musictl play ` | Load and play a playlist |
| `musictl play --random [--count N]` | Play N random tracks |
| `musictl update` | Set folder/playlists on current track via YAD dialog, remove from queue |
| `musictl delete-current` | Delete current track from library and disk, remove from queue |
| `musictl clean-current` | Remove current track from MPD queue |
| `musictl import [args]` | Import tracks via `beet import` |
| `musictl cue-split --cue ` | Split audio file by CUE sheet |
| `musictl generate-playlists` | Regenerate all .m3u playlist files |
| `musictl rename-playlist ` | Rename a playlist across all tracks |
| `musictl rename-folder ` | Rename a folder, move files, update tags |
| `musictl waybar` | JSON output for waybar custom module |
### Piping
```bash
# Search and play results
musictl search 'artist:Beatles' | musictl play
# Search and play from a specific folder
musictl search 'folder:rock' | musictl play
```
### Waybar Integration
Add to your waybar config:
```json
"custom/music": {
"exec": "musictl waybar",
"interval": 5,
"return-type": "json"
}
```
### Hyprland Keybindings
```conf
bind = $mainMod, M, exec, musictl play --random --count 20
bind = $mainMod SHIFT, M, exec, musictl update
bind = $mainMod CTRL, M, exec, musictl delete-current
```
## Development
```bash
just check # ruff check + basedpyright
just fmt # ruff fix + ruff format
just test # run tests
just sync # uv sync dependencies
```