Lyric Studio

一个用于制作歌词视频的工具：一张背景图片 + 一条音轨，歌词行会在你选择的精确时间戳出现和消失，并使用任意真实的 Google Font 字体。

它有两个部分，共享同一个项目：

• 编辑器 UI — 一个在浏览器中打开的 Web 应用，用于上传媒体、输入带时间的歌词行、选择字体/颜色并渲染。

• MCP 服务器 — 同一个项目，以工具的形式暴露出来，让 AI 助手（Claude Desktop、Claude Code 等）可以代你添加/编辑歌词行并触发渲染。

因为它们共享同一个 projects/default/project.json，AI 添加的歌词行会出现在浏览器 UI 中（它每 5 秒轮询一次），反之亦然。

环境要求

• Node.js 18+

• ffmpeg 和 ffprobe 已加入你的 PATH（用 ffmpeg -version 检查）

• 互联网访问（首次使用每种字体时下载 Google Fonts）

Related MCP server: Music Media MCP Server

设置

npm install

1. 运行编辑器 UI

npm run start

然后打开 http://localhost:4790。

在 UI 中：

1. 添加一个音频文件。

2. 添加一张或多张背景图片。对于每张图片，在 "until" 框中输入它应该播放的时长（例如 3:00），然后点击 将图片添加到序列 —— 图片会按你添加的顺序依次播放。最后一张图片的 "until" 留空，让它一直播放到歌曲结束。例如一首 4 分钟的歌配 2 张图片：先添加图片 1，until: 3:00，然后添加图片 2，until 留空（它会自动运行到 4:00）。

3. 选择 Google Font 字体、字号、颜色、描边和位置（top/middle/bottom）。

4. 添加歌词行：文本 + 开始时间 + 结束时间（3:05、185 或 1:03:05 都可以）。拖动歌词块 可调整其时间，或 拖动其左/右边缘 只调整开始或结束时间 —— 松开后都会自动提交。

5. 拖动时间轴预览任意时刻显示哪一行歌词和哪一张图片。

6. 点击 渲染视频 —— 完成后 MP4 会出现并附带下载链接。

2. 运行 MCP 服务器（用于 AI 控制）

MCP 服务器通过 stdio 通信，因此你需要让 AI 工具的配置指向它，而不是自己手动运行。

Claude Desktop / Claude Code —— 添加到你的 MCP 配置（claude_desktop_config.json 或等效文件）中：

{
  "mcpServers": {
    "lyric-studio": {
      "command": "node",
      "args": ["/absolute/path/to/lyric-video-mcp/mcp-server.js"]
    }
  }
}

重启客户端，AI 将可以使用以下工具：

多张图片，每首歌的每个段落一张

图片按你添加的顺序依次播放 —— 每张图片从上一张结束的位置开始，一直播放到你给它的 until 时间：

将音频设置为 /Users/me/song.mp3（时长 4 分钟）。添加 /Users/me/cover1.jpg，until 为 "3:00"。然后添加 /Users/me/cover2.jpg，不设 "until" —— 它应一直播放到结束。

这样你得到：cover1.jpg 播放 0:00–3:00，cover2.jpg 播放 3:00–4:00。你可以用这种方式添加任意多张图片 —— 每张新图片只需要自己的 until。如果图片没有完全覆盖音频长度，渲染会失败并给出明确的错误信息，因此你会知道哪里需要填补空白。

连接后给 AI 的示例提示

使用 lyric-studio：将图片设置为 /Users/me/cover.jpg，音频设置为 /Users/me/raikan-cinta.mp3。使用 "Poppins" 字体，白色，黑色描边，底部位置。添加这行歌词："Mari mawar raikan cinta, tanpa cintanya kita tiada, mawar cinta mawar ku abadi, cinta pemilik segala jadi"，时间从 3:05 到 3:35。然后渲染它。

渲染原理

歌词行会被转换为 .ass 字幕文件，并使用 ffmpeg/libass 烧录到视频中，使用的是真实的 Google Font TTF（下载并缓存在 fonts-cache/ 中）—— 而不是通用的系统字体替代品。

项目结构

shared/projectStore.js   core logic — used by BOTH the UI server and MCP server
shared/fonts.js          Google Fonts catalog + real TTF downloader
shared/timeUtils.js      "3:05" / "185" / "1:03:05" time parsing
ui-server.js             Express server + REST API for the browser UI
mcp-server.js            MCP server (stdio) for AI control
public/                  browser UI (index.html, style.css, app.js)
projects/default/        this project's media, generated .ass file, project.json
fonts-cache/             downloaded Google Font TTF files (cached after first use)
public/output/           rendered MP4s

备注

• 这是一个有意设计为单项目的工具（当前只有一个活动项目 default）—— 最适合“一首歌、一个视频”的使用场景。如果你想要多个并发项目，shared/projectStore.js 中的每个函数都已经接受 projectId，因此只需做一个小改动，就可以在两个服务器中传递不同的 id。

• 字体文件在首次下载后会被缓存，因此使用相同字体重新渲染时不会再次访问网络。