Skip to main content

renderMedia()v3.0

@remotion/renderer 包的一部分.

🌐 Part of the @remotion/renderer package.

以编程方式渲染视频或音频。

🌐 Render a video or an audio programmatically.

render.mjs
await renderMedia({
  composition,
  serveUrl,
  codec: 'h264',
  outputLocation,
  inputProps,
});

在服务器端渲染页面上查看 renderMedia() 与 bundle() 和 selectComposition() 的示例。

🌐 See an example of renderMedia() together with bundle() and selectComposition() on the server-side rendering page.

参数​

🌐 Arguments

一个具有以下属性的对象：

🌐 An object with the following properties:

serveUrl​

string

可以是指向由 bundle() 生成的 Remotion Webpack 打包包的本地路径，或者是托管该打包包的 URL。

🌐 Either a local path pointing to a Remotion Webpack bundle generated by bundle() or a URL where the bundle is hosted.

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.

codec​

字符串 Codec

🌐 string Codec

为你的输出媒体选择合适的编解码器。请参考编码指南以找到最适合你使用场景的编解码器。

🌐 Choose a suitable codec for your output media. Refer to the Encoding guide to find the best codec for your use case.

outputLocation?​

string

将输出工件保存到何处。可以是绝对路径，也可以是相对于当前工作目录解析的相对路径。必须是文件路径（不是文件夹）。

🌐 Where to save the output artifact to. Either an absolute path or a relative path that will be resolved relative to the current working directory. Must be a file path (not a folder).

如果未指定或设置为 null，文件将以内存缓冲区的形式返回。

🌐 If not specified or set to null, the file will be returned in-memory as a buffer.

inputProps?​

object

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

确保也将相同的 inputProps 传递给 selectComposition() 才能使其正常工作。

🌐 Make sure to also pass the same inputProps to selectComposition() for this to work correctly.

port?​

number

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

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

frameRange?​

数字 | [数字, 数字] | [数字, null] FrameRange

🌐 number | [number, number] | [number, null] FrameRange

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

concurrency?​

数字 | 字符串 | 空 Concurrency

🌐 number | string | null Concurrency

一个 number 指定应启动多少个渲染进程，一个 string 指定要使用的 CPU 线程百分比（例如 50%），或者 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 (e.g. 50%), or null to let Remotion decide based on the CPU of the host machine. Default is half of the CPU threads available.

metadata?v4.0.216​

object

An object containing metadata to be embedded in the video. See here for which metadata is accepted.

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​

函数 OnArtifact

🌐 function OnArtifact

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

audioCodec?​

字符串 AudioCodec

🌐 string AudioCodec

选择你的音频编码。

🌐 Choose the encoding of your audio.

  • 默认值取决于所选择的 codec。
  • 如果你需要未压缩的音频，请选择 pcm-16。
  • 并非所有视频容器都支持所有音频编解码器。
  • 如果 codec 选项也指定了音频编解码器，则此选项优先。

请参阅 编码指南 以查看默认设置和支持的组合。

🌐 Refer to the Encoding guide to see defaults and supported combinations.

audioBitrate?v3.2.32​

Specify the target bitrate for the generated video. The syntax for FFmpeg's -b:a parameter should be used. FFmpeg may encode the video in a way that will not result in the exact audio bitrate specified. Example values: 512K for 512 kbps, 1M for 1 Mbps. Default: 320k

videoBitrate?v3.2.32​

Specify the target bitrate for the generated video. The syntax for FFmpeg's-b:v parameter should be used. FFmpeg may encode the video in a way that will not result in the exact video bitrate specified. Example values: 512K for 512 kbps, 1M for 1 Mbps.

crf?​

数字 | 空 Crf

🌐 number | null Crf

恒定速率因子，用于控制质量。参见：使用 CRF 设置控制质量

🌐 The constant rate factor, controlling the quality. See: Controlling quality using the CRF setting.

note

如果启用硬件加速，则无法设置 crf。请改用videoBitrate 选项。

bufferSize?v4.0.78​

The value for the -bufsize flag of FFmpeg. Should be used in conjunction with the encoding max rate flag.

maxRate?v4.0.78​

The value for the -maxrate flag of FFmpeg. Should be used in conjunction with the encoding buffer size flag.

imageFormat?​

字符串 VideoImageFormat

