gtrk-music-visualizer

1# 音乐可视化（gtrk-music-visualizer）
2 
3把用户的一首歌，用 `gtrk` CLI 跑通「**主音频上传（+可选背景/封面各自上传）** → 云端出频谱可视化成片 → 拉回本地」，再把产物目录回给用户。**CLI 是手、你是脑。**
4 
5> **本 skill 已含你需要的全部信息**（参数、取值、执行、排错），照它做即可。具体模板 id 与参数细节以云端 API 文档为准（本地不冻结模板列表）。
6 
7## 前置：CLI 装没装 + 体检
8 
9先跑 `gtrk doctor`：
10- **`gtrk` 找不到 / command not found** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
11- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key，交互式、需真终端，你别替他跑）。
12- 全绿就往下走。
13 
14## 一条命令
15 
16> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
17> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
18> 成片等一切产物只落产物目录（缺省 = 音频同目录）或**用户显式指定的 `--out`**；
19> **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
20> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。
21 
22```
23gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]
24```
25 
26- `<音频>`：本地音频文件（mp3/wav/m4a/aac/flac/ogg/wma 等）。按其时长计费。
27- `--template <id>`：**必填**。可视化模板 id（如 `aurora`）。取值以云端 API 文档 / 服务端模板列表为准；用户没指定就问他要，或让他去文档挑一个。传错服务端会报错并列出可选集。
28 
29### 可选辅助文件（各自独立上传）
30- `--background <图或视频>`：背景素材，接受图片或视频。
31- `--cover <图>`：封面图，**仅接受图片**。
32 
33### 可选样式参数
34- `--track <曲名>` / `--artist <歌手>`：叠加到画面的文字。
35- `--resolution <WxH>`：输出分辨率，如 `1080x1920`（竖屏）、`1920x1080`（横屏）。缺省走服务端默认 1920x1080。
36- `--fps <30-60>`：帧率，缺省 30。
37- `--c1 <hex>`：频谱主色，十六进制如 `#ff0066`。缺省白色。
38- `--c2 <hex>`：频谱**第二色**——**给了它才是双色渐变**，不给就是 `--c1` 单色。想要炫一点的渐变频谱就配上 `--c2`。
39- `--blur <0-40>`：背景模糊强度，缺省 16。
40 
41### 通用
42- `--out <dir>`：产物目录（缺省 = 音频同目录下带时间戳的子目录）。
43…