wallpaper-engine 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,529 @@
+/** File type accepted by file/directory properties */
+type WallpaperFileType = "image" | "video";
+/**
+ * Localization map inside `project.json`'s `general.localization`.
+ * Outer key: BCP-47 language code (e.g. `"en-us"`, `"de-de"`, `"zh-chs"`).
+ * Inner key: `ui_` token string. Value: translated display text.
+ *
+ * @example
+ * {
+ *   "en-us": { "ui_mycolor": "Background color" },
+ *   "de-de": { "ui_mycolor": "Hintergrundfarbe" }
+ * }
+ */
+type WallpaperLocalization = Record<string, Record<string, string>>;
+interface WallpaperPropertyBase {
+    /** Display label shown in the properties panel, or a `ui_` token for localization */
+    text: string;
+    /** Sort index within the properties panel */
+    order?: number;
+    /** Internal sequential index (auto-assigned by the editor) */
+    index?: number;
+    /**
+     * JavaScript expression evaluated to determine visibility.
+     * References other property keys, e.g. `"showclock.value == true"`.
+     */
+    condition?: string;
+}
+/**
+ * Color picker property. Shows a color picker to the user.
+ * The runtime value is `"R G B"` where each channel is in the **0–1** range.
+ */
+interface WallpaperColorProperty extends WallpaperPropertyBase {
+    type: "color";
+    /** Default color as `"R G B"` with each channel in the 0–1 range. */
+    value: string;
+}
+/**
+ * Slider property. Lets users pick a number in a defined range.
+ * Enable `fraction` for decimal values; `precision` controls decimal places (default: `2`).
+ */
+interface WallpaperSliderProperty extends WallpaperPropertyBase {
+    type: "slider";
+    /** Default value — should be within `[min, max]`. */
+    value: number;
+    min: number;
+    max: number;
+    /** Allow fractional (decimal) values. */
+    fraction?: boolean;
+    /** Number of decimal places when `fraction` is `true` (default: `2`). */
+    precision?: number;
+}
+/** Checkbox (on/off toggle) property. */
+interface WallpaperBoolProperty extends WallpaperPropertyBase {
+    type: "bool";
+    /** Default checked state. */
+    value: boolean;
+}
+interface WallpaperComboOption {
+    /** Human-readable label shown in the dropdown, or a `ui_` token */
+    label: string;
+    /** Hidden value passed to `applyUserProperties` */
+    value: string;
+}
+interface WallpaperComboProperty extends WallpaperPropertyBase {
+    type: "combo";
+    /** Key of the default selected option */
+    value: string;
+    options: WallpaperComboOption[];
+}
+/** Free-text input property. */
+interface WallpaperTextInputProperty extends WallpaperPropertyBase {
+    type: "textinput";
+    /** Default text value. */
+    value: string;
+}
+/**
+ * File selector property. Lets users import a single image or video file.
+ * The runtime `value` path must be prefixed with `"file:///"` before use as a URL.
+ */
+interface WallpaperFileProperty extends WallpaperPropertyBase {
+    type: "file";
+    /** Default file path (empty string = no file selected). */
+    value: string;
+    fileType?: WallpaperFileType;
+}
+/**
+ * Directory selector for mass-importing image or video files.
+ * Choose between `"ondemand"` (one random file at a time via
+ * `wallpaperRequestRandomFileForProperty`) and `"fetchall"` (all files
+ * surfaced via `userDirectoryFilesAddedOrChanged` / `userDirectoryFilesRemoved`).
+ */
+interface WallpaperDirectoryProperty extends WallpaperPropertyBase {
+    type: "directory";
+    /** Default directory path (empty string = no directory selected). */
+    value: string;
+    fileType?: WallpaperFileType;
+    /**
+     * - `"ondemand"` — call `wallpaperRequestRandomFileForProperty` to get a file.
+     * - `"fetchall"` — all files are surfaced via `userDirectoryFilesAddedOrChanged`.
+     */
+    mode: "ondemand" | "fetchall";
+}
+/** Union of all property definition types stored in `project.json`. */
+type WallpaperPropertyDefinition = WallpaperColorProperty | WallpaperSliderProperty | WallpaperBoolProperty | WallpaperComboProperty | WallpaperTextInputProperty | WallpaperFileProperty | WallpaperDirectoryProperty;
+/** The `general` block inside `project.json`. */
+interface WallpaperProjectGeneral {
+    properties?: Record<string, WallpaperPropertyDefinition>;
+    localization?: WallpaperLocalization;
+}
+/** Full shape of the `project.json` file generated by Wallpaper Engine */
+interface WallpaperProject {
+    /** Entry HTML file name relative to the project directory */
+    file: string;
+    /** Wallpaper title shown in the Wallpaper Engine UI */
+    title: string;
+    type: "web";
+    /**
+     * Set to `true` to enable audio data delivery.
+     * Wallpaper Engine auto-detects this from `wallpaperRegisterAudioListener`
+     * calls, but you can also set it manually.
+     */
+    supportsaudioprocessing?: boolean;
+    general?: WallpaperProjectGeneral;
+}
+
+/**
+ * Runtime value of a color property.
+ * `value` is `"R G B"` where each channel is in the **0–1** range.
+ * Multiply by 255 to convert for CSS `rgb()`.
+ *
+ * @example
+ * const [r, g, b] = props.myColor.value.split(' ').map(c => Math.ceil(+c * 255));
+ * el.style.color = `rgb(${r},${g},${b})`;
+ */
+interface WallpaperColorValue {
+    /** Color string `"R G B"` — each channel 0.0–1.0. */
+    value: string;
+}
+/** Runtime value of a slider property. */
+interface WallpaperSliderValue {
+    value: number;
+}
+/** Runtime value of a checkbox (`bool`) property. */
+interface WallpaperBoolValue {
+    value: boolean;
+}
+/**
+ * Runtime value of a combo (dropdown) property.
+ * `value` is the hidden key configured in the editor;
+ * `text` is the visible display label.
+ */
+interface WallpaperComboValue {
+    /** The hidden value configured on the combo option. */
+    value: string;
+    /** Display label of the selected option (may be a `ui_` localization token). */
+    text: string;
+}
+/** Runtime value of a text-input property. */
+interface WallpaperTextValue {
+    value: string;
+}
+/**
+ * Runtime value of a file property.
+ * Prepend `"file:///"` to `value` before using it as a URL.
+ *
+ * @example
+ * img.src = 'file:///' + props.myImage.value;
+ */
+interface WallpaperFileValue {
+    /** File path — prepend `"file:///"` before use as a URL. */
+    value: string;
+}
+/**
+ * Runtime value of a directory property in `ondemand` mode.
+ * An empty string means no directory is currently selected.
+ * Call `wallpaperRequestRandomFileForProperty` to retrieve a random file.
+ */
+interface WallpaperDirectoryValue {
+    /** Directory path, or empty string when no directory is selected. */
+    value: string;
+}
+/** Union of all possible runtime property values delivered by `applyUserProperties`. */
+type WallpaperPropertyRuntimeValue = WallpaperColorValue | WallpaperSliderValue | WallpaperBoolValue | WallpaperComboValue | WallpaperTextValue | WallpaperFileValue | WallpaperDirectoryValue;
+/**
+ * Map of property key → current runtime value passed to
+ * `wallpaperPropertyListener.applyUserProperties`.
+ * On first load all properties are present; on subsequent calls only the
+ * changed ones are included — always guard with `if (properties.key)`.
+ */
+type WallpaperUserProperties = Record<string, WallpaperPropertyRuntimeValue>;
+/** App-level settings delivered by `wallpaperPropertyListener.applyGeneralProperties`. */
+interface WallpaperGeneralProperties {
+    /** Current FPS limit set by the user in Wallpaper Engine settings. `0` = unlimited. */
+    fps?: number;
+}
+/**
+ * Assign to `window.wallpaperPropertyListener` to receive property and
+ * app-settings updates. **Must be a top-level global** — never assign inside
+ * `window.onload` or other events, or startup events may be missed.
+ *
+ * @example
+ * window.wallpaperPropertyListener = {
+ *   applyUserProperties(properties) {
+ *     if (properties.mycolor) { ... }
+ *   },
+ * };
+ */
+interface WallpaperPropertyListener {
+    /**
+     * Called once on wallpaper load (with all user properties) and again
+     * whenever the user changes a property. Only changed properties are
+     * included on subsequent calls — always guard with `if (properties.key)`.
+     */
+    applyUserProperties?: (properties: WallpaperUserProperties) => void;
+    /**
+     * Called on load and whenever the user changes app-level settings
+     * such as the FPS limit. See {@link WallpaperGeneralProperties}.
+     */
+    applyGeneralProperties?: (properties: WallpaperGeneralProperties) => void;
+    /**
+     * Called for `directory` properties in `fetchall` mode when files are
+     * added or modified in the selected directory. Prepend `"file:///"` to
+     * each path before using it as a URL.
+     */
+    userDirectoryFilesAddedOrChanged?: (propertyName: string, changedFiles: string[]) => void;
+    /**
+     * Called for `directory` properties in `fetchall` mode when files are
+     * removed from the selected directory.
+     */
+    userDirectoryFilesRemoved?: (propertyName: string, removedFiles: string[]) => void;
+}
+/**
+ * Assign to `window.wallpaperPluginListener` to detect when RGB plugins load.
+ * Check `name` to distinguish `"led"` (all RGB hardware via `wpPlugins.led`)
+ * from `"cue"` (Corsair iCUE direct SDK, only needed for advanced features).
+ *
+ * @example
+ * window.wallpaperPluginListener = {
+ *   onPluginLoaded(name, version) {
+ *     if (name === 'led') { // general RGB hardware ready
+ *     }
+ *     if (name === 'cue') { // Corsair iCUE SDK ready
+ *     }
+ *   },
+ * };
+ */
+interface WallpaperPluginListener {
+    /**
+     * Fired when a plugin finishes loading.
+     * @param name    - `"led"` for general RGB hardware or `"cue"` for Corsair iCUE.
+     * @param version - Plugin version string.
+     */
+    onPluginLoaded?: (name: string, version: string) => void;
+}
+/**
+ * Event fired by `wallpaperRegisterMediaStatusListener` when the user enables
+ * or disables media integration in the Wallpaper Engine app settings.
+ */
+interface WallpaperMediaStatusEvent {
+    /** `true` when media integration is active; `false` when disabled. */
+    enabled: boolean;
+}
+/**
+ * Event fired by `wallpaperRegisterMediaPropertiesListener` when the
+ * currently playing track's metadata changes (title, artist, album, etc.).
+ */
+interface WallpaperMediaPropertiesEvent {
+    /** Title of the currently playing media. */
+    title: string;
+    /** Artist of the currently playing media. */
+    artist: string;
+    /** Optional sub-title (e.g. episode name for podcasts). */
+    subTitle?: string;
+    /** Optional album title. */
+    albumTitle?: string;
+    /** Optional album artist (may differ from `artist`). */
+    albumArtist?: string;
+    /** Optional comma-separated list of genres. */
+    genres?: string;
+    /** Media type: `"music"`, `"video"`, or `"image"`. */
+    contentType: "music" | "video" | "image";
+}
+/**
+ * Event fired by `wallpaperRegisterMediaThumbnailListener` when album art changes.
+ * Assign `event.thumbnail` directly to `img.src`.
+ *
+ * @example
+ * window.wallpaperRegisterMediaThumbnailListener((e) => {
+ *   document.getElementById('cover').src = e.thumbnail;
+ *   document.body.style.background = e.primaryColor;
+ *   titleEl.style.color = e.textColor;
+ * });
+ */
+interface WallpaperMediaThumbnailEvent {
+    /** Base64-encoded PNG of the album art — usable directly as `img.src`. */
+    thumbnail: string;
+    /** Dominant color extracted from the thumbnail. */
+    primaryColor: string;
+    /** Secondary color from the thumbnail palette. */
+    secondaryColor: string;
+    /** Tertiary color from the thumbnail palette. */
+    tertiaryColor: string;
+    /**
+     * Text color guaranteed to contrast sufficiently against `primaryColor`.
+     * May be `secondaryColor` or `tertiaryColor` when the contrast is sufficient.
+     */
+    textColor: string;
+    /** Either black or white — whichever contrasts more against `primaryColor`. */
+    highContrastColor: string;
+}
+/** Media is actively playing on the system. */
+declare const PLAYBACK_PLAYING: 0;
+/** Media was playing but has been temporarily paused by the user. */
+declare const PLAYBACK_PAUSED: 1;
+/** Media playback is completely stopped. */
+declare const PLAYBACK_STOPPED: 2;
+/**
+ * Numeric playback state for {@link WallpaperMediaPlaybackEvent}.
+ * Compare against `window.wallpaperMediaIntegration.PLAYBACK_PLAYING` etc.
+ * or the module-level constants {@link PLAYBACK_PLAYING}, {@link PLAYBACK_PAUSED},
+ * {@link PLAYBACK_STOPPED}.
+ */
+type WallpaperMediaPlaybackState = typeof PLAYBACK_PLAYING | typeof PLAYBACK_PAUSED | typeof PLAYBACK_STOPPED;
+/**
+ * Event fired by `wallpaperRegisterMediaPlaybackListener` when playback
+ * starts, pauses, or stops.
+ */
+interface WallpaperMediaPlaybackEvent {
+    /**
+     * Current playback state. Compare against the `PLAYBACK_*` constants:
+     * - `PLAYBACK_PLAYING` (`0`) — actively playing
+     * - `PLAYBACK_PAUSED`  (`1`) — temporarily paused
+     * - `PLAYBACK_STOPPED` (`2`) — playback stopped
+     */
+    state: WallpaperMediaPlaybackState;
+}
+/**
+ * Event fired by `wallpaperRegisterMediaTimelineListener` when track position
+ * changes. **Not all media players support this** — ensure your wallpaper
+ * works correctly even if this listener is never called.
+ */
+interface WallpaperMediaTimelineEvent {
+    /** Current playback position in seconds. */
+    position: number;
+    /** Total track duration in seconds. */
+    duration: number;
+}
+/** Returned by `window.cue.getProtocolDetails` */
+interface CueProtocolDetails {
+    sdkVersion: string;
+    serverVersion: string;
+    sdkProtocolVersion: number;
+    serverProtocolVersion: number;
+    breakingChanges: boolean;
+}
+/** Returned by `window.cue.getDeviceInfo` — mirrors `CorsairDeviceInfo` in the C++ SDK */
+interface CueDeviceInfo {
+    /** `CorsairDeviceType` enum value */
+    type: number;
+    /** Human-readable device model name */
+    model: string;
+    /** `CorsairPhysicalLayout` enum value */
+    physicalLayout: number;
+    /** `CorsairLogicalLayout` enum value */
+    logicalLayout: number;
+    /** Number of available LEDs on this device */
+    ledCount: number;
+    /** `CorsairDeviceCaps` bitmask */
+    capsMask: number;
+}
+/** An entry in the array returned by `window.cue.getLedPositionsByDeviceIndex` */
+interface CueLedPosition {
+    /** `CorsairLedId` as integer */
+    ledId: number;
+    /** `CorsairLedId` as string */
+    ledIdName: string;
+    /** Position in mm from the top of the device */
+    top: number;
+    /** Position in mm from the left of the device */
+    left: number;
+    width: number;
+    height: number;
+}
+/** LED color entry used in `setLedsColorsAsync` / `setAllLedsColorsAsync` */
+interface CueLedColor {
+    /** `CorsairLedId` as integer */
+    ledId: number;
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Direct Corsair iCUE SDK access exposed as `window.cue`.
+ * Only available after the `"cue"` plugin has loaded via `wallpaperPluginListener`.
+ */
+interface WallpaperCuePlugin {
+    /** Returns current iCUE SDK status and version info */
+    getProtocolDetails(callback: (protocolDetails: CueProtocolDetails) => void): void;
+    /** Returns the number of recognised iCUE-compatible devices */
+    getDeviceCount(callback: (deviceCount: number) => void): void;
+    /** Returns hardware details for a specific device by index */
+    getDeviceInfo(deviceIndex: number, callback: (deviceInfo: CueDeviceInfo) => void): void;
+    /** Returns all LED positions for a specific device */
+    getLedPositionsByDeviceIndex(callback: (arrayOfLEDs: CueLedPosition[]) => void): void;
+    /** Update specific LEDs by supplying an array of `CueLedColor` objects */
+    setLedsColorsAsync(arrayOfLEDColors: CueLedColor[]): void;
+    /** Set all LEDs on one or more devices to a single color */
+    setAllLedsColorsAsync(deviceIndexOrArray: number | number[], LEDColor: CueLedColor): void;
+    /**
+     * Update device LEDs from an RGB bitmap string (same format as
+     * `wpPlugins.led.setAllDevicesByImageData`, but targets specific devices).
+     */
+    setLedColorsByImageData(deviceIndexOrArray: number | number[], encodedImageData: string, width: number, height: number): void;
+}
+interface WallpaperLedPlugin {
+    /**
+     * Push concatenated RGB bytes (as a string) to all connected LED devices.
+     * Use a small canvas (e.g. 100×20) and convert it with `getImageData` for
+     * best performance.
+     */
+    setAllDevicesByImageData(encodedImageData: string, width: number, height: number): void;
+}
+
+declare global {
+    interface Window {
+        /**
+         * Assign this object to receive property change events.
+         * Must be set as a global — not inside `window.onload` or similar events.
+         *
+         * @example
+         * window.wallpaperPropertyListener = {
+         *   applyUserProperties(properties) {
+         *     if (properties.mycolor) { ... }
+         *   },
+         * };
+         */
+        wallpaperPropertyListener?: WallpaperPropertyListener;
+        /**
+         * Register a callback that receives 128 audio volume samples (~30 fps).
+         * - Indices 0–63: left channel (bass → treble)
+         * - Indices 64–127: right channel (bass → treble)
+         * Each value is 0.0–1.0 (may occasionally exceed 1.0 — clamp with `Math.min`).
+         *
+         * @example
+         * window.wallpaperRegisterAudioListener((audioArray) => { ... });
+         */
+        wallpaperRegisterAudioListener(callback: (audioArray: number[]) => void): void;
+        /**
+         * Request a random file path from an `ondemand` directory property.
+         *
+         * @param propertyName - The key of the directory property.
+         * @param callback - Receives the property name and the file path.
+         *   Prepend `"file:///"` to the path before using it as a URL.
+         *
+         * @example
+         * window.wallpaperRequestRandomFileForProperty('mybg', (name, filePath) => {
+         *   img.src = 'file:///' + filePath;
+         * });
+         */
+        wallpaperRequestRandomFileForProperty(propertyName: string, callback: (propertyName: string, filePath: string) => void): void;
+        /**
+         * Assign this object to detect when plugins (LED, CUE) are loaded.
+         * Check `name === "led"` or `name === "cue"` inside `onPluginLoaded`.
+         */
+        wallpaperPluginListener?: WallpaperPluginListener;
+        /**
+         * Provides access to LED and iCUE plugin APIs after the respective plugin
+         * has loaded (see `wallpaperPluginListener`).
+         */
+        wpPlugins: {
+            led: WallpaperLedPlugin;
+        };
+        /**
+         * Fired when the user enables/disables media integration in app settings.
+         * Register at the bottom of `<body>`, not inside `window.onload`.
+         */
+        wallpaperRegisterMediaStatusListener(callback: (event: WallpaperMediaStatusEvent) => void): void;
+        /**
+         * Fired when track title, artist, album, or content type changes.
+         */
+        wallpaperRegisterMediaPropertiesListener(callback: (event: WallpaperMediaPropertiesEvent) => void): void;
+        /**
+         * Fired when the album art thumbnail changes.
+         * `event.thumbnail` is a base64 PNG string usable as `img.src`.
+         */
+        wallpaperRegisterMediaThumbnailListener(callback: (event: WallpaperMediaThumbnailEvent) => void): void;
+        /**
+         * Fired when playback starts, pauses, or stops.
+         * Compare `event.state` against `window.wallpaperMediaIntegration` constants.
+         */
+        wallpaperRegisterMediaPlaybackListener(callback: (event: WallpaperMediaPlaybackEvent) => void): void;
+        /**
+         * Fired when the track position changes.
+         * Not all media players support this — ensure your wallpaper works without it.
+         */
+        wallpaperRegisterMediaTimelineListener(callback: (event: WallpaperMediaTimelineEvent) => void): void;
+        /** Playback state constants for use with `WallpaperMediaPlaybackEvent.state` */
+        wallpaperMediaIntegration: {
+            PLAYBACK_PLAYING: WallpaperMediaPlaybackState;
+            PLAYBACK_PAUSED: WallpaperMediaPlaybackState;
+            PLAYBACK_STOPPED: WallpaperMediaPlaybackState;
+        };
+        /**
+         * Direct Corsair iCUE SDK access. Only available when the `"cue"` plugin
+         * has loaded (check via `wallpaperPluginListener.onPluginLoaded`).
+         */
+        cue: WallpaperCuePlugin;
+    }
+    var wallpaperPropertyListener: WallpaperPropertyListener | undefined;
+    var wallpaperPluginListener: WallpaperPluginListener | undefined;
+    var wpPlugins: {
+        led: WallpaperLedPlugin;
+    };
+    var wallpaperMediaIntegration: {
+        PLAYBACK_PLAYING: WallpaperMediaPlaybackState;
+        PLAYBACK_PAUSED: WallpaperMediaPlaybackState;
+        PLAYBACK_STOPPED: WallpaperMediaPlaybackState;
+    };
+    var cue: WallpaperCuePlugin;
+    function wallpaperRegisterAudioListener(callback: (audioArray: number[]) => void): void;
+    function wallpaperRequestRandomFileForProperty(propertyName: string, callback: (propertyName: string, filePath: string) => void): void;
+    function wallpaperRegisterMediaStatusListener(callback: (event: WallpaperMediaStatusEvent) => void): void;
+    function wallpaperRegisterMediaPropertiesListener(callback: (event: WallpaperMediaPropertiesEvent) => void): void;
+    function wallpaperRegisterMediaThumbnailListener(callback: (event: WallpaperMediaThumbnailEvent) => void): void;
+    function wallpaperRegisterMediaPlaybackListener(callback: (event: WallpaperMediaPlaybackEvent) => void): void;
+    function wallpaperRegisterMediaTimelineListener(callback: (event: WallpaperMediaTimelineEvent) => void): void;
+}
+
+export { type CueDeviceInfo, type CueLedColor, type CueLedPosition, type CueProtocolDetails, PLAYBACK_PAUSED, PLAYBACK_PLAYING, PLAYBACK_STOPPED, type WallpaperBoolProperty, type WallpaperBoolValue, type WallpaperColorProperty, type WallpaperColorValue, type WallpaperComboOption, type WallpaperComboProperty, type WallpaperComboValue, type WallpaperCuePlugin, type WallpaperDirectoryProperty, type WallpaperDirectoryValue, type WallpaperFileProperty, type WallpaperFileType, type WallpaperFileValue, type WallpaperGeneralProperties, type WallpaperLedPlugin, type WallpaperLocalization, type WallpaperMediaPlaybackEvent, type WallpaperMediaPlaybackState, type WallpaperMediaPropertiesEvent, type WallpaperMediaStatusEvent, type WallpaperMediaThumbnailEvent, type WallpaperMediaTimelineEvent, type WallpaperPluginListener, type WallpaperProject, type WallpaperProjectGeneral, type WallpaperPropertyDefinition, type WallpaperPropertyListener, type WallpaperPropertyRuntimeValue, type WallpaperSliderProperty, type WallpaperSliderValue, type WallpaperTextInputProperty, type WallpaperTextValue, type WallpaperUserProperties };