Skip to main content

<OffthreadVideo>

v3.0.11

该组件导入并显示视频，类似于 <Html5Video/>，但在渲染过程中，会从视频中提取精确帧，并将其显示在 <Img> 标签中。这个提取过程是在浏览器之外使用 FFmpeg 进行的。

🌐 This component imports and displays a video, similar to <Html5Video/>, but during rendering, extracts the exact frame from the video and displays it in a <Img> tag. This extraction process happens outside the browser using FFmpeg.

该组件旨在解决默认 <Html5Video> 元素的局限性。参见：视频标签比较。

🌐 This component was designed to combat limitations of the default <Html5Video> element. See: Comparison of video tags.

在客户端渲染中不支持

<OffthreadVideo> 在 @remotion/web-renderer 中不受支持。请改为使用来自 @remotion/media 的 <Video>。

示例​

🌐 Example

import {AbsoluteFill, OffthreadVideo, staticFile} from 'remotion';

export const MyVideo = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo src={staticFile('video.webm')} />
    </AbsoluteFill>
  );
};

你也可以从 URL 加载视频：

🌐 You can load a video from an URL as well:

export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo src="https://remotion.media/BigBuckBunny.mp4" />
    </AbsoluteFill>
  );
};

属性​

🌐 Props

src​

要渲染的视频的 URL。可以是远程 URL，也可以是通过 staticFile() 引用的本地文件。

🌐 The URL of the video to be rendered. Can be a remote URL or a local file referenced with staticFile().

trimBefore?v4.0.319​

将删除视频开头（左侧）的一部分。

🌐 Will remove a portion of the video at the beginning (left side).

在以下示例中，我们假设该组成部分的fps是30。

🌐 In the following example, we assume that the fps of the composition is 30.

传入 trimBefore={60} 时，播放将立即开始，但视频的前 2 秒会被剪掉。 传入 trimAfter={120} 时，文件中 4 秒之后的任何视频都会被剪掉。

🌐 By passing trimBefore={60}, the playback starts immediately, but with the first 2 seconds of the video trimmed away.
By passing trimAfter={120}, any video after the 4 second mark in the file will be trimmed away.

视频将播放从 00:02:00 到 00:04:00 的范围，这意味着视频将播放 2 秒钟。

🌐 The video will play the range from 00:02:00 to 00:04:00, meaning the video will play for 2 seconds.

有关确切行为，请参见：运算顺序。

🌐 For exact behavior, see: Order of operations.

export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo src={staticFile('video.webm')} trimBefore={60} trimAfter={120} />
    </AbsoluteFill>
  );
};

trimAfter?v4.0.319​

移除视频末尾（右侧）的一部分。有关说明，请参见 trimBefore。

🌐 Removes a portion of the video at the end (right side). See trimBefore for an explanation.

startFrom?​

已弃用

此属性在 4.0.319 中已重命名为 trimBefore。它仍然可以使用，但不能与新属性同时使用。

endAt?​

已弃用

此属性在 4.0.319 中已重命名为 trimAfter。它仍然可以使用，但不能与新属性同时使用。

transparent?v4.0.0​

如果设置为 true，帧将被提取为 PNG，从而支持透明度，但也会减慢渲染速度。

🌐 If set to true, frames will be extracted as PNG, enabling transparency but also slowing down your render.

如果设置为 false（默认），帧将以位图 (BMP) 的形式提取，这样速度更快。

🌐 If set to false (default), frames will be extracted as bitmap (BMP), which is faster.

volume?​

允许你控制整个音轨的音量或按每帧进行更改。请参考 使用音频 指南以了解如何使用它。

🌐 Allows you to control the volume for the whole track or change it on a per-frame basis. Refer to the using audio guide to learn how to use it.

Example using static volume
export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo volume={0.5} src={staticFile('video.webm')} />
    </AbsoluteFill>
  );
};
Example of a ramp up over 100 frames
export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo volume={(f) => interpolate(f, [0, 100], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('video.webm')} />
    </AbsoluteFill>
  );
};

默认情况下，支持 0 到 1 之间的音量，在 iOS Safari 中，音量始终为 1。
有关更多信息，请参阅 音量限制。

🌐 By default, volumes between 0 and 1 are supported, where in iOS Safari, the volume is always 1.
See Volume Limitations for more information.

loopVolumeCurveBehavior?v4.0.142​

控制 frame，当使用 volume 回调函数并将 OffthreadVideo 封装在 <Loop> 中时返回的值。

🌐 Controls the frame which is returned when using the volume callback function and wrapping OffthreadVideo in a <Loop>.

