Skip to main content

renderFrames()

@remotion/renderer 包的一部分.

🌐 Part of the @remotion/renderer package.

使用 Puppeteer 渲染一系列图片并计算混合音频的信息。

🌐 Renders a series of images using Puppeteer and computes information for mixing audio.

如果你只想渲染静止图片，请使用 renderStill()。

🌐 If you want to render only a still image, use renderStill().

info

在 Remotion 3.0 中，我们添加了 renderMedia() API，它将 renderFrames() 和 stitchFramesToVideo() 合并为一个简化步骤，并加快了渲染速度。如果可以的话，优先使用 renderMedia()。

参数​

🌐 Arguments

接受一个具有以下键的对象：

🌐 Takes an object with the following keys:

composition​

视频配置

🌐 VideoConfig

一个描述使用 id、width、height、fps 和 durationInFrames、defaultProps 以及 props 的组合的对象。
调用 selectComposition() 或 getCompositions() 来获取可能配置的数组。

🌐 An object describing a composition using id, width, height, fps and durationInFrames, defaultProps and props.
Call selectComposition() or getCompositions() to get an array of possible configs.

onStart​

回调函数，在渲染器准备开始渲染并计算出将要渲染的帧数后被调用：

🌐 Callback function that gets called once the renderer has prepared to start rendering and has calculated the amount of frames that are going to be rendered:

import {OnStartData} from '@remotion/renderer';

const onStart = ({
  frameCount,
  parallelEncoding, // available from v4.0.52
  resolvedConcurrency, // available from v4.0.180
}: OnStartData) => {
  console.log(`Beginning to render ${frameCount}.`);

  if (parallelEncoding) {
    console.log('Parallel encoding is enabled.');
  }

  console.log(`Using concurrency: ${resolvedConcurrency}`);
};

onFrameUpdate​

每当一帧渲染完成时会调用的回调函数。会传入一个参数，其中包含已经渲染的帧数（而不是已渲染帧的帧编号）。

🌐 A callback function that gets called whenever a frame finished rendering. An argument is passed containing how many frames have been rendered (not the frame number of the rendered frame).

在 v3.0.0 中，添加了第二个参数：frame，返回刚渲染的帧编号。

🌐 In v3.0.0, a second argument was added: frame, returning the frame number that was just rendered.

在 v3.2.30 中，渲染了第三个参数：timeToRenderInMilliseconds，描述渲染该帧所用的时间（以毫秒为单位）。

🌐 In v3.2.30, a third argument was rendered: timeToRenderInMilliseconds, describing the time it took to render that frame in milliseconds.

const onFrameUpdate = (framesRendered: number, frame: number, timeToRenderInMilliseconds: number) => {
  console.log(`${framesRendered} frames rendered.`);

  // From v3.0.0
  console.log(`${frame} was just rendered.`);

  // From v3.2.30
  console.log(`It took ${timeToRenderInMilliseconds}ms to render that frame.`);
};

outputDir​

一个 string，指定应将帧保存到的目录（绝对路径）。将 null 传递给此选项，并使用 onFrameBuffer 回调来获取帧的 Buffer，而不是将其写入任何位置。

🌐 A string specifying the directory (absolute path) to which frames should be saved. Pass null to this option and use the onFrameBuffer callback instead to get a Buffer of the frame rather than to write it to any location.

inputProps​

传递给所选视频组合的输入属性。。
必须是一个 JSON 对象。
可以从根组件使用 getInputProps() 读取属性。
你可以使用 calculateMetadata() 转换输入属性。

serveUrl​

可以是 Webpack 包，或者指向已打包 Remotion 项目的 URL。调用 bundle() 来生成一个包。你可以传入文件位置，或者将其部署为网站并传入 URL。

🌐 Either a Webpack bundle or a URL pointing to a bundled Remotion project. Call bundle() to generate a bundle. You can either pass the file location or deploy it as a website and pass the URL.

imageFormat?​

默认："jpeg"。默认选择jpeg，因为它是最快的。

