Skip to content

RELEASE_NOTES.md

Latest commit

 

History

History
540 lines (361 loc) · 46.7 KB

RELEASE_NOTES.md

File metadata and controls

540 lines (361 loc) · 46.7 KB
Raw

spotify_profile_monitor release notes

This is a high-level summary of the most important changes.

Changes in 3.8.2 (28 Aug 2026)

Version 3.8.2 keeps configuration upgrade notes visible after startup redraws, makes explicit --verbose and --debug flags override config defaults, shows the effective JSON_DIR path, stops settings, diagnostics and fallback notices from being coloured as errors and makes Doctor verify real legacy playlist access instead of token issuance alone.

Bug fixes:

  • BUGFIX: Accurate error colouring - Lines that only mention a problem word are no longer painted red. The Error retry timer row 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
  • BUGFIX: Visible configuration upgrade notes - Settings retired from older official config templates are still ignored so upgraded files continue to work, but their cleanup note is now deferred until after the startup screen clear. The note remains readable while monitoring continues
  • BUGFIX: Reliable diagnostic flags - Explicit --verbose and --debug flags now stay enabled after an auto-discovered or selected config file loads, even when that file leaves the matching setting disabled
  • BUGFIX: JSON history destination in verbose startup - --verbose and --debug now show the effective JSON_DIR location alongside other file destinations. The complete startup log includes it too
  • BUGFIX: Accurate Doctor metadata result - When optional legacy OAuth app credentials and a target playlist are available, --doctor now makes the same kind of live playlist metadata request used by monitoring. A token that Spotify issues but cannot use on the playlist endpoint is reported as a warning with the automatic web-player fallback, instead of a misleading legacy metadata success

Changes in 3.8.1 (27 Aug 2026)

Version 3.8.1 adds a dedicated JSON_DIR setting for follower and following plus playlist history files. It also makes rejected config content actionable by showing the config path plus exact line number and reason without clearing the error into guided setup.

Features and improvements:

  • IMPROVE: Configurable JSON history directory - Set JSON_DIR to read and write the follower, following and playlist history files outside the current working directory. The directory is created when monitoring starts. Leaving it empty preserves the existing filenames and location

Bug fixes:

  • BUGFIX: Visible configuration errors - Unsupported settings plus f-strings and other non-literal config values now report the config path plus exact line number and reason in normal output. Invalid discovered configs exit before the no-argument guided setup can clear or replace the diagnostic

Changes in 3.8 (27 Aug 2026)

Version 3.8 adds coloured terminal output with a customizable theme, restores Python 3.9 support, applies the check interval and connectivity settings from the config file and escapes Spotify text in profile-picture emails, CSV exports and email links. Pillow is now optional, config files are parsed instead of executed, --debug output is redacted, environment-variable secrets work without a dotenv file and the project adds a documentation site, a security policy plus releases with a checksum file and a signed build attestation.

Features and improvements:

  • NEW: Coloured terminal output - Live output is now coloured by default: usernames, Spotify IDs, playlist, track and album names, dates, durations, follower and playlist 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-color or COLORED_OUTPUT = False. Colour switches itself off when output is redirected or piped, when TERM is unset or dumb and when NO_COLOR is set. Log files stay plain text, so grep and tail are unaffected, and the existing grc recipe still colours saved logs. Install the optional colorama package for the classic Windows Command Prompt
  • NEW: Searchable documentation site - Full documentation is now published at misiektoja.github.io/spotify_profile_monitor with one page per task and full-text search
  • CONFIG CHANGE: Artwork is now an optional extra - Pillow is no longer required. Email and ntfy artwork moved to the notification-images extra and NTFY_IMAGES now defaults to False. Install with pip install "spotify_profile_monitor[notification-images]" or let setup do it for you. Upgraders who use artwork should install the extra, then set NTFY_IMAGES = True again for ntfy alerts
  • IMPROVE: Faster follower and playlist comparisons - Detecting added and removed followers and playlists now scales linearly instead of quadratically
  • IMPROVE: Playlist exports get their own folder - --export-all-playlists now writes into a dedicated directory instead of the working directory
  • IMPROVE: Masked refresh token - -w now prints a masked refresh token by default; add --verbose to show the full value
  • IMPROVE: Clearer ntfy webhook customization - WEBHOOK_TEMPLATE, WEBHOOK_USERNAME and WEBHOOK_AVATAR_URL are documented as Discord-only; customize ntfy delivery through WEBHOOK_HEADERS
  • IMPROVE: Checksums and signed attestation for releases - Releases now ship a SHA256SUMS.txt, a signed build attestation checkable with gh attestation verify and the attestation bundle itself as an .intoto.jsonl asset, so provenance can be verified from the downloaded files without calling GitHub
  • IMPROVE: Releases publish only after the tests pass - PyPI 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 new contract tests catch unsafe workflow changes
  • IMPROVE: Automated checks on every change - A pinned Ruff lint pass now runs in CI ahead of the test suite, which now covers Python 3.9 through 3.14 plus a Windows job. Optional pre-commit hooks and a shared .editorconfig catch the same issues before you commit
  • IMPROVE: Continuous security scanning - Dependencies 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, issue and pull request templates and a test suite guide
  • IMPROVE: Corrected and improved wording in setup wizard and doctor preflight

