Slack Apple Music Downloader Bot

A Slack bot that allows users to seamlessly search and download tracks and albums from Apple Music directly via Slack mentions. It streams live download progress back to Slack!

Features

• Search: Interactive Slack Block Kit menu powered by the iTunes API (@MusicBot search Daft Punk). It includes built-in deduplication for clean results.
• Download: Parses Apple Music URLs and initiates background downloads (@MusicBot download <url>).
• Live Progress: Replaces the Slack message with an active, real-time downloading progress bar. It dynamically updates states (e.g., Downloading, Decrypting, Muxing).
• Graceful Error Handling: Instantly detects backend errors (e.g., Invalid CKC, Unavailable tracks) and outputs truncated error logs to Slack, avoiding API rate limits.

Prerequisites

• Python: 3.9 or higher.
• Package Manager: uv for fast dependency management.
• Backend Downloader: The amdl binary must be installed and configured in your path (e.g. ~/.local/bin/amdl).
• Slack App Tokens:
  • An App-Level Token (xapp-...) with connections:write (Socket Mode).
  • A Bot Token (xoxb-...) with chat:write and app_mentions:read scopes.

Installation & Setup

1. Clone the repository:

   git clone <repository-url>
   cd music-bot

2. Configure Environment Variables: Copy the example environment file and fill in your Slack App tokens:

   cp .env.example .env

Environment Variables

The bot is highly configurable via the .env file. Only the Slack tokens are strictly required.

Variable	Description	Default
SLACK_APP_TOKEN	App-Level Token (xapp-...) used for Socket Mode.	Required
SLACK_BOT_TOKEN	Bot User OAuth Token (xoxb-...) used to call Slack web APIs.	Required
LOG_LEVEL	Logging verbosity (e.g., INFO, DEBUG).	INFO
SEARCH_RESULT_LIMIT	Max number of items returned in the Slack search dropdown menu.	10
AMDL_EXECUTABLE_PATH	Absolute path to the amdl binary. Overrides the automatic PATH search.	Auto-detected

3. Install Dependencies (Development): You can run the bot directly during development using uv:

   uv run main.py

Production Deployment (Systemd)

We provide a convenient bash script to automatically configure and start the bot as an independent background service on Linux using Systemd.

1. Run the installation script as root:

   sudo ./install.sh

2. The bot is now running in the background! You can manage it with:

   • Check Status: sudo systemctl status music-bot
   • View Live Logs: sudo journalctl -fu music-bot
   • Stop Service: sudo systemctl stop music-bot

Usage

Tag the bot in any channel it has been invited to:

• To download via URL: @MusicBot download https://music.apple.com/...
• To search for music: @MusicBot search <query>