DeemixKit

A macOS automation toolkit for downloading music from Spotify and Deezer via Deemix

Search albums from Spotify/Deezer → Auto-download via Deemix

What is DeemixKit?

DeemixKit is a collection of automation scripts that bridge popular music services (Spotify, Deezer) with Deemix, the popular music downloader. It helps you quickly find and download albums with minimal effort.

Key Features

🎧 Multiple Music Services: Support for both Spotify and Deezer
🔍 Flexible Search: Search by artist, album, or currently playing track
📋 Clipboard Automation: Automatic clipboard management for seamless workflows
🖥️ Multiple Interfaces: CLI, GUI dialogs, and Keyboard Maestro macros
💿 Bulk Operations: Download entire artist discographies, playlists, batch lists
⚡ One-Click Workflows: Download what you're currently listening to instantly
🚫 No External Dependencies: Uses built-in macOS tools and standard Python libraries

Quick Start

Prerequisites

macOS (required for AppleScript automation)
Python 3.7+ (for most scripts)
Node.js 14+ (optional, for Spotify currently-playing script)
Deemix desktop application.
Click icon below for direct Download or go to GitHub

Installation

Quick Install (Recommended)

Paste the following into your terminal and follow the prompts

curl -s https://raw.githubusercontent.com/deathrashed/deemixkit/main/install/install.sh | bash

It will automatically:

Download and install Deemix
Clone DeemixKit to your specified location
Install the required Python dependencies
Set up your credentials file
Prompt for Spotify API keys (optional)

See install/README.md for details.

or you can also Double-click install/Install DeemixKit.command

Manual Installation

# Clone or download this repository
git clone https://github.com/deathrashed/deemixkit.git
cd deemixkit

# Install Python dependencies
pip install requests pyperclip

# Download Deemix from https://deemix.org and install to /Applications

Configuration (Spotify Only)

Click to expand Spotify setup

If you plan to use Spotify features, you'll need API credentials:

Go to Spotify Developer Dashboard
Create a new application
Copy your Client ID and Client Secret
Create ~/.config/deemixkit/credentials.json:

{
  "spotify": {
    "client_id": "your_spotify_client_id",
    "client_secret": "your_spotify_client_secret"
  }
}

Deezer requires no configuration - it uses a free public API!

ϟ Usage Examples

Search Deezer Album (Fastest - No Setup)

# CLI
./deezer/deezer-to-deemix.sh "Metallica" "Master of Puppets"

# GUI Dialog
osascript deezer/deezer-to-deemix.applescript

Search Spotify Album

# CLI
./spotify/spotify-to-deemix.sh "Pink Floyd" "The Dark Side of the Moon"

# GUI Dialog
osascript spotify/spotify-to-deemix.applescript

Download Full Discography

# Downloads all albums and EPs for an artist
./discography/discography-to-deemix.sh "Radiohead" "OK Computer"

# GUI Dialog
osascript discography/discography-to-deemix.applescript

Download All Albums from Playlist

# Extract ALL albums from a playlist
./playlist/playlist-downloader.sh "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"

Download from Text File

# Download multiple albums from a text file
./batch/batch-downloader.sh -f albums.txt

# Custom file with Spotify
./batch/batch-downloader.sh -f my-list.txt -s spotify

Universal URL Resolver

# Accept ANY Spotify or Deezer URL (track, album, artist, playlist)
./global/global-resolver.sh "https://open.spotify.com/artist/4Z8W4fKeB5YxbusRsdQVPb"

# Artist URLs automatically fetch ALL albums
./global/global-resolver.sh "https://www.deezer.com/artist/27"

# Uses clipboard if no argument
./global/global-resolver.sh

Download Currently Playing Track (Spotify)

# One-click download of what you're listening to
node spotify/currently-playing-to-deemix.js

ϟ What's Included

Universal Tools

Tool	Purpose	Input
Global Resolver	Accept ANY Spotify/Deezer URL	Track/Album/Artist/Playlist URL
Batch Downloader	Bulk download from text file	`albums.txt` file
Playlist Downloader	Extract ALL albums from playlist	Playlist URL
Riley's Playlist Resolver	Get only albums you DON'T have	Playlist URL + collection match

Service-Specific Tools

