1实现原理 · 为什么它能做到
唯一一条防坑铁律：条形/波形高度必须由当前帧推导，绝不使用实时 AnalyserNode + rAF 循环。
skills/audiogram/SKILL.md
**Drive every bar height from the current frame, never from a real-time analyser loop.**
这里在做什么：把「波形动画」从音频回调迁移到帧函数——这是本 skill 能在 headless 渲染下正确出片的前提，其他所有布局规则都建立在此之上。
给出机制解释：实时分析读的是「此刻在播什么」，而渲染器乱序/变速绘制帧，于是波形会失步或冻住。
skills/audiogram/SKILL.md
Live `AnalyserNode` + `requestAnimationFrame` reads "what is playing right now" — but a video renderer paints frames out of order and faster/slower than real time, so the wave desyncs or freezes.
这里在做什么：不是禁令而是因果说明，agent 才能在「用 canvas 自己画」时也选对做法（离线解码成 per-frame 样本）。
两条实现路线各自绑定 API：频谱 bars 用 visualizeAudio，平滑示波 用 visualizeAudioWaveform；numberOfSamples 必须是 2 的幂。
skills/audiogram/SKILL.md
`numberOfSamples` must be a power of two (16/32/64); use 16–32 for a chunky branded look, 64+ for a detailed spectrum.
这里在做什么：把「技术选型」写成对照表（bars＝音乐/能量，波形＝人声/极简），并给出会直接报错/失真的硬性约束。
居中均衡器要把前半段镜像到两侧，让低频落在中间。
skills/audiogram/SKILL.md
For a centered equalizer, take the first N bars and **mirror** them around the middle so the bass sits in the center.
这里在做什么：一个纯几何规则解决「频谱从左到右排列时中心是高频」的观感问题；reference 给出了 `[...half.reverse(), ...half]` 的完整实现。
长音频别整段载入：先裁到 ≤90s，或改用 useWindowedAudioData（按 HTTP range 只取当前帧附近）。
skills/audiogram/SKILL.md
For anything long, trim first or use `useWindowedAudioData()`, which fetches only the audio around the current frame via HTTP range requests.
这里在做什么：把「一集播客」的成本问题前置解决；同时这也是本 skill 唯一涉及「按需取字节」的行为（本地文件时无网络）。
版式固定为五层（背景 / 封面+标题 / 波形 / 字幕 / 进度条），进度条是 frame/durationInFrames 的纯函数。
skills/audiogram/SKILL.md
const progress = useCurrentFrame() / durationInFrames; // 0 → 1
这里在做什么：分层是为了「一份版式裁到 1:1 / 9:16 / 16:9 都不散」，进度条不依赖音频数据也保持帧驱动。
字幕机制不在本 skill 实现，明确交给 caption-animation（那是另一个仓库的 skill）；本 skill 只负责把字幕轨放进版式并共用同一音频时钟。
skills/audiogram/SKILL.md
The mechanics of word-by-word reveal, active-word highlighting, and SRT/JSON timing belong to the **caption-animation** skill
这里在做什么：跨包（跨仓库）能力委派；代价是只装 youtube 包的用户拿不到字幕那一环，SKILL.md 未提示这个依赖。
一稿多幅：同一组件按画幅注册多个 Composition，重新取景而不是加黑边。
skills/audiogram/SKILL.md
Design once inside the center safe zone, then reframe — don't letterbox.
这里在做什么：reference 给出 Audiogram-1x1 与 Audiogram-9x16 两个注册示例，并用 durationInFrames = round(audioData.durationInSeconds × fps) 对齐真实音频长度。
HEAVY tier 的验收核心是「离线烘焙」：渲染期不做音频分析，样本要么烤进 props 要么 useAudioData 提前解码。
skills/audiogram/SKILL.md
never analyse audio at render time; headless render has no realtime audio clock.
这里在做什么：直接把「无实时时钟」写成设计约束——这也是与实时可视化库最根本的分野。
验证回路针对「保真 + 事故」两件事：静帧的波形高度必须匹配该时刻音频幅度、字幕同步，同时排查封面缺失/字幕出界/条溢出。
skills/audiogram/SKILL.md
This is HEAVY tier: the deliverable is a real **MP4** (audio muxed in), and the waveform must be *data-driven* — its shape at any frame must match the audio at that time.
这里在做什么：把「看起来像波形」与「确实是这段音频的波形」区分开，并要求在付编码成本前用静帧抓一次失步。
2核心能力
01镜像频谱均衡器（visualizeAudio，numberOfSamples 2 的幂，smoothing 可开关）
02平滑示波波形（visualizeAudioWaveform，适合人声/播客的克制观感）
03五层版式（背景 / 封面+标题 / 波形 / 字幕槽 / 进度条）与封面-标题区
04真实音频混流（<Audio> 或 staticFile），保证导出的 MP4 有声音
05一稿多幅：同一组件注册 1:1 / 9:16 / 16:9，durationInFrames 由真实音频长度推出
06长音频策略：裁到 ≤90s 或用 useWindowedAudioData 按需取字节
07零依赖 Web Audio + canvas 变体（离线解码成 per-frame RMS，确定性绘帧）
08字幕层（借 caption-animation）+ 9:16 底部 18% 禁区等安全区约定
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| package | @remotion/media-utils（useAudioData / useWindowedAudioData / visualizeAudio / visualizeAudioWaveform） |
| cli | npx remotion still / render / compositions |
| cli | scripts/contact-sheet.sh + scripts/probe-mp4.sh（仓库根共享验证工具箱，SKILL.md 明列） |
| network | （条件式）useWindowedAudioData 对远程音频走 HTTP range 请求；本地 staticFile 时无网络 |
| cli | 跨包委派：caption-animation（位于另一仓库 iart-ai/tiktok-video-skills） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: （SKILL.md 明列的验证回路）`npx remotion still Audiogram out/f-{start,mid,end}.png -
- 网络端点: 声明外部网络访问: `npx remotion …` 与 `@remotion/media-utils`：首次经 npm 官方渠道取包（registry.npmjs.or
- 本地工作目录: 文件读写与工件输出: agent 按本 skill 构建的 Remotion 工程与 out/audiogram.mp4（1:1 时为 out/clip-square.mp
审计说明： 。三段自证：① 判级对象＝skills/audiogram/（find 确认只有 SKILL.md、references/waveform-render.md 与一个 0 字节 README，零脚本、零资产）；② 目录内自身行为＝本地读取素材（音频/封面）与本地写入（Remotion 工程、out/*.mp4、静帧、sheet.png）＋本地 CLI（`npx remotion`；ffmpeg/ffprobe 经仓库根 scripts/），skills/ 全域 `process.env` / `api[_-]?key` / `token` / `cookie` / `https?://` 均 0 命中；③ 唯一网络面是 npm 官方渠道取包（remotion / @remotion/media-utils），与站内蓝档先例（hyperframes、general-video、motion-background）同口径；useWindowedAudioData 的 range 请求仅在音频来源为远程时发生，属用户自选输入而非 skill 主动外发。不升黄/橙：无固定公开端点查询、无抓取、零凭据/环境变量读取。非红档：无 TLS 降级、无沙箱关闭、无反自动化绕过、无任意代码执行面。需另记（不改档）：跨包委派 caption-animation（位于另一个仓库），按批4 细则1 不做传递式抬档；只装 youtube 包时字幕能力缺失，写进 risks。
5第二遍独立确认
- [ok] 「禁止实时 analyser」是否在 reference 的两条实现路线里都成立（防第一遍只信开头那句） — Remotion 路线：Bars 组件用 `useAudioData(staticFile(src))` + `visualizeAudio({ audioData, frame, fps, numberOfSamples, smoothing: true })`，值是 frame 的纯函数。canvas 路线：reference 明写 `No Remotion. Decode the file once to a per-frame amplitude array (RMS per frame), then a deterministic loop draws each frame`，并在末尾注明实时 AnalyserNode 只能用于实时预览——`// but never use it to drive a deterministic/offline render.`。两条路线都守住了铁律，且都点名了不得使用实时分析。
- [discrepancy] windowInSeconds 参数在两处的语义是否一致（第一遍漏检） — SKILL.md 在「长文件」小节把 windowInSeconds 用在 `useWindowedAudioData(staticFile("full-episode.mp3"), fps, /* windowInSeconds */ 10)`——语义是「HTTP range 抓取窗口」；而 reference 的参数速查表写 `| windowInSeconds | visualizeAudioWaveform | small (≈1/fps) tracks per-frame amplitude |`——语义是「逐帧幅度分析窗口」，且 §参数示例里 `windowInSeconds: 1 / fps` 出现在 visualizeAudioWaveform 调用中。两个 API 确实各有同名参数，但文档未区分说明，读者极易把「抓取窗口」与「分析窗口」混为一谈（设成 1/fps 去抓长音频，或设成 10 去分析都会出问题）。属对 pin commit 有效的表述出入，非能力虚假。
- [unlocatable] 「80% 静音观看」「加字幕显著提升留存」是否有据 — SKILL.md 写 "the captions carry the message for the 80% who watch on mute" 与 "subtitled video holds attention far longer"，仓库内无引用来源与数据文件；只读侦查不验证，仅记为文档声明。
- [discrepancy] 跨包字幕委派会不会造成「只装本包即能力缺失」 — SKILL.md 把词级字幕机制交给 `caption-animation`，但该 skill 位于**另一个仓库** iart-ai/tiktok-video-skills（本包目录树内不存在）。youtube 包的 .claude-plugin/plugin.json 只声明本包两个 skill，README 也未提示这一跨包依赖。结论：只安装 youtube 包时，本 skill 的「captions carry the message」这一层需要用户自行补装另一包，SKILL.md 未说明——属真实的安装面缺口（不影响档位）。
- [ok] HEAVY tier 的「离线烘焙」要求是否与 reference 的实现一致 — SKILL.md 要求「Bake the amplitude/waveform samples into props (or decode once via useAudioData) offline — never analyse audio at render time」，reference 的两条路线恰好各对应一半：Remotion 路线在一次解码后按帧取值，canvas 路线预先把整轨解码为每帧 RMS 数组。要求与实现一致，不是空头约束。
- [ok] 一稿多幅与真实音频长度对齐是否落实 — reference §Full audiogram composition 末尾给出 1x1 与 9x16 两个 `<Composition>` 注册示例，并写 `Set durationInFrames from the actual clip length: Math.round(audioData.durationInSeconds * fps), or read it ahead of time with getAudioDurationInSeconds() and feed it via calculateMetadata.`；批量命令 `npx remotion render Audiogram-1x1 …` / `Audiogram-9x16 …` 亦给出。
6结论
适合： 适合：播客/访谈/口述类音频要转成社交短视频（Reels/TikTok/Shorts/1:1 feed 帖）的场景；也适合给旁白/口述加一个「有声音在响」的视觉信号；需要一稿出 1:1 与 9:16 两种画幅、并把真实音频混进成片的项目。适合能接受「先出三张静帧核对波形与字幕、再付编码成本」的流程。
不适合： 不适合：① 音乐 MV/需要精细音画对位的作品（本 skill 是幅度驱动示意，不做节拍检测或谱面）；② 长音频原文输出（>90s 且不愿裁剪，属成本错配）；③ 需要原生字幕能力却只安装 youtube 包的环境（应同时装 tiktok 包取得 caption-animation）；④ 实时可视化/现场直播需求（架构本身就是为离线确定性渲染设计的）；⑤ 无声场景或纯文字视频（无音频则本 skill 的核心视觉无意义）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload audiogram.tar.gz
sha256:
Option B · Copy Guide for Agent77694b043f16eba0…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f3df381d65.