Security
- Default scripts_management, callbacks_management, links_management, and
media_folders_management to False so a leaked token cannot escalate to RCE
through admin CRUD endpoints.
- TokenSpec + scope hierarchy (read | control | admin); legacy bare-string
api_tokens entries promote to admin for back-compat. Management endpoints
now require admin scope.
- WebSocket subprotocol auth (Sec-WebSocket-Protocol: media-server.token.<T>)
preferred over ?token= query so the token no longer lands in URL/history/
Referer; query fallback retained for HA integration back-compat.
- Origin allow-list check on the WS endpoint (CSWSH defence).
- In-process token-bucket rate limiter: 5/min for failed auths,
10/min for /api/scripts/execute and /api/callbacks/execute.
- shell=False subprocess path (shlex.split) + per-parameter regex `pattern`
in ScriptParameterConfig to harden shell=true scripts against parameter
injection (Windows cmd.exe env-var expansion).
- CSP gains form-action, worker-src, manifest-src directives.
- Refuse cors_origins=["*"] at startup; strip token=... from uvicorn access
logs; validate Gitea release tag against strict SemVer regex.
- noopener noreferrer + no-referrer referrerpolicy on every outbound link.
- icacls hardening of config.yaml on Windows (current user + SYSTEM +
Administrators only); 0600 still enforced on POSIX.
- WS volume handler clamps input and never drops the socket on bad messages.
Performance
- Album-art read in windows_media gated by track key — was decoding the
WinRT thumbnail twice per second regardless of track changes.
- /api/media/artwork returns content-derived ETag + Cache-Control so the
browser sends If-None-Match and gets 304s on track repeats.
- Foreground-service ctypes argtypes hoisted to one-time module init
(was re-declaring ~14 prototypes per probe).
- display_service _static_cache keyed by (edid_hash, ...) tuple with
eviction of disappeared monitors — fixes stale capabilities on hot-plug
swaps where the new topology has the same monitor count.
- Visualizer rAF loop paused on document.hidden, resumed on visible.
Reliability / bug fixes
- Lifespan rewritten as try/yield/finally so a partial-startup failure
cannot orphan background tasks or executors.
- _run_callback in routes/media.py keeps a strong task ref (GC-safe) and
uses the dedicated callback executor instead of the default pool.
- macos_media.set_volume() no longer always returns True.
- TrayManager._restart_requested initialised in __init__; set before
signalling exit so the main thread observes it correctly.
- Missing static_dir now logs a WARNING instead of silent UI disable.
UX / accessibility / PWA
- manifest.json theme_color and background_color match the Studio Reference
base (#0E0D0B); added id and scope for PWA installability.
- ARIA on mini-player icon buttons; inner SVGs marked aria-hidden.
- OS mediaSession API wired so headset / lockscreen / Bluetooth buttons
drive play/pause/next/prev/seek and show track metadata + artwork.
Observability
- X-Request-ID middleware (accept upstream id if it matches a safe regex,
otherwise UUID4); request_id_var added to ContextVars and included in
every log line alongside the token label.
- Audit log (append-only JSONL) for every script + callback execution,
including the on_play/on_pause/etc. event callbacks. Background-thread
writer; queue capped; flushed in lifespan teardown.
Deployment
- proxy_headers + forwarded_allow_ips plumbed through Settings →
uvicorn.Config for reverse-proxy installs.
- HTTPS support via ssl_certfile + ssl_keyfile (+ optional password);
startup refuses to launch with only one of the pair set.
- Thumbnail cache moved from project-root .cache to
%LOCALAPPDATA%/media-server/cache (Windows) and
$XDG_CACHE_HOME/media-server/thumbnails (POSIX).
Tests
- 35 new tests across auth scopes, rate limiter, browser path traversal
(../ NUL UNC absolute), script-param validation incl. regex, Gitea tag
whitelist, config atomic write + POSIX perms. 47 passed / 4 skipped.
- Refactored index.html: Split into separate HTML (309 lines), CSS (908 lines), and JS (1,286 lines) files
- Implemented media browser with folder configuration, recursive navigation, and thumbnail display
- Added metadata extraction using mutagen library (title, artist, album, duration, bitrate, codec)
- Implemented thumbnail generation and caching with SHA256 hash-based keys and LRU eviction
- Added platform-specific file playback (os.startfile on Windows, xdg-open on Linux, open on macOS)
- Implemented path validation security to prevent directory traversal attacks
- Added smooth thumbnail loading with fade-in animation and loading spinner
- Added i18n support for browser (English and Russian)
- Updated dependencies: mutagen>=1.47.0, pillow>=10.0.0
- Added comprehensive media browser documentation to README
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
FastAPI REST API server for controlling system-wide media playback
on Windows, Linux, macOS, and Android.
Features:
- Play/Pause/Stop/Next/Previous track controls
- Volume control and mute
- Seek within tracks
- Current track info (title, artist, album, artwork)
- WebSocket real-time status updates
- Script execution API
- Token-based authentication
- Cross-platform support
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
alexei.dolgolyov