Bug fixes:

  • BUGFIX: Environment variables work without a dotenv file - Secrets exported as environment variables, such as SP_DC_COOKIE, SMTP_PASSWORD, WEBHOOK_URL or NTFY_ACCESS_TOKEN, were applied only when a dotenv file also existed, so an export-only setup silently fell back to the shipped defaults. They are now honored on their own, including with --env-file none. --doctor now also names the dotenv file it loaded and lists which secrets are in effect and whether each one came from that file, an environment variable or the configuration file, so a secret that never arrived is visible at a glance
  • BUGFIX: Python 3.9 startup restored - The tool starts again on Python 3.9, the documented minimum runtime
  • BUGFIX: Config-file check interval honored - SPOTIFY_CHECK_INTERVAL set in the config file now correctly scales the liveness check cadence and playlist cache lifetime
  • BUGFIX: Reliable playlist and search references - -l / --list-tracks-for-playlist now accepts a URL, URI or bare ID reliably instead of misparsing values containing user, track or album. -s / --search-username encodes the search term so spaces and punctuation no longer break the request. PLAYLISTS_TO_SKIP_FILE entries are matched with their original case, since Spotify IDs are case sensitive
  • BUGFIX: Stable playlist output and steady memory - Removed stray duplicate log lines and swept stale collaborator cache entries so long-running processes no longer grow unbounded
  • BUGFIX: Hardened email notifications - The monitored account's display name is now escaped in profile-picture emails, matching other notifications. Link addresses are attribute-escaped too, so a crafted identifier can no longer break out of an href
  • 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. A reloaded WEBHOOK_URL is rechecked before use
  • 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. Generated config files and backups are owner-only from the start on macOS and Linux
  • BUGFIX: Connectivity check respects configuration - The startup internet check now honors CHECK_INTERNET_URL, CHECK_INTERNET_TIMEOUT and VERIFY_SSL
  • BUGFIX: Redacted debug output - --debug output is now passed through the same redaction as error text, so a transcript can no longer carry a cookie, token or password
  • BUGFIX: Spotify requests stay on Spotify - Paginated requests now verify each page URL is an HTTPS Spotify host before sending your access token, with a cap on how many pages are followed. Profile pictures are accepted only from Spotify's own CDN hosts, capped at 5 MB, with no redirects followed
  • BUGFIX: Terminal- and spreadsheet-safe Spotify text - Spotify-supplied names and descriptions are stripped of terminal control sequences before reaching the console or log file, including every early-exit listing mode. 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 and from the playlist progress bar. Text that could be read as a spreadsheet formula is escaped with a leading apostrophe in exported CSV files
  • BUGFIX: Reliable anti-hang watchdog - The watchdog can no longer be disabled by a nested request timer while its timeout no longer pre-empts legitimate slow requests
  • BUGFIX: Shell-free image preview - IMGCAT_PATH now launches the viewer with an argument list instead of a shell command string
  • BUGFIX: Windows compatibility fixes - Export writes UTF-8 explicitly and playlist artwork filenames no longer embed characters Windows rejects
  • BUGFIX: Smaller fixes - --truncate 0 is honored, a non-string SMTP_HOST reports a clean error and the Firefox cookie handle is closed after import

Changes in 3.7 (04 Aug 2026)