🌐 string VideoImageFormat

帧应以哪种图片格式渲染。

🌐 In which image format the frames should be rendered.

  • jpeg 是默认的，也是最快的
  • png 如果你想要 渲染透明视频
  • none 如果你正在渲染音频

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.

everyNthFrame?v3.1.0​

只渲染每第 n 帧。例如，只渲染每第二帧、每第三帧等。仅适用于 GIF 渲染。更多详情请见这里。

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

numberOfGifLoops?v3.1.0​

Allows you to set the number of loops as follows:
  • null (or omitting in the CLI) plays the GIF indefinitely.
  • 0 disables looping
  • 1 loops the GIF once (plays twice in total)
  • 2 loops the GIF twice (plays three times in total) and so on.

pixelFormat?​

字符串 PixelFormat

🌐 string PixelFormat

自定义像素格式以使用。 通常用于特殊情况，例如透明视频。

envVariables?​

Record<string, string>

包含要注入到你的项目中的环境变量的对象。

🌐 An object containing environment variables to be injected in your project.

请参阅：环境变量

🌐 See: Environment variables

jpegQuality?​

number

设置生成的 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.

muted?v3.2.1​

boolean

如果设置为真，则不会渲染音频。

🌐 If set to true, no audio is being rendered.

hardwareAcceleration?v4.0.228​

One of "disable", "if-possible", or "required" . Default "disable". Encode using a hardware-accelerated encoder if available. If set to "required" and no hardware-accelerated encoder is available, then the render will fail.

enforceAudioTrack?v3.2.1​

boolean

如果没有其他音轨，则渲染一个静音音轨。

🌐 Render a silent audio track if there wouldn't be any otherwise.

puppeteerInstance?​

puppeteer.Browser

一个已打开的 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()。

scale?​

按一个因子缩放输出尺寸。参见 Scaling 了解有关此功能的更多信息。

🌐 Scales the output dimensions by a factor. See Scaling to learn more about this feature.

overwrite?​

boolean

如果设置为 false，当文件已存在时将不会写入输出文件。

🌐 If set to false, the output file will not be written if a file already exists.

onStart?​

函数 OnStartData

🌐 function OnStartData

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