可以是 "repeat"（默认，每次迭代从 0 开始）或 "extend"（保持帧数递增）。

🌐 Can be either "repeat" (default, start from 0 on each iteration) or "extend" (keep increasing frames).

style?​

你可以传递任何可以传递给原生 HTML 元素的样式。请记住，在渲染期间，<OffthreadVideo> 会渲染一个 <Img> 标签，但在预览时使用的是 <video> 标签。

🌐 You can pass any style you can pass to a native HTML element. Keep in mind that during rendering, <OffthreadVideo> renders an <Img> tag, but a <video> tag is used during preview.

export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <Img src={staticFile('video.webm')} style={{height: 720, width: 1280}} />
    </AbsoluteFill>
  );
};

name?v4.0.71​

一个名称，将显示为 Remotion Studio 时间线中序列的标签。此属性纯粹是为了帮助你在时间线上跟踪项目。

🌐 A name and that will be shown as the label of the sequence in the timeline of the Remotion Studio. This property is purely for helping you keep track of items in the timeline.

toneFrequency?v4.0.47​

调整音频的音调——仅在渲染时应用。

🌐 Adjust the pitch of the audio - will only be applied during rendering.

接受介于 0.01 和 2 之间的数字，其中 1 表示原始音高。小于 1 的值会降低音高，而大于 1 的值会提高音高。

🌐 Accepts a number between 0.01 and 2, where 1 represents the original pitch. Values less than 1 will decrease the pitch, while values greater than 1 will increase it.

0.5 的 toneFrequency 会将音高降低一半，而 toneFrequency 为 1.5 会将音高提高 50%。

🌐 A toneFrequency of 0.5 would lower the pitch by half, and a toneFrequency of 1.5 would increase the pitch by 50%.

onError?​

处理播放视频时的错误。从 v3.3.89 开始，如果你传递一个 onError 回调，则不会抛出异常。以前，该错误无法被捕获。

🌐 Handle an error playing the video. From v3.3.89, if you pass an onError callback, then no exception will be thrown. Previously, the error could not be caught.

playbackRate?v2.2.0​

控制视频的速度。1 是默认值，表示正常速度，0.5 会减慢视频播放，使视频变为原来的两倍时长，2 会加快视频播放，使视频速度加倍。

🌐 Controls the speed of the video. 1 is the default and means regular speed, 0.5 slows down the video so it's twice as long and 2 speeds up the video so it's twice as fast.

虽然 Remotion 不限制可能的播放速度范围，但在开发模式下使用 HTMLMediaElement.playbackRate API，该 API 会在极端值时抛出错误。截至撰写本文时，如果播放速率低于 0.0625 或高于 16，Google Chrome 会抛出异常。

🌐 While Remotion doesn't limit the range of possible playback speeds, in development mode the HTMLMediaElement.playbackRate API is used which throws errors on extreme values. At the time of writing, Google Chrome throws an exception if the playback rate is below 0.0625 or above 16.

Example of a video playing twice as fast
export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo playbackRate={2} src={staticFile('video.webm')} />
    </AbsoluteFill>
  );
};
note

不支持倒放视频。

muted?​

你可以通过添加一个 muted 属性来去掉视频的音频：

🌐 You can drop the audio of the video by adding a muted prop:

Example of a muted video
export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo muted src="https://remotion.media/BigBuckBunny.mp4" />
    </AbsoluteFill>
  );
};

acceptableTimeShiftInSeconds?v3.2.42​

在 Studio 或 Remotion Player 中，如果视频与 Remotion 的内部时间不同步过多，Remotion 将会进行视频搜索——无论是由于视频加载缓慢还是页面无法实时跟上。默认情况下，当遇到 0.45 秒的时间偏移时，会触发搜索。使用此属性，你可以自定义阈值。

🌐 In the Studio or in the Remotion Player, Remotion will seek the video if it gets too much out of sync with Remotion's internal time - be it due to the video loading or the page being too slow to keep up in real-time. By default, a seek is triggered if 0.45 seconds of time shift is encountered. Using this prop, you can customize the threshold.

toneFrequency?v4.0.47​

调整音频的音调——仅在渲染时应用。

🌐 Adjust the pitch of the audio - will only be applied during rendering.

接受介于 0.01 和 2 之间的数字，其中 1 表示原始音高。小于 1 的值会降低音高，而大于 1 的值会提高音高。

🌐 Accepts a number between 0.01 and 2, where 1 represents the original pitch. Values less than 1 will decrease the pitch, while values greater than 1 will increase it.

0.5 的 toneFrequency 会将音高降低一半，而 toneFrequency 为 1.5 会将音高提高 50%。

