A unified command-line music shuffler that combines Spotify, Pandora, and YouTube Music into a single streaming experience with pianobar-style controls and Last.fm scrobbling support.
- Shuffle music across multiple streaming services simultaneously
- Spotify Connect support - 320kbps Premium streaming via spotifyd/librespot
- Pianobar-style single-key controls for seamless interaction
- Built-in Last.fm scrobbling with real-time now playing updates
- Last.fm-based music discovery using similar artists/tracks
- Pandora QuickMix support with automatic Tor proxy for geographic restrictions
- Modern progress bar with brand colors and audio quality display
- Genre tags from Last.fm shown in real-time
- Heart icon (♥) for tracks loved on Last.fm
- Love tracks synced to both Last.fm AND source service
- Endless playback - queue auto-refills when empty
- Python 3.11+
- mpv (with libmpv)
- ffmpeg
- pipx (recommended for installation)
- Tor (optional, for Pandora outside USA - auto-starts when needed)
- spotifyd or librespot (optional, for Spotify 320kbps streaming)
Run the interactive installer that handles dependencies and configuration:
git clone https://github.com/ronilaukkarinen/omnishuffle.git
cd omnishuffle
./install.shThe installer automatically detects your OS (macOS, Arch, Debian/Ubuntu, Fedora) and installs all required dependencies.
brew install mpv ffmpeg tor pipx
git clone https://github.com/ronilaukkarinen/omnishuffle.git
cd omnishuffle
pipx install -e .sudo pacman -S mpv ffmpeg tor python-pipx
git clone https://github.com/ronilaukkarinen/omnishuffle.git
cd omnishuffle
pipx install -e .sudo apt install mpv ffmpeg tor pipx
git clone https://github.com/ronilaukkarinen/omnishuffle.git
cd omnishuffle
pipx install -e .Simply run:
omnishuffleThe player will start shuffling music from all configured sources.
▄▆ [SPOTIFY] Artist - Song Title ♥ (rock, metal)
━━━━━━━━╸──────────────── 2:42/5:28 320kbps vorbis ⚡ vol 100%
- Brand-colored progress bar (green=Spotify, blue=Pandora, red=YouTube)
- ⚡ indicates Spotify Connect (320kbps)
- ♥ indicates track is loved on Last.fm
- Genre tags from Last.fm
| Key | Action |
|---|---|
n |
Next track |
p |
Pause/Resume |
Space |
Pause/Resume |
+ |
Love current track (syncs to Last.fm + source) |
- |
Ban current track |
( |
Volume down |
) |
Volume up |
l |
Refresh Last.fm recommendations |
i |
Show track info (genres, quality, queue size) |
S |
Shuffle queue |
h |
Show help |
q |
Quit |
Configuration is stored in ~/.config/omnishuffle/config.json.
{
"general": {
"default_mode": "shuffle",
"sources": ["spotify", "pandora", "youtube"],
"volume": 100
},
"spotify": {
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"redirect_uri": "http://127.0.0.1:8080"
},
"pandora": {
"email": "your@email.com",
"password": "your_password",
"proxy": "socks5://127.0.0.1:9050"
},
"lastfm": {
"api_key": "your_api_key",
"api_secret": "your_shared_secret",
"username": "your_lastfm_username",
"password": "your_lastfm_password"
}
}- Go to Spotify Developer Dashboard
- Click Create app
- Fill in the details:
- App name:
OmniShuffle - Redirect URI:
http://127.0.0.1:8080(click Add) - Which API/SDKs: Select Web API
- App name:
- Click Save, then Settings
- Copy the Client ID and Client Secret
On first run, a browser opens for authorization.
For true 320kbps Spotify quality, install spotifyd:
# macOS
brew install spotifyd
brew services start spotifyd
# Arch Linux
yay -S spotifyd
systemctl --user enable --now spotifyd
# Or install librespot directly
yay -S librespotConfigure spotifyd (~/.config/spotifyd/spotifyd.conf):
[global]
username = "your_spotify_username"
password = "your_spotify_password"
device_name = "OmniShuffle"
device_type = "computer"
bitrate = 320
backend = "pulseaudio" # Linux
# backend = "rodio" # macOSOmniShuffle will automatically detect the spotifyd device and use it for Spotify tracks at 320kbps. You'll see:
✓ Spotify connected (320kbps via OmniShuffle)
If no Spotify Connect device is found, it falls back to YouTube:
✓ Spotify connected (via YouTube fallback)
Pandora is only available in the USA. For users outside the USA, OmniShuffle auto-starts Tor with US exit nodes.
- Install Tor:
- macOS:
brew install tor - Arch:
sudo pacman -S tor - Debian/Ubuntu:
sudo apt install tor
- macOS:
- Use Tor Browser or configure your browser to use SOCKS5 proxy
127.0.0.1:9050 - Go to pandora.com and create a free account
- Create some stations based on artists/songs you like
{
"pandora": {
"email": "your@email.com",
"password": "your_password",
"proxy": "socks5://127.0.0.1:9050"
}
}OmniShuffle will:
- Auto-start Tor with US exit nodes
- Verify the exit node is in the US
- Retry with a new circuit if needed
- Use QuickMix (Shuffle) station that mixes from all your selected stations
If you're in the USA, leave proxy empty or omit it.
YouTube Music works without authentication - OmniShuffle searches YouTube and plays via yt-dlp.
Authentication is only needed for personal playlists. See the detailed setup in the wiki if needed.
OmniShuffle has built-in Last.fm support - no external scrobblers needed.
Features:
- Real-time "now playing" updates
- Automatic scrobbling (after 50% or 4 minutes)
- Love track sync (pressing
+loves on Last.fm + source service) - Smart recommendations based on your listening history
- Go to Last.fm API account creation
- Fill in the form (Application name:
OmniShuffle) - Copy the API Key and Shared Secret
{
"lastfm": {
"api_key": "your_api_key",
"api_secret": "your_shared_secret",
"username": "your_lastfm_username",
"password": "your_lastfm_password"
}
}When Last.fm is configured, OmniShuffle uses it as the primary discovery engine:
- Fetches your loved tracks and top artists from Last.fm
- Finds similar tracks and artists using Last.fm's database
- Searches for these on YouTube Music
- Mixes with Pandora's personalized radio
- Shuffles everything together
Press l to refresh recommendations anytime.
| Source | Quality | Notes |
|---|---|---|
| Spotify Connect | 320kbps Vorbis | Requires spotifyd/librespot + Premium |
| Spotify (YouTube fallback) | ~128-160kbps | When no Connect device available |
| Pandora Free | 64kbps AAC | |
| Pandora Plus | 192kbps | |
| Pandora Premium | 320kbps | |
| YouTube | ~128-160kbps Opus | Best available audio |
┌───────────────────────────────────────────────────────┐
│ OmniShuffle │
├──────────┬──────────┬──────────┬──────────┬───────────┤
│ Spotify │ Pandora │ YouTube │ Last.fm │ spotifyd │
│ (spotipy)│ (pydora) │ (ytmusic)│ (pylast) │ (320kbps) │
└────┬─────┴────┬─────┴────┬─────┴────┬─────┴───────┬───┘
│ │ │ │ │
│ │ │ recommendations │
│ │ │ │ playback
└──────────┴──────────┴──────────┘ │
│ │
┌──────▼──────┐ │
│ Shuffle │◄──────────────────────┘
│ Queue │
└──────┬──────┘
│
┌───────────┴───────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ mpv │ │ Spotify │
│(Pandora/ │ │ Connect │
│ YouTube) │ │ (320kbps)│
└────┬─────┘ └──────────┘
│
▼
┌──────────┐
│ pylast │────► Last.fm (scrobble)
└──────────┘
| Package | Purpose |
|---|---|
| python-mpv | MPV playback control |
| spotipy | Spotify API client |
| pydora | Pandora API client |
| ytmusicapi | YouTube Music API client |
| yt-dlp | YouTube stream extraction |
| pylast | Last.fm scrobbling |
| readchar | Keyboard input |
| rich | Terminal UI |
| httpx | HTTP client with SOCKS |
spotifyd/librespot is not running or not detected. Start it:
systemctl --user start spotifydTor might have selected a non-US exit node. OmniShuffle retries automatically, but you can also:
# Check your Tor exit IP
curl --socks5 127.0.0.1:9050 https://ipinfo.io/countryVerify mpv is working:
mpv --no-video "https://www.youtube.com/watch?v=dQw4w9WgXcQ"If you need new scopes (e.g., after updating OmniShuffle):
rm ~/.config/omnishuffle/spotify_cache
omnishuffleMIT License. See LICENSE for details.