Config Migration

DearScenario Player's config.json uses a schema versioning system. When you upgrade the player to a newer version, the configuration file is automatically migrated to the latest schema — no manual editing required.

How migration works

1. On startup, the player reads the schema_version field from config.json.
2. If the version is older than the current binary's schema version, migration functions run sequentially: v0→v1, v1→v2, etc.
3. Migrated fields are renamed or restructured to match the new schema.
4. The updated config is written back to disk.
5. Migration notes are logged at INFO level.

If schema_version is absent, it is treated as 0 (the initial schema).

Current schema version

Migration history

v0 → v1: network.http.web_root renamed

network.http.web_root  →  network.http_web_root

The nested network.http object was flattened. The http sub-object is removed after migration.

Before (v0):

{
  "network": {
    "http": { "web_root": "web-console" }
  }
}

After (v1):

{
  "network": {
    "http_web_root": "web-console"
  }
}

v1 → v2: playlist.prefer_hardware_decoding replaced

playlist.prefer_hardware_decoding (bool)  →  playlist.hwdec_mode (string)

The boolean hardware decoding toggle was replaced with a more expressive string mode to support Raspberry Pi V4L2 M2M decoding.

Before (v1):

{
  "playlist": {
    "prefer_hardware_decoding": true
  }
}

After (v2):

{
  "playlist": {
    "hwdec_mode": "auto"
  }
}

Mapping: true → "auto", false → "no".

v2 → v3: audio output device added

audio.output_device = "auto"

The migration creates the audio object when needed and adds output_device: "auto". Existing audio configuration is preserved.

Current loader: playlist.hwdec_mode moved to decode

The remaining playlist object was a leftover name from deleted autoload / resume keys. The loader copies playlist.hwdec_mode to decode.hwdec_mode, logs playlist.hwdec_mode moved to decode.hwdec_mode, and erases playlist on save. If both objects exist, decode.hwdec_mode wins.

Forward compatibility

If the schema_version in config.json is newer than what the binary supports (e.g. you downgrade the player), the binary:

• Does not modify the config.
• Logs a note: "config schema is newer than this binary; keeping unknown fields intact".
• Preserves all unknown fields as-is.

This ensures that downgrading the player does not destroy newer configuration.

Monitoring migrations

Migration activity is logged at startup:

[INFO] [Config] migrated network.http.web_root -> network.http_web_root
[INFO] [Config] migrated playlist.prefer_hardware_decoding -> playlist.hwdec_mode
[INFO] [Config] added audio.output_device with auto default

Check the log file (see Logs & Crash Dumps) after upgrading to verify migrations ran correctly.

Manual intervention

In most cases, no manual action is needed. If a migration fails or you want to start fresh:

1. Back up your current config.json.
2. Delete config.json (or rename it to config.json.bak).
3. Launch the player — it generates a new config with default values.
4. Re-apply your custom settings.

After manually editing the selected configuration file, restart the player. Settings also saves changes for the next process startup.

See Configuration Sources for the full configuration loading priority and restart behavior.

Previous / Next

• Previous: Configuration Sources
• Next: Action System