🌐 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 type {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}`);
};

onProgress?​

函数 RenderMediaOnProgress

🌐 function RenderMediaOnProgress

React 用于渲染进度。以下回调函数类似于 Remotion 在其 CLI 上显示渲染进度的方式：

🌐 React to render progress. The following callback function is similar to how Remotion displays render progress on it's CLI:

Simple example - Log overall progress
import type {RenderMediaOnProgress} from '@remotion/renderer';

const onProgress: RenderMediaOnProgress = ({progress}) => {
  console.log(`Rendering is ${progress * 100}% complete`);
};
Advanced example - Fine-grained progress values
import type {RenderMediaOnProgress} from '@remotion/renderer';

const onProgress: RenderMediaOnProgress = ({renderedFrames, encodedFrames, encodedDoneIn, renderedDoneIn, stitchStage}) => {
  if (stitchStage === 'encoding') {
    // Rendering frames and encoding into video
    console.log('Encoding...');
  } else if (stitchStage === 'muxing') {
    // If parallel rendering and encoding is being used, a second stage is used to
    // encode the audio and combine it with the video. This stage does not occur on every render.
    console.log('Muxing audio...');
  }
  // Amount of frames rendered into images
  console.log(`${renderedFrames} rendered`);
  // Amount of frame encoded into a video
  console.log(`${encodedFrames} encoded`);
  // Time to create images of all frames
  if (renderedDoneIn !== null) {
    console.log(`Rendered in ${renderedDoneIn}ms`);
  }
  // Time to encode video from images
  if (encodedDoneIn !== null) {
    console.log(`Encoded in ${encodedDoneIn}ms`);
  }
};
note

progress 属性从 v3.2.17 开始可用。

onDownload?​

函数 RenderMediaOnDownload

🌐 function RenderMediaOnDownload

如果你的项目中包含音频（或带声音的视频），Remotion 需要下载它以便在输出文件中使用其音频。你可以使用此回调来响应下载的发生和进度。

🌐 If an audio (or a video with sound) is included in your project, Remotion needs to download it in order to use it's audio in the output file. You can use this callback to react to a download happening and progressing.

import type {RenderMediaOnDownload} from '@remotion/renderer';

const onDownload: RenderMediaOnDownload = (src) => {
  console.log(`Downloading ${src}...`);
  return ({percent, downloaded, totalSize}) => {
    // percent and totalSize can be `null` if the downloaded resource
    // does not have a `Content-Length` header
    if (percent === null) {
      console.log(`${downloaded} bytes downloaded`);
    } else {
      console.log(`${Math.round(percent * 100)}% done)`);
    }
  };
};

proResProfile?​

设置 ProRes 配置文件。仅适用于使用 prores 编解码器渲染的视频。有关可能的选项，请参见 编码指南。

🌐 Sets a ProRes profile. Only applies to videos rendered with prores codec. See Encoding guide for possible options.

x264Preset?​

string

Sets a x264 preset profile. Only applies to videos rendered with h264 codec.
Possible values: superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo.
Default: medium

onBrowserLog?​

函数 BrowserLog

🌐 function BrowserLog

捕获控制台打印的消息。示例：

🌐 Catch a console message being printed. Example:

import type {BrowserLog} from '@remotion/renderer';

const onBrowserLog = (log: BrowserLog) => {
  // `type` is the console.* method: `log`, `warn`, `error`, etc.
  console.log(`[${log.type}]`);
  console.log(log.text);
  console.log(`at ${log.stackTrace}`);
};

timeoutInMilliseconds?​

一个数字，描述渲染可能花多长时间来解决所有 delayRender() 调用 在超时之前。默认值：30000

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

cancelSignal?v3.0.15​

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

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

chromiumOptions?v2.6.5​

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

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

note

Chromium 标志需要在浏览器启动时设置。如果你使用 puppeteerInstance 传递一个实例，传递给 renderMedia() 的选项将不起作用，而是会使用传递给 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?​

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"

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.

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.

ffmpegOverride?v3.2.22​

函数 FfmpegOverrideFn

🌐 function FfmpegOverrideFn

修改 Remotion 在底层使用的 FFMPEG 命令。它的工作方式类似于 reducer，也就是说，你传入一个函数，该函数以命令作为参数并返回一个新的命令。

🌐 Modifies the FFMPEG command that Remotion uses under the hood. It works reducer-style, meaning that you pass a function that takes a command as an argument and returns a new command.

import type {FfmpegOverrideFn} from '@remotion/renderer';

const ffmpegOverride: FfmpegOverrideFn = ({type, args}) => {
  console.log(type); // "stitcher" | "pre-stitcher
  return [...args, '-vf', 'eq=brightness=0:saturation=1'];
};

你传入的函数必须接受一个对象作为它的唯一参数，该对象包含以下属性：

🌐 The function you pass must accept an object as it's only parameter which contains the following properties:

  • type：要么 "stitcher" 要么 "pre-stitcher"。如果有足够的内存和 CPU，可采用两遍处理的视频生成方式。pre-stitcher 是编码阶段，stitcher 是复用阶段。如果覆盖函数只调用一次 stitcher，那么编码和复用将在同一步完成。你可以通过在渲染命令中添加 --log=verbose 来判断是否启用了并行编码。
  • args：作为参数传递给 FFMPEG 命令的字符串数组。

你的函数必须返回一个修改过的字符串数组。

🌐 Your function must return a modified array of strings.

warning

不建议使用此功能。在使用它之前，我们希望让你了解一些注意事项：

  • 渲染命令可能会随任何新的 Remotion 版本而更改，即使是在补丁升级时。这可能会导致你使用此功能时出现问题。
  • 根据所选的编解码器、可用的 CPU 和内存，Remotion 可能会使用或不使用“并行编码”，这将导致执行多个 FFMPEG 命令。你的函数必须能够处理被多次调用的情况。
  • 使用 Remotion Lambda 时此功能不可用。

在使用此技巧之前，请通过 Discord 联系 Remotion 团队，并询问我们是否愿意以干净的方式实现你需要的功能——我们经常根据用户反馈快速实现新功能。

🌐 Before you use this hack, reach out to the Remotion team on Discord and ask us if we are open to implement the feature you need in a clean way - we often do implement new features quickly based on users feedback.

disallowParallelEncoding?v3.2.29​

不允许渲染器同时进行帧渲染和编码。这使渲染过程更节省内存，但可能会更慢。

🌐 Disallows the renderer from doing rendering frames and encoding at the same time. This makes the rendering process more memory-efficient, but possibly slower.

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.

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

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.

colorSpace?v4.0.28​

Color space to use for the video. Acceptable values: "default"(default since 5.0), "bt601" (same as "default", since v4.0.424), "bt709" (since v4.0.28), "bt2020-ncl" (since v4.0.88), "bt2020-cl" (since v4.0.88), .
For best color accuracy, it is recommended to also use "png" as the image format to have accurate color transformations throughout.
Only since v4.0.83, colorspace conversion is actually performed, previously it would only tag the metadata of the video.

repro?v4.0.88​

boolean - 默认 false

🌐 boolean - default false

Create a ZIP that you can submit to Remotion if asked for a reproduction.

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.

separateAudioTo?v4.0.123​

If set, the audio will not be included in the main output but rendered as a separate file at the location you pass. It is recommended to use an absolute path. If a relative path is passed, it is relative to the Remotion Root.

forSeamlessAacConcatenation?v4.0.123​

If enabled, the audio is trimmed to the nearest AAC frame, which is required for seamless concatenation of AAC files. This is a requirement if you later want to combine multiple video snippets seamlessly.

This option is used internally. There is currently no documentation yet for to concatenate the audio chunks.

compositionStart?v4.0.279​

仅在实现分布式渲染器时使用的选项，具体设置请参阅分布式渲染。

🌐 An option to be used only if implementing a distributed renderer, see Distributed rendering for what to set it to.

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.

licenseKey?v4.0.409​

License key for sending a usage event using @remotion/licensing.

isProduction?v4.0.409​

默认 true

🌐 default true

Pass false if this a development render to not count it as a billable render on remotion.pro. Only can be used in conjuction with licenseKey.

apiKey?v4.0.375​

在 v4.0.409 中已弃用

🌐 deprecated in v4.0.409

API key for sending a usage event using @remotion/licensing.

parallelism?​

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

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

quality?​

在 v4.0.0 中重命名为 jpegQuality。

🌐 Renamed to jpegQuality in v4.0.0.

dumpBrowserLogs?​

默认 false，在 v4.0 中已被弃用

🌐 default false, deprecated in v4.0

已弃用，建议使用 logLevel 替代。

🌐 Deprecated in favor of logLevel.

verbose?​

在 v4.0 中弃用

🌐 deprecated in v4.0

已弃用，建议使用 logLevel 替代。

🌐 Deprecated in favor of logLevel.

onSlowestFrames?​

在 v3.2.29 中引入，在 v4.0 中移除。slowestFrames 已被移动到返回类型。

🌐 Introduced in v3.2.29, removed from v4.0. slowestFrames has been moved to the return type.

回调函数，会在 renderMedia() 解析之前被调用。
唯一的参数 slowestFrames 是一个包含形状为 {frame:<Frame number>, time:<Time to render frame ms>} 的 10 个最慢帧的数组。你可以使用这些信息来优化你的渲染时间。

ffmpegExecutable​

在v4.0中移除，字符串

🌐 removed in v4.0, string

用于覆盖 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

从 v4.0.0 起：

🌐 from v4.0.0:

返回值是一个具有以下属性的对象：

🌐 The return value is an object with the following properties:

  • buffer：如果未指定 outputLocation 或 null，则包含一个缓冲区，否则 null。
  • slowestFrames：一个由 {frame:<Frame number>, time:<Time to render frame ms>} 形状的 10 个最慢帧组成的数组。你可以使用此信息来优化渲染时间。
  • contentType：v4.0.426 渲染输出的内容类型，例如 "video/mp4"、"video/webm"、"image/gif"。

从 v3.0.26:

🌐 from v3.0.26:

如果未指定 outputLocation 或 null，返回值是一个解析为 Buffer 的 Promise。如果指定了输出位置，返回值是一个不解析任何值的 Promise。

🌐 If outputLocation is not specified or null, the return value is a Promise that resolves a Buffer. If an output location is specified, the return value is a Promise that resolves no value.

兼容性​

🌐 Compatibility

BrowsersServersEnvironments
Chrome
Firefox
Safari
Node.js
Bun
Serverless Functions

另请参阅​

🌐 See also

Last updated on