Version 3.7 focuses on making Spotify Profile Monitor easier to set up, safer to configure and easier to troubleshoot. It adds guided onboarding, Spotify login cookie import from Firefox and Chromium-based browsers and a Doctor self-check while improving terminal output, configuration recovery and email artwork controls.

Features and improvements:

  • NEW: Guided first-run setup - Run --setup or accept the no-arguments prompt to configure the monitoring target, polling interval, Spotify authentication, email and webhook notifications plus config and dotenv destinations
  • NEW: Browser cookie import - Import an sp_dc cookie from Firefox, Chrome, Brave or Chromium with profile selection and Spotify validation before SP_DC_COOKIE is updated. Firefox needs no extra dependency and works on macOS, Linux and Windows. Chromium-based import uses the optional browser extra on macOS and Linux while Windows users are guided to Firefox
  • NEW: Doctor self-check - --doctor checks Python dependencies, configuration, secrets, output destinations, Spotify authentication, the metadata backend, connectivity, an optional target and notifications. Interactive runs offer separate email and webhook tests only after confirmation. Failures show a To fix: action while --debug retains technical detail
  • IMPROVE: Recoverable configuration writes - New content is validated before an atomic write, existing files receive timestamped backups and replacement requires confirmation or --force. Generated configuration keeps secret placeholders while follow-up commands preserve the active interpreter and custom config or dotenv paths
  • IMPROVE: Focused terminal output - A pure ASCII profile banner, short no-arguments welcome, concise startup summary and install-aware --help examples keep routine output approachable. Use --verbose for the complete non-secret summary or --debug for sanitized request flow and internal troubleshooting detail
  • IMPROVE: Portable log separators - The new ASCII_LOG_SEPARATORS setting 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.
  • NEW: Independent email artwork - EMAIL_IMAGES is disabled by default and enables playlist plus album artwork in email notifications without changing profile-picture detection or its dedicated attachments
  • CONFIG CHANGE: Supported Python versions - Runtime support and package metadata now cover Python 3.9 through 3.14

Bug fixes:

  • BUGFIX: Stable playlist like counts - Temporarily missing values no longer produce false n/a availability changes. Current profile metadata and the last cached numeric value act as fallbacks while unavailable snapshots retain the previous numeric baseline

Changes in 3.6 (30 Jul 2026)

Version 3.6 adds safer private setup for Spotify authentication, support for Spotify monitoring targets in different formats and independent Discord and ntfy webhook notifications for profile, playlist, follower and monitoring alerts with customizable delivery. Email notifications now include inline playlist or album artwork for relevant changes.

Features and improvements:

  • NEW: Added independent Discord and ntfy webhook notifications with per-event controls for profile changes, playlist updates, follower or following changes and monitoring errors
  • IMPROVE: Added support for accepting monitoring targets as raw Spotify user IDs, spotify:user: URIs or profile URLs and added TARGET_USER_URI_ID for config-only startup. Positional targets continue to take precedence
  • NEW: Added private sp_dc entry with --set-sp-dc. The cookie is entered through a hidden prompt, validated with Spotify and saved to a dotenv file only after validation. Existing dotenv, environment, command-line and config-file options remain available
  • NEW: Added private webhook URL setup with --set-webhook-url, one-run provider and URL overrides plus --send-test-webhook for delivery checks
  • NEW: Added customizable Discord-format payloads with validated templates, transforms and headers plus mention suppression
  • NEW: Added native ntfy topic delivery with protected-topic authentication, profile or playlist artwork and automatic text fallback, using Pillow for bounded in-memory image preparation
  • IMPROVE: Added bounded webhook delivery, automatic provider correction and strict destination validation while keeping email and webhook delivery independent
  • IMPROVE: Added inline artwork to playlist email notifications, preferring playlist artwork over album artwork when both are available and preserving text-only delivery if image preparation fails
  • IMPROVE: Added compact email and webhook category rollups to the startup summary with short labels and unstarred continuation lines when needed

Bug fixes:

  • BUGFIX: Kept long ntfy messages below its 4 KB attachment boundary, added a visible truncation explanation and preserved complete UTF-8 characters
  • BUGFIX: Made SIGHUP clear cached Spotify authentication after credential rotation and redetect Discord or ntfy when the private webhook destination changes

Changes in 3.5 (21 Jul 2026)

Version 3.5 keeps public playlist monitoring working under Spotify's current API restrictions. It adds automatic fallback to Spotify web-player data, removes the extra OAuth app requirement for cookie and client users and improves playlist polling accuracy and efficiency.

