# gtrk-music-visualizer

Adopt this skill: https://proskills.md/skills/other/gitruck-cli-skills-gtrk-music-visualizer

Page: https://proskills.md/skills/other/gitruck-cli-skills-gtrk-music-visualizer
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/gtrk-music-visualizer/SKILL.md
size: 5999
upstream: https://github.com/gitruck/cli/blob/main/skills/gtrk-music-visualizer/SKILL.md

````text
---
name: gtrk-music-visualizer
description: 音乐可视化成片——把一首歌通过同合云出成一条频谱可视化视频（可选背景/封面 + 模板/配色样式）。当用户想「把这首歌做成可视化视频 / 音乐可视化 / 频谱视频 / 歌曲配画面出片 / music visualizer / 给歌配个动态封面视频」时使用本 skill。凡涉及把一段音频做成频谱可视化成片，优先用本 skill 驱动 gtrk CLI 的 `music-visualizer` 命令，不要手搓 ffmpeg。
---

# 音乐可视化（gtrk-music-visualizer）

把用户的一首歌，用 `gtrk` CLI 跑通「**主音频上传（+可选背景/封面各自上传）** → 云端出频谱可视化成片 → 拉回本地」，再把产物目录回给用户。**CLI 是手、你是脑。**

> **本 skill 已含你需要的全部信息**（参数、取值、执行、排错），照它做即可。具体模板 id 与参数细节以云端 API 文档为准（本地不冻结模板列表）。

## 前置：CLI 装没装 + 体检

先跑 `gtrk doctor`：
- **`gtrk` 找不到 / command not found** → 让用户装 `npm i -g @gitruck/cli@latest`（需先有 Node.js），再重试。
- 报「缺 API Key」→ 让用户先跑一次 `gtrk init`（一次性配 Key，交互式、需真终端，你别替他跑）。
- 全绿就往下走。

## 一条命令

> **产物落点纪律（MUST · 全文见随包 `AGENT.md` 同名一节）**：
> 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。
> 成片等一切产物只落产物目录（缺省 = 音频同目录）或**用户显式指定的 `--out`**；
> **MUST NOT** 把成片、预览或任何大媒体文件复制到 agent 自有工作目录（如用户文档目录下 agent 产品自建的目录、agent 家目录缓存、会话工作区）——需要引用媒体时**用原路径引用**，不做副本；
> 临时文件一律放系统 temp 且**用完即删**。交付物直接写入工程目录或用户显式指定的路径；引用媒体用原路径。

```
gtrk music-visualizer <音频> --template <模板id> [可选样式/文件] [--json]
```

- `<音频>`：本地音频文件（mp3/wav/m4a/aac/flac/ogg/wma 等）。按其时长计费。
- `--template <id>`：**必填**。可视化模板 id（如 `aurora`）。取值以云端 API 文档 / 服务端模板列表为准；用户没指定就问他要，或让他去文档挑一个。传错服务端会报错并列出可选集。

### 可选辅助文件（各自独立上传）
- `--background <图或视频>`：背景素材，接受图片或视频。
- `--cover <图>`：封面图，**仅接受图片**。

### 可选样式参数
- `--track <曲名>` / `--artist <歌手>`：叠加到画面的文字。
- `--resolution <WxH>`：输出分辨率，如 `1080x1920`（竖屏）、`1920x1080`（横屏）。缺省走服务端默认 1920x1080。
- `--fps <30-60>`：帧率，缺省 30。
- `--c1 <hex>`：频谱主色，十六进制如 `#ff0066`。缺省白色。
- `--c2 <hex>`：频谱**第二色**——**给了它才是双色渐变**，不给就是 `--c1` 单色。想要炫一点的渐变频谱就配上 `--c2`。
- `--blur <0-40>`：背景模糊强度，缺省 16。

### 通用
- `--out <dir>`：产物目录（缺省 = 音频同目录下带时间戳的子目录）。
- `--param k=v` / `--params-json '{...}'`：透传任意云端参数（覆盖优先级最高）。
- `--json`：机读模式，stdout 只出结果 JSON。
- `--reupload`：强制重新上传，忽略缓存。

## 常见用法

- 最简：`gtrk music-visualizer ./song.mp3 --template aurora`
- 竖屏 + 双色渐变 + 叠字：`gtrk music-visualizer ./song.mp3 --template aurora --resolution 1080x1920 --c1 #ff0066 --c2 #6600ff --track 夜曲 --artist 周杰伦`
- 带自定义背景 + 封面：`gtrk music-visualizer ./song.mp3 --template aurora --background ./bg.jpg --cover ./cover.png`

## 配色引导（你帮用户想清楚）

- 用户只说「配色炫一点 / 渐变」→ 给 `--c1` + `--c2` 两个色（双色渐变）。
- 用户说「纯色 / 简洁」→ 只给 `--c1`。
- 拿不准具体 hex：给常见搭配建议（如霓虹粉紫 `#ff0066`→`#6600ff`、青蓝 `#00e5ff`→`#0066ff`），或让用户给个大概色系你转 hex。
- hex 必须是 `#RRGGBB` 或 `#RGB`；写错命令会在提交前报错。

## 读产物

完成后产物目录里有：
- `<音频名>-visualizer.mp4`：成片。
- `result.json`：`ok`/`files`/`taskId`；`ok=false` 时看 `errors`，可凭 `task.json` 的 `taskId` 稍后恢复，别急着重跑（重跑会重新计费）。

## 排错

- **缺 `--template`**：必填，问用户要模板 id 或让他查云端 API 文档的模板列表。
- **模板 id 报错**：服务端会列出可选集，照着改。
- **`--cover` 报「仅接受图片」**：封面只能是图片；视频素材放 `--background`。
- **样式参数报错**：`--fps` 30-60、`--blur` 0-40、`--resolution` 必须 `宽x高`、`--c1/--c2` 必须十六进制——按报错提示改。
- **产物下载失败（ok=false）**：网络波动或链接过期；凭 `taskId` 恢复，不整条重跑。

---

## 改工程：走 `gtrk patch`，不要裸手改 JSON

跑完之后要**微调某个片段**（挪位置 / 改时长 / 切开 / 改音量）时，一律用 `gtrk patch`：

```bash
gtrk patch move --project <dir> --clip <clip_id> --to 5.0
gtrk patch trim --project <dir> --clip <clip_id> --out -1s
```

**MUST NOT 直接编辑 `.gtrk` 的 JSON。** 片段时码是两套并存的（`clip_st`+`clip_ed` 与
`clip_st`+`duration`）：改一份不改另一份，客户端优先读 `clip_ed`、后端又不强校验它 ⇒
**没人报错，成片却用了陈旧出点**。`gtrk patch` 替你做恒等式同步 + 帧对齐 + 写前全档校验。

> 参数手册在 `AGENT.md` 的「元素级编辑：`gtrk patch`」一节与 README 命令参考。
> 本节**只指路不搬手册** —— 搬过来就会长出会漂移的副本。
````

## File: README.md
upstream: https://github.com/gitruck/cli/blob/main/README.md

````text
<div align="center">

<img src="assets/readme/wordmark.svg" alt="gtrk CLI" width="420">

<h1>一句句把片子聊出来</h1>

<p><strong>让你的 AI Agent，把素材做成可以继续精修的视频工程。</strong></p>
<p>剪口播 · 切高光 · 做解说 · 配画面 · 叠动效 · 上字幕</p>

<p>
<a href="#demo">观看演示</a> ·
<a href="#quick-start">快速开始</a> ·
<a href="https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk">使用教程</a> ·
<a href="https://github.com/Gitruck/ai-drama-desk">AI Drama Desk</a> ·
<a href="docs/development.md">开发文档</a> ·
<a href="README.en.md">English</a>
</p>

<p>
<a href="https://www.npmjs.com/package/@gitruck/cli"><img src="https://img.shields.io/npm/v/@gitruck/cli?style=flat-square&color=f43b48" alt="npm 版本"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520.6-43853d?style=flat-square" alt="Node.js ≥20.6"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-f43b48?style=flat-square" alt="MIT"></a>
<img src="https://img.shields.io/badge/CLI-Windows%20%7C%20macOS%20%7C%20Linux-555?style=flat-square" alt="CLI 支持 Windows、macOS、Linux">
</p>

<p><a href="https://ai-mcn.tv/gtrk"><strong>产品主页 ↗</strong></a>　<a href="https://cloud.ai-mcn.tv/zh-CN/download"><strong>下载客户端 ↗</strong></a>　<a href="https://cloud.ai-mcn.tv/zh-CN/dashboard"><strong>获取 API Key ↗</strong></a></p>

</div>

<!-- 中英双份：修改本页须同步 README.en.md，详细参数维护在 docs/reference*.md。 -->

**gtrk 是为 AI Agent 准备的视频创作 CLI。** 在 Codex、Claude Code、Cursor、TRAE 等支持 Skills 的 Agent 里说需求，Agent 调用 gtrk 完成剪辑与装配，你在客户端里看效果、挑素材、调细节。

从一条口播、一场访谈、一篇稿子或一组旅拍素材开始。把粗剪、配画面、动态图、配乐和字幕接成工作流，也可以单独调用其中一个工具。**你负责创意和判断，gtrk 负责执行。**

<a id="demo"></a>

## 每一步都能改，每一层都在轨上

<a href="https://www.bilibili.com/video/BV1HAec6fELP/"><img src="assets/readme/editable-project.webp" alt="真实客户端工程：画面预览、动态图与多轨时间线，可逐段精修。点击观看流程速览。" width="100%"></a>

<p align="center"><strong>在 Agent 里说需求，在客户端里看效果。</strong><br>上图为真实客户端工程。<a href="https://www.bilibili.com/video/BV1HAec6fELP/">▶ 2 分 28 秒，看完整条路</a></p>

| 先看一次实测 | 再看完整制作 |
| :---: | :---: |
| [![快速成片演示](assets/readme/quick-mode.webp)](https://www.bilibili.com/video/BV1PcYK6kEEL/) | [![解说全流程演示](assets/readme/narration-tour.webp)](https://www.bilibili.com/video/BV1iZYK6YEew/) |
| **7 分钟快速模式** · 口播、字卡、BGM、字幕 | **35 分钟解说实战** · 看素材、写稿、配音、配画面 |

<a id="quick-start"></a>

## 安装一次，开始对话

准备一个支持 Skills、能执行本地命令的 AI Agent，以及 **Node.js ≥ 20.6**。

```bash
npx @gitruck/cli@latest install
```

安装器会配置 gtrk、安装配套 Skills，并引导填写 API Key。Key 在[同合云控制台](https://cloud.ai-mcn.tv/zh-CN/dashboard)获取；调用云端能力需要账户和可用额度。完成后重新打开 Agent 会话，让新 Skills 生效。

把素材文件夹交给 Agent，然后说：

> 帮我把「口播.mp4」做成一期视频，文字稿在同目录。先给我看制作方案。

只想先粗剪，也可以说：

> 把这条口播剪一版，去掉重复和长停顿，给我能在剪映里继续改的工程。

**Windows 推荐同时安装桌面客户端**，用于预览和精修：[全套安装指南](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [客户端下载](https://cloud.ai-mcn.tv/zh-CN/download)。CLI 支持 Windows、macOS、Linux；桌面客户端目前提供 Windows 版。

<details>
<summary>直接用命令、检查环境与升级</summary>

```bash
gtrk oralcut "./talk.mp4" --script "./script.txt"
gtrk transcript "./interview.mp4"
gtrk doctor
gtrk upgrade
```

音视频处理需要 FFmpeg。用 `gtrk deps status` 检查；缺少时按提示显式运行 `gtrk deps install`。已有配置会保留，需要修改时用 `gtrk init --reconfigure`。

[完整配置与命令参考](docs/reference.md)

</details>

<details>
<summary>从 Skills 目录或插件市场安装（Claude Code / Codex）</summary>

```bash
# 通用 skills CLI（skills.sh）
npx skills add Gitruck/cli

# Claude Code 插件市场
/plugin install gtrk --marketplace Gitruck/cli

# Codex 插件市场
codex plugin marketplace add Gitruck/cli
codex plugin add gtrk@gitruck
```

以上几种方式都只装 Skills。gtrk CLI 和 API Key 仍需用 `npx @gitruck/cli@latest install` 安装和配置。

</details>

## 看看它能做什么

下面选用与[产品专页](https://ai-mcn.tv/gtrk)一致的真实案例。点击封面观看成片，口播示例也可打开原片对比。

<table>
<tr>
<td width="50%" valign="top">
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_after.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/oralcut/fishing_after.webp" alt="器材测评口播成片" width="100%"></a>
<strong>口播：从毛片到包装成片</strong><br>
1:04 → 0:48 · 粗剪、结构图解、器材特写、字幕。<br>
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_before.webm">看原片</a> · <a href="https://api.ai-mcn.tv:9000/cloud/static/assets/oralcut/webm/fishing_after.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe">口播教程</a>
</td>
<td width="50%" valign="top">
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_16_9.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/l2s/huangqin_talking_demo_1_16_9.webp" alt="双人访谈高光短片" width="100%"></a>
<strong>长剪短：让好话题单独成片</strong><br>
26:29 访谈中的 45 秒高光 · 横竖屏分别制作。<br>
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_16_9.webm">横屏成片</a> · <a href="https://api.ai-mcn.tv:9000/cloud/static/assets/l2s/webm/huangqin_talking_demo_1_9_16.webm">竖屏成片</a> · <a href="https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb">长剪短教程</a>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/travel/webm/3.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/narration/travel_3.webp" alt="黄石国家公园旅拍解说" width="100%"></a>
<strong>旅拍：把一组素材讲成故事</strong><br>
黄石国家公园 · 3:05 · 素材理解、解说、配音与画面。<br>
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/travel/webm/3.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/CjDPwyLMcimfjDk1c2NcSv3unCf">旅拍教程</a>
</td>
<td width="50%" valign="top">
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/food/webm/1.webm"><img src="https://api.ai-mcn.tv:9000/cloud/static/assets/showcase/posters/narration/food_1.webp" alt="铁板炒肉定食美食解说" width="100%"></a>
<strong>美食：一家店，一顿饭，一条片子</strong><br>
铁板炒肉定食 · 2:36 · 提炼看点、保留现场、重述故事。<br>
<a href="https://api.ai-mcn.tv:9000/cloud/static/assets/narration/food/webm/1.webm">看成片</a> · <a href="https://hocassian.feishu.cn/wiki/EbY3wo6YhiABCjkhczRcpixVniQ">美食教程</a>
</td>
</tr>
</table>

[更多题材与前后对照 →](https://ai-mcn.tv/gtrk)

## 从你的素材开始

不用记命令或 Skill 名字，直接描述想做的事。

| 你手上有什么 | 对 Agent 说 | 工作流 |
| --- | --- | --- |
| 一条或几条口播，可能还有外录音频 | “把这些口播做成一期，剪掉重录，配上字卡和字幕。” | [口播](https://hocassian.feishu.cn/wiki/Y6Odw4Kz5iPKMxkOOPJc6FyOnpe) |
| 一篇已经写好的稿子 | “用这篇稿子做条配音视频，先给我选音色。” | [配音](https://hocassian.feishu.cn/wiki/CdpewYDOmialPLkjOmacI97Wnfd) |
| 播客、课程、访谈或直播回放 | “挑出值得单发的话题，做成几条短片工程。” | [长剪短](https://hocassian.feishu.cn/wiki/Gls1wTebVi1tpDkeaK8cINqbnMb) |
| 影视、游戏、旅拍或探店素材 | “看完这些素材，提炼看点，写解说并配画面。” | [通用解说](https://hocassian.feishu.cn/wiki/CmtRwmqzYi5dRtkWKgDc7ApWnre) |
| 录屏和同时录制的人像 | “把录屏合进来，做成讲师画中画。” | [录屏画中画](https://hocassian.feishu.cn/wiki/GO84wbFqOi9W92kzGzpcc3nQnNh) |
| 一批现场素材，想保留同期声 | “把这批素材做成纪实 Vlog，保留现场声音，再补旁白。” | [Vlog Skill](skills/gtrk-vlog-docu/SKILL.md) |

长剪短保留原声高光；解说会提炼素材并重新讲述。具体流程、交付文件和可选环节见[工作流指南](docs/workflow.md)。

## 为什么用 gtrk

- **在你熟悉的 Agent 里创作。** 配套 Skills 负责组织步骤，CLI 负责执行；也能直接接入脚本和自动化流程。
- **工程留在手里。** 画面、音频、字幕和动效写进可编辑工程。你可以在客户端继续调整，并按支持范围导出到剪映、Premiere。
- **用自己的素材，也能找新画面。** 按文稿检索本地素材库或平台素材，将候选铺到时间线上，逐段挑选。
- **栏目风格可以复用。** 字体、配色、画面语言和创作规则可通过自己的 Skills 与栏目配置延续到下一期。

## 一份工程，贯穿全程

```mermaid
flowchart LR
    A["你在 Agent 里说需求"] --> B["gtrk CLI 执行"]
    B <--> C["同合云分析与处理"]
    B --> D["本地 .gtrk 工程"]
    D <--> E["客户端预览与精修"]
    D --> F["CLI 渲染 MP4"]
    E --> G["导出成片 / 支持的剪辑工程"]
```

**当前对话入口在你自己的 Agent 中，客户端没有内置 AI 对话框。** Agent 修改工程后，在客户端查看效果、继续精修；也可以用 `gtrk render` 渲染成片。需要云端渲染的动态图会单独计费，缓存可复用。

粗剪阶段的三端工程，与完整包装后的导出支持范围不同；[工作流指南](docs/workflow.md)说明每种交付物在哪打开、哪些效果需要渲染。

客户端精修 `.gtrk` 后，用 `gtrk project export --project <目录>` 导出剪映、Premiere XML、FCPXML 或 OTIO，保留精修时间线；不要重跑 `oralcut`，否则会重新生成粗剪。导出会把 MG 颗粒预渲进 NLE 工程，结构导出按次计费，未命中共享缓存的颗粒按分钟计费；`project init` 仍是 0 积分。只选 `gtrk` 时会保留原生 `beat_track` 并自动跳过颗粒预渲。

## gtrk + AI Drama Desk：从分镜到可回轨片段

如果你的素材不是实拍，而是希望把一份分镜稿变成 AI 情景片段，可以把 [Gitruck AI Drama Desk](https://github.com/Gitruck/ai-drama-desk) 接到同一条工程链里。两者分工很清楚：

| 组件 | 负责什么 | 产物 |
| --- | --- | --- |
| `gtrk CLI` | 在 Agent 中理解需求、组织工作流、管理 `.gtrk` 工程 | 可继续精修的视频工程 |
| `AI Drama Desk` | 导入分镜稿、管理角色与画风、生成 keyframe / I2V 片段、导出回轨包 | `return-v1` 片段包 + `man
````