Backend Interface

This page is the conceptual “contract” between frontend and backend.

What the backend provides

At minimum, the backend exposes:

• A configuration object describing the run (see Config Reference)
• A single entry point to execute separation (see Backend API)
• Optional hooks:
  • progress reporting
  • cancellation

How the GUI calls the backend

The desktop GUI typically runs the backend:

• in-process, background thread (default)
  See Backend Integration.

Optionally, PATCHBAY can run the backend as a subprocess worker (useful when you want a hard boundary for GPU memory lifecycle). That protocol is also documented in Backend Integration.

Error handling

• Backend raises exceptions on fatal errors.
• The GUI captures the traceback and displays it in the UI.
• See Troubleshooting and Logging & Debugging.

Last updated: 2026-01-24

Backend API at a glance

classDiagram
  class Config {
    +str model
    +Path audio
    +str description
    +List~Anchor~ anchors
    +str anchor_mode
    +float max_len_s
    +float overlap_s
    +bool predict_spans
    +int reranking_candidates
    +str device
    +bool fp16
    +Path out_target
    +Path out_residual
  }

  class Anchor {
    <<tuple>>
    +str sign
    +float start_s
    +float end_s
  }

  class ProgressReporter {
    <<interface>>
    +start(total_chunks)
    +update(percent, message)
    +finish()
  }

  class CancellationToken {
    +cancel()
    +is_cancelled() bool
    +raise_if_cancelled()
  }

  class FileLogger {
    +info(msg)
    +warn(msg)
    +error(msg)
  }

  class Pipeline {
    +run_pipeline(cfg, progress, logger, cancel_token) (out_target, out_residual)
  }

  Config --> Anchor
  Pipeline ..> Config
  Pipeline ..> ProgressReporter
  Pipeline ..> CancellationToken
  Pipeline ..> FileLogger

Loading

Control flow (GUI)

sequenceDiagram
  participant UI as GUI (main thread)
  participant W as BackendWorker
  participant P as run_pipeline()
  participant M as SAM-Audio model

  UI->>W: start(cfg)
  W->>P: run_pipeline(cfg, progress, cancel_token)
  P->>P: chunk plan + anchor plan
  P->>M: inference per chunk
  M-->>P: target + residual per chunk
  P-->>W: (out_target, out_residual)
  W-->>UI: done / error + progress events

Loading