Sync your music to Slack, Discord, Last.fm, and more

A lightweight daemon that monitors what you're listening to and syncs it to your status across platforms. Simple to set up, runs in the background, and just works.

Jukd watches your music player and automatically:

• 🎵 Updates your Slack status with now-playing info
• 🎮 Shows Discord Rich Presence with album art and track details
• 📻 Scrobbles to Last.fm
• 🔔 Sends webhooks for custom integrations
• 💾 Tracks your listening history
• 🔄 Restores your previous status when music stops

• Slack - Status updates with customizable emoji and format
• Discord - Rich Presence with album art, timestamps, and track info
• Last.fm - Automatic scrobbling with proper timing
• Webhooks - POST track events to any URL for custom integrations
• Spotify API - Direct Spotify monitoring (alternative to MPRIS)

• Linux - MPRIS2 support (Spotify, VLC, Firefox, Chrome, etc.)
• macOS - Apple Music and Spotify support
• Works with any MPRIS-compatible player

• 📊 Statistics - Top artists, tracks, listening time
• 📝 History - SQLite database of all plays
• 📤 Export - CSV and JSON export for analysis
• 📺 TUI Dashboard - Live monitoring with real-time stats

• Configurable status format and prefix
• Player filtering (include/exclude specific apps)
• Auto-restore previous status when music stops
• Systemd service with auto-restart
• Debug logging and monitoring

# From releases (recommended)
curl -L https://github.com/amebalabs/jukd/releases/latest/download/jukd-linux-amd64 -o jukd
chmod +x jukd
sudo mv jukd /usr/local/bin/

# Or build from source
git clone https://github.com/amebalabs/jukd
cd jukd
go build -o jukd ./cmd/jukd
sudo mv jukd /usr/local/bin/

# Initialize config
jukd init

# Edit config file
$EDITOR ~/.config/jukd/config.yaml

Minimal config:

slack:
  enabled: true
  token: "xoxp-your-token-here"
  emoji: ":musical_note:"

discord:
  enabled: true

monitoring:
  poll_interval: 2s
  debounce_delay: 5s

# Foreground
jukd run

# Or install as systemd service
sudo cp jukd.service ~/.config/systemd/user/
systemctl --user enable --now jukd

# Start monitoring
jukd run

# View current track
jukd status

# View play history
jukd history              # Recent 50 plays
jukd history -n 100       # Recent 100 plays
jukd history --today      # Today only

# View statistics
jukd stats                # This week
jukd stats -p today       # Today
jukd stats -p month       # This month
jukd stats -p all         # All time

# Export history
jukd export -f csv -o plays.csv        # Export to CSV
jukd export -f json -p week            # Export this week as JSON
jukd export -n 100                     # Export last 100 plays

# Live dashboard
jukd tui

# Authentication
jukd auth slack           # Authenticate with Slack
jukd auth spotify         # Authenticate with Spotify
jukd auth lastfm          # Authenticate with Last.fm

# Enable/disable services
jukd enable discord
jukd disable slack

Option 1: Manual Setup (Recommended)

1. Create a Slack app at https://api.slack.com/apps
2. Add OAuth scopes: users.profile:read, users.profile:write
3. Install to your workspace
4. Copy the User OAuth Token (starts with xoxp-)
5. Add to ~/.config/jukd/config.yaml:

   slack:
     enabled: true
     token: "xoxp-your-token-here"

Option 2: OAuth Flow (Advanced)

If you want to use jukd auth slack, you need to create your own Slack app first (Slack requires HTTPS redirect URLs which CLI apps can't provide easily):

1. Create app at https://api.slack.com/apps
2. Add redirect URL using ngrok or similar: https://your-ngrok-url.ngrok.io/callback
3. Set environment variables:

   export JUKD_SLACK_CLIENT_ID="your-client-id"
   export JUKD_SLACK_CLIENT_SECRET="your-client-secret"

4. Update the redirect URI in internal/auth/slack.go to match your ngrok URL
5. Run jukd auth slack

Just enable in config - no setup needed:

discord:
  enabled: true

Discord Desktop must be running for Rich Presence to work.

Just run the auth command:

jukd auth lastfm

This will open your browser to authorize jukd with your Last.fm account.

For direct Spotify API monitoring instead of MPRIS:

jukd auth spotify

This will open your browser to authorize jukd with your Spotify account.

If you want to use your own app credentials instead of jukd's built-in ones, set these environment variables:

# Slack
export JUKD_SLACK_CLIENT_ID="your-client-id"
export JUKD_SLACK_CLIENT_SECRET="your-client-secret"

# Discord
export JUKD_DISCORD_CLIENT_ID="your-app-id"

# Last.fm
export JUKD_LASTFM_API_KEY="your-key"
export JUKD_LASTFM_API_SECRET="your-secret"

# Spotify
export JUKD_SPOTIFY_CLIENT_ID="your-client-id"

Then create apps at:

• Slack: https://api.slack.com/apps (OAuth scopes: users.profile:read, users.profile:write)
• Discord: https://discord.com/developers/applications
• Last.fm: https://www.last.fm/api/account/create
• Spotify: https://developer.spotify.com/dashboard (PKCE flow, redirect URI: http://127.0.0.1:8888/callback)

Edit ~/.config/jukd/config.yaml:

# Status format
prefix: "🎵 Listening to"
format: ""  # Leave empty for default: "{prefix}: {artist} - {title}"

# Monitor type (mpris, spotify, applemusic)
monitor:
  type: mpris

# Slack
slack:
  enabled: true
  token: "xoxp-..."
  emoji: ":musical_note:"

# Discord
discord:
  enabled: true

# Last.fm
lastfm:
  enabled: true
  session_key: ""  # Set by `jukd auth lastfm`

# Spotify (for direct API monitoring)
spotify:
  enabled: false
  access_token: ""  # Set by `jukd auth spotify`
  refresh_token: ""

# Webhooks
webhooks:
  enabled: false
  urls:
    - http://localhost:9999/webhook
  timeout: 5s

# Monitoring
monitoring:
  poll_interval: 2s
  debounce_delay: 5s

# Filter players
filters:
  include_players: []  # Empty = monitor all
  exclude_players: ["firefox", "chrome"]  # Ignore browsers

POST requests are sent to configured URLs on track events:

{
  "event": "track_started",
  "timestamp": 1760748612,
  "state": "playing",
  "track": {
    "title": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "player": "Spotify",
    "duration": 354,
    "art_url": "https://..."
  }
}

Events: track_started, track_stopped States: playing, paused, stopped

• Linux: playerctl for MPRIS2 monitoring

  # Ubuntu/Debian
  sudo apt install playerctl
  
  # Arch Linux
  sudo pacman -S playerctl

• macOS: Works with Apple Music and Spotify natively
• Discord: Desktop client must be running for Rich Presence

• Config: ~/.config/jukd/config.yaml
• State: ~/.local/state/jukd/
• History: ~/.local/state/jukd/history.db
• Service: ~/.config/systemd/user/jukd.service

Slack "missing_scope" error:

• Add both users.profile:read and users.profile:write scopes
• Reinstall app to workspace
• Copy new token

Status not updating:

# Check player is visible
playerctl status

# Check logs
journalctl --user -u jukd -f

# Run with debug logging
jukd run --debug

Discord not showing:

• Ensure Discord desktop client is running
• Check Discord isn't in Do Not Disturb mode

MIT

Built with Go • Inspired by good music taste