therepanic/spotify-telegram-sync repository overview

⁠Features

• Sync currently playing / saved tracks from Spotify to Telegram Profiles (Saved Messages).
• Pin synced tracks in Telegram; unpinning removes them from the profile.
• Uses a rolling cache of tracks - old tracks are automatically removed once the cache window advances.
• Supports using an existing Spotify refresh token (optional) so you can run the container on remote machines without a browser.
• Works with either a Telethon session file or a Telegram tdata folder (desktop Telegram data).

⁠Screenshot / Visual

(left: Spotify, right: Telegram - shows how the sync flows)

⁠Quick start - Docker

Run the image from Docker Hub (recommended):

docker run -d \
  --name spotify-telegram-sync \
  -p 7000:7000 \
  -v /root/session.session:/app/session.session \
  -e SPOTIFY_CLIENT_SECRET="<YOUR_SPOTIFY_CLIENT_SECRET>" \
  -e SPOTIFY_CLIENT_ID="<YOUR_SPOTIFY_CLIENT_ID>" \
  -e SPOTIFY_REDIRECT_URI="http://127.0.0.1:7000/callback" \
  -e SPOTIFY_SCOPE="user-read-currently-playing" \
  -e SPOTIFY_REFRESH_TOKEN="<OPTIONAL_REFRESH_TOKEN>" \
  -e TELEGRAM_API_ID="<YOUR_TELEGRAM_API_ID>" \
  -e TELEGRAM_API_HASH="<YOUR_TELEGRAM_API_HASH>" \
  -e TRACKS_CACHE_SIZE=20 \
  -e TRACKS_DOWNLOAD_WORKERS=2 \
  -e TRACKS_BACKEND=mixed_track_backend.MixedTrackBackend \
  -e CLEAN_TRACKS=True \
  therepanic/spotify-telegram-sync:latest

If you prefer to build locally:

# from project root
docker build -t spotify-telegram-sync:latest .
# then run the same docker run command (replace image name)

⁠Environment variables / configuration

⁠Track backends

TRACKS_BACKEND controls where track audio and metadata are obtained from. Three backends are supported:

• mixed_track_backend.MixedTrackBackend - default. Uploads a zero-duration placeholder immediately and then tries to replace that exact slot later with the original audio from spotdl.
• spotdl_track_backend.SpotdlTrackBackend - original-only mode. Uses spotdl logic to locate and download audio for the requested Spotify track.
• zero_track_backend.ZeroTrackBackend - fallback. If no backend can find/download the actual audio, this backend uploads a message to Telegram containing the track metadata and cover art but no audio (the uploaded track will have 0 seconds duration).

⁠Session volume (Telegram auth)

You must provide a Telegram session. Two supported ways:

• Telethon session file (recommended):

  -v /root/session.session:/app/session.session
  

  Copy

• tdata folder from your Desktop Telegram installation (Opentele will convert it to a Telethon session automatically):

  -v /root/tdata:/app/tdata
  

  Copy

If neither is present, the container will walk you through the auth flow on first run (it depends on Telethon/opentele capabilities).

⁠Auth / obtaining a Spotify refresh token

1. Create a Spotify App at: https://developer.spotify.com/dashboard⁠ and copy CLIENT_ID, CLIENT_SECRET and set a REDIRECT_URI (e.g. http://127.0.0.1:7000/callback).
2. Create a Telegram app at: https://my.telegram.org/apps⁠ and copy API_ID and API_HASH.
3. Start the container. Open http://<HOST>:7000/auth in your browser and follow the Spotify authorization flow.
4. Spotify will redirect to the callback you registered; after authorization the container logs will include the refresh_token (if you need one to run headlessly, copy it from the logs and set SPOTIFY_REFRESH_TOKEN in your run command on the remote machine).

⁠How it works (high level)

1. The service reads your Spotify playback / currently playing via the Web API (spotipy).
2. For tracks that should be shown, the configured backend (default: mixed) prepares a track file or uploadable content.
3. In mixed mode, the service first uploads a zero-duration placeholder and upgrades it later if the original audio download succeeds.
4. The track is uploaded to your Telegram Saved Messages and pinned. When a track falls out of the cache window or is unpinned/removed, the service deletes it from Saved Messages.

This gives the visual effect of "Music on Profiles" - tracks remain visible while they are inside the configured cache window.

⁠Troubleshooting

• No Telegram session / auth fails: ensure session.session or tdata is correctly mounted and readable by the container. Check container logs for Telethon errors.
• Spotify auth redirect fails: confirm SPOTIFY_REDIRECT_URI exactly matches the redirect in your Spotify app settings.
• No refresh token in logs: re-run the /auth flow and watch the container logs carefully after completing the browser authorization; the refresh token is printed once.
• Tracks not uploaded: check the TRACKS_BACKEND configuration and ensure spotdl dependencies are present in the image (they are required for the default mixed mode and for spotdl-only mode). Also verify network access.

⁠Development & Contributing

Contributions are welcome. Open an issue or a pull request with a clear description of the change. If you add backends or make changes to defaults, please update this README.

⁠License

This project is Unlicensed.