repository·master·Indexed 27 days ago
https://github.com/xanderfrangos/twinkle-trayA Windows utility for managing the brightness of external monitors via the system tray, bypassing native Windows limitations. Version 1.18.0-beta2 supports DDC/CI and WMI, providing a command-line interface (v1.13.0+) for brightness changes, monitor selection, and VCP code transmission. The repository also includes modules such as @paymoapp/active-window for retrieving active window metadata across Windows, MacOS, and Linux, and @hensm/ddcci for Windows-based DDC/CI support.
Install the library via npm to use native modules for retrieving active window metadata (title, application name, icon, etc.) on Windows, MacOS, and Linux (X11 only).
Note: The project uses Node-API version 6 and provides prebuilt binaries via prebuild. If a prebuilt binary is unavailable, it will be built during installation. You can manually trigger a rebuild using npm run build:gyp.
npm install --save @paymoapp/active-windowThe win32-displayconfig module provides simplified Node.js bindings to the Win32 Display Device Reference API.
Compatibility Requirements:
The platform-dependent C++ / Objective-C++ libraries can be tested using the provided demo programs. Navigate to the specific platform's demo directory (e.g., module/linux/demo) and use make to build.
Available running modes:
make run - Fetches current window details, waits 3 seconds, then fetches again.make run MODE=loop - Polls the current window every 3 seconds until SIGINT (Ctrl+C).make run MODE=watch - Watches for changes to the active window or its title without polling.make run MODE=benchmark - Fetches window details 100,000 times (Linux) or 10,000 times (Windows) and prints total CPU seconds consumed.Install the @hensm/ddcci package via npm. Note that this package is currently only supported on Windows.
npm install @hensm/ddcciTo use the library, you must first call ActiveWindow.initialize(). On MacOS, if you are not running a GUI application, you should pass { osxRunLoop: true } to initialize() to enable subscriptions.
On MacOS, you must also check requestPermissions() to ensure the application has screen recording permissions; otherwise, the window title will return as an empty string.
import ActiveWindow from '@paymoapp/active-window';
// Must be called before any other method
ActiveWindow.initialize();
// Required for MacOS to fetch window titles
if (!ActiveWindow.requestPermissions()) {
console.log('Error: You need to grant screen recording permission in System Preferences > Security & Privacy > Privacy > Screen Recording');
process.exit(0);
}
const activeWin = ActiveWindow.getActiveWindow();
console.log('Window title:', activeWin.title);
console.log('Application:', activeWin.application);
console.log('Application path:', activeWin.path);
console.log('Application PID:', activeWin.pid);
console.log('Application icon:', activeWin.icon);import ActiveWindow from '@paymoapp/active-window';
ActiveWindow.initialize();
if (!ActiveWindow.requestPermissions()) {
console.log('Error: You need to grant screen recording permission in System Preferences > Security & Privacy > Privacy > Screen Recording');
process.exit(0);
}
const activeWin = ActiveWindow.getActiveWindow();
console.log('Window title:', activeWin.title);
console.log('Application:', activeWin.application);
console.log('Application path:', activeWin.path);
console.log('Application PID:', activeWin.pid);
console.log('Application icon:', activeWin.icon);To run a development build, you must build on Windows.
node-gyp build tools (often included with NodeJS).npm install.npm run build.npm start.npm install
npm run buildYou can install Twinkle Tray using several Windows package managers:
winget install xanderfrangos.twinkletrayTo install:
choco install twinkle-trayTo upgrade:
choco upgrade twinkle-trayNote: Chocolatey packages are not maintained by this repository.
To install:
scoop bucket add extras
scoop install extras/twinkle-trayTo upgrade:
scoop update twinkle-trayNote: Scoop packages are not maintained by this repository.
winget install xanderfrangos.twinkletrayTwinkle Tray can be configured to launch automatically when you log in to Windows. This is managed via the Windows Registry (Software\Microsoft\Windows\CurrentVersion\Run).
StartupApproved registry key.Twinkle Tray supports multiple languages via JSON localization files.
en, zh-CN, pt).localization/fr.json) exists, it is loaded; otherwise, it falls back to the default English (en.json) file.getLocalization function handles the mapping of system locales to supported language codes.Twinkle Tray supports custom hotkeys to control monitor settings like brightness, SDR level, contrast, volume, and power state.
Supported Action Types:
set: Sets a specific value.offset: Adjusts the current value by a given amount.cycle: Cycles through a predefined list of values.refresh: Triggers a monitor refresh.off: Triggers the sleep action defined in settings.Targetable Properties:
brightness: Controls standard brightness.sdr: Controls the SDR level (for HDR monitors).contrast: Controls contrast (uses VCP 0x12).volume: Controls volume (uses VCP 0x62).powerState: Controls power state (uses VCP 0xD2).Note: If settings.hotkeysBreakLinkedLevels is true, using a hotkey will automatically disable linked brightness levels.
Twinkle Tray can save and re-apply brightness settings for known displays.
applyProfile function can be used to apply a set of brightness/contrast settings to a list of monitors. It supports:useTransition is enabled, brightness changes are smoothed over time using transitionBrightness.settings.userSkipReapply can be excluded from profile application.Twinkle Tray relies on DDC/CI and WMI. Ensure DDC/CI is enabled in your monitor's physical settings/OSD menu.
Common Issues: