---
name: "onMusic2RgbChange"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.7.0" }
title: "onMusic2RgbChange"
---

## onMusic2RgbChange

> [VERSION] @ray-js/panel-sdk >= 1.7.0

> 💡 监听期间会保持屏幕常亮。若已在监听中，重复调用会直接返回。
> 停止监听需调用 offMusic2RgbChange。
> db、index、customProps 字段需 v1.13.2+ 版本。

### 描述

开启音乐律动监听，将麦克风音频实时转换为 HSV 颜色数据

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `callback` | `(data: MusicRgbCallbackData) => void` | 是 | 音频 RGB 变化回调，接收色调/饱和度/明度等音乐律动数据 |
| `musicOption` | `MusicRgbOption` | 否 | 律动配置（可选） |

### 返回值

类型: `Promise<unknown>`

操作结果 Promise

### 引用对象

##### `type` MusicRgbCallbackData

onMusic2RgbChange 回调参数类型

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `mode` | `number` | 颜色渐变模式：0 跳变，1 渐变 |
| `hue` | `number` | 色调，范围 0–360 |
| `saturation` | `number` | 饱和度，范围 0–1000 |
| `value` | `number` | 明度，范围 0–1000 |
| `bright` | `number` | 亮度，范围 0–1000 |
| `temperature` | `number` | 色温，范围 0–1000 |
| `db` | `number` | 分贝值，v1.13.2+ 支持 |
| `index` | `number` | 灵敏度索引，v1.13.2+ 支持 |
| `customProps` | `Record<string, any>` | 自定义属性透传，v1.13.2+ 支持 |

##### `type` MusicRgbOption

onMusic2RgbChange 律动配置选项

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `mode` | `0 \| 1` | 颜色渐变模式：0 跳变，1 渐变，默认 1 |
| `colorList` | `Object[]` | 自定义颜色列表，随机取色；不传则由麦克风音频换算 RGB |
| `dBRange` | `[number, number]` | 分贝范围，影响颜色亮度，默认 [40, 80] |
| `customProps` | `Record<string, any>` | 自定义属性透传，v1.13.2+ 支持 |
| `throttle` | `number` | 节流时间（ms），默认 300 |

##### `type` MusicRgbOption.colorList

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `hue` | `number` | 色调，范围 0–360 |
| `saturation` | `number` | 饱和度，范围 0–1000 |
| `value` | `number` | 明度，范围 0–1000 |


### 示例代码

#### 基础用法

```ts
import { kit } from '@ray-js/panel-sdk';
const { onMusic2RgbChange } = kit.music2rgb;

onMusic2RgbChange(({ hue, saturation, value }) => {
  publishDps({ colour_data: { hue, saturation, value } });
});
```

#### 自定义颜色列表

```ts
import { kit } from '@ray-js/panel-sdk';
const { onMusic2RgbChange } = kit.music2rgb;

onMusic2RgbChange(
  ({ hue, saturation, value }) => {
    publishDps({ colour_data: { hue, saturation, value } });
  },
  {
    mode: 1,
    colorList: [
      { hue: 0, saturation: 1000, value: 1000 },
      { hue: 120, saturation: 1000, value: 1000 },
      { hue: 240, saturation: 1000, value: 1000 },
    ],
    dBRange: [30, 70],
    throttle: 200,
  }
);
```


## 注意事项

- 问题1: 如何判断音乐律动的响应状态？
- 方案：可先缓存之前5次（约数，可自行调整）的返回值，如果5次都相同，则认为音乐律动响应状态不变，那么将状态改为不响应，否则认为音乐律动响应。