Keyboard Shortcuts

Overview

py-xiaozhi provides comprehensive global keyboard shortcut support, allowing quick operations even when running in the background. The shortcut system is implemented with the pynput library and supports cross-platform use.

Default Shortcuts

Category	Shortcut	Function	Description
Voice Interaction	Ctrl+J	Push-to-Talk	Hold to record, release to send
	Ctrl+K	Auto Conversation	Toggle automatic voice detection on/off
	Ctrl+Q	Abort Conversation	Immediately stop AI response
Mode Control	Ctrl+M	Switch Interaction Mode	Switch between manual/auto modes
	Ctrl+W	Show/Hide Window	Minimize/restore the main window

Shortcut Details

Voice Interaction Shortcuts

Ctrl+J - Push-to-Talk

• Function: Manual press mode; records while the key is held
• How to use:
  1. Hold Ctrl+J
  2. Speak into the microphone
  3. Release the key to auto-send the audio
• Use cases: Precise control over recording duration, avoiding ambient noise interference

Ctrl+K - Auto Conversation

• Function: Toggle auto conversation mode on/off
• How to use: Press Ctrl+K to switch auto conversation state
• Use cases: Continuous conversation, long-duration interaction

Ctrl+Q - Abort Conversation

• Function: Immediately stop the current AI voice response
• How to use: Press Ctrl+Q while the AI is responding
• Use cases: When you need to urgently interrupt the AI's response

Mode Control Shortcuts

Ctrl+M - Switch Interaction Mode

• Function: Cycle through different voice interaction modes
• How to use: Press Ctrl+M to cycle through modes
• Mode types: Manual Press Mode ↔ Auto Conversation Mode

Ctrl+W - Show/Hide Window

• Function: Control the visibility of the main window
• How to use: Press Ctrl+W to toggle window visibility
• Use cases: Quickly hide/show the main interface

Shortcut Configuration

Configuration File Location

Shortcut configuration is stored in config/config.json:

{
  "SHORTCUTS": {
    "ENABLED": true,
    "MANUAL_PRESS": {
      "modifier": "ctrl",
      "key": "j",
      "description": "按住说话"
    },
    "AUTO_TOGGLE": {
      "modifier": "ctrl",
      "key": "k",
      "description": "自动对话"
    },
    "ABORT": {
      "modifier": "ctrl",
      "key": "q",
      "description": "中断对话"
    },
    "MODE_TOGGLE": {
      "modifier": "ctrl",
      "key": "m",
      "description": "切换模式"
    },
    "WINDOW_TOGGLE": {
      "modifier": "ctrl",
      "key": "w",
      "description": "显示/隐藏窗口"
    }
  }
}

Custom Shortcuts

Supported Modifier Keys

• ctrl - Ctrl key
• alt - Alt key
• shift - Shift key
• ctrl+alt - Ctrl+Alt combo
• ctrl+shift - Ctrl+Shift combo

Supported Primary Keys

• Letter keys: a-z
• Number keys: 0-9
• Function keys: f1-f12
• Special keys: space, enter, tab, esc

Configuration Example

{
  "SHORTCUTS": {
    "ENABLED": true,
    "MANUAL_PRESS": {
      "modifier": "alt",
      "key": "space",
      "description": "按住说话"
    },
    "AUTO_TOGGLE": {
      "modifier": "ctrl+shift",
      "key": "a",
      "description": "自动对话"
    }
  }
}

Platform Compatibility

Windows

• Full Support: All shortcut functions work normally
• Permission Requirements: Administrator privileges may be required in some cases
• Note: Avoid conflicts with system shortcuts

macOS

• Permission Configuration: Accessibility permissions must be granted
• Configuration Path: System Preferences → Security & Privacy → Privacy → Accessibility
• Terminal Permissions: If running via terminal, the terminal must also be authorized

Linux

• User Group: The user must be added to the input group
• Configuration Command: sudo usermod -a -G input $USER
• Desktop Environment: Supports X11 and Wayland

Troubleshooting

Shortcuts Not Responding

Check Configuration

1. Confirm SHORTCUTS.ENABLED is true in the config file
2. Check that the shortcut configuration format is correct
3. Verify the validity of modifier and primary keys

Permission Issues

# macOS: Check accessibility permissions
System Preferences → Security & Privacy → Privacy → Accessibility

# Linux: Add user to the audio group
sudo usermod -a -G input $USER

# Windows: Run with administrator privileges
Right-click application → Run as Administrator

Conflict Detection

1. Check if other programs are occupying the same shortcuts
2. Try switching to less common shortcut combinations
3. Close potentially conflicting applications

Common Error Handling

ImportError: No module named 'pynput'

# Install pynput library
pip install pynput

macOS Permission Denied

# Check and re-authorize
System Preferences → Security & Privacy → Privacy → Accessibility
# Remove and re-add the application

Linux Keyboard Listener Failure

# Re-login for user group changes to take effect
sudo usermod -a -G input $USER
# Log out and log back in

Advanced Configuration

Error Recovery Mechanism

The system has built-in shortcut error recovery:

• Health Check: Checks listener status every 30 seconds
• Auto Restart: Automatically restarts when failure is detected
• Error Counting: Triggers recovery when consecutive errors exceed the limit
• State Cleanup: Clears key states on restart

Debug Mode

Enable verbose log output:

# Enable debug logging in configuration
import logging
logging.getLogger('pynput').setLevel(logging.DEBUG)

Performance Optimization

• Key Cache: Reduces duplicate key detection
• Async Processing: Non-blocking key event handling
• Resource Management: Automatic cleanup of listener resources

Code Reference

Where the shortcut system is implemented:

• Main Implementation: src/plugins/shortcuts/
• Configuration Management: src/utils/config_manager.py
• Application Integration: src/application.py

Core Methods

# Start shortcut listener
from src.plugins.shortcuts import ShortcutsPlugin
shortcuts_plugin = ShortcutsPlugin()

# Manually stop listener
await shortcuts_plugin.stop()