---
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

> 💡 The screen will be kept on during monitoring. If already monitoring, repeated calls return immediately. To stop monitoring, call offMusic2RgbChange. The db, index, and customProps fields require v1.13.2+.

### Description

Start music rhythm monitoring and convert microphone audio to HSV color data in real time

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `callback` | `(data: MusicRgbCallbackData) => void` | Yes | Audio RGB change callback, receives music‑rhythm data such as hue/saturation/value |
| `musicOption` | `MusicRgbOption` | No | Rhythm configuration (optional) |

### Return Value

Type: `Promise<unknown>`

Operation result Promise

### Referenced Types

##### `type` MusicRgbCallbackData

onMusic2RgbChange callback parameter type

| Property | Type | Description |
| --- | --- | --- |
| `mode` | `number` | Color transition mode: 0 instant switch, 1 gradual transition |
| `hue` | `number` | Hue, range 0–360 |
| `saturation` | `number` | Saturation, range 0–1000 |
| `value` | `number` | Value, range 0–1000 |
| `bright` | `number` | Brightness, range 0–1000 |
| `temperature` | `number` | Color temperature, range 0–1000 |
| `db` | `number` | Decibel value, supported in v1.13.2+ |
| `index` | `number` | Sensitivity index, supported in v1.13.2+ |
| `customProps` | `Record<string, any>` | Custom property passthrough, supported in v1.13.2+ |

##### `type` MusicRgbOption

Rhythm configuration options for onMusic2RgbChange

| Property | Type | Description |
| --- | --- | --- |
| `mode` | `0 \| 1` | Color transition mode: 0 instant switch, 1 gradual transition, default 1 |
| `colorList` | `Object[]` | Custom color list with random selection; if omitted, RGB is derived from microphone audio |
| `dBRange` | `[number, number]` | Decibel range, affects color brightness, default [40, 80] |
| `customProps` | `Record<string, any>` | Custom property passthrough, supported in v1.13.2+ |
| `throttle` | `number` | Throttle interval (ms), default 300 |

##### `type` MusicRgbOption.colorList

| Property | Type | Description |
| --- | --- | --- |
| `hue` | `number` | Hue, range 0–360 |
| `saturation` | `number` | Saturation, range 0–1000 |
| `value` | `number` | Value, range 0–1000 |


### Examples

#### Basic usage

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

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

#### Custom color list

```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,
  }
);
```


## Notes

- Question 1: How to determine the response status of the music rhythm?
- Solution: You can cache the return values of the previous 5 times (approximate number, adjustable by yourself). If the 5 times are the same, it is considered that the music rhythm response status remains unchanged, so the status is changed to no response, otherwise it is considered that the music rhythm responds.