Refactor: Rename player hotkey manager to GlobalMediaKeysManager and optimize speech logic

Author: M-Rajabi-dev

AudioShelf.py

@@ -95,8 +95,8 @@ def handle_uncaught_exception(exc_type, exc_value, exc_traceback):
     try:
         app = wx.GetApp()
         if app and hasattr(app, 'player_frame_instance') and app.player_frame_instance:
-            if hasattr(app.player_frame_instance, 'hotkey_manager') and app.player_frame_instance.hotkey_manager:
-                app.player_frame_instance.hotkey_manager.unregister_hotkeys()
+            if hasattr(app.player_frame_instance, 'global_keys_manager') and app.player_frame_instance.global_keys_manager:
+                app.player_frame_instance.global_keys_manager.unregister_hotkeys()
     except Exception as e:
         logging.error(f"Failed to cleanup during crash: {e}")
 

frames/player/event_handlers.py

@@ -8,21 +8,16 @@
 from typing import Optional, TYPE_CHECKING
 
 from database import db_manager
-from nvda_controller import set_app_focus_status
+from nvda_controller import set_app_focus_status, speak, LEVEL_MINIMAL
 
 if TYPE_CHECKING:
     from ..player_frame import PlayerFrame
 
 
 def on_engine_file_changed(frame: 'PlayerFrame', event, new_engine_index: int):
-    """
-    Handles the 'on_file_changed' event from the engine.
-    Updates the frame state, resets loops, and announces the new file.
-    """
     if new_engine_index < 0 or frame.is_exiting:
         return
 
-    # Reset Loop State
     if frame.loop_point_a_ms is not None:
         frame.loop_point_a_ms = None
     if frame.is_file_looping:
@@ -46,21 +41,18 @@ def on_engine_file_changed(frame: 'PlayerFrame', event, new_engine_index: int):
         logging.error("Critical Error: Invalid file index in book data")
         return
 
-    # Update NVDA focus label if applicable
     try:
-        if frame.nvda_focus_label and frame.current_file_path:
+        if frame.current_file_path:
             file_name = os.path.basename(frame.current_file_path)
-            frame.nvda_focus_label.SetLabel(file_name)
+            frame.update_file_display(file_name)
     except Exception:
         pass
 
-    # Update Duration
     try:
         frame.current_file_duration_ms = frame.book_file_durations[frame.current_file_index]
     except IndexError:
         frame.current_file_duration_ms = 0
 
-    # Reset start position for next file
     if frame.start_pos_ms > 0:
         frame.start_pos_ms = 0
 
@@ -172,8 +164,8 @@ def on_escape(frame: 'PlayerFrame', event=None):
     frame.is_exiting = True
 
     # Cleanup resources
-    if hasattr(frame, 'hotkey_manager') and frame.hotkey_manager:
-        frame.hotkey_manager.unregister_hotkeys()
+    if hasattr(frame, 'global_keys_manager') and frame.global_keys_manager:
+        frame.global_keys_manager.unregister_hotkeys()
 
     frame.ui_timer.Stop()
 

frames/player/global_media_keys.py

