my-telegram-apple-music-downloader

Imported from har4s/my-telegram-apple-music-downloader (AGENTS.md). Install upstream with npx skills add har4s/my-telegram-apple-music-downloader. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

A Telegram bot that downloads Apple Music content (songs, albums, playlists) and sends them back to authorized users. The bot uses gamdl (a Python Apple Music downloader) under the hood and processes metadata, lyrics, and cover art before uploading tracks to Telegram.

Tech Stack

• Language: Python 3.12
• Main Dependencies:
  • python-telegram-bot (v22+) - Telegram bot framework with async support
  • gamdl (v2.6+) - Apple Music downloader (wraps yt-dlp, pywidevine)
  • mutagen - MP4 metadata manipulation
  • Pillow - Image processing for cover art thumbnails
  • python-decouple - Environment configuration

Development Commands

Running Locally

# Install dependencies using uv (recommended)
pip install uv
uv pip install -r requirements.txt

# Or using pip directly
pip install -r requirements.txt

# Run the bot
python main.py

Docker Deployment

# Build the Docker image
docker build -t telegram-apple-music-bot .

# Run with docker-compose
cd deployment
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the bot
docker-compose down

Dependency Management

Dependencies are managed in pyproject.toml and compiled to requirements.txt using uv:

# Update requirements.txt after changing pyproject.toml
uv pip compile pyproject.toml -o requirements.txt

Architecture

Core Components

The bot is a single-file application (main.py) with the following key parts:

1. API Initialization (get_api):

   • Lazy initialization of global AppleMusicApi instance
   • Loads Apple Music cookies from ./data/cookies.txt
   • Reuses single API instance across all download requests

2. Downloader Creation (create_downloader):

   • Creates a new AppleMusicDownloader instance per message
   • Configures output path specific to the message (dl-{message_id})
   • Sets save_cover=True to save cover art (equivalent to -s flag)
   • Accepts a codec parameter to configure song quality (ALAC, AAC, AAC_LEGACY)
   • Initializes all downloader types (song, music video, uploaded video)

3. Message Handler (handle_message):

   • Filters messages for URLs (text links or entities)
   • Validates user authorization against TELEGRAM_ADMIN_ID
   • Creates unique download directories per message (dl-{message_id})
   • Delegates to async watcher task with URL list

4. Download Watcher (watch_download):

   • Implements codec fallback mechanism (ALAC → AAC → AAC_LEGACY)
   • For each codec, creates a downloader instance and attempts all URLs
   • If any URL succeeds with a codec, stops trying lower quality codecs
   • Cleans up failed attempts before trying next codec
   • Sends status updates to user
   • On success: processes all .m4a files in download directory
   • Calls prepare_track and prepare_thumbnail for each file
   • Uploads audio with metadata to Telegram
   • Cleans up download directory

5. URL Download (download_url):

   • Uses gamdl Python API to download a single URL
   • Gets URL info and download queue from API
   • Downloads each item in the queue
   • Returns success/failure status

6. Track Preparation (prepare_track):

   • Loads and parses LRC lyrics files (if present)
   • Embeds plain text lyrics in ©lyr tag
   • Embeds synchronized lyrics in custom SYLT atom (JSON format)
   • Adds comment tag with bot signature
   • Returns title and artist for upload

7. Thumbnail Processing (prepare_thumbnail):

   • Reads Cover.jpg from download directory
   • Resizes to 320x320px using Pillow with LANCZOS resampling
   • Returns JPEG BytesIO buffer for Telegram upload

8. Lyrics Parsing (parse_lrc_file):

   • Parses LRC format timestamps: [mm:ss.fff]text
   • Converts to milliseconds for MP4 SYLT atom
   • Returns both timestamped entries and plain text

Configuration

Environment variables are loaded via python-decouple in config.py:

• TELEGRAM_TOKEN (required): Bot token from @BotFather
• TELEGRAM_ADMIN_ID (required): Comma-separated list of authorized user IDs
• REDIS (unused): Legacy config, not currently used by the bot

File Structure

.
├── main.py           # Single-file bot with all handlers and logic
├── config.py         # Environment variable parsing
├── pyproject.toml    # Python package definition
├── requirements.txt  # Compiled dependencies (generated by uv)
├── Dockerfile        # Container build with ffmpeg installation
└── deployment/
    ├── docker-compose.yml   # Service definition
    ├── example.env          # Environment template
    └── _data/
        └── cookies.txt      # Apple Music session cookies (required)