Script	Purpose	Credentials
`deezer/deezer-resolver.py`	Search Deezer API	Not required ✅
`spotify/spotify-resolver.py`	Search Spotify API	Required ❌
`discography/discography-resolver.py`	Fetch full discography	Not required ✅

Complete Workflows

Workflow	CLI	GUI	Description
Deezer to Deemix	`deezer/deezer-to-deemix.sh`	`deezer/deezer-to-deemix.applescript`	Search Deezer → Auto-paste to Deemix
Spotify to Deemix	`spotify/spotify-to-deemix.sh`	`spotify/spotify-to-deemix.applescript`	Search Spotify → Auto-paste to Deemix
Discography to Deemix	`discography/discography-to-deemix.sh`	`discography/discography-to-deemix.applescript`	Get all albums → Bulk paste to Deemix
Global Resolver	`global/global-resolver.sh`	`global/global-resolver.applescript`	Any URL → Auto-detect → Deemix
Playlist Downloader	`playlist/playlist-downloader.sh`	`playlist/playlist-downloader.applescript`	Playlist → All albums → Deemix
Batch Downloader	`batch/batch-downloader.sh`	`batch/batch-downloader.applescript`	File list → All albums → Deemix

Keyboard Maestro Macros

Comprehensive macros for Keyboard Maestro included in macros/ folder:

Macro	Description
Download	Activate Deemix, trigger download with hotkey
Discography for Deemix	Full discography downloader - prompts for artist/album, fetches entire catalog, auto-pastes to Deemix
Global Resolver	Universal resolver - accepts any URL, auto-detects type, sends to Deemix

Click to expand Discography Macro Details

The Discography for Deemix macro provides a complete workflow:

Prompts you for Artist and Album name (uses album to identify correct artist among duplicates)
Fetches complete discography from Deezer (albums + EPs only, excludes singles by default)
Copies all album URLs to clipboard automatically
Activates Deemix and pastes all URLs for bulk downloading
Notifies you when complete

Features:

Artist disambiguation (finds correct "America" or "Boston" among duplicate band names)
Smart filtering (albums + EPs only, singles excluded)
Bulk paste (all URLs pasted at once for simultaneous download)
Handles large discographies (100+ albums via API pagination)
Duplicate filtering removes duplicate album titles

Setup: Update the macro's Execute Shell Script path to your DeemixKit location.

Special Scripts

Script	Purpose	Language
`spotify/currently-playing-to-deemix.js`	Download currently playing Spotify track	Node.js
`scripts/paste-to-deemix.applescript`	Paste clipboard into Deemix	AppleScript
`scripts/rileys-collection-matcher.py`	Fuzzy matching against local collection	Python

ϟ Workflow Comparison

Feature	Deezer	Spotify	Discography	Global	Playlist	Batch
Setup Required	None ⚡	API credentials	None	None for Deezer	None for Deezer	None for Deezer
CLI Available	✅	✅	✅	✅	✅	✅
GUI Available	✅	✅	✅	✅	✅	✅
Auto-Paste to Deemix	✅	✅	✅	✅	✅	✅
Bulk Download	❌	❌	✅ (all albums)	✅ (artist URLs)	✅ (all albums)	✅ (file list)
URL Input	❌	❌	❌	✅ (any URL)	✅ (playlist)	❌

ϟ Quick Decision Guide

Found a URL? → Global Resolver (any Spotify/Deezer URL)
Found a playlist? → Playlist Downloader (all) or Riley's Playlist Resolver (missing only)
Have a list of albums? → Batch Downloader
Want full discography? → Discography to Deemix
Currently playing? → Currently Playing to Deemix
Search by name? → Deezer to Deemix (fastest) or Spotify to Deemix

ϟ Advanced Usage

Python Resolver Options

All Python resolvers support these options:

# Verbose logging
python3 deezer/deezer-resolver.py --band "Artist" --album "Album" --verbose

# Print URL instead of clipboard
python3 deezer/deezer-resolver.py --band "Artist" --album "Album" --no-clipboard

# Full search query
python3 deezer/deezer-resolver.py --query "Artist Album"

# Interactive mode (prompts for input)
python3 deezer/deezer-resolver.py

# Pipe from stdin
echo "Artist - Album" | python3 deezer/deezer-resolver.py

Keyboard Maestro Integration

Ready-to-use macros included in macros/ folder - just import and use!

For custom macros, here's a basic example for album downloads:

Prompt for Input: Artist name
Prompt for Input: Album name

Execute Shell Script:

/path/to/deemixkit/deezer/deezer-to-deemix.sh "$KMVAR_Artist" "$KMVAR_Album"

Display Text: "Album added to Deemix!"

See docs/Keyboard Maestro DeemixKit.md for detailed macro examples and the macros/ folder for complete pre-built workflows.

Raycast Integration

Ready-to-use Raycast scripts included in raycast/ folder!

Quick Setup

# Symlink all scripts to Raycast
ln -s /path/to/DeemixKit/raycast/*.sh ~/.config/raycast/script-commands/

# Update DEEMIXKIT_PATH in each script to your installation path

Then reload Raycast: Type "Reload Script Commands" in Raycast

Available Scripts

All scripts prefixed with deemix- for easy discovery:

Script	Arguments	Description
Deemix - Deezer	Artist, Album	Search Deezer and download
Deemix - Spotify	Artist, Album	Search Spotify and download
Deemix - Discography	Artist, Album	Download full discography
Deemix - Global	URL (optional)	Resolve any Spotify/Deezer URL
Deemix - Playlist	Playlist URL	Download all albums from playlist
Deemix - Text File	Service, File	Download from text file
Deemix - Rileys Resolver	Playlist URL	Get only missing albums
Deemix - Currently Playing	None	Download current track

See raycast/README.md for detailed setup and usage instructions.

ϟ Additional

ϟ Troubleshooting

"Spotify API credentials not configured"

Solution: Set up credentials file as described in the Configuration section above.

"Failed to resolve link"

Solutions:

Check spelling of artist/album names
Verify network connection
For Spotify: Ensure your API credentials are valid
Try a different album name (some may not be available)

AppleScript permission errors

Solution: Grant System Events accessibility permission:

System Settings → Privacy & Security → Accessibility
Add Terminal or Script Editor to the list
Or grant permission when prompted

Deemix doesn't open

Solutions:

Ensure Deemix is installed from deemix.org
Check that Deemix is in your Applications folder
Try launching Deemix manually first

"Failed to copy to clipboard"

Solutions:

# Install pyperclip library
pip install pyperclip

ϟ Project Structure

DeemixKit/
├── README.md                      # This file
├── LICENSE                        # MIT License
├── scripts/                       # Utility scripts
│   ├── paste-to-deemix.applescript  # Shared paste utility
│   └── rileys-collection-matcher.py  # Fuzzy matching module
├── docs/                          # Documentation
│   ├── CREDENTIALS.md             # API credentials setup
│   ├── AGENTS.md                  # Developer guide for AI agents
│   ├── DeemixKit.md               # Project overview
│   ├── Keyboard Maestro DeemixKit.md
│   └── ...
├── deezer/                        # Deezer workflows
│   ├── deezer-resolver.py         # Python resolver
│   ├── deezer-to-deemix.sh        # CLI wrapper
│   ├── deezer-to-deemix.applescript
│   └── docs/                      # Deezer-specific docs
├── spotify/                       # Spotify workflows
│   ├── spotify-resolver.py        # Python resolver
│   ├── spotify-to-deemix.sh       # CLI wrapper
│   ├── spotify-to-deemix.applescript
│   ├── currently-playing-to-deemix.js
│   └── docs/                      # Spotify-specific docs
├── discography/                   # Discography workflow
│   ├── discography-resolver.py    # Python resolver
│   ├── discography-to-deemix.sh   # CLI wrapper
│   ├── discography-to-deemix.applescript
│   └── docs/                      # Discography-specific docs
├── global/                        # Universal resolver
│   ├── global-resolver.py         # Python resolver
│   ├── global-resolver.sh         # CLI wrapper
│   ├── global-resolver.applescript
│   └── docs/                      # Global-specific docs
├── playlist/                      # Playlist workflows
│   ├── playlist-downloader.py     # Generic playlist tool
│   ├── playlist-downloader.sh
│   ├── rileys-playlist-resolver.py # Personal tool with filtering
│   ├── rileys-playlist-resolver.sh
│   └── docs/                      # Playlist-specific docs
├── raycast/                       # Raycast script commands
│   ├── deemix-deezer.sh
│   ├── deemix-spotify.sh
│   ├── deemix-discography.sh
│   ├── deemix-global.sh
│   ├── deemix-playlist.sh
│   ├── deemix-textfile.sh
│   ├── deemix-rileys.sh
│   ├── deemix-currently-playing.sh
│   └── README.md                  # Setup instructions
├── batch/                         # Batch download workflow
│   ├── batch-downloader.sh        # CLI wrapper
│   ├── batch-downloader.applescript
│   ├── albums.txt                 # Example file
│   └── docs/                      # Batch-specific docs
├── install/                       # Automated installer
│   ├── Install DeemixKit.command  # Double-click to install
│   ├── install.sh                 # Installer script
│   └── README.md                  # Installation guide
├── examples/                      # Example configurations
│   └── credentials.json.example
└── macros/                        # Ready-to-use Keyboard Maestro macros

ϟ Security & Contributing

Security

Never commit credentials: The .gitignore file prevents accidental commits of API keys
Use credentials.example: Commit only example files, never real credentials
File permissions: Set restrictive permissions on credentials files: chmod 600 ~/.config/deemixkit/credentials.json

Contributing

When adding new scripts:

Follow existing patterns (see docs/AGENTS.md for developer guide)
Read credentials from ~/.config/deemixkit/credentials.json
Create or update documentation
Update examples/credentials.json.example if adding new services
Test with and without credentials present

ϟ Documentation

docs/CREDENTIALS.md - Detailed credentials setup
docs/AGENTS.md - Developer guide for AI agents
docs/DeemixKit.md - Project overview
Individual service folders contain docs for each tool

ϟ Tips & Tricks

Save AppleScripts as Dock Apps

Open Script Editor
Copy content from deezer/deezer-to-deemix.applescript
Save as "Deezer to Deemix" with File Format: Application
Drag to Dock for one-click access

Create Shell Aliases

Add to your ~/.zshrc or ~/.bash_profile:

alias deemix='./deezer/deezer-to-deemix.sh'
alias spoti='./spotify/spotify-to-deemix.sh'
alias disco='./discography/discography-to-deemix.sh'
alias global='./global/global-resolver.sh'
alias playlist='./playlist/playlist-downloader.sh'
alias batch='./batch/batch-downloader.sh'
alias now='node spotify/currently-playing-to-deemix.js'

Then use short commands:

deemix "Artist" "Album"
spoti "Artist" "Album"
disco "Artist" "Album"
global "https://open.spotify.com/artist/..."
playlist "https://open.spotify.com/playlist/..."
batch -f albums.txt
now

Batch Downloads

#!/bin/bash
# Download multiple albums at once
albums=("Metallica:Master of Puppets" "Pink Floyd:The Wall" "Radiohead:OK Computer")
for album in "${albums[@]}"; do
  IFS=':' read -r artist name <<< "$album"
  ./deezer/deezer-to-deemix.sh "$artist" "$name"
  sleep 10  # Wait between downloads
done

ϟ Acknowledgments

Deemix - Music downloader application
Spotify Web API - Music service API
Deezer API - Music service API

ϟ Support

For issues, questions, or suggestions:

Check the Troubleshooting section above
Review individual script documentation files
Open an issue on GitHub

Made for music enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
batch		batch
deezer		deezer
discography		discography
docs		docs
examples		examples
global		global
install		install
macros		macros
playlist		playlist
raycast		raycast
scripts		scripts
spotify		spotify
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

deathrashed/deemixkit

Folders and files

Latest commit

History

Repository files navigation

DeemixKit

What is DeemixKit?

Key Features

Quick Start

Prerequisites

Installation

Quick Install (Recommended)

Manual Installation

Configuration (Spotify Only)

ϟ Usage Examples

Search Deezer Album (Fastest - No Setup)

Search Spotify Album

Download Full Discography

Download All Albums from Playlist

Download from Text File

Universal URL Resolver

Download Currently Playing Track (Spotify)

ϟ What's Included

Universal Tools

Service-Specific Tools

Complete Workflows

Keyboard Maestro Macros

Special Scripts

ϟ Workflow Comparison

ϟ Quick Decision Guide

ϟ Advanced Usage

Quick Setup

Available Scripts

ϟ Additional

"Spotify API credentials not configured"

"Failed to resolve link"

AppleScript permission errors

Deemix doesn't open

"Failed to copy to clipboard"

Security

Contributing

Save AppleScripts as Dock Apps

Create Shell Aliases

Batch Downloads

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages