osd-notification

Cross-platform, network-triggerable On-Screen Display notification tool.

• Frameless, animated Qt notification widget (fade in/out, auto-sizing, screen-edge positioning)
• Threaded GNTP/1.0 TCP server and JSON UDP server, size-capped and payload-validated
• Typed, validated, self-healing INI configuration (auto-repairs missing keys, clamps out-of-range values)
• NotificationClient library with retry/backoff for sending notifications from other processes
• Path-traversal-safe icon resolution (icons must resolve inside an allow-listed directory)
• Production CLI: osd-notification

Install

pip install osd-notification
#or
pip install -e .[pretty,dotenv]

CLI usage

# Show config file path
osd-notification -c

# Show all config values (secrets masked)
osd-notification -c -s

# Get one value
osd-notification -c notification timeout

# Set one value
osd-notification -c notification timeout 5000

# Local demo notification (no server)
osd-notification -t

# Start GNTP (TCP) + UDP servers, blocks until Ctrl+C
osd-notification --server

# Send a notification to a running server
osd-notification --send --title "Build Successful" --text "All tests passed." --transport udp

Library usage

from osd_notification import NotificationClient

client = NotificationClient(host="127.0.0.1", udp_port=23064)
client.send(title="Build Successful", text="All unit tests passed.", icon="icon.png")

from osd_notification.app import OSDApplication

app = OSDApplication()
app.start_servers()
app.run()

Configuration

Config lives at ~/.osd-notification/osd-notification.ini (Windows: %USERPROFILE%\.osd-notification\osd-notification.ini).

Security notes

• Icon references from the network are resolved with resolve_icon_path, which rejects anything outside allowed_icon_dirs, non-image extensions, or non-existent files — this closes the path-traversal hole present in a naive os.path.exists(icon) check.
• UDP/TCP payloads are size-capped and run through NotificationPayload validation (title/text length limits, timeout bounds) before they ever reach the GUI.
• Secret-looking config keys (token, password, client_id, client_secret) are masked in --show output.

Development

pip install -e .[dev]
pytest

👤 Author

Hadi Cahyadi

Support me on Patreon