feat: much better config management and new schema

closes #121 & closes #120

Author: goodroot

lib/src/cli_commands.py

@@ -2207,48 +2207,35 @@ def setup_config(backend: Optional[str] = None, model: Optional[str] = None, rem
             for key, value in remote_config.items():
                 config.set_setting(key, value)
 
-        config.save_config()
-        log_success(f"Created {config_file}")
+        if config.save_config():
+            log_success(f"Created {config_file}")
+        else:
+            log_error(f"Failed to create {config_file}")
     else:
         log_info(f"Config already exists at {config_file}")
-        # Update existing config if needed
+        # Update existing config via ConfigManager (handles migrations, sparse save)
         try:
-            with open(config_file, 'r', encoding='utf-8') as f:
-                existing_config = json.load(f)
-            
-            # Update backend if provided (accept both old 'local'/'remote' and new backend types)
+            config = ConfigManager()
+
             if backend:
                 # Map old values for backward compatibility
                 if backend == 'local':
-                    backend = 'cpu'  # Map old 'local' to 'cpu'
+                    backend = 'cpu'
                 elif backend == 'remote':
-                    backend = 'rest-api'  # Map old 'remote' to 'rest-api'
-                existing_config['transcription_backend'] = backend
-            
-            # Apply remote configuration if provided
+                    backend = 'rest-api'
+                config.set_setting('transcription_backend', backend)
+
             if remote_config:
                 for key, value in remote_config.items():
-                    existing_config[key] = value
-            
-            # Update model if provided, otherwise default to base if missing
+                    config.set_setting(key, value)
+
             if model:
-                existing_config['model'] = model
-            elif 'model' not in existing_config and not remote_config:
-                # Only set default model if not using remote backend
-                existing_config['model'] = 'base'
-            
-            # Add audio_feedback if missing
-            if 'audio_feedback' not in existing_config:
-                existing_config['audio_feedback'] = True
-                existing_config['start_sound_volume'] = 1.0
-                existing_config['stop_sound_volume'] = 1.0
-                existing_config['start_sound_path'] = 'ping-up.ogg'
-                existing_config['stop_sound_path'] = 'ping-down.ogg'
-            
-            with open(config_file, 'w', encoding='utf-8') as f:
-                json.dump(existing_config, f, indent=2)
-            
-            log_success("Updated existing config")
+                config.set_setting('model', model)
+
+            if config.save_config():
+                log_success("Updated existing config")
+            else:
+                log_error("Failed to save updated config")
         except Exception as e:
             log_error(f"Failed to update config: {e}")
 

lib/src/config_manager.py

@@ -3,6 +3,7 @@
 Handles loading, saving, and managing application settings
 """
 
+import copy
 import json
 from pathlib import Path
 from typing import Any, Dict
@@ -15,7 +16,9 @@
 
 class ConfigManager:
     """Manages application configuration and settings"""
-    
+
+    SCHEMA_URL = "https://raw.githubusercontent.com/goodroot/hyprwhspr/main/share/config.schema.json"
+
     def __init__(self):
         # Default configuration values - minimal set for hyprwhspr
         self.default_config = {
@@ -75,6 +78,15 @@ def __init__(self):
             'onnx_asr_model': 'nemo-parakeet-tdt-0.6b-v3',  # Best balance of speed and quality for CPU (includes punctuation)
             'onnx_asr_quantization': 'int8',             # INT8 quantization for CPU performance (or None for fp32)
             'onnx_asr_use_vad': True,                    # Use VAD for long recordings (>30s)
+            # Audio feedback settings
+            'audio_feedback': False,             # Play sounds on recording start/stop/error
+            'audio_volume': 0.5,                 # Master audio feedback volume (0.0-1.0)
+            'start_sound_volume': 1.0,           # Volume multiplier for start sound
+            'stop_sound_volume': 1.0,            # Volume multiplier for stop sound
+            'error_sound_volume': 0.5,           # Volume multiplier for error sound
+            'start_sound_path': None,            # Custom path for start sound (None = built-in ping-up.ogg)
+            'stop_sound_path': None,             # Custom path for stop sound (None = built-in ping-down.ogg)
+            'error_sound_path': None,            # Custom path for error sound (None = built-in ping-error.ogg)
             # Visual feedback settings
             'mic_osd_enabled': True,             # Show microphone visualization overlay during recording
             'mute_detection': True,              # Enable mute detection to cancel recording when mic is muted
@@ -94,7 +106,8 @@ def __init__(self):
         self.config_file = CONFIG_FILE
 
         # Current configuration (starts with defaults)
-        self.config = self.default_config.copy()
+        # Deep copy so mutable values (dicts, lists) aren't shared references
+        self.config = copy.deepcopy(self.default_config)
 
         # Ensure config directory exists
         self._ensure_config_dir()
@@ -120,34 +133,49 @@ def _load_config(self):
                 with open(self.config_file, 'r', encoding='utf-8') as f:
                     loaded_config = json.load(f)
 
+                # Detect whether this is a new-style sparse config (has $schema)
+                # or a legacy full config. Legacy configs need "missing key" migrations;
+                # sparse configs omit default values intentionally.
+                is_legacy_config = '$schema' not in loaded_config
+
+                # Strip $schema key so it doesn't pollute self.config
+                loaded_config.pop('$schema', None)
+
                 # Migrate old push_to_talk config to recording_mode (before merging with defaults)
                 # Check the original loaded_config, not self.config (which has defaults merged)
-                migration_occurred = False
+                migrations = []
                 if 'push_to_talk' in loaded_config and 'recording_mode' not in loaded_config:
                     if loaded_config['push_to_talk']:
                         loaded_config['recording_mode'] = 'push_to_talk'
                     else:
                         loaded_config['recording_mode'] = 'toggle'
                     # Remove old push_to_talk key from loaded config
                     del loaded_config['push_to_talk']
-                    migration_occurred = True
+                    migrations.append("'push_to_talk' -> 'recording_mode'")
 
                 # Migrate old audio_device config key to audio_device_id
                 if 'audio_device' in loaded_config and 'audio_device_id' not in loaded_config:
                     loaded_config['audio_device_id'] = loaded_config['audio_device']
                     del loaded_config['audio_device']
-                    migration_occurred = True
+                    migrations.append("'audio_device' -> 'audio_device_id'")
+
+                # Migrate pre-audio-feedback configs: enable audio feedback for existing users
+                # who set up before this feature existed (previously done in setup_config).
+                # Only for legacy configs — sparse configs omit audio_feedback intentionally.
+                if is_legacy_config and 'audio_feedback' not in loaded_config:
+                    loaded_config['audio_feedback'] = True
+                    migrations.append("enabled 'audio_feedback' for legacy config")
 
                 # Merge loaded config with defaults (preserving any new default keys)
                 self.config.update(loaded_config)
-                
+
                 # Attempt automatic migration of API key if needed
                 self.migrate_api_key_to_credential_manager()
-                
+
                 # Save migrated config if migration occurred
-                if migration_occurred:
+                if migrations:
                     self.save_config()
-                    print("Migrated 'push_to_talk' config to 'recording_mode'")
+                    print(f"Migrated config: {', '.join(migrations)}")
 
                 print(f"Configuration loaded from {self.config_file}")
             else:
@@ -160,10 +188,14 @@ def _load_config(self):
             print("Using default configuration")
 
     def save_config(self) -> bool:
-        """Save current configuration to file"""
+        """Save current configuration to file (sparse: only non-default keys + $schema)"""
         try:
+            sparse = {"$schema": self.SCHEMA_URL}
+            for key, value in self.config.items():
+                if key not in self.default_config or self.default_config[key] != value:
+                    sparse[key] = value
             with open(self.config_file, 'w', encoding='utf-8') as f:
-                json.dump(self.config, f, indent=2)
+                json.dump(sparse, f, indent=2)
             print(f"Configuration saved to {self.config_file}")
             return True
         except Exception as e:
@@ -184,7 +216,7 @@ def get_all_settings(self) -> Dict[str, Any]:
 
     def reset_to_defaults(self):
         """Reset configuration to default values"""
-        self.config = self.default_config.copy()
+        self.config = copy.deepcopy(self.default_config)
         print("Configuration reset to defaults")
 
     def get_temp_directory(self) -> Path: