Talon/cpu-affinity-nvda-addon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Talon
2025-10-12 13:48:41 +02:00
commit 35cd34b3ca
17 changed files with 10495 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
README.md Normal file
View File

@@ -0,0 +1,136 @@
# CPU Priority Manager for NVDA
An NVDA add-on that allows you to manage CPU affinity and process priority for NVDA processes, improving performance on systems with heterogeneous CPU architectures (e.g., Intel CPUs with Performance and Efficiency cores).
## Features
- **CPU Affinity Control**: Pin NVDA processes to specific CPU cores
- **Priority Management**: Set process priority from Normal to Realtime
- **Easy Configuration**: Integrated settings panel in NVDA preferences
- **Automatic Application**: Settings are applied automatically when NVDA starts
- **Child Process Support**: Applies settings to NVDA child processes as well
## Why Use This Add-on?
Modern AMD Ryzen and Intel CPUs feature a hybrid architecture with:
- **Performance cores (P-cores)**: High-performance cores for demanding tasks
- **Efficiency cores (E-cores)**: Power-efficient cores for background tasks
NVDA performs significantly better when pinned to Performance cores. This add-on allows you to pin NVDA to your CPU's Performance cores for better responsiveness and set higher process priority so NVDA theoretically gets more CPU time
## Installation
1. <a href="https://iamtalon.me/cpuPriority-1.0.0.nvda-addon">Download the .nvda-addon file</a>
2. Open it with NVDA running (press Enter on the file)
3. Follow the installation prompts
4. Restart NVDA
## Configuration
1. Open NVDA Settings (NVDA+N → Preferences → Settings)
2. Navigate to "CPU Priority Manager" category
3. Configure the following options:
### Settings
#### Enable CPU Priority Management
Check this box to activate the add-on's functionality.
#### CPU Cores
Specify which CPU cores NVDA should use, as a comma-separated list (e.g., `4,5,6,7`).
#### Process Priority
Choose the priority level for NVDA processes:
- **Normal**: Standard priority (default Windows behavior)
- **Above Normal**: Higher than normal applications
- **High**: High priority (recommended for most users)
- **Realtime**: Highest priority ⚠️ **Use with caution!**
**Recommended Setting:** High Priority
**Warning:** Realtime priority can make your system unstable if NVDA consumes too much CPU time. Only use this if you understand the implications.
### Applying Changes
After changing settings:
1. Click "OK" or "Apply" to save
2. **Restart NVDA** for changes to take effect
The add-on applies settings during NVDA startup, so a restart is required.
## How It Works
The add-on uses the `psutil` library to:
1. Identify the current NVDA process and its children
2. Set CPU affinity to restrict execution to specified cores
3. Set process priority using Windows priority classes
Settings are stored in your NVDA configuration and support configuration profiles.
## Troubleshooting
### Settings don't seem to apply
- Make sure you've restarted NVDA after changing settings
- Check the NVDA log (NVDA+F1) for any error messages
- Ensure you're running NVDA with sufficient permissions
### Invalid CPU cores error
- Make sure you're using valid core numbers (0 to N-1, where N is your total logical core count)
- Use only numbers and commas, no spaces: `0,1,2,3`
- The add-on will show your system's total core count in the settings panel
### Performance not improving
- Verify your CPU actually has Performance/Efficiency cores
- Try different core combinations
- Check Task Manager to confirm NVDA is running on the specified cores
- Consider starting with "High" priority before trying "Realtime"
### System becomes unstable
- If you set Realtime priority and experience issues:
1. Restart NVDA in safe mode (use `nvda.exe --safe-mode`)
2. Disable the add-on or change priority to "High"
3. Restart NVDA normally
### Configuration Storage
Settings are stored in `nvdaConfig\nvda.ini` under the `[cpuPriority]` section:
```ini
[cpuPriority]
enabled = True
cpuCores = 4,5,6,7
priorityLevel = HIGH
```
### Logging
The add-on logs all actions to the NVDA log. View the log with NVDA+F1 to see:
- When settings are applied
- Which processes were configured
- Any errors encountered
## Building from Source
If you want to build the add-on yourself:
1. You need python
2. Clone or download this repository
3. Install SCons: `uv tool install scons`
4. Run: `scons` in the project directory
5. The `.nvda-addon` file will be created in the project root
## License
This add-on is licensed under the GNU General Public License v2.0.
## Credits
- **psutil library**: Copyright (c) 2009, Jay Loden, Dave Daeschler, Giampaolo Rodola
- **NVDA**: Copyright (c) 2006-2025 NV Access
## Contributing
If you think I messed something up, feel free to poke me on <a href="https://dragonscave.space/@talon">Mastodon</a>. I had to close registrations to this forge because of a frankly insane amount of spam BS, so if you want in, let me know and I'll let you in. Alternatively, just fork the thing on your preferred forge and make some edits, tell me about it, and I'll pull in your changes.
## Disclaimer
This add-on modifies system-level process settings, so it's entirely possible something might fall over in weird circumstances. Check the safe mode above if you can't get NVDA to run anymore.
Also, this is my first time working with NVDA addons. I have very little idea of what I'm doing here as of yet. This addon works for me, it might work for you. That's about all I can say. Always happy to hear of improvements I could make, either on Mastodon or just by email or whatever. You can also hit my Discord at TalonTheDragon.