Features and Improvements:

  • NEW: Added an automatic public web-player playlist backend for Spotify's restricted Development Mode apps. It restores public playlist details, track history and collaborator monitoring without relying on blocked legacy Web API endpoints. Large playlists are loaded across all pages and the tool automatically refreshes temporary tokens, adapts to Spotify query changes and retries brief Spotify service failures
  • IMPROVE: Made Spotify OAuth app credentials optional alongside cookie and client modes. Existing complete SP_APP_CLIENT_ID and SP_APP_CLIENT_SECRET configurations remain supported and are tried first, then public playlist requests switch automatically to the web-player backend if the legacy API is restricted. Startup output now shows which playlist backend will be used. Note: This OAuth change does not replace the other authentication modes. Standalone oauth_app remains a legacy option that works only with an existing compatible app, while oauth_user setup and its own app credentials remain unchanged
  • CONFIG CHANGE: Changed TOTP secret handling for cookie mode. Version 3.5 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_URL and TOTP_VER no longer control token generation. Future overrides use TOTP_VERSION and TOTP_SECRET_CIPHER_BYTES, which are validated before use and can be updated from values produced by spotify_monitor_secret_grabber
  • IMPROVE: Made large and unchanged playlists faster to process. Playlist revisions are cached so unchanged track lists are not downloaded again, metadata-only checks skip unnecessary track pages and caches remain bounded during long-running monitoring

Bug fixes:

  • BUGFIX: Correctly detects added and removed playlists even when the total count stays unchanged, with accurate console and email messages
  • BUGFIX: Prevents duplicate track notifications after a partial polling failure. Successful playlists now advance normally while only failed playlists remain pending for another check

Changes in 3.4.1 (09 Mar 2026)

Features and Improvements:

  • IMPROVE: Added toleration for missing playlist likes and tracking of N/A availability transitions
  • IMPROVE: Updated SECRET_CIPHER_DICT_URL used in cookie mode and enabled last v61 secret since it does not appear to be rotated anymore

Bug fixes:

  • BUGFIX: Corrected inaccurate API change error messages and comments
  • BUGFIX: Added error email notification when user cannot be monitored

Changes in 3.4 (23 Feb 2026)

Features and Improvements:

  • NEW: Added --export-all-playlists flag to export all user's playlists to individual CSV files (named after the playlist) when using -i / --show-user-profile mode (requires pathvalidate library) (thanks @tomballgithub)
  • IMPROVE: Added graceful handling for playlists visible in user's profile, but returning 404 while getting its details (marked as [ RESTRICTED ], applies mainly for Spotify-curated playlists, closes #36)
  • NEW: Added debug mode with DEBUG_MODE config option and --debug CLI flag for technical troubleshooting output

Bug fixes:

  • BUGFIX: Capped server-provided Retry-After for HTTP 429 responses to avoid long hangs
  • BUGFIX: Fixed fetching of TOTP secrets so it happens before retries

Changes in 3.3 (07 Feb 2026)

Features and Improvements:

  • IMPROVE: Implemented API endpoints adaptability to handle Spotify API changes scheduled for February 11, 2026 (token validation, user removal scraping, graceful follower count degradation, playlist handling to support new items field naming)

Breaking changes:

  • BREAKING: Starting February 11, 2026, oauth_app alone will no longer work for monitoring users (Spotify is removing GET /users/{id} endpoint) - use cookie or client method instead
  • BREAKING: Starting February 11, 2026, oauth_user will no longer work for monitoring other users (Spotify is removing the GET /users/{id} endpoint). Self-monitoring your own account via oauth_user remains fully functional. For monitoring others, use the cookie or client method instead.
  • BREAKING: Starting March 9, 2026, oauth_user mode will require the authorized user to have a Spotify Premium account

Changes in 3.2 (06 Feb 2026)

