Configuration Model

musegpt runs in DAWs on varied hardware for extremely non-technical users. The config system must:

• Work out of the box with zero configuration
• Let power users override settings via env vars or a config file
• Let all users tune settings from the plugin UI
• Merge settings from all sources with predictable priority
• Be fully testable without a running plugin or backend

Config Sources (Priority Order)

Settings are merged from four sources. Higher priority wins when the same key is set in multiple places:

When the user changes a setting in the plugin UI, the change takes effect immediately and is persisted back to the config file for future sessions.

Config File

Default location: ~/.musegpt/config.toml

Can be overridden with MUSEGPT_CONFIG_PATH env var.

[backend]
name = "ollama"
url = "http://localhost:11434"
model = "llama3.2"
timeout_ms = 30000

[inference]
context_window = 4096
max_tokens = 512
temperature = 0.7
top_p = 0.9
stream = true
seed = -1              # -1 = not sent; >= 0 = sent in request body
system_prompt = ""     # empty = no system prompt

[resources]
max_threads = 4
max_memory_mb = 4096
gpu_enabled = true
gpu_layers = 0          # 0 = auto
gpu_memory_limit_mb = 0 # 0 = no limit

[network]
connect_timeout_ms = 5000
read_timeout_ms = 30000
retry_count = 2
retry_delay_ms = 1000

[buffers]
token_queue_size = 1024
midi_queue_size = 64
audio_buffer_frames = 512

[logging]
level = "info"          # debug, info, warn, error
file = ""               # empty = no file logging

Environment Variables

Every config key maps to an env var prefixed with MUSEGPT_ and using uppercase + underscores:

Plugin UI

The plugin UI exposes all settings through its native interface. When a user changes a value:

1. The new value takes effect immediately (runtime override, highest priority)
2. The value is written back to the config file for persistence
3. Other config sources are not modified

Merge Behavior

Final value = UI override ?? env var ?? config file ?? default

The ?? operator means "use this value if set, otherwise fall back." Each source either provides a value for a key or is absent. There is no partial merge within a section; each key is resolved independently.

Merge rules

• Type coercion: env vars are strings. The config system parses them to the correct type (int, float, bool, string). Invalid values are ignored with a warning and the next source in priority is used.
• Validation: every key has a valid range. Out-of-range values are clamped and a warning is logged.
• Unknown keys: unknown keys in the config file are preserved (not deleted) but ignored. Unknown env vars are ignored.
• Missing config file: not an error. Defaults are used.
• Malformed config file: logged as a warning. Defaults are used for unparseable keys.

Validation Ranges