Skip to content

feat(config): add persistent settings and key bindings with Figment - #138

Closed
aRustyDev wants to merge 5 commits into
talwat:mainfrom
aRustyDev:stack/0/figment
Closed

aRustyDev wants to merge 5 commits into
talwat:mainfrom
aRustyDev:stack/0/figment

Conversation

@aRustyDev

@aRustyDev aRustyDev commented Oct 30, 2026 •

Copy link
Copy Markdown

TL;DR

Let users save playback settings and key bindings in config.toml, with environment variables and explicit CLI flags taking precedence. Existing defaults remain the starting point.

Note

#blocking #139

This PR is independent and ready for review. #139 waits for it to merge.

Changes

  • Load an optional config.toml from Lowfi's platform data directory; never create or overwrite it.
  • Resolve settings in order: defaults → TOML → LOWFI_* environment → explicit CLI flags. For example, LOWFI_UI__FPS=20 overrides the file, and --fps 30 overrides both.
  • Make terminal bindings configurable. Reject unknown fields, invalid values, and duplicate bindings with errors that identify the setting and source. Keep Ctrl+C reserved.
  • Preserve the legacy LOWFI_DISABLE_UI and LOWFI_FIXED_MPRIS_NAME switches outside structured settings.
  • Add docs/CONFIGURATION.md as the options reference, with file locations, defaults, accepted values, env/CLI mappings, binding rules, and troubleshooting. Keep a short README example and cross-link the legacy environment-variable documentation.
  • Add configuration/input regression tests. Terminal control hints continue to show the default keys.
  • Document the loading and validation contracts beside the code, including missing files, explicit CLI overrides, binding lookup, and list replacement. Link to the configuration reference for option details.

Why this approach

Flags work for a single invocation, but persistent settings currently need a shell alias or wrapper. A configuration file also gives key bindings a place to live.

Figment handles merging and source metadata instead of adding a custom file/env/CLI merge layer. Clap still parses CLI arguments; only explicitly supplied flags enter the merge, so parser defaults cannot silently overwrite a user's file. Strict validation catches misspellings rather than ignoring them. A binding list replaces one action's defaults, which also lets users disable that action's configurable keys with an empty list.

Preserve the existing width cap: values above 32 are accepted and render as 32. The reference and CLI help now describe that behavior. Rejecting those values would change established CLI behavior without being necessary for the configuration migration.

Validation

cargo test --locked: 46 passed, covering precedence, defaults, validation errors, bindings, and legacy environment switches. Config-loading tests isolate process environment changes with Figment Jail. cargo fmt --check reports the inherited formatting differences in src/ui/media_controls.rs, which this PR does not change.

Checked the documented fields and scalar defaults against Settings, parsed the TOML examples, verified relative file links, and ran lowfi --help to confirm the width description. Private-item documentation builds with inherited shared-code link warnings, repaired in #139.

@aRustyDev aRustyDev changed the title Migrate configuration to Figment Add persistent settings and key bindings with Figment Oct 30, 2026
@aRustyDev aRustyDev changed the title Add persistent settings and key bindings with Figment feat(config): add persistent settings and key bindings with Figment Oct 30, 2026
@aRustyDev
aRustyDev marked this pull request as ready for review October 30, 2026 02:40
@danielwerg

Copy link
Copy Markdown
Collaborator

@danielwerg danielwerg closed this Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants