---
name: "MusicTransformer"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "MusicTransformer"
summary: "MusicTransformer 用于解析照明 music_data DP，实现音乐数据的解析与格式化。"
questions:
  - "MusicTransformer 的作用是什么？"
  - "MusicTransformer 如何解析音乐数据？"
  - "MusicTransformer 的输入和输出是什么？"
  - "MusicTransformer 的转换规则是什么？"
---

## MusicTransformer

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

> 💡 适用于灯类产品的 APP 音乐律动 DP（如 music_data），将音乐模式、HSV 色值、
> 白光亮度与色温等参数与十六进制 DP 字符串互转。
> 协议格式：mode(1位) + hue(4位) + saturation(4位) + value(4位) + brightness(4位) + temperature(4位)

### 描述

APP 音乐标准 DP 协议转换器，用于音乐律动数据与 DP 十六进制协议的双向转换

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `uuid` | `string` | 否 | DP 标识符，默认为 'music_data' |
| `defaultValue` | `TMusicData` | 否 | 默认音乐数据，当解析失败时返回此值 |

### 返回值

类型: `MusicTransformer`

MusicTransformer 实例

#### 方法

| 方法名 | 说明 |
| --- | --- |
| `parser` | 将 DP 十六进制字符串解析为音乐数据对象 |
| `formatter` | 将音乐数据对象格式化为 DP 十六进制字符串 |

### 引用对象

##### `type` TMusicData

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `mode` | `number` | 模式 |
| `hue` | `number` | 色相 |
| `saturation` | `number` | 饱和度 |
| `value` | `number` | 亮度 |
| `brightness` | `number` | 白光亮度 |
| `temperature` | `number` | 色温 |


### 示例代码

#### 示例

```ts
import { MusicTransformer } from '@ray-js/panel-sdk';

const transformer = new MusicTransformer();
// 解析 DP 字符串
const data = transformer.parser('0016803e803e803e803e8');
// => { mode: 0, hue: 360, saturation: 1000, value: 1000, brightness: 1000, temperature: 1000 }

// 格式化为 DP 字符串
const dpStr = transformer.formatter({ mode: 0, hue: 120, saturation: 800, value: 900, brightness: 500, temperature: 300 });
```