🌐 Default: "jpeg". Choose jpeg by default because it is the fastest.

  • 如果你希望你的图片序列具有 alpha 通道（用于透明），请选择 png。
  • 如果你只想渲染音频，请选择 none。

imageSequencePattern? v4.0.313​

用于命名输出图片序列文件的字符串模式。你可以使用以下魔法替换项：

🌐 A string pattern for naming the output image sequence files. You can use the following magic replacements:

  • [frame]：将被替换为零填充的帧编号（例如 0001、0002、...）
  • [ext]：将被替换为图片格式扩展名（例如 jpeg、png）

默认：element-[frame].[ext]

🌐 Default: element-[frame].[ext]

示例：

renderFrames({
  ...otherOptions,
  imageSequencePattern: 'frame_[frame]_custom.[ext]',
});
// Produces: frame_0001_custom.jpeg, frame_0002_custom.jpeg, ...

concurrency?​

number 指定应并行启动多少个渲染进程，string 指定应使用的 CPU 线程百分比，或 null 让 Remotion 根据主机的 CPU 决定。默认值为可用 CPU 线程的一半。

🌐 A number specifying how many render processes should be started in parallel, a string specifying the percentage of the CPU threads to use, or null to let Remotion decide based on the CPU of the host machine. Default is half of the CPU threads available.

scale?v2.6.7​

数字 - 默认值: 1

🌐 number - default: 1

Scales the output dimensions by a factor. For example, a 1280x720px frame will become a 1920x1080px frame with a scale factor of 1.5. See Scaling for more details.

jpegQuality?​

设置生成的 JPEG 图片的质量。必须是 0 到 100 之间的整数。默认情况下由浏览器决定，当前默认值为 80。

🌐 Sets the quality of the generated JPEG images. Must be an integer between 0 and 100. Default is to leave it up to the browser, current default is 80.

仅在 imageFormat 为 'jpeg' 时适用，否则此选项无效。

🌐 Only applies if imageFormat is 'jpeg', otherwise this option is invalid.

port?​

偏好用于服务 Remotion 项目的特定端口。如果未指定，将使用随机端口。

🌐 Prefer a specific port that will be used to serve the Remotion project. If not specified, a random port will be used.

frameRange?​

指定单个帧（传入 number）或帧范围（传入元组 [number, number]）进行渲染。通过传入 null（默认值）将渲染合成的所有帧。传入 [number, null] 可从某一帧渲染到合成的结束。v4.0.421

muted?v3.2.1​

禁用音频输出。此选项只能与视频编码器结合设置，并且也应传递给 stitchFramesToVideo()。

🌐 Disables audio output. This option may only be set in combination with a video codec and should also be passed to stitchFramesToVideo().

logLevel?v4.0.0​

One of trace, verbose, info, warn, error.
Determines how much info is being logged to the console.

Default info.

onArtifact?v4.0.176​

