Repository files navigation

psn_monitor is a tool for real-time monitoring of Sony PlayStation (PSN) players' activities.

• Real-time tracking of PlayStation users' gaming activity (including detection when a user gets online/offline or plays games)
• Basic statistics for user activity (duration in different states, time spent playing a game, overall time and number of games played in a session etc.)
• Email notifications for various events (player gets online/offline, starts/finishes/changes a game, errors)
• Saving all user activities with timestamps to a CSV file
• Possibility to control the running copy of the script via signals

1. Requirements
2. Installation
   • Install from PyPI
   • Manual Installation
3. Quick Start
4. Configuration
   • Configuration File
   • PSN NPSSO Code
   • User Privacy Settings
   • Time Zone
   • SMTP Settings
   • Storing Secrets
5. Usage
   • Monitoring Mode
   • Email Notifications
   • CSV Export
   • Check Intervals
   • Signal Controls (macOS/Linux/Unix)
   • Coloring Log Output with GRC
6. Change Log
7. License

• Python 3.10 or higher
• Libraries:PSNAWP,requests,python-dateutil,pytz,tzlocal,python-dotenv

Tested on:

• macOS: Ventura, Sonoma, Sequoia
• Linux: Raspberry Pi OS (Bullseye, Bookworm), Ubuntu 24, 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.

pip install psn_monitor

Download thepsn_monitor.py file to the desired location.

Install dependencies via pip:

pip install PSNAWP requests python-dateutil pytz tzlocal python-dotenv

Alternatively, from the downloadedrequirements.txt:

pip install -r requirements.txt

• Grab yourPSN npsso code and track thepsn_user_id gaming activities:

psn_monitor<psn_user_id> -n"your_psn_npsso_code"

Or if you installedmanually:

python3 psn_monitor.py<psn_user_id> -n"your_psn_npsso_code"

To get the list of all supported command-line arguments / flags:

psn_monitor --help

Most settings can be configured via command-line arguments.

If you want to have it stored persistently, generate a default config template and save it to a file namedpsn_monitor.conf:

psn_monitor --generate-config> psn_monitor.conf

Edit thepsn_monitor.conf file and change any desired configuration options (detailed comments are provided for each).

Log in to yourMy PlayStation account.

In another tab, go to:https://ca.account.sony.com/api/v1/ssocookie

Copy the value ofnpsso code.

Provide thePSN_NPSSO secret using one of the following methods:

• Pass it at runtime with-n /--npsso-key
• Set it as anenvironment variable (e.g.export PSN_NPSSO=...)
• Add it to.env file (PSN_NPSSO=...) for persistent use

Fallback:

• Hard-code it in the code or config file

Tokens expire after 2 months. The tool alerts on expiration.

If you store thePSN_NPSSO in a dotenv file you can update its value and send aSIGHUP signal to the process to reload the file with the newnpsso value without restarting the tool. More info inStoring Secrets andSignal Controls (macOS/Linux/Unix).

In order to monitor PlayStation user activity, proper privacy settings need to be enabled on the monitored user account.

The user should go toPlayStation account management.

The value inPrivacy Settings → Personal Info | Messaging → Online Status and Now Playing should be set set toFriends only orAnyone.

By default, time zone is auto-detected usingtzlocal. You can set it manually inpsn_monitor.conf:

LOCAL_TIMEZONE='Europe/Warsaw'

You can get the list of all time zones supported by pytz like this:

python3 -c"import pytz; print('\n'.join(pytz.all_timezones))"

If you want to use email notifications functionality, configure SMTP settings in thepsn_monitor.conf file.

Verify your SMTP settings by using--send-test-email flag (the tool will try to send a test email notification):

psn_monitor --send-test-email

It is recommended to store secrets likePSN_NPSSO orSMTP_PASSWORD as either an environment variable or in a dotenv file.

Set environment variables usingexport onLinux/Unix/macOS/WSL systems:

export PSN_NPSSO="your_psn_npsso_code"export SMTP_PASSWORD="your_smtp_password"

OnWindows Command Prompt useset instead ofexport and onWindows PowerShell use$env.

Alternatively store them persistently in a dotenv file (recommended):

PSN_NPSSO="your_psn_npsso_code"SMTP_PASSWORD="your_smtp_password"

By default the tool will auto-search for dotenv file named.env in current directory and then upward from it.

You can specify a custom file withDOTENV_FILE or--env-file flag:

psn_monitor<psn_user_id> --env-file /path/.env-psn_monitor

You can also disable.env auto-search withDOTENV_FILE = "none" or--env-file none:

psn_monitor<psn_user_id> --env-file none

As a fallback, you can also store secrets in the configuration file or source code.

To monitor specific user activity, just type the PlayStation (PSN) user's id (psn_user_id in the example below):

psn_monitor<psn_user_id>

If you have not setPSN_NPSSO secret, you can use-n flag:

psn_monitor<psn_user_id> -n"your_psn_npsso_code"

By default, the tool looks for a configuration file namedpsn_monitor.conf in:

• current directory
• home directory (~)
• script directory

If you generated a configuration file as described inConfiguration, but saved it under a different name or in a different directory, you can specify its location using the--config-file flag:

psn_monitor<psn_user_id> --config-file /path/psn_monitor_new.conf

The tool runs until interrupted (Ctrl+C). Usetmux orscreen for persistence.

You can monitor multiple PSN players by running multiple instances of the script.

The tool automatically saves its output topsn_monitor_<psn_user_id>.log file. It can be changed in the settings viaPSN_LOGFILE configuration option or disabled completely viaDISABLE_LOGGING /-d flag.

The tool also saves the timestamp and last status (after every change) topsn_<psn_user_id>_last_status.json file, so the last status is available after the restart of the tool.

To enable email notifications when a user gets online or offline:

• setACTIVE_INACTIVE_NOTIFICATION toTrue
• or use the-a flag

psn_monitor<psn_user_id> -a

To be informed when a user starts, stops or changes the played game:

• setGAME_CHANGE_NOTIFICATION toTrue
• or use the-g flag

psn_monitor<psn_user_id> -g

To disable sending an email on errors (enabled by default):

• setERROR_NOTIFICATION toFalse
• or use the-e flag

psn_monitor<psn_user_id> -e

Make sure you defined your SMTP settings earlier (seeSMTP settings).

Example email:

If you want to save all reported activities of the PSN user to a CSV file, setCSV_FILE or use-b flag:

psn_monitor<psn_user_id> -b psn_user_id.csv

The file will be automatically created if it does not exist.

If you want to customize polling intervals, use-k and-c flags (or corresponding configuration options):

psn_monitor<psn_user_id> -k 30 -c 120

• PSN_ACTIVE_CHECK_INTERVAL,-k: check interval when the user is online (seconds)
• PSN_CHECK_INTERVAL,-c: check interval when the user is offline (seconds)

The tool has several signal handlers implemented which allow to change behavior of the tool without a need to restart it with new configuration options / flags.

List of supported signals:

Send signals withkill orpkill, e.g.:

pkill -USR1 -f"psn_monitor <psn_user_id>"

As Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.

You can useGRC to color logs.

Add to your GRC config (~/.grc/grc.conf):

# monitoring log file.*_monitor_.*\.logconf.monitor_logs

Now copy theconf.monitor_logs to your~/.grc/ and log files should be nicely colored when usinggrc tool.

Example:

grc tail -F -n 100 psn_monitor_<psn_user_id>.log

SeeRELEASE_NOTES.md for details.

Licensed under GPLv3. SeeLICENSE.