🌐 A toneFrequency of 0.5 would lower the pitch by half, and a toneFrequency of 1.5 would increase the pitch by 50%.

pauseWhenBuffering?v4.0.111​

如果设置为 true 并且视频正在加载，播放器将进入 本地缓冲状态。默认是 false，但在 Remotion 5.0 中将变为 true。

🌐 If set to true and the video is loading, the Player will enter into the native buffering state. The default is false, but will become true in Remotion 5.0.

toneMapped?v4.0.117​

自 Remotion 4.0.117 起，Remotion 在转换为 RGB 时会调整不同色彩空间（如 HDR）视频的颜色，以抵消颜色偏移。
由于浏览器以 sRGB 显示，因此这是确保颜色正确显示所必需的。
此行为默认是 true，可以通过将 toneMapped 设置为 false 来禁用。
禁用色调映射可以加快渲染速度，但可能导致颜色不够鲜艳。

🌐 Since Remotion 4.0.117, Remotion will adjust the colors of videos in different color spaces (such as HDR) when converting to RGB, to counteract color shifts.
Since the browser is painting in sRGB, this is necessary to ensure that the colors are displayed correctly.
This behavior is by default true and can be disabled by setting toneMapped to false.
Disabling tone mapping will speed up rendering, but may result in less vibrant colors.

在 Remotion 4.0.117 之前，色调映射始终被禁用，并且 toneMapped 属性不可用。

🌐 Prior to Remotion 4.0.117, tone mapping was always disabled, and the toneMapped prop was not available.

audioStreamIndex?v4.0.340​

选择要使用的音频流。默认是 0。

🌐 Select the audio stream to use. The default is 0.

export const MyComposition = () => {
  return (
    <AbsoluteFill>
      <OffthreadVideo audioStreamIndex={1} src={'https://remotion.media/multiple-audio-streams.mov'} />
    </AbsoluteFill>
  );
};
note

这个属性仅在渲染期间有效。 浏览器在未启用实验性标志的情况下不支持选择音轨。

不要与音频通道混淆。一个视频可以有多个音频流，每个流可以有多个通道。 例如，多个音频流可以用于为视频添加多种语言。

🌐 Not to be confused with audio channels. A video can have multiple audio streams, each stream can have multiple channels.
Multiple audio streams can be used for example for adding multiple languages to a video.

音频流从零开始索引。

🌐 Audio streams are zero-indexed.

showInTimeline?v4.0.122​

如果设置为 false，在 Remotion Studio 的时间轴中将不会显示任何图层。默认值是 true。

🌐 If set to false, no layer will be shown in the timeline of the Remotion Studio. The default is true.

delayRenderTimeoutInMilliseconds?v4.0.150​

自定义此组件进行的 delayRender() 调用的 超时 设置。

🌐 Customize the timeout of the delayRender() call that this component makes.

delayRenderRetries?v4.0.178​

自定义此组件进行的 delayRender() 调用的 重试次数。

🌐 Customize the number of retries of the delayRender() call that this component makes.

onAutoPlayError?v4.0.187​

当视频由于自动播放限制而无法播放时调用的回调函数。
如果不传入回调，视频将被静音并重试一次。
如果你想自己处理错误（例如暂停播放器），这个属性很有用。
在此处了解更多关于自动播放限制的信息。

🌐 A callback function that gets called when the video fails to play due to autoplay restrictions.
If you don't pass a callback, the video will be muted and be retried once.
This prop is useful if you want to handle the error yourself, e.g. for pausing the Player.
Read more here about autoplay restrictions.

onVideoFrame?v4.0.190​

当从视频中提取一帧时调用的回调函数。 对视频处理非常有用。 回调函数会传入一个CanvasImageSource对象。 在预览期间，这是一个HTMLVideoElement对象，渲染期间，它是一个HTMLImageElement对象。

🌐 A callback function that gets called when a frame is extracted from the video.
Useful for video manipulation.
The callback is called with a CanvasImageSource object.
During preview, this is a HTMLVideoElement object, during rendering, it is an HTMLImageElement.

crossOrigin?v4.0.190​

对应 <video> 元素的 crossOrigin 属性。
可以是 "anonymous"、"use-credentials" 或 undefined 之一。
默认值：如果指定了 onVideoFrame，则为 "anonymous"；否则为 undefined。

🌐 Corresponds to the crossOrigin attribute of the <video> element.
One of "anonymous", "use-credentials" or undefined.
Default: "anonymous" if onVideoFrame is specified, undefined, otherwise.

useWebAudioApi?v4.0.306​

为 video 标签启用 Web Audio API。

🌐 Enable the Web Audio API for the video tag.

