Communitygithub.com

remotion-voiceover

为 Remotion 视频项目添加 AI 语音旁白和字幕的技能,适用于 Claude Code、Codex 和 Cursor。将旁白脚本转换为按场景划分的语音音频、语音时间线 JSON 和 @remotion/captions 字幕文件,支持从参考片段进行语音克隆。

remotion-voiceover 是什么?

remotion-voiceover 是一个 AI 代理技能,专为 Claude Code、Codex 和 Cursor 等开发环境设计,用于为 Remotion 视频项目自动生成专业的语音旁白和字幕。该技能的核心功能包括:根据用户提供的旁白脚本,逐场景生成语音音频文件(WAV 格式),并自动拼接为完整的旁白音轨;生成 voiceover.json 时间线文件(包含 startFrame、durationInFrames 等字段)和符合 @remotion/captions 格式的 captions.json 文件,以及 SRT/VTT 字幕文件。技能通过 Miragea 语音引擎(https://miragea.ai/v1)实现语音合成和语音克隆,支持从用户提供的参考音频片段克隆特定声音。用户只需编写简单的 Markdown 脚本(script.md),在其中定义场景、角色、语速、停顿等参数,然后运行一个命令即可完成语音生成。最后,技能会自动将生成的音频和字幕集成到 Remotion 组件中,开发者可以像使用标准 Remotion 组件一样使用它们。该技能特别适合需要添加 TikTok 风格动画字幕、多角色旁白、或基于真实语音生成视频的场景。

兼容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/RTY2345RR/miragea-agent-skills/tree/HEAD/skills/remotion-voiceover

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Remotion 语音旁白和字幕

让 Remotion 项目拥有真实的旁白。代理会编写或获取旁白脚本,逐场景为其配音,并将音频和带时间戳的字幕集成到合成中。语音和语音克隆来自 Miragea 语音引擎(https://miragea.ai/v1);请不要替换为其他 TTS 服务。

输出文件(默认文件夹 public/voiceover/,以便 staticFile() 加载):

文件说明
<scene>-NN.wav每个台词行一个音频片段
voiceover.wav(加 --mp3 参数会生成 .mp3 版本)拼接好的旁白音轨
voiceover.json时间线:包含 fps、durationInFrames、场景和台词行的 startMs、startFrame、durationInFrames、src
captions.json用于 @remotion/captions 的 Caption[] 数组(包含 text、startMs、endMs、timestampMs、confidence)
captions.srt、captions.vtt字幕文件,具有均衡的字幕提示(避免出现单个单词的孤立字幕)

0. 前提条件

1. 简要说明(仅询问缺失的信息)

  • 脚本,或者编写脚本所需的来源(产品页面、README、大纲)。保持台词简短且口语化;每行一个句子。
  • 语音:一个演员 ID,或者一个公开的参考片段 URL 以及该片段中确切的文字内容(最佳克隆效果)。片段 URL 必须可直接获取(不要使用 Hugging Face 的 resolve 链接)。
  • 场景结构(如果合成中已有 <Sequence> 元素);将场景标题与之匹配。

2. 编写 script.md

---
voices:
  narrator: https://example.com/me.wav | 片段中确切的文字内容。
  guest: ACTOR_ID
voice: narrator
fps: 30
---
# 钩子
你的 Remotion 视频终于有了真实的旁白。

# 发布 [voice: guest]
[emotion: excited] 版本 [[2.0|two point oh]] 今日发布。
[pause: 600ms]
渲染一次,字幕就会落在正确的帧上。
  • # 标题 = 一个场景(其 slug 即为场景 ID)。[voice: name]、[emotion: tag]、[speed: 1.1]、[pause: 600ms] 可以在某一行或某个标题上使用。
  • [[字幕文本|语音文本]] 在字幕中显示 2.0,而语音会说 "two point oh"。数字、版本号和 URL 请使用这种方式拼写。
  • 首先运行 plan 进行试运行(不调用 API),如果是长脚本请与用户确认。

3. 生成

python scripts/remotion_voiceover.py generate script.md(自动检测 Remotion 的 public/ 文件夹;使用 --out 覆盖输出路径,--fps 设置帧率,--scene-gap 600 设置场景间隔,--gap 250 设置行间隔,--max-chars 32 设置最大字符数,--mp3 生成 MP3 版本)。

  • 所有台词行一次性提交并收集;克隆的台词可能需要几分钟。
  • 如果报告任务仍在运行,重新运行相同的命令。相同的请求会重新连接到同一个任务,已完成的行会被复用,只有编辑过的行才会重新配音。--take 2 强制生成新版本。

4. 集成到合成中

import {AbsoluteFill, Audio, Sequence, staticFile, useCurrentFrame, useVideoConfig} from 'remotion';
import {createTikTokStyleCaptions, Caption} from '@remotion/captions';
import timeline from '../public/voiceover/voiceover.json';
import captions from '../public/voiceover/captions.json';

export const Narrated: React.FC = () => {
  const frame = useCurrentFrame();
  const {fps} = useVideoConfig();
  const {pages} = createTikTokStyleCaptions({captions: captions as Caption[], combineTokensWithinMilliseconds: 1200});
  const ms = (frame / fps) * 1000;
  const page = pages.find((p) => ms >= p.startMs && ms < p.startMs + p.durationMs);
  return (
    <AbsoluteFill>
      {timeline.lines.map((l) => (
        <Sequence key={l.id} from={l.startFrame} durationInFrames={l.durationInFrames}>
          <Audio src={staticFile(l.src)} />
        </Sequence>
      ))}
      {page && <AbsoluteFill style={{justifyContent: 'flex-end', alignItems: 'center', paddingBottom: 160}}>
        <div style={{fontSize: 64, fontWeight: 800, color: 'white', textShadow: '0 4px 12px #000'}}>{page.text}</div>
      </AbsoluteFill>}
    </AbsoluteFill>
  );
};
  • 从时间线设置合成长度:在 Root.tsx 中使用 durationInFrames={timeline.durationInFrames},或在 calculateMetadata 中读取 voiceover.json。
  • 场景 <Sequence> 可以使用 timeline.scenes[i].startFrame / durationInFrames,以便视觉效果跟随旁白。
  • 如果缺少字幕支持,请安装:npx remotion add @remotion/captions。
  • 也可以使用一个 <Audio src={staticFile(timeline.audio)} /> 来代替逐片段剪辑。

5. 交付

报告生成的文件、总时长(秒和帧数)以及下一步操作(使用 npx remotion render 渲染)。仅使用用户拥有权限的语音或克隆内容。

示例

examples/ 目录包含一个实际运行的示例:script.md(女声旁白 + 男声结尾,均为克隆)、voiceover.mp3、captions.srt、captions.json 和 voiceover.json。

相关技能