spotify-monitor 2.3.1__tar.gz → 2.6__tar.gz

{spotify_monitor-2.3.1 → spotify_monitor-2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spotify_monitor
-Version: 2.3.1
+Version: 2.6
 Summary: Tool implementing real-time tracking of Spotify friends music activity
 Author-email: Michal Szymanski <misiektoja-pypi@rm-rf.ninja>
 License-Expression: GPL-3.0-or-later
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 # spotify_monitor
 
-Tool for real-time monitoring of Spotify friends' music activity feed.
+Tool for real-time monitoring of **Spotify friends' music activity feed**.
 
 ✨ If you're interested in tracking changes to Spotify users' profiles including their playlists, take a look at another tool I've developed: [spotify_profile_monitor](https://github.com/misiektoja/spotify_profile_monitor).
 
@@ -38,13 +38,15 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 - Real-time tracking of songs listened by Spotify users (including detection when user gets online & offline)
 - Possibility to automatically play songs listened by the tracked user in your local Spotify client
 - Information about the duration the user listened to a song and whether the song was skipped
+- Detection and annotation for crossfaded songs during playback with configurable thresholds
 - Information about the context of the listened song (playlist/artist/album) with clickable URLs
 - Email notifications for various events (user becomes active/inactive, specific or all songs, songs on loop, errors)
 - Saving all listened songs with timestamps to the CSV file
-- Clickable Spotify, Apple Music, YouTube Music and Genius Lyrics search URLs printed in the console & included in email notifications
+- Clickable Spotify, Apple Music, YouTube Music, Amazon Music, Deezer, Tidal, Genius Lyrics, AZLyrics, Tekstowo.pl, Musixmatch and Lyrics.com search URLs printed in the console and included in email notifications (configurable per service)
 - Displaying basic statistics for the user's playing session (duration, time span, number of listened and skipped songs, songs on loop)
 - Support for two different methods to get a Spotify access token (`sp_dc cookie`, `desktop client`)
 - Possibility to control the running copy of the script via signals
+- Functional, procedural Python (minimal OOP)
 
 <p align="center">
    <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor.png" alt="spotify_monitor_screenshot" width="90%"/>
@@ -57,6 +59,7 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 2. [Installation](#installation)
    * [Install from PyPI](#install-from-pypi)
    * [Manual Installation](#manual-installation)
+   * [Upgrading](#upgrading)
 3. [Quick Start](#quick-start)
 4. [Configuration](#configuration)
    * [Configuration File](#configuration-file)
@@ -77,8 +80,11 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
    * [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix)
    * [Coloring Log Output with GRC](#coloring-log-output-with-grc)
 6. [Debugging Tools](#debugging-tools)
+   * [Access Token Retrieval via sp_dc Cookie and TOTP](#access-token-retrieval-via-sp_dc-cookie-and-totp)
+   * [Secret Key Extraction from Spotify Web Player Bundles](#secret-key-extraction-from-spotify-web-player-bundles)
 7. [Change Log](#change-log)
-8. [License](#license)
+8. [Maintainers](#maintainers)
+9. [License](#license)
 
 <a id="requirements"></a>
 ## Requirements
@@ -88,8 +94,8 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 
 Tested on:
 
-* **macOS**: Ventura, Sonoma, Sequoia
-* **Linux**: Raspberry Pi OS (Bullseye, Bookworm), Ubuntu 24, Rocky Linux 8.x/9.x, Kali Linux 2024/2025
+* **macOS**: Ventura, Sonoma, Sequoia, Tahoe
+* **Linux**: Raspberry Pi OS (Bullseye, Bookworm, Trixie), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2024/2025
 * **Windows**: 10, 11
 
 It should work on other versions of macOS, Linux, Unix and Windows as well.
@@ -112,7 +118,7 @@ Download the *[spotify_monitor.py](https://raw.githubusercontent.com/misiektoja/
 Install dependencies via pip:
 
 ```sh
-pip install requests python-dateutil urllib3 pyotp python-dotenv
+pip install requests python-dateutil urllib3 pyotp python-dotenv wcwidth
 ```
 
 Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/requirements.txt)*:
@@ -121,6 +127,17 @@ Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercon
 pip install -r requirements.txt
 ```
 
+<a id="upgrading"></a>
+### Upgrading
+
+To upgrade to the latest version when installed from PyPI:
+
+```sh
+pip install spotify_monitor -U
+```
+
+If you installed manually, download the newest *[spotify_monitor.py](https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/spotify_monitor.py)* file to replace your existing installation.
+
 <a id="quick-start"></a>
 ## Quick Start
 
@@ -143,6 +160,10 @@ To get the list of all supported command-line arguments / flags:
 spotify_monitor --help
 ```
 
+<p align="center">
+   <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_skipped.png" alt="spotify_monitor_skipped" width="90%"/>
+</p>
+
 <a id="configuration"></a>
 ## Configuration
 
@@ -160,6 +181,8 @@ spotify_monitor --generate-config > spotify_monitor.conf
 
 Edit the `spotify_monitor.conf` file and change any desired configuration options (detailed comments are provided for each).
 
+**New in v2.6:** The configuration file includes options to enable/disable music service URLs (Apple Music, YouTube Music, Amazon Music, Deezer, Tidal) and lyrics service URLs (Genius, AZLyrics, Tekstowo.pl, Musixmatch, Lyrics.com) in console and email outputs. You can also configure crossfade detection thresholds and the number of recent songs to include in inactivity emails.
+
 <a id="spotify-access-token-source"></a>
 ### Spotify access token source
 
@@ -199,7 +222,7 @@ If your `sp_dc` cookie expires, the tool will notify you via the console and ema
 
 If you store the `SP_DC_COOKIE` in a dotenv file you can update its value and send a `SIGHUP` signal to reload the file with the new `sp_dc` cookie without restarting the tool. More info in [Storing Secrets](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).
 
-`Note`: encrypted byte sequences used for TOTP secret generation tend to expire every now and then; you can either check the [issues](https://github.com/misiektoja/spotify_monitor/issues) section of the project to see if there are any new secrets published or you can run the [spotify_monitor_secret_grabber.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [Debugging Tools](https://github.com/misiektoja/spotify_monitor#debugging-tools) for more info).
+> **NOTE:** secrets used for TOTP generation (`SECRET_CIPHER_DICT`) expire every two days, that's why since v2.4 the tool fetches it from remote URL (see `SECRET_CIPHER_DICT_URL`); you can also run the [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [Secret Key Extraction from Spotify Web Player Bundles](#secret-key-extraction-from-spotify-web-player-bundles) for more info).
 
 <a id="spotify-desktop-client"></a>
 #### Spotify Desktop Client
@@ -404,6 +427,8 @@ To be informed when a user gets inactive:
 spotify_monitor <spotify_user_uri_id> -i
 ```
 
+Inactivity emails include recent songs from the session with skipped track status. Configure the number of recent songs to include via the `INACTIVE_EMAIL_RECENT_SONGS_COUNT` configuration option.
+
 To get email notifications when a monitored track/playlist/album plays:
 - set `TRACK_NOTIFICATION` to `True`
 - or use the `-t` flag
@@ -572,32 +597,165 @@ grc tail -F -n 100 spotify_monitor_<user_uri_id/file_suffix>.log
 <a id="debugging-tools"></a>
 ## Debugging Tools
 
-To help with troubleshooting and development, two debug utilities are available in the `debug` directory:
+To help with troubleshooting and development, two debug utilities are available in the [debug](https://github.com/misiektoja/spotify_monitor/tree/dev/debug) directory.
 
-- [spotify_monitor_totp_test.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py): fetching of Spotify access token based on a Spotify Web Player `sp_dc` cookie value:
+<a id="access-token-retrieval-via-sp_dc-cookie-and-totp"></a>
+### Access Token Retrieval via sp_dc Cookie and TOTP
+
+The [spotify_monitor_totp_test](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py) tool retrieves a Spotify access token using a Web Player `sp_dc` cookie and TOTP parameters. 
+
+Download from [here](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py) or:
+
+```sh
+wget https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/dev/debug/spotify_monitor_totp_test.py
+```
+
+Install requirements:
 
 ```sh
 pip install requests python-dateutil pyotp
+```
+
+Run:
+
+```sh
 python3 spotify_monitor_totp_test.py --sp-dc "your_sp_dc_cookie_value"
 ```
 
-- [spotify_monitor_secret_grabber.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py): automatic extractor for secret keys used for TOTP generation in Spotify Web Player JavaScript bundles:
+You should get a valid Spotify access token, example output:
+
+<p align="center">
+   <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_totp_test.png" alt="spotify_monitor_totp_test" width="100%"/>
+</p>
+
+> **NOTE:** secrets used for TOTP generation (`SECRET_CIPHER_DICT`) expire every two days; you can either run the [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [here](#secret-key-extraction-from-spotify-web-player-bundles) for more info) or you can pass `--fetch-secrets` flag in `spotify_monitor_totp_test` (available since v1.6). There is also a [xyloflake/spot-secrets-go/](https://github.com/xyloflake/spot-secrets-go/) repo which offers JSON files that are automatically updated with current secrets (you can pass `--download-secrets` flag in `spotify_monitor_totp_test` to get it automatically from remote URL, available since v1.8).
+
+<a id="secret-key-extraction-from-spotify-web-player-bundles"></a>
+### Secret Key Extraction from Spotify Web Player Bundles
+
+The [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) tool automatically extracts secret keys used for TOTP generation in Spotify Web Player JavaScript bundles. 
+
+> 💡 **Quick tip:** The easiest and recommended way to run this tool is via Docker. Jump directly to the [Docker usage section below](#-secret-key-extraction-via-docker-recommended-easiest-way).
+
+Download from [here](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) or:
+
+```sh
+wget https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/dev/debug/spotify_monitor_secret_grabber.py
+```
+
+Install requirements:
 
 ```sh
 pip install playwright
 playwright install
+```
+
+Run interactively (default output mode):
+
+```sh
 python3 spotify_monitor_secret_grabber.py
 ```
 
+You should get output similar to below:
+
 <p align="center">
    <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_secret_grabber.png" alt="spotify_monitor_secret_grabber" width="100%"/>
 </p>
 
+Show help:
+```sh
+python3 spotify_monitor_secret_grabber.py -h
+```
+
+---
+
+<a id="cli-output-modes"></a>
+### CLI Output Modes
+
+The script supports several output modes for different use cases:
+
+| Flag | Description | Output |
+|------|--------------|--------|
+| `--secret` | Prints plain JSON array of extracted secrets | `[{"version": X, "secret": "..."}, ...]` |
+| `--secretbytes` | Prints JSON array with ASCII byte values | `[{"version": X, "secret": [..]}, ...]` |
+| `--secretdict` | Prints JSON object/dict mapping version → byte list | `{"X": [..], "Y": [..]}` |
+| `--all` | Extracts secrets and **writes all three outputs** to local files | `secrets.json`, `secretBytes.json`, `secretDict.json` |
+
+Print extracted secrets in specific format, for example Python-friendly secret bytes (JSON object/dict) and save to indicated file:
+
+```sh
+python3 spotify_monitor_secret_grabber.py --secretdict > secretDict.json
+```
+
+Or, to generate and save all secret formats to files (`secrets.json`, `secretBytes.json`, `secretDict.json`) at once:
+
+```sh
+python3 spotify_monitor_secret_grabber.py --all
+```
+
+Default file paths and names can be configured directly in the `OUTPUT_FILES` dictionary at the top of the script.
+
+---
+
+<a id="-secret-key-extraction-via-docker-recommended-easiest-way"></a>
+### 🐳 Secret Key Extraction via Docker (Recommended Easiest Way)
+
+A prebuilt multi-architecture image is available on Docker Hub: [`misiektoja/spotify-secrets-grabber`](https://hub.docker.com/r/misiektoja/spotify-secrets-grabber)
+
+This image works on:
+- macOS (Intel & Apple Silicon)
+- Linux (x86_64 and ARM64)
+- Windows (Docker Desktop / WSL2)
+- Raspberry Pi 4/5 (64-bit OS)
+
+Run interactively (default output mode):
+
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber
+```
+
+Show help:
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber -h
+```
+
+Print extracted secrets in specific format, for example Python-friendly secret bytes (JSON object/dict) and save to indicated file:
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber --secretdict > secretDict.json
+```
+
+Or, to generate and save all secret formats to files (`secrets.json`, `secretBytes.json`, `secretDict.json`) at once:
+
+```sh
+docker run --rm -v .:/work -w /work misiektoja/spotify-secrets-grabber --all
+```
+
+*For SELinux hosts (Fedora/RHEL), use `-v .:/work:Z`.*
+
+<a id="optional-use-docker-compose-one-command-for-all-oss"></a>
+Or optionally use Docker Compose (a preconfigured [compose.yaml](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber_docker/compose.yaml) file is included in the repo):
+
+```sh
+docker compose run --rm spotify-secrets-grabber --all
+```
+
+This will save all files into your current directory on any system (macOS, Linux or Windows).
+
+---
+
+You can now update the secrets used for TOTP generation (for example `SECRET_CIPHER_DICT` in `spotify_monitor_totp_test`, `spotify_monitor` and `spotify_profile_monitor`) either manually or by referencing an external `secretDict.json` file, which can be hosted in another repo or stored locally. See the description of `SECRET_CIPHER_DICT_URL` in those files for details.
+
 <a id="change-log"></a>
 ## Change Log
 
 See [RELEASE_NOTES.md](https://github.com/misiektoja/spotify_monitor/blob/main/RELEASE_NOTES.md) for details.
 
+<a id="maintainers"></a>
+## Maintainers
+
+[![Maintainer: misiektoja](https://img.shields.io/badge/maintainer-misiektoja-blue)](https://github.com/misiektoja)  
+[![Maintainer: tomballgithub](https://img.shields.io/badge/maintainer-tomballgithub-blue)](https://github.com/tomballgithub)
+
 <a id="license"></a>
 ## License
 

{spotify_monitor-2.3.1 → spotify_monitor-2.6}/README.md

@@ -1,6 +1,6 @@
 # spotify_monitor
 
-Tool for real-time monitoring of Spotify friends' music activity feed.
+Tool for real-time monitoring of **Spotify friends' music activity feed**.
 
 ✨ If you're interested in tracking changes to Spotify users' profiles including their playlists, take a look at another tool I've developed: [spotify_profile_monitor](https://github.com/misiektoja/spotify_profile_monitor).
 
@@ -12,13 +12,15 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 - Real-time tracking of songs listened by Spotify users (including detection when user gets online & offline)
 - Possibility to automatically play songs listened by the tracked user in your local Spotify client
 - Information about the duration the user listened to a song and whether the song was skipped
+- Detection and annotation for crossfaded songs during playback with configurable thresholds
 - Information about the context of the listened song (playlist/artist/album) with clickable URLs
 - Email notifications for various events (user becomes active/inactive, specific or all songs, songs on loop, errors)
 - Saving all listened songs with timestamps to the CSV file
-- Clickable Spotify, Apple Music, YouTube Music and Genius Lyrics search URLs printed in the console & included in email notifications
+- Clickable Spotify, Apple Music, YouTube Music, Amazon Music, Deezer, Tidal, Genius Lyrics, AZLyrics, Tekstowo.pl, Musixmatch and Lyrics.com search URLs printed in the console and included in email notifications (configurable per service)
 - Displaying basic statistics for the user's playing session (duration, time span, number of listened and skipped songs, songs on loop)
 - Support for two different methods to get a Spotify access token (`sp_dc cookie`, `desktop client`)
 - Possibility to control the running copy of the script via signals
+- Functional, procedural Python (minimal OOP)
 
 <p align="center">
    <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor.png" alt="spotify_monitor_screenshot" width="90%"/>
@@ -31,6 +33,7 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 2. [Installation](#installation)
    * [Install from PyPI](#install-from-pypi)
    * [Manual Installation](#manual-installation)
+   * [Upgrading](#upgrading)
 3. [Quick Start](#quick-start)
 4. [Configuration](#configuration)
    * [Configuration File](#configuration-file)
@@ -51,8 +54,11 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
    * [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix)
    * [Coloring Log Output with GRC](#coloring-log-output-with-grc)
 6. [Debugging Tools](#debugging-tools)
+   * [Access Token Retrieval via sp_dc Cookie and TOTP](#access-token-retrieval-via-sp_dc-cookie-and-totp)
+   * [Secret Key Extraction from Spotify Web Player Bundles](#secret-key-extraction-from-spotify-web-player-bundles)
 7. [Change Log](#change-log)
-8. [License](#license)
+8. [Maintainers](#maintainers)
+9. [License](#license)
 
 <a id="requirements"></a>
 ## Requirements
@@ -62,8 +68,8 @@ Tool for real-time monitoring of Spotify friends' music activity feed.
 
 Tested on:
 
-* **macOS**: Ventura, Sonoma, Sequoia
-* **Linux**: Raspberry Pi OS (Bullseye, Bookworm), Ubuntu 24, Rocky Linux 8.x/9.x, Kali Linux 2024/2025
+* **macOS**: Ventura, Sonoma, Sequoia, Tahoe
+* **Linux**: Raspberry Pi OS (Bullseye, Bookworm, Trixie), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2024/2025
 * **Windows**: 10, 11
 
 It should work on other versions of macOS, Linux, Unix and Windows as well.
@@ -86,7 +92,7 @@ Download the *[spotify_monitor.py](https://raw.githubusercontent.com/misiektoja/
 Install dependencies via pip:
 
 ```sh
-pip install requests python-dateutil urllib3 pyotp python-dotenv
+pip install requests python-dateutil urllib3 pyotp python-dotenv wcwidth
 ```
 
 Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/requirements.txt)*:
@@ -95,6 +101,17 @@ Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercon
 pip install -r requirements.txt
 ```
 
+<a id="upgrading"></a>
+### Upgrading
+
+To upgrade to the latest version when installed from PyPI:
+
+```sh
+pip install spotify_monitor -U
+```
+
+If you installed manually, download the newest *[spotify_monitor.py](https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/spotify_monitor.py)* file to replace your existing installation.
+
 <a id="quick-start"></a>
 ## Quick Start
 
@@ -117,6 +134,10 @@ To get the list of all supported command-line arguments / flags:
 spotify_monitor --help
 ```
 
+<p align="center">
+   <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_skipped.png" alt="spotify_monitor_skipped" width="90%"/>
+</p>
+
 <a id="configuration"></a>
 ## Configuration
 
@@ -134,6 +155,8 @@ spotify_monitor --generate-config > spotify_monitor.conf
 
 Edit the `spotify_monitor.conf` file and change any desired configuration options (detailed comments are provided for each).
 
+**New in v2.6:** The configuration file includes options to enable/disable music service URLs (Apple Music, YouTube Music, Amazon Music, Deezer, Tidal) and lyrics service URLs (Genius, AZLyrics, Tekstowo.pl, Musixmatch, Lyrics.com) in console and email outputs. You can also configure crossfade detection thresholds and the number of recent songs to include in inactivity emails.
+
 <a id="spotify-access-token-source"></a>
 ### Spotify access token source
 
@@ -173,7 +196,7 @@ If your `sp_dc` cookie expires, the tool will notify you via the console and ema
 
 If you store the `SP_DC_COOKIE` in a dotenv file you can update its value and send a `SIGHUP` signal to reload the file with the new `sp_dc` cookie without restarting the tool. More info in [Storing Secrets](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).
 
-`Note`: encrypted byte sequences used for TOTP secret generation tend to expire every now and then; you can either check the [issues](https://github.com/misiektoja/spotify_monitor/issues) section of the project to see if there are any new secrets published or you can run the [spotify_monitor_secret_grabber.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [Debugging Tools](https://github.com/misiektoja/spotify_monitor#debugging-tools) for more info).
+> **NOTE:** secrets used for TOTP generation (`SECRET_CIPHER_DICT`) expire every two days, that's why since v2.4 the tool fetches it from remote URL (see `SECRET_CIPHER_DICT_URL`); you can also run the [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [Secret Key Extraction from Spotify Web Player Bundles](#secret-key-extraction-from-spotify-web-player-bundles) for more info).
 
 <a id="spotify-desktop-client"></a>
 #### Spotify Desktop Client
@@ -378,6 +401,8 @@ To be informed when a user gets inactive:
 spotify_monitor <spotify_user_uri_id> -i
 ```
 
+Inactivity emails include recent songs from the session with skipped track status. Configure the number of recent songs to include via the `INACTIVE_EMAIL_RECENT_SONGS_COUNT` configuration option.
+
 To get email notifications when a monitored track/playlist/album plays:
 - set `TRACK_NOTIFICATION` to `True`
 - or use the `-t` flag
@@ -546,32 +571,165 @@ grc tail -F -n 100 spotify_monitor_<user_uri_id/file_suffix>.log
 <a id="debugging-tools"></a>
 ## Debugging Tools
 
-To help with troubleshooting and development, two debug utilities are available in the `debug` directory:
+To help with troubleshooting and development, two debug utilities are available in the [debug](https://github.com/misiektoja/spotify_monitor/tree/dev/debug) directory.
 
-- [spotify_monitor_totp_test.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py): fetching of Spotify access token based on a Spotify Web Player `sp_dc` cookie value:
+<a id="access-token-retrieval-via-sp_dc-cookie-and-totp"></a>
+### Access Token Retrieval via sp_dc Cookie and TOTP
+
+The [spotify_monitor_totp_test](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py) tool retrieves a Spotify access token using a Web Player `sp_dc` cookie and TOTP parameters. 
+
+Download from [here](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py) or:
+
+```sh
+wget https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/dev/debug/spotify_monitor_totp_test.py
+```
+
+Install requirements:
 
 ```sh
 pip install requests python-dateutil pyotp
+```
+
+Run:
+
+```sh
 python3 spotify_monitor_totp_test.py --sp-dc "your_sp_dc_cookie_value"
 ```
 
-- [spotify_monitor_secret_grabber.py](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py): automatic extractor for secret keys used for TOTP generation in Spotify Web Player JavaScript bundles:
+You should get a valid Spotify access token, example output:
+
+<p align="center">
+   <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_totp_test.png" alt="spotify_monitor_totp_test" width="100%"/>
+</p>
+
+> **NOTE:** secrets used for TOTP generation (`SECRET_CIPHER_DICT`) expire every two days; you can either run the [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) and extract it by yourself (see [here](#secret-key-extraction-from-spotify-web-player-bundles) for more info) or you can pass `--fetch-secrets` flag in `spotify_monitor_totp_test` (available since v1.6). There is also a [xyloflake/spot-secrets-go/](https://github.com/xyloflake/spot-secrets-go/) repo which offers JSON files that are automatically updated with current secrets (you can pass `--download-secrets` flag in `spotify_monitor_totp_test` to get it automatically from remote URL, available since v1.8).
+
+<a id="secret-key-extraction-from-spotify-web-player-bundles"></a>
+### Secret Key Extraction from Spotify Web Player Bundles
+
+The [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) tool automatically extracts secret keys used for TOTP generation in Spotify Web Player JavaScript bundles. 
+
+> 💡 **Quick tip:** The easiest and recommended way to run this tool is via Docker. Jump directly to the [Docker usage section below](#-secret-key-extraction-via-docker-recommended-easiest-way).
+
+Download from [here](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) or:
+
+```sh
+wget https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/dev/debug/spotify_monitor_secret_grabber.py
+```
+
+Install requirements:
 
 ```sh
 pip install playwright
 playwright install
+```
+
+Run interactively (default output mode):
+
+```sh
 python3 spotify_monitor_secret_grabber.py
 ```
 
+You should get output similar to below:
+
 <p align="center">
    <img src="https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/assets/spotify_monitor_secret_grabber.png" alt="spotify_monitor_secret_grabber" width="100%"/>
 </p>
 
+Show help:
+```sh
+python3 spotify_monitor_secret_grabber.py -h
+```
+
+---
+
+<a id="cli-output-modes"></a>
+### CLI Output Modes
+
+The script supports several output modes for different use cases:
+
+| Flag | Description | Output |
+|------|--------------|--------|
+| `--secret` | Prints plain JSON array of extracted secrets | `[{"version": X, "secret": "..."}, ...]` |
+| `--secretbytes` | Prints JSON array with ASCII byte values | `[{"version": X, "secret": [..]}, ...]` |
+| `--secretdict` | Prints JSON object/dict mapping version → byte list | `{"X": [..], "Y": [..]}` |
+| `--all` | Extracts secrets and **writes all three outputs** to local files | `secrets.json`, `secretBytes.json`, `secretDict.json` |
+
+Print extracted secrets in specific format, for example Python-friendly secret bytes (JSON object/dict) and save to indicated file:
+
+```sh
+python3 spotify_monitor_secret_grabber.py --secretdict > secretDict.json
+```
+
+Or, to generate and save all secret formats to files (`secrets.json`, `secretBytes.json`, `secretDict.json`) at once:
+
+```sh
+python3 spotify_monitor_secret_grabber.py --all
+```
+
+Default file paths and names can be configured directly in the `OUTPUT_FILES` dictionary at the top of the script.
+
+---
+
+<a id="-secret-key-extraction-via-docker-recommended-easiest-way"></a>
+### 🐳 Secret Key Extraction via Docker (Recommended Easiest Way)
+
+A prebuilt multi-architecture image is available on Docker Hub: [`misiektoja/spotify-secrets-grabber`](https://hub.docker.com/r/misiektoja/spotify-secrets-grabber)
+
+This image works on:
+- macOS (Intel & Apple Silicon)
+- Linux (x86_64 and ARM64)
+- Windows (Docker Desktop / WSL2)
+- Raspberry Pi 4/5 (64-bit OS)
+
+Run interactively (default output mode):
+
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber
+```
+
+Show help:
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber -h
+```
+
+Print extracted secrets in specific format, for example Python-friendly secret bytes (JSON object/dict) and save to indicated file:
+```sh
+docker run --rm misiektoja/spotify-secrets-grabber --secretdict > secretDict.json
+```
+
+Or, to generate and save all secret formats to files (`secrets.json`, `secretBytes.json`, `secretDict.json`) at once:
+
+```sh
+docker run --rm -v .:/work -w /work misiektoja/spotify-secrets-grabber --all
+```
+
+*For SELinux hosts (Fedora/RHEL), use `-v .:/work:Z`.*
+
+<a id="optional-use-docker-compose-one-command-for-all-oss"></a>
+Or optionally use Docker Compose (a preconfigured [compose.yaml](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber_docker/compose.yaml) file is included in the repo):
+
+```sh
+docker compose run --rm spotify-secrets-grabber --all
+```
+
+This will save all files into your current directory on any system (macOS, Linux or Windows).
+
+---
+
+You can now update the secrets used for TOTP generation (for example `SECRET_CIPHER_DICT` in `spotify_monitor_totp_test`, `spotify_monitor` and `spotify_profile_monitor`) either manually or by referencing an external `secretDict.json` file, which can be hosted in another repo or stored locally. See the description of `SECRET_CIPHER_DICT_URL` in those files for details.
+
 <a id="change-log"></a>
 ## Change Log
 
 See [RELEASE_NOTES.md](https://github.com/misiektoja/spotify_monitor/blob/main/RELEASE_NOTES.md) for details.
 
+<a id="maintainers"></a>
+## Maintainers
+
+[![Maintainer: misiektoja](https://img.shields.io/badge/maintainer-misiektoja-blue)](https://github.com/misiektoja)  
+[![Maintainer: tomballgithub](https://img.shields.io/badge/maintainer-tomballgithub-blue)](https://github.com/tomballgithub)
+
 <a id="license"></a>
 ## License
 

{spotify_monitor-2.3.1 → spotify_monitor-2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spotify_monitor"
-version = "2.3.1"
+version = "2.6"
 description = "Tool implementing real-time tracking of Spotify friends music activity"
 readme = "README.md"
 license = "GPL-3.0-or-later"