imageFormat v3.0.22​

在 v4.0.0 中移除

🌐 removed in v4.0.0

要么 jpeg 要么 png。默认 jpeg。 使用 png，可以显示透明视频（VP8、VP9、ProRes），但是速度大约慢 40%，VP8 视频的速度慢得多。

🌐 Either jpeg or png. Default jpeg.
With png, transparent videos (VP8, VP9, ProRes) can be displayed, however it is around 40% slower, with VP8 videos being much slower.

allowAmplificationDuringRender?v3.3.17​

自 v4.0.279 起已弃用：此属性旨在选择将音量设置为高于一的值，即使它仅在渲染期间应用。

🌐 Deprecated since v4.0.279: This prop intended to opt into setting the volume to a value higher than one, even though it would only apply during render.

这个选项不再有意义，因为现在可以将音量设置高于 1。为了防止合成放大，音量不要设置高于 1。

🌐 The option does not make sense anymore, because it is now possible to set the volume higher than 1.
To prevent synthetic amplification, set a volume not higher than 1.

其他属性​

🌐 Other props

支持属性 onError、className 和 style，它们会传递给底层的 HTML 元素。请记住，在渲染期间，这是一个 <img> 元素，而在预览期间，这是一个 <video> 元素。

🌐 The props onError, className and style are supported and get passed to the underlying HTML element. Remember that during render, this is a <img> element, and during Preview, this is a <video> element.

性能技巧​

🌐 Performance tips

只有在需要透明度时才将 transparent 设置为 true。它比非透明帧提取更慢。 如果你不在意颜色准确性，你也可以将 toneMapped 设置为 false，以节省颜色转换的时间。

🌐 Only set transparent to true if you need transparency. It is slower than non-transparent frame extraction.
If you don't care about color accuracy, you can set toneMapped to false as well to save time on color conversion.

循环离线程视频​

🌐 Looping a OffthreadVideo

与<Html5Video>不同，OffthreadVideo没有实现loop属性。 考虑使用另一个视频标签来循环播放。

🌐 Unlike <Html5Video>, OffthreadVideo does not implement the loop property.
Consider using another video tag for looping.

note

当视频结束时，默认情况下视频的最后一帧会保持可见。
这与 <Html5Video> 的行为一致。

你可以使用以下 <LoopableOffthreadVideo> 组件，它使用 Mediabunny 来确定循环视频的时长。

🌐 You can use the following <LoopableOffthreadVideo> component that uses Mediabunny to determine the duration for looping a video.

src/LoopableOffthreadVideo.tsx
import React, {useEffect, useState} from 'react';
import {cancelRender, continueRender, delayRender, Loop, OffthreadVideo, RemotionOffthreadVideoProps, useRemotionEnvironment, useVideoConfig, Html5Video} from 'remotion';
import {getMediaMetadata} from './get-media-metadata';

const LoopedOffthreadVideo: React.FC<RemotionOffthreadVideoProps> = (props) => {
  const [duration, setDuration] = useState<number | null>(null);
  const [handle] = useState(() => delayRender());
  const {fps} = useVideoConfig();

  useEffect(() => {
    getMediaMetadata(props.src)
      .then(({durationInSeconds}) => {
        setDuration(durationInSeconds);
        continueRender(handle);
      })
      .catch((err) => {
        cancelRender(err);
      });

    return () => {
      continueRender(handle);
    };
  }, [handle, props.src]);

  if (duration === null) {
    return null;
  }

  return (
    <Loop durationInFrames={Math.floor(duration * fps)}>
      <OffthreadVideo {...props} />
    </Loop>
  );
};

export const LoopableOffthreadVideo: React.FC<
  RemotionOffthreadVideoProps & {
    loop?: boolean;
  }
> = ({loop, ...props}) => {
  const env = useRemotionEnvironment();
  if (env.isRendering) {
    if (loop) {
      return <LoopedOffthreadVideo {...props} />;
    }

    return <OffthreadVideo {...props} />;
  }

  return <Html5Video loop={loop} {...props}></Html5Video>;
};

<OffthreadVideo>支持的编解码器​

🌐 Supported codecs by <OffthreadVideo>

以下编解码器可以被 <OffthreadVideo> 读取：

🌐 The following codecs can be read by <OffthreadVideo>:

  • H.264（“MP4”）
  • H.265（"HEVC"）
  • VP8 和 VP9（“WebM”）
  • AV1（来自 v4.0.6）
  • ProRes

兼容性​

🌐 Compatibility

BrowsersEnvironments
Chrome
Firefox
Safari

另请参阅​

🌐 See also

Last updated on