Developer Architecture

Developer Architecture

The desktop application is a PySide6 controller/view application around a service-oriented transcription core.

flowchart LR
    Entry[A2M.py] --> Controller[AppController]
    Controller --> Window[MainWindow / SettingsPanel]
    Controller --> Workers[Qt workers]
    Workers --> Conversion[conversion_service]
    Conversion --> Engine[piano_engine]
    Engine --> Runtime[runtime_service / onnx_runtime_service]
    Runtime --> ORT[ONNX Runtime sessions]
    Controller --> Model[model_service]
    Controller --> Packs[runtime_pack_service / GPU helper]
    Controller --> Config[config_service]

Loading

Responsibilities

Area	Primary module
Startup, signals, preflight, state transitions	app_controller.py
Main UI and settings controls	ui/main_window.py, ui/settings_panel.py
Background task lifecycle	workers/
Audio-to-event engine	core/piano_engine.py
Event-to-MIDI conversion	core/conversion_service.py
ONNX import, provider order, session creation	core/onnx_runtime_service.py
Runtime preference and cached state	core/runtime_service.py
Provider pack acquisition and validation	core/runtime_pack_service.py
Out-of-process GPU diagnostics	core/gpu_helper.py, core/gpu_runtime_manager.py
Model acquisition and validation	core/model_service.py
Settings schema and atomic persistence	core/config_service.py
Resource presets	core/resource_service.py

Important state boundaries

• UI work remains on the Qt thread; long work is delegated to workers.
• Workers communicate through payloads and signals and use cooperative stop events.
• Native ONNX Runtime implementations are selected carefully because importing one backend affects process state.
• GPU inventory and real session probes run in helper processes to isolate native imports and failures.
• Piano Engine sessions are cached using the bundle, device, provider, runtime path, and relevant options.
• Changing provider/resource state resets or invalidates compatible caches.

Source environment

The tracked requirements currently pin Python packages including NumPy 2.3.5, SciPy 1.18.0, ONNX Runtime 1.27.0, PySide6 6.10.1, SoundFile 0.14.0, soxr 1.1.0, pretty_midi 0.2.11, and audioread 3.1.0. The project declares Python 3.11+ in its user-facing source instructions; provider packs must additionally match the running CPython ABI recorded in pack metadata.

For technical background, start with How A2M Works, then Audio Processing Pipeline and A2M Piano Engine.