@hfd-sdk/keyboard-kit 1.0.0 → 1.1.0

package/dist/music-v2/key-positions.d.ts

@@ -0,0 +1,39 @@
+import { keyPosition, volcanoMountainPositions, musicConfig } from '../shared/types';
+/**
+ * 68 键圆环坐标配置
+ */
+export declare const RING_68_KEY_POSITIONS: keyPosition[][];
+/**
+ * 87 键圆环坐标配置
+ */
+export declare const RING_87_KEY_POSITIONS: keyPosition[][];
+/**
+ * 108 键圆环坐标配置
+ */
+export declare const RING_108_KEY_POSITIONS: keyPosition[][];
+/**
+ * 获取音乐律动圆环坐标
+ * @param ringKeyPositions 圆环坐标配置，可以是预设名或自定义数组
+ */
+export declare function getMusicRingKeyPositions(ringKeyPositions?: musicConfig['ringKeyPositions']): keyPosition[][] | undefined;
+/**
+ * 64 键 3141-32777-YUNZII B68 PRO Keyboard 右上是块大屏
+ */
+export declare const VOLCANO_64_KEY_POSITIONS: volcanoMountainPositions;
+/**
+ * 标准 84 键，例如 ISO
+ */
+export declare const VOLCANO_84_ISO_KEY_POSITIONS: volcanoMountainPositions;
+/**
+ * 标准 87 键，例如 X87 V2、2902
+ */
+export declare const VOLCANO_87_KEY_POSITIONS: volcanoMountainPositions;
+/**
+ * 标准 98 键（扩展按键 1-4 行）
+ */
+export declare const VOLCANO_98_KEY_POSITIONS: volcanoMountainPositions;
+/**
+ * 获取音乐律动火山按键坐标
+ * @param volcanoKeyPositions 火山坐标配置，可以是预设名或自定义左/中/右山坐标
+ */
+export declare function getMusicVolcanoKeyPositions(volcanoKeyPositions?: musicConfig['volcanoKeyPositions']): volcanoMountainPositions | undefined;

package/dist/music-v2/plugin-client.d.ts

@@ -0,0 +1,16 @@
+import { MusicV2AmplitudeSource, MusicV2ScreenLightClient } from './types';
+export interface MusicV2PluginClientOptions {
+    /** 请求超时（毫秒），默认 500 */
+    timeoutMs?: number;
+    /** Worker 内振幅轮询间隔（毫秒），默认 50 */
+    pollIntervalMs?: number;
+}
+export interface MusicV2PluginClient extends MusicV2AmplitudeSource, MusicV2ScreenLightClient {
+    /** 获取硬件信息 */
+    getHardwareInfo: () => Promise<unknown>;
+}
+/**
+ * 创建本地音乐律动插件客户端（默认 http://127.0.0.1:9191）。
+ * fetch 在 Web Worker 中执行；振幅由 Worker 独立轮询并缓存，主线程只读缓存。
+ */
+export declare function createMusicV2PluginClient(baseUrl?: string, options?: MusicV2PluginClientOptions): MusicV2PluginClient;

package/dist/music-v2/system-audio.d.ts

@@ -0,0 +1,18 @@
+import { MusicV2AmplitudeSource } from './types';
+export interface SystemAudioFrequencyBands {
+    low: number;
+    mid: number;
+    high: number;
+}
+export interface SystemAudioSource extends MusicV2AmplitudeSource {
+    /** 是否正在采集系统音频 */
+    isActive: () => boolean;
+    /** 获取低（20-250Hz）、中（250-4000Hz）、高（4000-20000Hz）频段强度，范围 0-1000 */
+    getFrequencyBands: () => SystemAudioFrequencyBands;
+}
+/**
+ * 创建浏览器系统音频振幅来源，无需插件。
+ * 通过 getDisplayMedia 分享屏幕/标签页采集音频，
+ * 用户需在浏览器分享对话框中勾选「分享系统音频」或「分享标签页音频」。
+ */
+export declare function createSystemAudioSource(): SystemAudioSource;

package/dist/music-v2/types.d.ts

@@ -0,0 +1,138 @@
+import { HFDSDKDevice, KeyboardConfig, RgbColor } from '../shared/types';
+/**
+ * 音乐律动 V2 显示模式
+ * - 1   绿/黄/红（曲率频阶）
+ * - 4   色谱（曲率频阶）
+ * - 13  随曲起舞
+ * - 14  尘埃光漩（旋转线条）
+ * - 15  蛰伏火山（山）
+ * - 16  光矢穿心（爱心）
+ * - 17  萤火轨迹（线性波动）
+ * - 18  光茧共振
+ * - 19  音叉振空（潮汐共振）
+ * - 20  曲率遗轨（线性波动缩短）
+ * - 21  行波律动
+ * - 22  双心共舞
+ * - 100 屏光联动（需要插件客户端）
+ */
+export type MusicV2Mode = 1 | 4 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 100;
+/**
+ * 背景灯光模式
+ * - 0  无背景
+ * - 6  白色 / 7 红色 / 8 橙色 / 9 黄色 / 10 蓝色 / 11 绿色
+ * - 1  绿/黄/红三行
+ * - 2  彩虹色多行
+ * - 4  色谱（色轮）
+ * - 5  频谱循环
+ */
+export type MusicV2BackgroundMode = 0 | 1 | 2 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+/** 振幅来源：返回 0-1000 的原始振幅 */
+export interface MusicV2AmplitudeSource {
+    /** 启动采集（如请求系统音频授权），可选 */
+    start?: () => void | Promise<void>;
+    /** 获取当前原始振幅，范围 0-1000 */
+    getAmplitude: () => number | Promise<number>;
+    /** 停止采集并释放资源，可选 */
+    stop?: () => void;
+}
+/** 屏光联动（模式 100）所需的插件客户端能力 */
+export interface MusicV2ScreenLightClient {
+    /** 设置键盘布局（base64 编码后的布局 JSON） */
+    setKeyboardLayout: (data: string) => Promise<unknown>;
+    /** 设置音乐律动模式 */
+    setMusicMode: (param: string) => Promise<unknown>;
+    /** 获取音乐律动状态（插件回传的每键颜色） */
+    getMusicStatus: () => Promise<{
+        keys: Array<{
+            row: number;
+            col: number;
+            keyCode: number;
+            keyIndex: number;
+            color: string;
+        }>;
+    }>;
+    /** 关闭音乐律动 */
+    close: () => Promise<unknown>;
+}
+/** 点阵屏配置，用于计算随音乐数据下发的振幅档位 */
+export interface MusicV2LedConfig {
+    rows: number;
+    cols: number;
+}
+export interface MusicV2EngineOptions {
+    /** 键盘布局与音乐协议配置 */
+    keyboardConfig: KeyboardConfig;
+    /** `@hfd-sdk/keyboard-sdk` 的 HFDDevice 实例 */
+    device: HFDSDKDevice;
+    /** 是否 USB 有线连接 */
+    isUSBDevice?: boolean;
+    /** 灯光协议版本 */
+    lightingVersion?: number;
+    /** 振幅来源；未提供时可使用测试模式驱动 */
+    amplitudeSource?: MusicV2AmplitudeSource;
+    /** 屏光联动（模式 100）客户端，通常由 createMusicV2PluginClient 创建 */
+    screenLightClient?: MusicV2ScreenLightClient;
+    /** 点阵屏配置（可选，存在时随音乐数据下发振幅档位） */
+    ledConfig?: MusicV2LedConfig;
+    /** 渲染 / 下发间隔（毫秒），默认 50 */
+    intervalMs?: number;
+    /** 静音阈值（连续 N 帧振幅为 0 才视为静音），默认 5 */
+    silenceThreshold?: number;
+    /** 初始显示模式，默认 13 */
+    mode?: MusicV2Mode;
+    /** 初始用户振幅（平滑系数）1-100，默认 50 */
+    amplitude?: number;
+    /** 初始背景模式，默认 0 */
+    backMode?: MusicV2BackgroundMode;
+    /** 初始背景亮度 10-100，默认 100 */
+    backBrightness?: number;
+    /** 每帧按键 RGB 变化回调（可用于 UI 预览） */
+    onKeysRgbChange?: (keysRgb: RgbColor[][]) => void;
+    /** 状态变化回调 */
+    onStateChange?: (state: MusicV2State) => void;
+    /** 引擎内部错误回调（绘制 / 下发失败等） */
+    onError?: (error: unknown) => void;
+}
+export interface MusicV2State {
+    /** 是否正在运行 */
+    running: boolean;
+    /** 当前显示模式 */
+    mode: MusicV2Mode;
+    /** 用户振幅（平滑系数）1-100 */
+    amplitude: number;
+    /** 背景模式 */
+    backMode: MusicV2BackgroundMode;
+    /** 背景亮度 10-100 */
+    backBrightness: number;
+    /** 当前归一化振幅 0-1 */
+    currentAmplitude: number;
+    /** 振幅来源是否可用（false 对应 web 端「未下载插件」状态） */
+    sourceActive: boolean;
+    /** 是否为测试模式 */
+    testMode: boolean;
+    /** 当前帧按键 RGB（最后一次渲染结果） */
+    currentKeysRgb: RgbColor[][] | null;
+}
+export interface MusicV2Engine {
+    /** 启动定时渲染循环 */
+    start: () => void;
+    /** 停止定时渲染循环（不释放振幅来源） */
+    stop: () => void;
+    /** 暂停（如 profile 切换期间），与 resume 配对 */
+    pause: () => void;
+    /** 恢复 */
+    resume: () => void;
+    /** 停止循环并释放振幅来源、关闭屏光联动 */
+    dispose: () => void;
+    setMode: (mode: MusicV2Mode) => void;
+    /** 设置用户振幅（平滑系数）1-100 */
+    setAmplitude: (value: number) => void;
+    setBackMode: (mode: MusicV2BackgroundMode) => void;
+    /** 设置背景亮度 10-100 */
+    setBackBrightness: (value: number) => void;
+    /** 开关测试模式；开启后以 testAmplitude（0-1000，默认 1000）驱动 */
+    setTestMode: (open: boolean, testAmplitude?: number) => void;
+    /** 运行时切换振幅来源 */
+    setAmplitudeSource: (source: MusicV2AmplitudeSource | undefined) => void;
+    getState: () => MusicV2State;
+}

package/dist/music-v2/visualizers.d.ts

@@ -0,0 +1,82 @@
+import { KeyboardConfig, RgbColor } from '../shared/types';
+import { MusicV2BackgroundMode, MusicV2Mode } from './types';
+export interface MusicV2RenderParams {
+    /** 显示模式 */
+    mode: MusicV2Mode;
+    /** 用户振幅（平滑系数）1-100 */
+    amplitude: number;
+    /** 背景模式 */
+    backMode: MusicV2BackgroundMode;
+    /** 背景亮度 10-100 */
+    backBrightness: number;
+    /** 当前归一化振幅 0-1 */
+    currentAmplitude: number;
+}
+/**
+ * 音乐律动 V2 渲染器：把每种显示模式绘制到按键 RGB 网格。
+ * 纯计算、无定时器，由引擎按固定帧率调用 `render()`。
+ */
+export declare class MusicV2Renderer {
+    private readonly keyboardConfig;
+    private bgStep;
+    private pulseOffset;
+    private pulseSpeed;
+    private colorCycleOffset;
+    private smoothedActiveRings;
+    private smoothedAmplitude;
+    private bgSpeed;
+    private lastMaxHeight;
+    private diffHeight;
+    private tidalOffset;
+    private readonly smoothingFactor;
+    private params;
+    constructor(keyboardConfig: KeyboardConfig);
+    /** 键盘行数 */
+    private get keyboardRows();
+    /** 键盘最大列数值（含最大列偏移） */
+    private get keyboardMaxCols();
+    /** 中心点 Y */
+    private get centerY();
+    /** 中心点 X */
+    private get centerX();
+    /** 按键总数 */
+    private get keyCount();
+    /**
+     * 渲染一帧按键 RGB 网格
+     * @param params 当前帧参数
+     * @returns 按键 RGB 网格 [row][col]
+     */
+    render(params: MusicV2RenderParams): RgbColor[][];
+    /** 根据模式填充背景颜色 */
+    fillModeColor(keysRgb: RgbColor[][], mode: number, brightness?: number): void;
+    /** 填充单色 */
+    private drawSolidColor;
+    /** 填充色谱 */
+    private drawColorWheel;
+    /** 填充频谱循环 */
+    private drawSpectrumCycle;
+    /** 填充多行颜色 */
+    private drawMultiRowColors;
+    /** 随曲起舞 */
+    private visualizerDance;
+    /** 双心共舞 */
+    private visualizerDualCenterDance;
+    /** 尘埃光漩（旋转线条） */
+    private visualizerRotatingLines;
+    /** 蛰伏火山（山） */
+    private visualizerMountains;
+    /** 光矢穿心（爱心） */
+    private visualizerHeart;
+    /** 光茧共振 */
+    private visualizerAfternoonSunlight;
+    /** 音叉振空（潮汐共振） */
+    private visualizerTidalResonance;
+    /** 萤火轨迹（线性波动） */
+    private visualizerLinearWave;
+    /** 曲率遗轨（线性波动缩短） */
+    private visualizerLinearWaveShortened;
+    /** 行波律动 */
+    private visualizerRowWaveRhythm;
+    /** 曲率频阶（底部到顶部） */
+    private visualizerBottomToTop;
+}

package/dist/runtime/index.d.ts

@@ -1,3 +1,3 @@
-export { setInterval, clearInterval } from 'worker-timers';
+export { setInterval, clearInterval, setTimeout, clearTimeout } from 'worker-timers';
 export * from '../shared/types';
 export { serializePreset, deserializePreset } from '../shared/serialize';