This is a high-level summary of the most important changes.
Version 3.3.1 makes explicit --debug and --verbose flags cover configuration startup while preserving their precedence over saved defaults, and stops settings, diagnostics and fallback notices from being coloured as errors.
Bug fixes:
- BUGFIX: Diagnostic flags cover configuration startup - Explicit
--debugand--verboseflags now take effect before configuration errors are reported, then remain enabled after the selected config loads - BUGFIX: Accurate error colouring - Lines that only mention a problem word are no longer painted red. The
Disappeared timerandError retry timerrows shown by--verbose, every[DEBUG]trace line, including the ones recording a retried or handled request, and the notice about switching to the web-player backend now keep their normal colours, while real failures stay red
Version 3.3 adds coloured terminal output with a customizable theme, fixes false Last.fm outage alerts, retries failed alert delivery and escapes a friend's display name in email notifications. Pillow is now optional, config files are parsed instead of executed, access tokens are reused until they expire and releases ship with a checksum file plus a signed build attestation.
Features and improvements:
- NEW: Coloured terminal output - Live output is now coloured by default: usernames, track, playlist and album names, dates, durations, counters and links each get their own colour, while errors, warnings and received signals are highlighted as whole lines. Override any part through
COLOR_THEME, which merges over the built-in theme, and turn colour off with--no-colororCOLORED_OUTPUT = False. Colour switches itself off when output is redirected or piped, whenTERMis unset ordumband whenNO_COLORis set. Log files stay plain text, sogrepandtailare unaffected, and the existing grc recipe still colours saved logs. Install the optionalcoloramapackage for the classic Windows Command Prompt - CONFIG CHANGE: Artwork is now an optional extra - Pillow is no longer required. Artwork moved to the
notification-imagesextra andNTFY_IMAGESnow defaults toFalse. Install withpip install "spotify_monitor[notification-images]"or let setup do it for you. Upgraders who want cover art back should install the extra and setNTFY_IMAGES = True - IMPROVE: Fewer Friend Activity requests - Cached access tokens are now reused until they expire, roughly halving the number of requests
- IMPROVE: Refreshed, automatically published Docker images - Both images now run Python 3.13 on Debian 13 with a digest-pinned, patched base and no
pipin the runtime, so a fresh pull carries no known fixable high/critical vulnerabilities. The secret grabber image is now built, versioned and published automatically, runs as a non-root user and is rebuilt weekly for security updates - IMPROVE: Clearer ntfy webhook customization -
WEBHOOK_TEMPLATE,WEBHOOK_USERNAMEandWEBHOOK_AVATAR_URLare documented as Discord-only; customize ntfy delivery throughWEBHOOK_HEADERS - IMPROVE: Checksums and signed attestation for releases - Releases now ship a
SHA256SUMS.txt, a signed build attestation checkable withgh attestation verifyand the attestation bundle itself as an.intoto.jsonlasset, so provenance can be verified from the downloaded files without calling GitHub - IMPROVE: Releases publish only after the tests pass - PyPI and Docker Hub releases can no longer publish unless the full test suite passes, every workflow action is pinned to a commit SHA, release tags reach the workflow through the environment instead of a shell command and
--versionis checked against package metadata and these notes - IMPROVE: Automated checks on every change - A pinned Ruff lint pass now runs in CI ahead of the test suite, which covers Python 3.9 through 3.14 plus a Windows job. Optional pre-commit hooks and a shared
.editorconfigcatch the same issues before you commit - IMPROVE: Continuous security scanning - Dependencies, images and source are scanned on every change and weekly, with a published SBOM, Dependabot coverage for Python dependencies and a public OpenSSF Scorecard rating
- IMPROVE: Security policy and support guidance - Added private vulnerability reporting, SUPPORT.md, contribution guidance, a code of conduct, a dependency licensing notice and issue templates that collect version, install method and
--doctoroutput - IMPROVE: Corrected and improved wording in setup wizard and doctor preflight
Bug fixes:
- BUGFIX: No more false Last.fm outages - Repeated plays are now matched pairwise instead of greedily
- BUGFIX: Alerts retried until every channel succeeds - Failed Friend Activity and scrobble-health alerts stay pending until every enabled email and webhook channel goes through. Successful channels are not sent again while another channel retries
- BUGFIX: Clearer missing-play alerts - Outage notifications now name the first missing play and correctly label the displayed tracks
- BUGFIX: Reliable Spotify links - Links built from a Spotify URI are now parsed exactly instead of guessed
- BUGFIX: Accurate dotenv and activity-file state -
SIGHUPnow clears removed secrets and resets caches while activity flag files are written atomically - BUGFIX: Hardened email notifications - A friend's display name is now escaped in emails, so it can no longer inject markup, a live link or a tracking image
- BUGFIX: Terminal-safe Spotify text - Spotify-supplied friend, artist, track, album and context names are stripped of terminal control sequences before reaching the console or log file, including
--list-friendsand normal monitoring output. Colour codes are the one exception, since they can only change how text looks, and they are still removed from everything written to a log file - BUGFIX: Webhook delivery respects
VERIFY_SSL- Discord and ntfy now honor the same TLS setting as other requests and follow no redirects, so alert content and headers cannot reach an unconfigured host - BUGFIX: Configuration files are read as data - The config file is now parsed instead of executed, so it can no longer run code at startup. Settings dropped by older upgrades are ignored gracefully and config backups keep owner-only permissions
- BUGFIX: Connectivity check respects configuration - The startup internet check now honors
CHECK_INTERNET_URL,CHECK_INTERNET_TIMEOUTandVERIFY_SSL - BUGFIX: Reliable anti-hang watchdog - The watchdog can no longer be disabled by a nested request timer
- BUGFIX: Safer debug utilities -
spotify_monitor_totp_testnow accepts only HTTPS Spotify destinations for token validation and follows no redirects - BUGFIX: Smaller fixes - Generated config preserves emoji, track IDs are validated before local playback and the direct Linux container instructions map host IDs when they differ from 1000
Version 3.2.1 makes Spotify-to-Last.fm token refreshes more resilient, adds portable log files and streamlines Friend Activity setup, help and diagnostics.
Features and improvements:
- IMPROVE: Portable log separators - The new
ASCII_LOG_SEPARATORSsetting controls whether separator-only lines saved to log files use ASCII hyphens."Auto"enables them on Windows by default,"On"enables them on every operating system and"Off"preserves Unicode separators. Terminal separators stay Unicode. Log files and all other logged text remain UTF-8. - IMPROVE: Flexible setup intervals - The setup wizard accepts polling interval durations such as
30s,2m,1.5h,1h 30mand1dwhile still saving the value as seconds - IMPROVE: Focused command-line help -
--helpnow groups concise examples into Friend Activity and Scrobble Health sections so the main setup, monitoring and diagnostic commands are easier to find - IMPROVE: Actionable Doctor output - Details remain attached to their checks, final target-specific log destinations are validated and
pycookiecheatis clearly identified as a Chromium-only import dependency that Firefox does not need - IMPROVE: Clearer Friend Activity guidance - Setup examples consistently document Spotify user IDs, URIs and profile URLs while in-app recovery links open the correct target guide
Bug fixes:
- BUGFIX: Resilient recent-play token refreshes - Spotify-to-Last.fm monitoring now retries a connection failure, timeout or temporary 5xx response once after a short delay. Rate limits and rejected credentials still return directly to the existing backoff and recovery handling
Version 3.2 adds Spotify-to-Last.fm scrobble health monitoring plus flexible webhook runtime controls and request customization for Discord, ntfy and advanced integrations.
Features and improvements:
- NEW: Added Spotify-to-Last.fm scrobble health monitoring to address new Spotify's six-month re-authorization requirement and warn when Spotify scrobbles stop showing up on Last.fm. Reconnecting may recover only the 50 most recent Spotify plays, so early detection reduces the risk of a permanent gap. The monitor compares recent plays automatically then sends console, email or webhook alerts when the problem persists and again when scrobbling recovers
- NEW: Added one-run webhook provider, URL and error-notification controls while retaining
--set-webhook-urlas the recommended way to save private destinations - NEW: Added customizable Discord-format payloads through
WEBHOOK_AVATAR_URL,WEBHOOK_TEMPLATE,WEBHOOK_TRANSFORMSand placeholder-awareWEBHOOK_HEADERS - NEW: Added compact ntfy activity alerts through
NTFY_SHORTwhile keeping Discord, email and error notification details unchanged (thanks @tomballgithub, #44) - IMPROVE: Added webhook request validation during Doctor checks and delivery plus automatic provider correction for standard Discord and
ntfy.shURLs - IMPROVE: Split the startup notification summary into compact email and webhook rows with short labels and unstarred continuation lines across concise, verbose and logged views (thanks @tomballgithub, #46)
- IMPROVE: Added portable beginner Python installation walkthroughs for Windows, macOS and Debian-family Linux systems
Bug fixes:
- BUGFIX: Applied terminal-width auto-detection when
TRUNCATE_CHARS = 999comes from configuration while preserving--truncateprecedence and skipping truncation when logging is disabled (thanks @tomballgithub, #45) - BUGFIX: Kept long ntfy text notifications below the server's 4 KB attachment boundary and added a visible truncation marker
- BUGFIX: Made
SIGHUPclear cached Spotify authentication after credential rotation and redetect Discord or ntfy when the private webhook destination changes
Bug fixes:
- BUGFIX: Updated the built-in guide link to the renamed Setup & First Run page so CLI help and recovery guidance no longer point to the retired Quick Start URL
Version 3.1 makes Docker onboarding portable across macOS, Linux and Windows. Setup now centers on host-aware Firefox authentication, keeps configuration and secrets on the persistent /data bind mount and carries exact Doctor and monitoring commands through recovery.
Features and improvements:
- IMPROVE: Kept Firefox import as the recommended Docker authentication path while making its deferred workflow explicit. Setup now asks whether Docker runs on macOS, standard Linux, Linux with Snap, Linux with Flatpak, Windows PowerShell or Windows Command Prompt then prints the matching read-only profile mount
- NEW: Added Windows-host Firefox import for direct Docker and Docker Compose through the normal
%APPDATA%\Mozilla\Firefoxprofile root with shell-specific PowerShell and Command Prompt commands - IMPROVE: Deferred Doctor until Firefox authentication has been imported. Container setup now finishes with ordered commands to import the login, verify authentication and the target then start monitoring
- IMPROVE: Preserved setup guidance across one-time authentication commands by keeping terminal history visible and repeating the exact Doctor and monitoring commands after a successful Firefox import
- IMPROVE: Printed the install-aware monitoring command after a successful Doctor run while preserving explicit or saved targets and selected configuration files
Bug fixes:
- BUGFIX: Fixed generated Docker commands that used the container UID
10001:10001and always assumed the Linux~/.mozilla/firefoxprofile path. macOS commands omit Linux user mapping while Linux commands resolve the host user and group IDs in the host shell - BUGFIX: Stopped standalone container recovery guidance from presenting one Linux-only Firefox command when the Docker host is unknown
- BUGFIX: Anchored default container setup files to the bind-mounted
/datadirectory so the generated configuration and dotenv files survive the temporary setup container - BUGFIX: Rejected Docker setup destinations outside
/datainstead of saving ephemeral files then printing commands for different paths - BUGFIX: Generated direct Docker commands with
${PWD}for macOS, Linux and Windows PowerShell then switched to%cd%for Windows Command Prompt while retaining Linux user mapping - BUGFIX: Saved the selected dotenv destination in generated configuration so later config-only starts and secret reloads keep using it
- BUGFIX: Printed an explicit Compose monitoring command when setup uses nondefault config or dotenv paths instead of falling back to hardcoded defaults
- BUGFIX: Preserved the selected configuration path through the hidden
--set-sp-dcfallback and its Doctor and monitoring guidance - BUGFIX: Prevented a Windows traceback after Ctrl+C when monitoring was started directly from setup. The setup parent now treats its duplicate console interrupt as the same clean termination already handled by the monitoring child
Features and improvements:
- IMPROVE: Made Firefox login import the recommended Docker and Docker Compose authentication path. A one-time read-only host profile mount imports
sp_dcinto the persistent.envfile, later runs no longer need the browser mount and hidden manual cookie entry remains available as a fallback - IMPROVE: Updated
spotify_monitor_totp_test --fetch-secretsto scan current web-player bundles for inline TOTP secret objects while retaining the original runtime hook for older bundle formats
Bug fixes:
- BUGFIX: Fixed Docker Compose startup after guided setup. The default service command now loads
/data/.envexplicitly, preventingdocker compose upfrom reporting a missingSP_DC_COOKIEwhen setup and doctor already saved and validated it
Version 3.0 focuses on making Spotify Monitor easier to set up, safer to configure and easier to recover when something goes wrong. It adds guided onboarding, simpler Spotify login, Docker Compose, clearer terminal output and Discord + ntfy webhook alerts while keeping advanced client mode available for experienced users.
Special thanks to @tomballgithub for testing this release in real time and providing valuable feedback.
Features and Improvements:
- NEW: Added an automatic public web-player metadata backend for track and public playlist details. Spotify's current Development Mode restrictions can block the required legacy Web API endpoints, so version 3.0 can retrieve the same monitoring data without depending on a new Spotify OAuth app. It refreshes temporary tokens, adapts when Spotify changes web-player queries and retries brief Spotify service failures automatically
- IMPROVE: Made Spotify OAuth app credentials optional in cookie and client modes. Existing complete
SP_APP_CLIENT_IDandSP_APP_CLIENT_SECRETconfigurations remain supported and are tried first. If the legacy Web API is restricted, track and playlist metadata switch independently to the web-player backend. Startup output now shows the login token source and metadata backend separately - IMPROVE: Clarified that Spotify requires the owner of every Development Mode app to keep an active Premium subscription regardless of app creation date. Doctor recovery guidance now checks this first while retaining automatic web-player fallback because an HTTP 403 alone does not prove its cause
- BUGFIX: Preserved Spotify-curated playlist detection when the legacy Web API returns HTTP 404. Web-player owner metadata now distinguishes a curated-playlist restriction from an app-wide legacy restriction and caches the correct routing decision
- NEW: Added webhook notifications for Discord and ntfy for active, inactive, tracked-song, every-song, loop and error events. Choose the service in the setup wizard or with
WEBHOOK_PROVIDER, store the private URL with--set-webhook-urland test it with--send-test-webhook. Discord remains the default while ntfy uses its native topic API. Email and webhook delivery work independently - NEW: Added authentication for protected ntfy topics via
NTFY_ACCESS_TOKENsupport with Bearer authentication and customAuthorizationheaders inWEBHOOK_HEADERS - NEW: Added playlist and album artwork in ntfy alerts, enabled by default and configurable through
NTFY_IMAGES. Set it toFalseto keep ntfy alerts text-only. Active and inactive alerts prefer playlist artwork then fall back to album artwork, while tracked-song, every-song and loop alerts use album artwork (thanks @tomballgithub, #39) - NEW: Added an interactive setup wizard for first-time setup. Run
--setupor launch the tool with no arguments and accept the prompt. The wizard detects PyPI, downloaded-script, Docker and Docker Compose installs, writes a ready-to-runspotify_monitor.conf, keeps private values in.envand can check or start local monitoring immediately - NEW: Added a confirmed target follow step to setup for cookie and advanced client authentication. The wizard checks the configured account through Spotify's private web-player operations, offers a follow prompt only when needed and verifies the follow state after every approved request
- NEW: Added browser-based
sp_dcimport from Firefox, Chrome, Brave and Chromium with profile selection. Firefox needs no extra dependency and works on macOS, Linux and Windows. Chromium-based import is optional on macOS and Linux, while Windows users are guided to Firefox - IMPROVE: Made targets and configuration easier to use. Targets can be raw Spotify user IDs,
spotify:userURIs or profile URLs and can be saved asTARGET_USER_URI_ID. Broken config files report the offending line, config writes create recoverable backups and private values stay hidden from normal or debug output - NEW: Added private
sp_dcentry with--set-sp-dc. The cookie is entered through a hidden prompt, checked with Spotify and saved only after validation. This is the recommended setup path for Docker and Docker Compose - NEW: Added a file-safe
--doctorself-check for configuration, secrets, Spotify authentication, metadata backends, connectivity, target visibility and notifications. Configured legacy OAuth metadata uses a memory-only live check and becomes a warning when the automatic web-player fallback succeeds. Interactive runs offer separate delivery tests for email and webhook channels. Each approved test sends one real message while non-interactive runs remain message-free. Common failures now include a clearTo fix:next step instead of only a technical error - CONFIG CHANGE: Changed TOTP secret handling for cookie mode. Version 3.0 embeds the current v61 cipher and no longer downloads a third-party secret dictionary. Existing configs keep working with the built-in default, but
SECRET_CIPHER_DICT,SECRET_CIPHER_DICT_URLandTOTP_VERno longer control token generation. Future overrides useTOTP_VERSIONandTOTP_SECRET_CIPHER_BYTES, which--doctorchecks. The updatedspotify_monitor_secret_grabberv1.3 can extract replacement values if Spotify rotates them - IMPROVE: Updated
spotify_monitor_secret_grabberto v1.3 so it extracts current inline object-literal TOTP secrets while retaining the original runtime hook for older bundle formats - NEW: Added a non-root Docker image, Docker Compose quick start and a copyable
.env.example. Setup commands adapt to containers and the release workflow supportslinux/amd64pluslinux/arm64images - IMPROVE: Added a friendlier terminal experience with a pure ASCII equalizer banner, a short no-arguments welcome, a concise startup summary and install-aware examples in
--help. Use--verbosefor the complete non-secret summary plus occasional operational details - NEW: Published a documentation site at misiektoja.github.io/spotify_monitor, built with MkDocs Material and deployed through GitHub Actions. The README is now a concise landing page while installation, configuration, usage, troubleshooting and debugging have dedicated guides
- IMPROVE: Added an editable setup summary so answers can be reviewed before saving
- IMPROVE: Simplified browser onboarding with separate Firefox and Chromium choices plus optional
pycookiecheatinstallation - IMPROVE: Made generated commands portable across Python installations and custom config paths
- IMPROVE: Added confirmation, backups and validation when replacing configuration files
- BUGFIX: No-argument launches now honor saved targets
- BUGFIX: Improved Docker and Compose support for Linux user mappings, persistent sessions and saved interface choices
- IMPROVE: Updated support to Python 3.9 through 3.14 and made Spotipy optional. It is now needed only for the advanced legacy OAuth metadata path
Bug fixes:
- BUGFIX: Bounded the retry loop in
spotify_get_access_token_from_sp_dcto prevent an infinite loop when TOTP secrets are repeatedly fetched but the resulting token refresh keeps failing (thanks @tomballgithub, fixes #37) - BUGFIX: Auto-fallback to the highest available TOTP version when the configured
TOTP_VERis missing fromSECRET_CIPHER_DICT(with a warning) so the script self-heals instead of failing every retry
Features and Improvements:
- IMPROVE: Updated SECRET_CIPHER_DICT_URL used in
cookiemode and enabled last v61 secret since it does not appear to be rotated anymore
Features and Improvements:
- NEW: Added configuration option
SPOTIFY_SUFFIXto allow a custom string after Spotify-curated public playlists (thanks @tomballgithub) - NEW: Added debug mode with
DEBUG_MODEconfig option and--debugCLI flag for technical troubleshooting output
Bug fixes:
- BUGFIX: Capped server-provided
Retry-Afterfor HTTP 429 responses to avoid long hangs - BUGFIX: Fixed fetching of TOTP secrets so it happens before retries
Features and Improvements:
- IMPROVE: Migrated deprecated
GET /browse/categoriesandGET /users/{id}endpoints to handle Spotify API changes scheduled for February 11, 2026; usedGET /tracks/{id}for oauth_app token validation andspclientinternal API for user status checks - IMPROVE: Enhanced
--generate-configto support writing directly to a file (e.g.spotify_monitor --generate-config spotify_monitor.conf). This avoids UTF-16 encoding issues on Windows PowerShell - IMPROVE: Expanded tabs to spaces in output log files to ensure consistent alignment across different viewers
- IMPROVE: Enhanced error handling for empty or malformed secret files
- IMPROVE: Added
spotify_monitor_secret_grabberandspotify_monitor_totp_testas pip-installed console scripts
Features and Improvements:
- NEW: Implemented hybrid authentication approach to support two auth methods: cookie/client for friend activity monitoring and oauth_app (Client Credentials OAuth Flow) for track API calls to address restrictions introduced by Spotify on 22 Dec 2025 (thanks @tomballgithub and @0xXiHan, fixes #27)
- NEW: Added configuration options (
SP_APP_CLIENT_ID,SP_APP_CLIENT_SECRET) and-r/--oauth-app-credsflag for Client Credentials OAuth Flow (oauth_app) - NEW: Added OAuth app token caching via
SP_APP_TOKENS_FILEconfiguration option - NEW: Added Spotipy dependency (required since v2.7 due to new Spotify restrictions)
- IMPROVE: Enhanced email notification formatting
Bug fixes:
- BUGFIX: Removed
spotify_get_playlist_infofunction to overcome Spotify's client credentials flow limitations and streamline playlist handling (fixes #31) - BUGFIX: Removed old TOTP versions from
SECRET_CIPHER_DICT(fixes #28) - BUGFIX: Updated TOTP version handling in
refresh_access_token_from_sp_dcfunction to ensure compatibility with varying TOTP versions (fixes #32) - BUGFIX: Added missing OAuth app support for user removal check and improved error handling in
is_user_removedfunction (fixes #30)
Breaking changes:
- BREAKING: Removed token owner display at startup due to
/v1/meendpoint limitations introduced by Spotify on 22 Dec 2025 - BREAKING: OAuth app credentials are now required for track information retrieval when using either
cookieorclienttoken source methods
Features and Improvements:
- NEW: Added support for Amazon Music, Deezer and Tidal URLs in console and email outputs
- NEW: Added support for AZLyrics, Tekstowo.pl, Musixmatch and Lyrics.com lyrics services
- NEW: Added detection and annotation for crossfaded songs during playback with configurable thresholds (see
DETECT_CROSSFADED_SONGS,CROSSFADE_DETECTION_MINandCROSSFADE_DETECTION_MAXconfig options) - NEW: Added configuration options to enable/disable music service URLs in console and email outputs (see
ENABLE_APPLE_MUSIC_URL,ENABLE_YOUTUBE_MUSIC_URL,ENABLE_AMAZON_MUSIC_URL,ENABLE_DEEZER_URLandENABLE_TIDAL_URLconfig options) - NEW: Added configuration options to enable/disable lyrics service URLs in console and email outputs (see
ENABLE_GENIUS_LYRICS_URL,ENABLE_AZLYRICS_URL,ENABLE_TEKSTOWO_URL,ENABLE_MUSIXMATCH_URLandENABLE_LYRICS_COM_URLconfig options) - NEW: Added recent songs tracking in session with inclusion in inactivity emails, including skipped track status (see
INACTIVE_EMAIL_RECENT_SONGS_COUNTconfig option) - IMPROVE: Introduced tolerance for "Played for" display to account for playback duration discrepancies (see
PLAYED_FOR_DURATION_TOLERANCEconfig option) - IMPROVE: Token owner info is now displayed at startup before the monitoring loop
Bug fixes:
- BUGFIX: Fixed "Played for" display when songs are played longer than track duration
- BUGFIX: Prevented duplicate emails when songs on loop also match track/song alerts
Features and Improvements:
- IMPROVE: Added support for loading TOTP secrets from local files via file:// URLs
- IMPROVE: Updated remote URL in SECRET_CIPHER_DICT_URL
- IMPROVE: Updated spotify_monitor_secret_grabber to dump secrets in different formats. Choose what you need with the
--secret,--secretbytesand--secretdictCLI flags, or go all out with the--allmode to write all secret formats to files likesecrets.json,secretBytes.jsonandsecretDict.json(thanks @tomballgithub) - IMPROVE: Added multi-arch Docker image build and compose support for spotify_monitor_secret_grabber - more info at Secret Key Extraction via Docker
- IMPROVE: Added deletion of flag_file at launch if specified via .conf file. Previously only done when flag_file was specified on command line
- IMPROVE: Added info to console output when TOTP secrets are fetched from a remote URL or local file
Bug fixes:
- BUGFIX: Removed walrus operator to support min python version 3.6 (thanks @tomballgithub, fixes #20)
Features and Improvements:
- IMPROVE: Added automatic fetching of secrets used by web-player access token endpoint (
cookiemode) while generating TOTP; it avoids manual updates since Spotify started rotating them every two days
Bug fixes:
- BUGFIX: Fixed bugs in retry logic and error handling in spotify_get_access_token_from_sp_dc()
Features and Improvements:
- IMPROVE: Updated secret cipher bytes used by web-player access token endpoint (
cookiemode) to v11 & v12 - IMPROVE: Moved secret cipher bytes for web-player endpoint to configuration section
- IMPROVE: Implemented auto-selection of highest cipher version when
TOTP_VERis set to 0 - NEW: Added tool to extract secret keys used for TOTP generation in Spotify Web Player JavaScript bundles (see Debugging Tools for more info)
Bug fixes:
- BUGFIX: Fixed truncation code to handle emojis with an actual width greater than one character (thanks @tomballgithub)
Features and Improvements:
- NEW: Added new config option (
FLAG_FILE) and flag (--flag-file) to create a file when the user is active and delete it when inactive; useful for external tools to detect streaming status (thanks @tomballgithub) - NEW: Added new config option (
TRUNCATE_CHARS) and flag (--truncate) to limit screen line length; set to 999 to auto-detect terminal width (thanks @tomballgithub) - IMPROVE: Updated secret cipher bytes used by web-player access token endpoint (
cookiemode) to v9 & v10 (thanks @Thereallo1026 for reverse engineering the current secrets) - IMPROVE: Added number of songs played and elapsed time to session events (thanks @tomballgithub)
Bug fixes:
- BUGFIX: Fixed missing asterisk on startup screen (thanks @tomballgithub)
Bug fixes:
- BUGFIX: Fixed web-player access token retrieval via sp_dc cookie by updating secret cipher bytes (thanks @WurdahMekanik and @matthewcamilizer, fixes #11)
- BUGFIX: Delayed removal/reappearance alerts; see new REMOVED_DISAPPEARED_COUNTER config option (fixes #10)
- BUGFIX: Fixed missing email alerts for failed token requests when using sp_dc cookie method
Features and Improvements:
- NEW: Added new config option (
USER_AGENT) and flag (--user-agent) to set Spotify user agent string - NEW: Ensured all Spotify requests now include the appropriate user agent, if not specified - it is randomly generated per session for specific type of token source
- IMPROVE: Improved detection when a Spotify user has been removed
- IMPROVE: HTTPAdapter now honors the Retry-After header on 429 responses for better Spotify API rate limit handling
- IMPROVE: Updated captions shown for Apple and YouTube Music links
- IMPROVE: Added more descriptive error messages and covered additional corner cases
- IMPROVE: Suppressed -z / --clienttoken-request-body-file from help output to reduce confusion (flag remains functional, but hidden)
- IMPROVE: Clarifications in inline comments explaining how to configure Spotify Desktop client method
Bug fixes:
- BUGFIX: Fixed issue with incorrectly reported songs played on loop
Bug fixes:
- BUGFIX: Fixed web-player access token retrieval via sp_dc cookie (fixes #8)
Bug fixes:
- BUGFIX: Ensured all Spotify requests include the custom User-Agent header
- BUGFIX: Fixed config file generation to work reliably on Windows systems
Features and Improvements:
- NEW: Added support for a new method to obtain the Spotify access token. This method uses captured credentials from the Spotify desktop client and a Protobuf-based login flow. It is intended for advanced users who want an indefinitely valid token with the widest scope. Check the Spotify Desktop Client for more info.
Features and Improvements:
- NEW: The tool can now be installed via pip:
pip install spotify_monitor - NEW: Added support for external config files, environment-based secrets and dotenv integration with auto-discovery
- NEW: Display access token owner information and Spotify friend profile URLs
- IMPROVE: Enhanced startup summary to show loaded config, dotenv and monitored tracks file paths
- IMPROVE: Simplified and renamed command-line arguments for improved usability
- NEW: Implemented SIGHUP handler for dynamic reload of secrets from dotenv files
- NEW: Added configuration option to control clearing the terminal screen at startup
- IMPROVE: Changed connectivity check to use Spotify API endpoint for reliability
- IMPROVE: Added check for missing pip dependencies with install guidance
- IMPROVE: Allow disabling liveness check by setting interval to 0 (default changed to 12h)
- IMPROVE: Improved handling of log file creation
- IMPROVE: Refactored CSV file initialization and processing
- NEW: Added support for
~path expansion across all file paths - IMPROVE: Refactored code structure to support packaging for PyPI
- IMPROVE: Enforced configuration option precedence: code defaults < config file < env vars < CLI flags
- IMPROVE: Removed short option for
--send-test-emailto avoid ambiguity
Bug fixes:
- BUGFIX: Fixed edge cases while converting Spotify URIs to URLs
Features and Improvements:
- IMPROVE: Improved 'track songs' file parsing: now supports comments (lines starting with #) and ignores empty lines
- IMPROVE: Refactored comparison logic for file-listed vs. user-played song tracks
- IMPROVE: Replaced repeated requests.get calls with a shared SESSION to reuse HTTP connections and improve performance
- IMPROVE: Add retry-enabled HTTPAdapter to global SESSION
- IMPROVE: Display number of friends sharing listening activity (when using -l parameter)
- IMPROVE: Updated horizontal line for improved output aesthetics
Bug fixes:
- BUGFIX: Fixed issue handling 'track songs' files encoded in Windows-1252/CP1252 (fixes #5)
Bug fixes:
- BUGFIX: Fixes occasional None return from get_random_user_agent(), avoiding downstream NoneType error (fixes #4)
Features and Improvements:
- NEW: Added support for TOTP parameters in Spotify Web Player token endpoint, the tool now requires the pyotp pip module (fixes #1, #2)
- NEW: Caching mechanism to avoid unnecessary token refreshes
- NEW: Added the possibility to disable SSL certificate verification (VERIFY_SSL global variable)
- IMPROVE: Email notification flags are now automatically disabled if the SMTP configuration is invalid
- IMPROVE: Better exception handling in network-related functions
- IMPROVE: Better overall error handling
- IMPROVE: Code cleanup & linting fixes
Features and Improvements:
- NEW: Support for YouTube Music search URLs
Features and Improvements:
- NEW: Added new parameter (-z / --send_test_email_notification) which allows to send test email notification to verify SMTP settings defined in the script
- IMPROVE: Possibility to define email sending timeout (default set to 15 secs)
Bug fixes:
- BUGFIX: Fixed "SyntaxError: f-string: unmatched (" issue in older Python versions
- BUGFIX: Fixed "SyntaxError: f-string expression part cannot include a backslash" issue in older Python versions
Features and Improvements:
- NEW: Added new signal handler for SIGPIPE allowing to switch songs on loop email notifications
- IMPROVE: Better way of checking for error strings (without case sensitivity) + some additional ones added to the list
- NEW: Support for float type of timestamps added in date/time related functions + get_short_date_from_ts() rewritten to display year if show_year == True and current year is different, also can omit displaying hour and minutes if show_hours == False
Bug fixes:
- BUGFIX: Escaping of exception error string fixed + some unbound vars corrected
Features and Improvements:
- NEW: Possibility to define output log file name suffix (-y / --log_file_suffix)
- NEW: Feature allowing to suppress repeating API or network related errors (check ERROR_500_NUMBER_LIMIT, ERROR_500_TIME_LIMIT, ERROR_NETWORK_ISSUES_NUMBER_LIMIT and ERROR_NETWORK_ISSUES_TIME_LIMIT variables)
- IMPROVE: Information about log file name visible in the start screen
- IMPROVE: Rewritten get_date_from_ts(), get_short_date_from_ts(), get_hour_min_from_ts() and get_range_of_dates_from_tss() functions to automatically detect if time object is timestamp or datetime
Bug fixes:
- BUGFIX: Fixed issues with sporadic broken links in HTML emails (vars with special characters are now escaped properly)
Features and Improvements:
- NEW: Full support for real-time playing of tracked songs (-g) in Spotify client in Linux
- NEW: Rewritten code for playing tracked songs (-g) in Spotify client in macOS
- NEW: New way of playing tracked songs (-g) in Spotify client in Windows
- IMPROVE: Improvements for running the code in Python under Windows
- IMPROVE: Better checking for wrong command line arguments
- IMPROVE: pep8 style convention corrections
Bug fixes:
- BUGFIX: Improved exception handling for some functions
Features and Improvements:
- NEW: Possibility to define SP_DC_COOKIE via command line argument (-u / --spotify_dc_cookie)
- IMPROVE: SPOTIFY_ACTIVITY_CHECK and -p / --online_timer parameter have been removed as it only complicated the code with no visible benefit; SPOTIFY_INACTIVITY_CHECK is used in all places now, so user is considered active if the time of last activity is <= SPOTIFY_INACTIVITY_CHECK
- IMPROVE: Email sending function send_email() has been rewritten to detect invalid SMTP settings
- IMPROVE: Strings have been converted to f-strings for better code visibility
- IMPROVE: Info about CSV file name in the start screen
Features and Improvements:
- NEW: Support for detection of songs listened on loop; if user plays the same song consecutively SONG_ON_LOOP_VALUE times (3 by default, configurable in the .py file) then there will be proper message on the console + you can get email notification (new -x / --song_on_loop_notification parameter); the alarm is triggered only once, when the SONG_ON_LOOP_VALUE is reached and once the user changes the song the timer is zeroed
- NEW: Feature to detect skipped songs; if the user plays the song for <= SKIPPED_SONG_THRESHOLD (0.6 by default = 60%, configurable in the .py file) of track duration, then the song is treated as skipped with proper message on the console & email notifications
- NEW: Information about number of listened songs in the session (console + notification emails)
- IMPROVE: Adding info about Artist and Album context of listened songs to notification emails
- IMPROVE: Adding info about Artist and Album context URLs in the console & email notifications
- IMPROVE: Information about readjusting session start due to too low inactivity timer is also in the notification email now
Features and Improvements:
- NEW: Support for detecting Artist context of listened songs
- IMPROVE: Additional search/replace strings to sanitize tracks for Genius URLs
Bug fixes:
- BUGFIX: Fix for "SyntaxWarning: invalid escape sequence '\d'" in regexps