ARGB

Music Sync RGB Lights
Language English
Advanced 20 min read March 18, 2026

为 Skydimo 开发插件：REST API 完整参考

Skydimo REST API 接口文档、插件开发入门、WebSocket 实时推送与自定义效果开发指南。

#插件开发 #REST API #WebSocket #开发者 #自动化

REST API 概述

Skydimo 提供完整的 REST API，允许外部应用程序控制所有 RGB 设备。

基础 URL：http://localhost:9527/api/v1
认证：API Token（在设置中生成）
内容类型：application/json

启用 API

设置 → 开发者 → 启用 REST API
端口：9527（可修改）
生成 API Token → 复制并保存

API 端点参考

获取所有设备

GET /api/v1/devices
Authorization: Bearer YOUR_TOKEN

响应示例：

{
  "devices": [
    {
      "id": "usb:1234:5678",
      "name": "Corsair K70 RGB",
      "type": "keyboard",
      "leds": 110,
      "vendor": "Corsair",
      "connected": true
    },
    {
      "id": "smbus:1",
      "name": "主板 ARGB 控制器",
      "type": "motherboard",
      "leds": 60,
      "vendor": "Gigabyte",
      "connected": true
    }
  ]
}

设置设备颜色

PUT /api/v1/devices/{device_id}/color
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "mode": "static",
  "color": {"r": 255, "g": 0, "b": 128}
}

设置单个 LED

PUT /api/v1/devices/{device_id}/leds
Authorization: Bearer YOUR_TOKEN

{
  "leds": [
    {"index": 0, "r": 255, "g": 0, "b": 0},
    {"index": 1, "r": 0, "g": 255, "b": 0},
    {"index": 2, "r": 0, "g": 0, "b": 255}
  ]
}

应用配置方案

POST /api/v1/profiles/{profile_id}/apply
Authorization: Bearer YOUR_TOKEN

音乐同步控制

POST /api/v1/music-sync/start
POST /api/v1/music-sync/stop

GET /api/v1/music-sync/status
# 响应：{"active": true, "mode": "ai", "latency_ms": 18}

WebSocket 实时推送

Skydimo 支持 WebSocket 连接，实时接收设备状态和音频数据：

const ws = new WebSocket('ws://localhost:9527/ws');

ws.onopen = () => {
  // 订阅音频频谱数据
  ws.send(JSON.stringify({
    type: 'subscribe',
    topics: ['spectrum', 'device_state']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'spectrum') {
    // 实时频谱数据
    const { bass, mid, high, raw } = data.payload;
    // raw: Float32Array，257 个频率分量的能量值
    updateVisualization(raw);
  }
  
  if (data.type === 'device_state') {
    // 设备状态变化
    console.log('Device updated:', data.payload);
  }
};

频谱数据格式

interface SpectrumMessage {
  type: 'spectrum';
  timestamp: number;
  payload: {
    bass: number;      // 0-1，低频能量
    mid: number;       // 0-1，中频能量
    high: number;      // 0-1，高频能量
    bpm: number;       // 当前检测到的 BPM
    is_beat: boolean;  // 当前帧是否为节拍点
    raw: number[];     // 257 个频率分量
  };
}

插件开发入门

Python 示例：音乐可视化插件

import requests
import websocket
import json
import colorsys
import threading

BASE_URL = "http://localhost:9527/api/v1"
TOKEN = "your_api_token_here"

headers = {"Authorization": f"Bearer {TOKEN}"}

def get_devices():
    resp = requests.get(f"{BASE_URL}/devices", headers=headers)
    return resp.json()["devices"]

def set_all_devices_color(r, g, b):
    devices = get_devices()
    for device in devices:
        requests.put(
            f"{BASE_URL}/devices/{device['id']}/color",
            headers=headers,
            json={"mode": "static", "color": {"r": r, "g": g, "b": b}}
        )

def on_spectrum(ws, message):
    data = json.loads(message)
    if data["type"] != "spectrum":
        return
    
    payload = data["payload"]
    bass = payload["bass"]
    high = payload["high"]
    
    # 将频谱映射为颜色
    # Bass → 色调（低频=紫色，高频=青色）
    hue = 0.75 - bass * 0.5  # 0.75=紫色, 0.5=蓝色
    saturation = 1.0
    value = 0.3 + bass * 0.7  # 响应 Bass 亮度
    
    r, g, b = colorsys.hsv_to_rgb(hue, saturation, value)
    set_all_devices_color(int(r*255), int(g*255), int(b*255))

def on_open(ws):
    ws.send(json.dumps({
        "type": "subscribe",
        "topics": ["spectrum"]
    }))
    print("已连接到 Skydimo，开始音乐同步...")

ws = websocket.WebSocketApp(
    "ws://localhost:9527/ws",
    on_message=on_spectrum,
    on_open=on_open
)

ws.run_forever()

JavaScript/Node.js 示例

const WebSocket = require('ws');
const fetch = require('node-fetch');

const BASE_URL = 'http://localhost:9527/api/v1';
const TOKEN = 'your_token';

async function setDeviceColor(deviceId, r, g, b) {
  await fetch(`${BASE_URL}/devices/${deviceId}/color`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ mode: 'static', color: { r, g, b } }),
  });
}

const ws = new WebSocket('ws://localhost:9527/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'subscribe', topics: ['spectrum'] }));
});

ws.on('message', async (raw) => {
  const msg = JSON.parse(raw);
  if (msg.type !== 'spectrum') return;
  
  const { bass, mid, high } = msg.payload;
  
  // 低频→红色，中频→绿色，高频→蓝色的简单映射
  const r = Math.round(bass * 255);
  const g = Math.round(mid * 255);
  const b = Math.round(high * 255);
  
  // 获取所有设备并更新（实际应缓存设备列表）
  const resp = await fetch(`${BASE_URL}/devices`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` }
  });
  const { devices } = await resp.json();
  
  for (const device of devices) {
    await setDeviceColor(device.id, r, g, b);
  }
});

插件发布

完成开发后，可以将插件提交到 Skydimo 插件市场：

  1. 准备 plugin.json 描述文件：
{
  "name": "我的音乐插件",
  "version": "1.0.0",
  "description": "自定义音乐可视化效果",
  "author": "你的名字",
  "license": "MIT",
  "entry": "main.py",
  "requirements": ["requests", "websocket-client"]
}
  1. 将代码上传到 GitHub
  2. 提交到 Skydimo 插件市场：plugins.skydimo.com

API 速率限制

端点类型限制
设备控制（PUT/POST）100 次/秒
设备查询（GET）无限制
WebSocket 推送无限制（服务端推送）
Batch 批量操作20 次批次/秒

💡 最佳实践：使用 WebSocket 接收实时数据，仅在需要时通过 REST 发送控制命令，避免频繁轮询。