@@ -0,0 +1,113 @@
+# frames/player/global_media_keys.py
+# Copyright (c) 2025 Mehdi Rajabi
+# License: GNU General Public License v3.0 (See LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import wx
+import logging
+from typing import Dict, Callable
+
+if wx.Platform == '__WXMSW__':
+    try:
+        import ctypes
+        from ctypes import wintypes
+        user32 = ctypes.windll.user32
+        MOD_NONE = 0x0000
+        
+        VK_MEDIA_PLAY_PAUSE = 0xB3
+        VK_MEDIA_NEXT_TRACK = 0xB0
+        VK_MEDIA_PREV_TRACK = 0xB1
+        VK_VOLUME_UP = 0xAF
+        VK_VOLUME_DOWN = 0xAE
+        VK_VOLUME_MUTE = 0xAD
+        VK_BROWSER_BACK = 0xA6
+        VK_BROWSER_FORWARD = 0xA7
+    except (ImportError, AttributeError):
+        logging.error("Failed to import ctypes or load user32.dll. Global hotkeys disabled.")
+        user32 = None
+        VK_MEDIA_PLAY_PAUSE = VK_MEDIA_NEXT_TRACK = VK_MEDIA_PREV_TRACK = 0
+        VK_VOLUME_UP = VK_VOLUME_DOWN = VK_VOLUME_MUTE = 0
+        VK_BROWSER_BACK = VK_BROWSER_FORWARD = 0
+else:
+    logging.info("Native global hotkeys are only implemented for Windows.")
+    user32 = None
+    VK_MEDIA_PLAY_PAUSE = VK_MEDIA_NEXT_TRACK = VK_MEDIA_PREV_TRACK = 0
+    VK_VOLUME_UP = VK_VOLUME_DOWN = VK_VOLUME_MUTE = 0
+    VK_BROWSER_BACK = VK_BROWSER_FORWARD = 0
+
+
+class GlobalMediaKeysManager:
+    """
+    Manages the registration and handling of system-wide global hotkeys using
+    native Windows API calls (user32.dll).
+    """
+
+    def __init__(self, frame: wx.Frame):
+        self.frame = frame
+        self.hwnd = self.frame.GetHandle()
+        self.hotkey_map: Dict[int, Callable] = {}
+        self.next_hotkey_id: int = 1
+
+        if not self.hwnd:
+            logging.error("GlobalMediaKeysManager: Cannot register hotkeys, window handle (HWND) is None.")
+
+    def _register(self, vk_code: int, callback: Callable):
+        """Registers a single global hotkey with the OS."""
+        if not user32 or not self.hwnd:
+            return
+
+        hk_id = self.next_hotkey_id
+        self.next_hotkey_id += 1
+
+        if not user32.RegisterHotKey(self.hwnd, hk_id, MOD_NONE, vk_code):
+            error_code = ctypes.GetLastError()
+            logging.error(f"Failed to register hotkey ID {hk_id} (VK: {vk_code}). Error: {error_code}")
+        else:
+            logging.info(f"Registered hotkey ID {hk_id} (VK: {vk_code})")
+            self.hotkey_map[hk_id] = callback
+
+    def setup_hotkeys(self, key_function_map: Dict[int, Callable]):
+        """
+        Registers multiple hotkeys based on a mapping of VK codes to callback functions.
+        """
+        if not user32:
+            return
+
+        logging.info("Registering native Windows global hotkeys...")
+        for vk_code, callback in key_function_map.items():
+            if vk_code != 0:
+                self._register(vk_code, callback)
+
+    def on_hotkey_pressed(self, event: wx.KeyEvent):
+        """
+        Event handler for wx.EVT_HOTKEY.
+        """
+        if self.frame.is_exiting:
+            return
+
+        hk_id = event.GetId()
+        callback = self.hotkey_map.get(hk_id)
+        
+        if callback:
+            logging.debug(f"Global hotkey pressed, ID: {hk_id}")
+            try:
+                callback()
+            except Exception as e:
+                logging.error(f"Error executing hotkey callback: {e}")
+        else:
+            logging.warning(f"Unknown hotkey ID received: {hk_id}")
+        
+        event.Skip()
+
+    def unregister_hotkeys(self):
+        """Unregisters all currently active global hotkeys."""
+        if not user32 or not self.hwnd:
+            return
+
+        logging.info("Unregistering global hotkeys...")
+        for hk_id in list(self.hotkey_map.keys()):
+            if not user32.UnregisterHotKey(self.hwnd, hk_id):
+                logging.debug(f"Failed to unregister hotkey ID {hk_id}")
+            else:
+                logging.debug(f"Unregistered hotkey ID {hk_id}")
+        
+        self.hotkey_map.clear()

frames/player_frame.py

@@ -8,7 +8,7 @@
 from typing import List, Tuple, Optional
 import wx.lib.newevent
 
-from nvda_controller import set_app_focus_status
+from nvda_controller import set_app_focus_status, cancel_speech
 from database import db_manager
 from i18n import _
 from utils import SleepTimer
@@ -19,14 +19,14 @@
     dialog_manager,
     info,
     event_handlers,
-    hotkey_manager,
+    global_media_keys,
     playback_logic,
     volume_logic,
     seek_logic,
     book_loader,
     equalizer_frame
 )
-from .player.hotkey_manager import (
+from .player.global_media_keys import (
     VK_MEDIA_PLAY_PAUSE, VK_MEDIA_NEXT_TRACK, VK_MEDIA_PREV_TRACK,
     VK_VOLUME_UP, VK_VOLUME_DOWN, VK_VOLUME_MUTE,
     VK_BROWSER_BACK, VK_BROWSER_FORWARD
@@ -95,7 +95,7 @@ def __init__(self,
         # Managers
         self.equalizer_frame_instance: Optional[wx.Frame] = None
         self.sleep_timer_manager: Optional[SleepTimer] = None
-        self.hotkey_manager: Optional[hotkey_manager.HotkeyManager] = None
+        self.global_keys_manager: Optional[global_media_keys.GlobalMediaKeysManager] = None
         self.book_loader: Optional[book_loader.BookLoader] = None
         self.DurationUpdateEvent = DurationUpdateEvent
 
@@ -164,6 +164,10 @@ def _init_managers(self):
 
         self.book_loader = book_loader.BookLoader(self)
 
+    def _do_global(self, func):
+        cancel_speech()
+        func()
+
     def _bind_events(self):
         """Binds all events (UI, Engine, Hotkeys)."""
         self.nvda_focus_label.Bind(wx.EVT_CHAR_HOOK, lambda event: controls.on_key_down(self, event))
@@ -178,19 +182,21 @@ def _bind_events(self):
         self.Bind(wx.EVT_CLOSE, lambda event: event_handlers.on_escape(self, event))
 
         # Setup Global Hotkeys
-        self.hotkey_manager = hotkey_manager.HotkeyManager(self)
+        self.global_keys_manager = global_media_keys.GlobalMediaKeysManager(self)
+        
         key_function_map = {
-            VK_MEDIA_PLAY_PAUSE: lambda: playback_logic.toggle_play_pause(self),
-            VK_MEDIA_NEXT_TRACK: lambda: playback_logic.play_next_file(self, manual=True),
-            VK_MEDIA_PREV_TRACK: lambda: playback_logic.play_prev_file(self),
-            VK_VOLUME_UP: lambda: volume_logic.change_volume(self, 5),
-            VK_VOLUME_DOWN: lambda: volume_logic.change_volume(self, -5),
-            VK_VOLUME_MUTE: lambda: volume_logic.toggle_mute(self),
-            VK_BROWSER_BACK: lambda: seek_logic.seek_backward_setting(self),
-            VK_BROWSER_FORWARD: lambda: seek_logic.seek_forward_setting(self),
+            VK_MEDIA_PLAY_PAUSE: lambda: self._do_global(lambda: playback_logic.toggle_play_pause(self)),
+            VK_MEDIA_NEXT_TRACK: lambda: self._do_global(lambda: playback_logic.play_next_file(self, manual=True)),
+            VK_MEDIA_PREV_TRACK: lambda: self._do_global(lambda: playback_logic.play_prev_file(self)),
+            VK_VOLUME_UP: lambda: self._do_global(lambda: volume_logic.change_volume(self, 5)),
+            VK_VOLUME_DOWN: lambda: self._do_global(lambda: volume_logic.change_volume(self, -5)),
+            VK_VOLUME_MUTE: lambda: self._do_global(lambda: volume_logic.toggle_mute(self)),
+            VK_BROWSER_BACK: lambda: self._do_global(lambda: seek_logic.seek_backward_setting(self)),
+            VK_BROWSER_FORWARD: lambda: self._do_global(lambda: seek_logic.seek_forward_setting(self)),
         }
-        self.hotkey_manager.setup_hotkeys(key_function_map)
-        self.Bind(wx.EVT_HOTKEY, self.hotkey_manager.on_hotkey_pressed)
+        
+        self.global_keys_manager.setup_hotkeys(key_function_map)
+        self.Bind(wx.EVT_HOTKEY, self.global_keys_manager.on_hotkey_pressed)
 
         self.ui_timer = wx.Timer(self)
         self.Bind(wx.EVT_TIMER, lambda event: event_handlers.on_ui_timer(self, event), self.ui_timer)
@@ -282,3 +288,9 @@ def on_eq_enabled_changed(self, new_enabled: bool):
         """Toggles the Equalizer on/off."""
         self.is_eq_enabled = new_enabled
         self._update_audio_filters()
+
+    def update_file_display(self, filename: str):
+        self.nvda_focus_label.SetLabel(filename)
+        if not self.IsActive():
+            from nvda_controller import speak, LEVEL_MINIMAL
+            speak(filename, LEVEL_MINIMAL)