remotion-media

remotion-media

Remotion 的媒体操作系统：解析 · 放置 · 验证 — 每种媒体类型，一项技能。

放置约定

所有静态资源都位于 public/ 目录中。只能通过 staticFile() 引用它们：

import {staticFile} from 'remotion';

// Images
<Img src={staticFile('hero.jpg')} />

// Audio
<Audio src={staticFile('background.mp3')} volume={0.4} />

// Video
<OffthreadVideo src={staticFile('footage.mp4')} />

切勿使用相对路径、磁盘绝对路径，或渲染时需要访问网络的 CDN URL（它们在离线渲染或 Lambda 中会失效）。

资源类型及其工具

类型	工具 / 包	用法
背景音乐	已解析的本地文件	<Audio src={staticFile('bgm.mp3')} volume={0.3} />
音效	已解析的本地文件	<Audio src={staticFile('click.mp3')} startFrom={30} />
图片 / 背景	本地文件或 staticFile()	<Img src={staticFile('bg.jpg')} />
Google Fonts	@remotion/google-fonts	loadFont() 返回 {fontFamily}
品牌标志（SVG）	public/ 中的本地 SVG	<Img src={staticFile('logo.svg')} />
配音 / TTS	本地 mp3 文件	<Audio src={staticFile('narration.mp3')} />
视频素材	本地 mp4 文件	<OffthreadVideo src={staticFile('clip.mp4')} />
字幕	@remotion/captions	按词计时的 <Captions> 组件

字体

Google Fonts 始终使用 @remotion/google-fonts，切勿使用 <link> 标签：

npm install @remotion/google-fonts

import {loadFont} from '@remotion/google-fonts/Inter';

const {fontFamily} = loadFont();

const Text = () => (
  <div style={{fontFamily, fontWeight: 700}}>Hello</div>
);

对于自定义字体，将字体文件放入 public/fonts/，并在 calculateMetadata 中通过 FontFace 加载，或使用 delayRender/continueRender 配对加载。

delayRender — 异步资源加载

当资源必须在第一帧渲染前获取或生成时，使用 remotion 中的 delayRender / continueRender：

import {delayRender, continueRender} from 'remotion';

const handle = delayRender('Loading font');

fetch('/api/data')
  .then(r => r.json())
  .then(data => {
    setData(data);
    continueRender(handle);
  });

不要在渲染函数中使用 delayRender — 应在模块作用域中调用，或在仅触发一次的 useEffect 中调用。

音频 / 视频时序

属性	效果
startFrom	跳过资源开头的 N 帧
endAt	在资源的第 N 帧停止播放
volume	0–1 标量值，或帧函数
playbackRate	播放速度倍率
loop	循环播放音频（确定性行为：根据合成时长重复）

OffthreadVideo 与 Video

	<OffthreadVideo>	<Video>
渲染精度	精确到帧（推荐）	可能丢帧
跳转行为	在主线程之外渲染	在浏览器中播放
使用场景	最终合成	仅用于预览

渲染时始终使用 <OffthreadVideo>。 <Video> 仅可用于 Studio 预览。

字幕

使用 @remotion/captions 添加按词计时的字幕：

npm install @remotion/captions

import {Captions} from '@remotion/captions';

<Captions
  subtitles={wordTimedSubtitles}
  startFrom={0}
  windowStart={currentWordStart}
  windowEnd={currentWordEnd}
  style={{fontSize: 48, color: 'white'}}
/>

转录工作流 → references/captions.md。

音频响应式准备

使用 @remotion/media-utils 在渲染流程之外预先分析音频：

import {getAudioData, visualizeAudio} from '@remotion/media-utils';

// In calculateMetadata (runs once before render):
const audioData = await getAudioData(staticFile('music.mp3'));

完整的音频响应式创作指南 → remotion-creative/references/audio-reactive.md。

主动排查 — 执行媒体机会检查

构建或审查合成时，进行一次有依据的扫描，然后询问一次：

检测到的信号	建议
屏幕文字没有配音	提供 TTS 配音选项
表情符号或占位图标 div	替换为真实的 SVG 图标
占位图片或纯色背景	建议使用 public/ 中的真实图片
硬切换且没有音效	建议添加转场音效
片段时长超过约 10 s 且没有背景音乐	建议添加背景音乐曲目

规则：有依据，不泛泛而谈（没有信号 → 不提出建议）；提出具体修复方案；每个项目仅一次（合并为一个请求）。

查阅位置

任务	阅读
staticFile、public/ 目录、资源路径	references/static-files.md
用于异步加载的 delayRender	references/async-assets.md
字体加载（@remotion/google-fonts、自定义字体）	references/fonts.md
OffthreadVideo、Audio 剪辑、音量曲线	references/media-elements.md
字幕、转录、@remotion/captions	references/captions.md
音频响应式动画、getAudioData	references/audio-reactive.md