Features and Improvements:

  • NEW: Implemented playlist change retry mechanism to address occasional Spotify API glitches returning incomplete/empty playlists list; see PLAYLISTS_CHANGE_COUNTER config option (closes #31)
  • IMPROVE: Enhanced --generate-config to support writing directly to a file (e.g. spotify_profile_monitor --generate-config spotify_profile_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

Bug fixes:

  • BUGFIX: Updated old collaborator state when reverting to baseline to ensure notification suppression (fixes #32)
  • BUGFIX: Suppressed collaborator notification for transient glitches when reverting to stable baseline (fixes #30)

Changes in 3.1 (27 Dec 2025)

Features and Improvements:

  • NEW: Implemented hybrid authentication approach when using cookie/client methods by using secondary client credentials OAuth flow (oauth_app) for playlist/user API calls to address restrictions introduced by Spotify on 22 Dec 2025

Bug fixes:

  • BUGFIX: Removed old TOTP versions from SECRET_CIPHER_DICT
  • BUGFIX: Updated TOTP version handling in refresh_access_token_from_sp_dc function to dynamically use the latest version and remove old TOTP versions from SECRET_CIPHER_DICT

Breaking changes:

  • BREAKING: Removed token owner display at startup due to /v1/me endpoint limitations introduced by Spotify on 22 Dec 2025
  • BREAKING: OAuth app credentials are now required for playlist/user information retrieval when using either cookie or client token source methods

Changes in 3.0 (13 Dec 2025)

Features and Improvements:

  • NEW: Implemented HTML formatting for email notifications for better readability
  • IMPROVE: Enhanced notifications for added/removed playlists with detailed information including songs count, duration, creation date and last update date in both console output and email notifications
  • IMPROVE: Added progress bar for playlist processing to provide better visual feedback

Bug fixes:

  • BUGFIX: Improved handling of transient API issues in collaborator change notifications (#17)

Changes in 2.9 (11 Nov 2025)

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 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_URL and ENABLE_TIDAL_URL config 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_URL and ENABLE_LYRICS_COM_URL config options)

Changes in 2.8 (12 Oct 2025)

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, --secretbytes and --secretdict CLI flags, or go all out with the --all mode to write all secret formats to files like secrets.json, secretBytes.json and secretDict.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: Moved CLEAN_OUTPUT assignment after loading configuration files. Checks that it is used only with -l or -x
  • IMPROVE: Added info to console output when TOTP secrets are fetched from a remote URL or local file

Bug fixes:

  • BUGFIX: Fixed -l errors if playlist provided is just the ID (thanks @tomballgithub, fixes #25)

Changes in 2.7 (14 Jul 2025)

Features and Improvements:

  • IMPROVE: Added automatic fetching of secrets used by web-player access token endpoint (cookie mode) 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()

Changes in 2.6.1 (10 Jul 2025)

Features and Improvements:

  • IMPROVE: Updated secret cipher bytes used by web-player access token endpoint (cookie mode) 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_VER is set to 0

Bug fixes:

  • BUGFIX: Fixed truncation code to handle emojis with an actual width greater than one character (thanks @tomballgithub)

Changes in 2.6 (07 Jul 2025)

Features and Improvements:

  • NEW: Added support for manually specifying additional playlists to monitor via the ADD_PLAYLISTS_TO_MONITOR configuration option (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 (cookie mode) to v9 & v10 (thanks @Thereallo1026 for reverse engineering the current secrets)

Bug fixes:

  • BUGFIX: Fixed missing asterisk on startup screen (thanks @tomballgithub)

Changes in 2.5.3 (02 Jul 2025)

Bug fixes:

  • BUGFIX: Fixed web-player access token retrieval via sp_dc cookie by updating secret cipher bytes (thanks @WurdahMekanik and @matthewcamilizer)
  • BUGFIX: Fixed missing email alerts for failed token requests when using sp_dc cookie method

Changes in 2.5.2 (18 Jun 2025)

Features and Improvements:

  • NEW: Added two new methods (oauth_app, oauth_user) to obtain Spotify access tokens using official Spotify API (Client Credentials and Authorization Code OAuth flows - requires Spotipy). Check the Spotify OAuth App and Spotify OAuth User for more info.
  • IMPROVE: HTTPAdapter now honors the Retry-After header on 429 responses for better Spotify API rate limit handling
  • 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
  • IMPROVE: Applied custom user agent to Spotipy-generated requests

Changes in 2.4 (13 Jun 2025)

Features and Improvements:

  • NEW: Added new -o / --export-for-spotify-monitor flag for simplified output when exporting playlists (-l) or liked songs (-x) to allow direct import into spotify_monitor (thanks @tomballgithub)
  • 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 same 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: Added more descriptive error messages and covered additional corner cases

Changes in 2.3.2 (10 Jun 2025)

Bug fixes:

  • BUGFIX: Fixed web-player access token retrieval via sp_dc cookie

Changes in 2.3.1 (10 Jun 2025)

Bug fixes:

  • BUGFIX: Ensured all Spotify requests include the custom User-Agent header
  • BUGFIX: Fixed config file generation to work reliably on Windows systems (#13)

Changes in 2.3 (09 Jun 2025)

Features and Improvements:

  • NEW: Added support for a new method to obtain the Spotify access token (#11). 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.
  • NEW: Added detection for whether a Spotify playlist's artwork is auto-generated or user-uploaded, along with the date and time the artwork was last changed
  • NEW: Added support for displaying playlist images in the terminal using imgcat on supported terminals

Bug fixes:

  • BUGFIX: Improved handling of API glitches and count changes for playlists, followers and followings (#12)

Changes in 2.2.1 (27 May 2025)

Bug fixes:

  • BUGFIX: Add safeguards against API glitches while processing track diffs, collaborators and likes

Changes in 2.2 (21 May 2025)

Features and Improvements:

  • NEW: The tool can now be installed via pip: pip install spotify_profile_monitor
  • NEW: Added support for external config files, environment-based secrets and dotenv integration with auto-discovery
  • NEW: Added support for exporting playlists and liked songs to CSV files
  • NEW: Display access token owner information for better transparency
  • IMPROVE: Improved filtering of unavailable tracks (e.g. due to copyright restrictions)
  • IMPROVE: Enhanced startup summary to show loaded config, dotenv and ignore-playlists file paths
  • IMPROVE: Auto detect and display availability of imgcat binary for profile picture preview
  • 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: Added warning about unsupported Python version
  • IMPROVE: Removed short option for --send-test-email to avoid ambiguity

Bug fixes:

  • BUGFIX: Fixed edge cases while processing playlist entries to avoid NoneType errors (#10)
  • BUGFIX: Improved playlist diff logic to ignore Spotify-owned playlists based on owner ID (#9)
  • BUGFIX: Fixed false positives in playlist diff by ignoring collaborator display names
  • BUGFIX: Fixed imgcat command under Windows (use echo. & instead of echo ;)

Changes in 2.1 (07 Apr 2025)

Features and Improvements:

  • IMPROVE: Display URL of collaborator user instead of just ID (thanks @filipw-ctrl)
  • IMPROVE: Added display of the number of tracks contributed by each collaborator with percentage breakdown to better visualize individual contributions
  • IMPROVE: Implemented caching for playlist info to reduce redundant API calls
  • IMPROVE: Improved detection and handling of completely removed or private playlists
  • IMPROVE: Enhanced error messages for better debugging and clarity
  • IMPROVE: Updated horizontal line for improved output aesthetics

Bug fixes:

  • BUGFIX: Refactored playlist processing to handle erratic Spotify API behavior (e.g. sudden playlist removal/addition) (fixes #7)
  • BUGFIX: Fixed issue where Spotify username changes caused incorrect detection of playlist changes on the user profile
  • BUGFIX: Fixed issue where manually defined LOCAL_TIMEZONE wasn't applied during timestamp conversion

Changes in 2.0.1 (26 Mar 2025)

Bug fixes:

  • BUGFIX: Added retry-enabled HTTPAdapter to global SESSION to address 'Remote end closed connection without response' errors

Changes in 2.0 (25 Mar 2025)

Features and Improvements:

  • NEW: Added playlist filtering (-t / --playlists_to_skip) and ignore Spotify-owned playlists by default (related to #3):
    • From now on, all Spotify-owned playlists are skipped from processing (unless IGNORE_SPOTIFY_PLAYLISTS is set to False)
    • On top of that, there is a new functionality which allows to indicate a file with additional playlists to be blacklisted
    • More details in Playlist blacklisting
  • IMPROVE: Replaced repeated requests.get calls with a shared SESSION (pre-configured with Client-Id and User-Agent headers) to reuse HTTP connections and improve performance (by around 25% for huge playlists)
  • IMPROVE: Improve mapping of user URI IDs to usernames to handle additional edge cases

Bug fixes:

  • BUGFIX: Corrects spotify_extract_id_or_name() to handle NoneType objects (fixes #4)
  • BUGFIX: Fixes mapping of user URI IDs to usernames for Spotify-generated playlists (fixes #2)
  • BUGFIX: Fixes occasional None return from get_random_user_agent(), avoiding downstream NoneType error

Changes in 1.9 (20 Mar 2025)

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)
  • NEW: New feature displaying the recently updated playlist after the list of all user's playlists
  • NEW: Caching mechanism to avoid unnecessary token refreshes
  • NEW: Added the possibility to disable SSL certificate verification (VERIFY_SSL global variable)
  • IMPROVE: Saving the added track timestamp instead of the time of checking to the CSV file
  • IMPROVE: Email notification flags are now automatically disabled if the SMTP configuration is invalid
  • IMPROVE: Different recently played artist limits are now used when using the -a & -i parameters (RECENTLY_PLAYED_ARTISTS_LIMIT and RECENTLY_PLAYED_ARTISTS_LIMIT_INFO global variables)
  • IMPROVE: Possibility to disable displaying the list of playlists (-q) when using the -i parameter
  • IMPROVE: Better exception handling in network-related functions
  • IMPROVE: Better overall error handling
  • IMPROVE: Code cleanup & linting fixes

Bug fixes:

  • BUGFIX: Fixed f-string syntax errors introduced in v1.7 (thanks @tomballgithub for reporting and code fixes!)

Changes in 1.8 (03 Feb 2025)

Features and Improvements:

  • NEW: Added new parameter (-k / --get_all_playlists) which retrieves all public playlists visible in the user's profile, even if they are not owned by them; it is helpful in the case of playlists created by one user added to another user's profile; by default, only public playlists owned by the user are processed
  • NEW: Added info about the playlist owner to the output with the list of playlists

Changes in 1.7 (28 Jan 2025)

Features and Improvements:

  • NEW: The tool now provides information about collaborators on playlists (if applicable) and adds details about collaborators when new tracks are added. This applies to both monitoring mode (including email notifications) and listing mode (-i, -l). Keep in mind: the tool displays the actual number of collaborators. That means it only counts users who have actually contributed to the playlist. If someone's name is visible in Spotify client, but they haven't added a single track, they don't make the cut (sorry, but the point is Spotify doesn't have an official API for that, so the tool gets its hands dirty by analyzing all the tracks in the playlist).

Bug fixes:

  • BUGFIX: Hopefully fixed a rare bug where the tool would report a changed profile picture even though the timestamp remained the same

Changes in 1.6 (03 Nov 2024)

Features and Improvements:

  • NEW: Detection of Spotify username changes
  • NEW: Support for YouTube Music search URLs
  • IMPROVE: Displaying last update date of user's profile pic when using -i parameter
  • IMPROVE: Added info to email notifications for playlists with errors

Bug fixes:

  • BUGFIX: Fixed bug with wrong number of user owned public playlists if there are none

Changes in 1.5 (11 Sep 2024)

Features and Improvements:

  • NEW: Possibility to disable detection of changes in user's public playlists (new -q / --do_not_monitor_playlists parameter)
  • NEW: Possibility to disable email notifications for changed followers/followings (new -g / --disable_followers_followings_notification parameter)
  • IMPROVE: Recently played artists limit increased from 15 to 50 + info about the limit in the output
  • IMPROVE: Indentation + linting fixes

Bug fixes:

  • BUGFIX: Fixed issue with missed playlists changes notifications in case of intermittent Spotify API issues
  • BUGFIX: Fixed bug with wrong CSV file event entry name
  • BUGFIX: Fixed issue with Spotify API sometimes returning wrong info that all user's playlists have been removed

Changes in 1.4 (15 Jun 2024)

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: Better handling of newly created / empty playlists
  • IMPROVE: Better handling of situations when user removes all public playlists
  • IMPROVE: Showing how much time passed since last playlist update in case all tracks are removed
  • IMPROVE: Possibility to define email sending timeout (default set to 15 secs)

Bug fixes:

  • BUGFIX: Fixed an issue of the tool crashing when user had no playlists and created a new one
  • 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

Changes in 1.3 (03 Jun 2024)

Features and Improvements:

  • NEW: Support for honoring last-modified timestamp for saved profile pics (it turned out it reflects timestamp when the picture has been actually added by the user); if you used previous version of the tool, remove the profile pic for the user and let the new version of the tool to re-download it with original modification time which will reflect the time when user actually changed the profile picture
  • IMPROVE: File suffix (-y) honored for JSON and profile picture JPEG file names as well
  • IMPROVE: 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; new version of function is used when number of tracks changes for the playlist (which might happen after a year, can't it ? 😉)
  • IMPROVE: Support for float type of timestamps added in date/time related functions

Bug fixes:

  • BUGFIX: Fix to handle situations when user removes track from playlist, but it is not the last track
  • BUGFIX: Escaping of exception error string fixed

Changes in 1.2 (24 May 2024)

Features and Improvements:

  • NEW: Feature allowing for detection of changed profile pictures; since Spotify user's profile picture URL seems to change from time to time, the tool detects changed profile picture by doing binary comparison of saved jpeg files; initially it saves the profile pic to spotify_{user_uri_id}_profile_pic.jpeg file after the tool is started (in monitoring mode); then during every check the new picture is fetched and the tool does binary comparison if it has changed or not; in case of changes the old profile picture is moved to spotify_{user_uri_id}_profile_pic_old.jpeg file and the new one is saved to spotify_{user_uri_id}_profile_pic.jpeg and also to file named spotify_{user_uri_id}_profile_pic_YYmmdd_HHMM.jpeg (so we can have history of all profile pictures); in order to control the feature there is a new DETECT_CHANGED_PROFILE_PIC variable set to True by default; the feature can be disabled by setting it to False or by enabling -j / --do_not_detect_changed_profile_pic parameter
  • NEW: Feature attaching changed profile pics directly in email notifications (when -p parameter is used)
  • NEW: Feature allowing to display the profile picture right in your terminal (if you have imgcat installed); put path to your imgcat binary in IMGCAT_PATH variable (or leave it empty to disable this functionality)
  • IMPROVE: Improved detection of tracks changed for the playlist; previously if the number of added and removed tracks was the same it went unnoticed by the tool; currently the tool also compares last update timestamp of the playlist to cover such use cases
  • IMPROVE: The tool now shows the time which passed since the previous time new track has been added to the playlist (console + email notifications)
  • NEW: Possibility to define output log file name suffix (-y / --log_file_suffix)
  • 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
  • IMPROVE: Detection of wrong Spotify user URI ID + unneeded while loop removed

Bug fixes:

  • BUGFIX: Fixed stupid bug with the tool crashing when user had no public playlists at all
  • BUGFIX: Fixed issues with sporadic broken links in HTML emails (vars with special characters are now escaped properly)

Changes in 1.1 (19 May 2024)

Features and Improvements:

  • IMPROVE: Improvements for running the code in Python under Windows
  • NEW: Automatic detection of local timezone if you set LOCAL_TIMEZONE variable to 'Auto' (it is default now); requires tzlocal pip module
  • IMPROVE: Information about time zone is displayed in the start screen now
  • IMPROVE: Better checking for wrong command line arguments
  • IMPROVE: pep8 style convention corrections

Bug fixes:

  • BUGFIX: Improved exception handling while processing JSON files

Changes in 1.0 (11 May 2024)

Features and Improvements:

  • NEW: Feature to search for user names (-s) to get user URI ID
  • NEW: Possibility to define SP_DC_COOKIE via command line argument (-u / --spotify_dc_cookie)
  • IMPROVE: Fetching only public playlists owned by the user (ignoring playlists of other users added to user's profile)
  • IMPROVE: Showing delta info (+N or -N) when informing about changed number of followers/followings/playlists/tracks
  • IMPROVE: Information about user's profile URL put in different parts of the code
  • IMPROVE: Possibility to configure limits for list of playlists (PLAYLISTS_LIMIT) and recently played artists (RECENTLY_PLAYED_ARTISTS_LIMIT) fetched from user's profile
  • IMPROVE: Additional search/replace strings to sanitize tracks for Genius Lyrics URLs
  • 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
  • IMPROVE: Small refactoring of functions processing playlists and its tracks to improve performance (it is still quite slow in case of huge number of playlists/tracks)
  • IMPROVE: In case of getting an exception in main loop we will send the error email notification only once (until the issue is resolved)

Bug fixes:

  • BUGFIX: Handling situations when user changes the playlist's visibility to private (previously the tool crashed)
  • BUGFIX: Handling situations when JSON files storing info about followers, followings or playlists get corrupted (previously the tool crashed)