Spotify Telegram Profile Music

Unofficial personal automation that mirrors your Spotify currently playing track into Telegram profile music.

This project is a proof of concept. It does not download audio from Spotify. When a matching iTunes preview is available, the preview clip is downloaded locally, uploaded to your private Telegram cache channel, and used as the Telegram profile music document.

Status

• Spotify OAuth PKCE login
• Reads current Spotify track with user-read-currently-playing
• Finds iTunes preview clips with artist/title matching
• Uploads previews to a private Telegram cache channel
• Calls Telegram account.saveMusic
• Supports private Telegram invite links
• Skips repeated updates for the same track

Requirements

• Python 3.11+
• Spotify developer app
• Telegram API app credentials from https://my.telegram.org/apps
• A private Telegram channel for cached preview uploads

Project Layout

• src/spotify_bridge.py - Spotify OAuth, currently-playing reads, and end-to-end sync
• src/itunes_preview.py - iTunes Search API preview lookup and matching
• src/telegram_cache.py - Telegram cache upload, profile music save, and local mapping tools
• assets/flow.webp - README flow diagram

Install

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Copy the example environment:

cp .env.example .env

Then fill in .env or export the variables in your shell:

export SPOTIFY_CLIENT_ID="your_spotify_client_id"
export TELEGRAM_API_ID="123456"
export TELEGRAM_API_HASH="your_telegram_api_hash"
export TELEGRAM_PHONE="+10000000000"
export TELEGRAM_CACHE_CHANNEL="https://t.me/+your_private_invite_hash"

Do not commit .env.

Spotify Setup

Create an app in the Spotify Developer Dashboard:

https://developer.spotify.com/dashboard

Add this redirect URI exactly:

http://127.0.0.1:8888/callback

Login once:

python3 src/spotify_bridge.py spotify-login

If your dashboard uses localhost instead, pass the same redirect URI to the CLI:

python3 src/spotify_bridge.py spotify-login \
  --redirect-uri "http://localhost:8888/callback"

There is also a manual fallback:

python3 src/spotify_bridge.py spotify-login --manual

Telegram Setup

Create a Telegram API app:

https://my.telegram.org/apps

Create a private Telegram channel for cached preview uploads. TELEGRAM_CACHE_CHANNEL accepts:

• @channel_username
• https://t.me/+inviteHash
• https://t.me/joinchat/inviteHash
• numeric channel id

The first Telegram command may ask for your login code and 2FA password. The session is stored locally in .telegram_preview_cache.session.

Usage

Check what Spotify reports:

python3 src/spotify_bridge.py current

Sync once:

python3 -u src/spotify_bridge.py sync-once

Run continuously:

python3 -u src/spotify_bridge.py watch --interval 30

If the current track is paused and you still want to sync it:

python3 -u src/spotify_bridge.py sync-once --include-paused

Force re-saving the current track:

python3 -u src/spotify_bridge.py sync-once --force

Remove a bad local Spotify-to-Telegram mapping:

python3 src/telegram_cache.py unlink \
  --spotify-track-id "spotify:track:..."

Local Files

Runtime files are intentionally ignored by Git:

• .spotify_token.json
• .telegram_preview_cache.session
• .bridge_state.json
• cache_db.json
• previews/

cache_db.json maps Spotify track IDs to Telegram uploaded audio documents. It may contain private channel IDs and should stay local.

Matching Notes

iTunes preview matching is heuristic. The matcher heavily penalizes artist mismatches so tracks with the same title but different artists are not silently accepted. If no safe match exists, the sync returns itunes_preview_failed.

Legal Notes

This is an unofficial personal automation project. It is not affiliated with Spotify, Apple, Telegram, or any rightsholder.

The project does not download music from Spotify. It uses Spotify only for currently-playing metadata. Apple iTunes previews are short preview clips fetched locally by the user when available. Do not redistribute downloaded preview files.

Review and follow:

• Spotify Developer Policy: https://developer.spotify.com/policy
• Apple iTunes Search API documentation: https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/
• Telegram API documentation: https://core.telegram.org/api

License

MIT. See LICENSE.