[处理由 <Artifact> 组件发出的工件](/docs/artifacts#using-rendermedia-renderstill-or-renderframes)。

puppeteerInstance?​

一个已打开的 Browser 实例。使用 openBrowser() 来创建一个新实例。在多个函数调用中重复使用同一个浏览器可以加快渲染过程。你需要自己负责打开和关闭浏览器。如果你不指定此选项，将会在结束时打开并关闭一个新的浏览器。

🌐 An already open Browser instance. Use openBrowser() to create a new instance. Reusing a browser across multiple function calls can speed up the rendering process. You are responsible for opening and closing the browser yourself. If you don't specify this option, a new browser will be opened and closed at the end.

note

尽管名字如此，实际上不兼容 puppeteer，仅兼容 openBrowser()。

envVariables?v2.2.0​

一个包含环境变量键值对的对象，这些变量将被注入到你的 Remotion 项目中，并且可以通过读取全局 process.env 对象来访问。

🌐 An object containing key-value pairs of environment variables which will be injected into your Remotion projected and which can be accessed by reading the global process.env object.

onBrowserLog?v3.0.0​

当你的项目调用 console.log 或控制台中的其他方法时会被调用。浏览器日志有三个属性：

🌐 Gets called when your project calls console.log or another method from console. A browser log has three properties:

  • text：正在打印的消息
  • stackTrace：一个包含以下属性的对象数组：
    • url：记录的资源的 URL。
    • lineNumber：日志被调用时文件中的零起点行号。
    • columnNumber：日志被调用时文件中的零起始列号。
  • type：控制台方法——以下之一 log、debug、info、error、warning、dir、dirxml、table、trace、clear、startGroup、startGroupCollapsed、endGroup、assert、profile、profileEnd、count、timeEnd、verbose
renderFrames({
  onBrowserLog: (info) => {
    console.log(`${info.type}: ${info.text}`);
    console.log(
      info.stackTrace
        .map((stack) => {
          return `  ${stack.url}:${stack.lineNumber}:${stack.columnNumber}`;
        })
        .join('\n'),
    );
  },
});

browserExecutable?v3.0.11​

一个字符串，定义应使用的浏览器可执行文件在磁盘上的绝对路径。默认情况下，Remotion 会尝试自动检测它，如果不可用，将下载一个。如果定义了 puppeteerInstance，它将优先于 browserExecutable。

🌐 A string defining the absolute path on disk of the browser executable that should be used. By default Remotion will try to detect it automatically and download one if none is available. If puppeteerInstance is defined, it will take precedence over browserExecutable.

cancelSignal?v3.0.15​

一个允许取消渲染的令牌。参见："makeCancelSignal()"

🌐 A token that allows the render to be cancelled. See: makeCancelSignal()

onFrameBuffer?v3.0.0​

如果你将 null 传递给 outputDir，这个方法将被调用，并传递当前帧的缓冲区。这主要在 Remotion 内部用于实现 renderMedia()，对于终端用户可能用处有限。

🌐 If you passed null to outputDir, this method will be called passing a buffer of the current frame. This is mostly used internally by Remotion to implement renderMedia() and might have limited usefulness for end users.

timeoutInMilliseconds?v2.6.3​

一个数字，描述在渲染超时并失败之前，一帧可能需要多长时间来完成所有delayRender()调用。默认值：30000

🌐 A number describing how long one frame may take to resolve all delayRender() calls before the render times out and fails. Default: 30000

everyNthFrame?v3.1.0​

只渲染每第 n 帧。例如，只渲染每第二帧、每第三帧等。仅用于渲染 GIF。在这里查看更多详细信息。

🌐 Renders only every nth frame. For example only every second frame, every third frame and so on. Only meant for rendering GIFs. See here for more details.

chromiumOptions?v2.6.5​

允许你设置某些 Chromium / Google Chrome 标志。见：Chromium 标志。

🌐 Allows you to set certain Chromium / Google Chrome flags. See: Chromium flags.

note

Chromium 标志需要在浏览器启动时设置。如果你使用 puppeteerInstance 传递一个实例，那么传递给 renderFrames() 的选项将不起作用，而是会使用传递给 openBrowser() 的标志。

disableWebSecurity?​

boolean - 默认 false

🌐 boolean - default false

这将尤其会禁用 CORS 以及其他安全功能。

🌐 This will most notably disable CORS among other security features.

enableMultiProcessOnLinux?v4.0.42​

boolean - 默认 true

🌐 boolean - default true

Removes the --single-process flag that gets passed to Chromium on Linux by default. This will make the render faster because multiple processes can be used, but may cause issues with some Linux distributions or if window server libraries are missing.
Default: false until v4.0.136, then true from v4.0.137 on because newer Chrome versions don't allow rendering with the --single-process flag.
This flag will be removed in Remotion v5.0.

ignoreCertificateErrors?​

boolean - 默认 false

🌐 boolean - default false

导致无效的 SSL 证书（例如自签名证书）被忽略。

🌐 Results in invalid SSL certificates, such as self-signed ones, being ignored.

headless?​

Deprecated - will be removed in 5.0.0. With the migration to Chrome Headless Shell, this option is not functional anymore.

If disabled, the render will open an actual Chrome window where you can see the render happen. The default is headless mode.

gl?​

string

Changelog
  • From Remotion v2.6.7 until v3.0.7, the default for Remotion Lambda was swiftshader, but from v3.0.8 the default is swangle (Swiftshader on Angle) since Chrome 101 added support for it.
  • From Remotion v2.4.3 until v2.6.6, the default was angle, however it turns out to have a small memory leak that could crash long Remotion renders.

Select the OpenGL renderer backend for Chromium.
Accepted values:

  • "angle"
  • "egl"
  • "swiftshader"
  • "swangle"
  • "vulkan" (from Remotion v4.0.41)
  • "angle-egl" (from Remotion v4.0.51)

The default is null, letting Chrome decide, except on Lambda where the default is "swangle"

userAgent?v3.3.83​

允许你设置 headless Chrome 浏览器使用的自定义用户代理。

🌐 Lets you set a custom user agent that the headless Chrome browser assumes.

darkMode?v4.0.381​

Whether Chromium should pretend to be in dark mode by emulating the media feature 'prefers-color-scheme: dark'. Default is false.

offthreadVideoCacheSizeInBytes?v4.0.23​

From v4.0, Remotion has a cache for <OffthreadVideo> frames. The default is null, corresponding to half of the system memory available when the render starts.
This option allows to override the size of the cache. The higher it is, the faster the render will be, but the more memory will be used.
The used value will be printed when running in verbose mode.
Default: null

mediaCacheSizeInBytes?v4.0.352​

Specify the maximum size of the cache that <Video> and <Audio> from @remotion/media may use combined, in bytes.
The default is half of the available system memory when the render starts.

offthreadVideoThreads?v4.0.261​

The number of threads that<OffthreadVideo> can start to extract frames. The default is 2. Increase carefully, as too many threads may cause instability.

binariesDirectory?v4.0.120​

The directory where the platform-specific binaries and libraries that Remotion needs are located. Those include an ffmpeg and ffprobe binary, a Rust binary for various tasks, and various shared libraries. If the value is set to null, which is the default, then the path of a platform-specific package located at node_modules/@remotion/compositor-* is selected.
This option is useful in environments where Remotion is not officially supported to run like bundled serverless functions or Electron.

onBrowserDownload?v4.0.137​

Gets called when no compatible local browser is detected on the system and this API needs to download a browser. Return a callback to observe progress. See here for how to use this option.

chromeMode?v4.0.248​

One of headless-shell, chrome-for-testing. Default headless-shell. Use chrome-for-testing to take advantage of GPU drivers on Linux.

quality?​

在 v4.0.0 中重命名为 jpegQuality。

🌐 Renamed to jpegQuality in v4.0.0.

dumpBrowserLogs?​

在 v4.0 中被弃用，取而代之的是 logLevel。

🌐 Deprecated in v4.0 in favor of logLevel.

parallelism?​

在 v3.2.17 中重命名为 concurrency。 在 v4.0.0 中已移除。

🌐 Renamed to concurrency in v3.2.17. Removed in v4.0.0.

ffmpegExecutable​

在 v4.0 中移除

🌐 removed in v4.0

用于覆盖 ffmpeg 可执行文件的绝对路径。

🌐 An absolute path overriding the ffmpeg executable to use.

ffprobeExecutable v3.0.17​

在 v4.0 中移除

🌐 removed in v4.0

用于覆盖 ffprobe 可执行文件的绝对路径。

🌐 An absolute path overriding the ffprobe executable to use.

返回值​

🌐 Return value

一个承诺，解析为包含以下属性的对象：

🌐 A promise resolving to an object containing the following properties:

  • frameCount：number - 描述渲染了多少帧。
  • assetsInfo：RenderAssetInfo - 可以传递给 stitchFramesToVideo() 用于混合音频的信息。该对象的结构应被视为 Remotion 内部实现，可能会随着 Remotion 版本而变化。

兼容性​

🌐 Compatibility

BrowsersServersEnvironments
Chrome
Firefox
Safari
Node.js
Bun
Serverless Functions

另请参阅​

🌐 See also

Last updated on