Backend Integration

This page documents how the GUI (and other host apps) integrate the backend.

In-process worker thread (DearPyGui frontend)

The current desktop GUI uses patchbay_desktop_gui/gui/worker.py.

Key properties:

• Backend runs in a daemon thread (threading.Thread)
• Progress + terminal events are written to a queue.Queue
• The UI polls the queue periodically and updates widgets on the main thread

Event payload (WorkerEvent) includes:

• kind: "progress" | "done" | "cancelled" | "error"
• message: status string
• percent: optional float for progress
• out_target, out_residual: only for "done"
• traceback_text: only for "error"

This design avoids cross-thread GUI calls (a common source of crashes).

Cancellation

Backend cancellation uses patchbay_backend.cancel_token.CancellationToken.

• The GUI calls BackendWorker.cancel()
• The pipeline checks cancel_token.raise_if_cancelled() at safe points:
  • after chunk planning
  • between chunks
  • after chunk inference

Cancellation is best-effort: if the model call is currently executing, it may only stop after that call returns.

Subprocess worker protocol (optional)

If you need stronger isolation (for example: always free CUDA memory on exit), you can run the backend in a separate process.

patchbay_backend/gui_subprocess.py defines the protocol:

Input: JSON config

The subprocess reads a JSON file:

{
  "model": "facebook/sam-audio-small",
  "audio": "input.wav",
  "description": "speech",
  "out_target": "target.wav",
  "out_residual": "residual.wav",
  "max_len_s": 20.0,
  "overlap_s": 2.0,
  "anchor_mode": "prepend_nearest",
  "anchors": [["+", 12.3, 14.1]]
}

Unknown keys are ignored (forward-compatible).

Output: JSON Lines on stdout

Each line is a JSON object:

• Progress: {"event":"update","message":"Chunk 2/8 ...","percent":56.0}
• Failure: {"event":"fail","message":"ValueError: ...","traceback":"..."}
• Final result (always emitted on success): {"event":"result","message":"OK","percent":100.0,"out_target":"...","out_residual":"..."}

Minimal runner snippet

import json, subprocess, sys, pathlib

cfg_path = pathlib.Path("run_config.json")
cfg_path.write_text(json.dumps(cfg, indent=2), encoding="utf-8")

p = subprocess.Popen(
    [sys.executable, "-m", "patchbay_backend.gui_subprocess", "--config", str(cfg_path)],
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True,
)
for line in p.stdout:
    print("GUI EVENT:", line.rstrip())

Progress callback API (embedding)

If you embed the backend directly, use CallbackProgress (see Backend API). The preferred signature is:

callback(event: str, message: str, percent: float | None)

Backwards-compatible signatures are supported (message-only callbacks), but you lose event granularity.

Last updated: 2026-01-24