Important Implementation Details

gamdl Integration

The bot uses the gamdl Python API directly instead of spawning subprocesses:

• Initializes AppleMusicApi from Netscape cookies at ./data/cookies.txt (global, lazy initialization)
• Creates a new AppleMusicDownloader instance per message with message-specific configuration
• Each downloader is configured with its own output path (dl-{message_id}) and save_cover=True
• Downloads are handled through get_url_info() → get_download_queue() → download() flow

The cookies file must contain a valid Apple Music session with an active subscription. Users can extract cookies using browser extensions (Export Cookies for Firefox, Open Cookies.txt for Chrome).

Codec Fallback System

The bot implements automatic codec fallback to ensure successful downloads:

• Priority order: ALAC (lossless) → AAC (high quality) → AAC_LEGACY (legacy compatibility)
• Fallback logic: Tries each codec in order until at least one URL succeeds
• Cleanup between attempts: Removes failed downloads before trying next codec
• Benefits: Handles cases where higher quality codecs aren't available for certain tracks

The codec priority list is defined in CODEC_PRIORITY at the top of main.py.

MP4 Metadata Tags

The bot uses iTunes-style MP4 atoms (see TAGS dict at top of main.py):

• Standard tags: ©nam (title), ©ART (artist), ©alb (album), etc.
• Custom SYLT atom: ----:com.apple.iTunes:SYLT stores synced lyrics as JSON array
• Comment tag: Adds t.me/myfuckinglifetimes watermark

Lyrics Format

Synchronized lyrics are stored in two formats:

1. Plain text (©lyr tag): Newline-separated lyrics without timestamps
2. Synced JSON (SYLT atom): Array of {"time_ms": int, "text": str} objects

The LRC parser supports multiple timestamps per line (karaoke-style) and handles fractional seconds (1-3 digits).

Async Task Management

The bot uses python-telegram-bot's task system:

• context.application.create_task() spawns background download watchers
• Multiple downloads can run concurrently (one per message)
• Each task is isolated with its own download directory and downloader instance
• Single global AppleMusicApi instance is reused across all tasks
• Cleanup happens in finally block to ensure directories are removed

Error Handling

• Download failures are caught per-URL in download_url() and logged
• If all URLs fail, user receives "Download failed" message
• Missing .m4a files after download triggers "Nothing to upload" message
• Thumbnail processing failures are logged but don't block upload
• All exceptions in watch_download are caught to send error message to user

Common Workflows

Changing Codec Priority

To modify which codecs are tried and in what order:

1. Edit the CODEC_PRIORITY list at the top of main.py
2. Available codecs: SongCodec.ALAC, SongCodec.AAC, SongCodec.AAC_LEGACY
3. Codecs are tried in list order (first to last)
4. To disable fallback: use only one codec in the list

Adding New Metadata Fields

1. Add the atom name to TAGS dict (use mutagen docs for atom names)
2. Extract value from gamdl output or LRC file
3. Set in track.tags[TAGS["field_name"]] in prepare_track
4. Call track.save() before returning

Modifying Lyrics Processing

The lyrics pipeline is:

1. load_lyrics checks for .lrc file next to .m4a
2. parse_lrc_file extracts timestamps and text
3. prepare_track embeds both plain and synced formats

To change format, modify parse_lrc_file or add a new parser function.

Changing Image Processing

Thumbnail generation in prepare_thumbnail:

• Current: 320x320px JPEG, LANCZOS resampling
• To change dimensions: modify ImageOps.fit() size tuple
• To change format: modify fitted.save(buffer, format="...")
• Return None to skip thumbnail (Telegram will use default)

Docker Container Details

The Dockerfile installs:

1. Static ffmpeg binary (required by gamdl for audio processing)
2. Python 3.12 slim base image
3. All requirements from requirements.txt

The container expects:

• Volume mount: ./deployment/_data:/app/data (for cookies.txt)
• Environment variables: TELEGRAM_TOKEN, TELEGRAM_ADMIN_ID

Security Considerations

• User authorization is checked on every message via TELEGRAM_ADMIN_ID
• Cookies file contains Apple Music session - treat as sensitive
• Bot signature is added to comment tag to identify downloaded tracks
• No rate limiting or queue management - handle with care in production