prefetch()

可在 v3.2.23 中使用

🌐 Available in v3.2.23

通过调用 prefetch()，一个资源将被获取并保存在内存中，以便在你想在 <Player> 中播放它时可以立即使用。

🌐 By calling prefetch(), an asset will be fetched and kept in memory so it is ready when you want to play it in a <Player>.

如果你将原始 URL 传入 <Html5Audio>、<Audio>、<Video>、<Html5Video>、<OffthreadVideo> 或 <Img> 标签，并且资源已完全获取，那么这些组件将改为使用 Blob URL。

🌐 If you pass the original URL into either an <Html5Audio>, <Audio>, <Video>, <Html5Video>, <OffthreadVideo> or <Img> tag and the asset is fully fetched, those components will use Blob URL instead.

note

远程资源需要支持 CORS。

更多信息

• Remotion 的来源通常是 http://localhost:3000，但如果在 Lambda 上渲染或端口被占用，可能会有所不同。

• 你可以 在渲染期间禁用 CORS 。

import {prefetch} from 'remotion';

const {free, waitUntilDone} = prefetch('https://example.com/video.mp4', {
  method: 'blob-url',
});

waitUntilDone().then(() => {
  console.log('Video has finished loading');
});

// Call free() if you want to un-prefetch and free up the memory:
free();

只有在你使用 <Player /> 组件并且希望显示媒体资源且希望确保它在出现之前完全加载时，此 API 才有用。

🌐 This API is only useful if you are using the <Player /> component and you want to display a media asset and want to be sure it is fully loaded before it appears.

prefetch() 的一个替代方案是 @remotion/preload API。请参阅 @remotion/preload vs prefetch() 来决定哪一个更适合你的使用场景。

🌐 An alternative to prefetch() are the @remotion/preload APIs. See @remotion/preload vs prefetch() to decide which one is better for your usecase.

应用编程接口

🌐 API

src

该函数接收一个 src，它可以是远程 URL、导入的资源，或使用 staticFile() 加载的资源（参见：导入资源）。

🌐 The function takes a src, which can be a remote URL, an imported asset or an asset loaded using staticFile() (see: Importing assets).

options

method?v3.2.35

之前默认设置为 blob-url

🌐 previously defaulted to blob-url

blob-url 或 base64。

🌐 Either blob-url or base64.

• 使用 blob-url，该资源通过 URL.createObjectURL() 被转换为 Blob URL
• 使用 base64，资源被转换为 Base 64 URL。

请阅读以下内容，了解哪种选项适合你。

🌐 Read below for which option is suitable for you.

contentType?v4.0.40

为 blob 设置内容类型。默认情况下，将采用 HTTP 响应中的内容类型。我们建议为媒体设置合适的内容类型，例如 video/mp4，仅当 HTTP 资源默认不包含正确的内容类型时。

🌐 Set a content type for the blob. By default, the content type from the HTTP response is taken. We recommend setting an appropriate content type for the media, e.g video/mp4 only if the HTTP resource does not contain the right one by default.

credentials?v4.0.229

在调用 fetch() 时为 credentials 设置一个值。

🌐 Set a value for credentials when calling fetch().

onProgress?v4.0.85

进度事件的回调。

🌐 Callback for progress events.

import {prefetch} from 'remotion';
import type {PrefetchOnProgress} from 'remotion';

const onProgress: PrefetchOnProgress = (progress) => {
  if (progress.totalBytes === null) {
    // HTTP response has no "Content-Length" header,
    // therefore no relative progress can be calculated.
    console.log('Loaded bytes:', progress.loadedBytes);
    return;
  }

  console.log('Loading progress:', Math.round((progress.loadedBytes / progress.totalBytes) * 100) + '%');
};

prefetch('https://example.com/video.mp4', {
  onProgress,
});

logLevel?v4.0.250

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

Default info.

返回值

🌐 Return value

一旦被调用，预取就会开始，并返回一个具有两个属性的对象：

🌐 Once called, prefetching starts and an object with two properties are returned:

free()

调用此函数将中止正在进行的预取操作并释放内存。使用该资源的组件可能会重新请求该资源。

🌐 Calling this function will abort the prefetching is still in progress and free up the memory. Components using the asset might re-request the asset.

waitUntilDone()

调用此方法将返回一个 Promise<string>，当资源下载完成并可以使用时，它会被解析。

🌐 Calling this will return a Promise<string> that resolves once asset has finished downloading and is ready to be used.

正在返回的 string 要么是:

🌐 The string that is being returned is either:

• 分别是 blob: URL 或 data: Base 64 数据
• 如果在渲染环境中，你传入的同一个 src。

你不需要在 <Video>、<Audio>、<Html5Audio>、<Html5Video>、<OffthreadVideo> 或 <Img> 中使用该 URL，它们会自动使用它。

🌐 You don't need to use this URL in <Video>, <Audio>, <Html5Audio>, <Html5Video>, <OffthreadVideo> or <Img>, which will automatically use it.

如果你需要某个地方的 URL（比如用于 mask-image），你可以从 waitUntilDone() 获取它。

🌐 If you neeed the URL somewhere (like for mask-image), you can grab it from waitUntilDone().

blob-url 还是 base64？

🌐 blob-url or base64?

将资源转成 blob URL 通常更快且更高效。
在 Safari 中，即使这是本地 URL，Safari 也可能不会立即播放音频，并且在缓冲音频时可能会有轻微延迟。

🌐 Turning the asset into a blob URL is much faster and efficient in general.
In Safari, even though it is a local URL, Safari may not be instantly playing the audio and have slight delays buffering audio.

如果你注意到即使 <Player> 请求一个 blob: URL，你的音频文件播放时仍然有停顿，请在 Safari 中使用 base64。

🌐 Use base64 in Safari if you notice that your audio file plays with hickups even though the <Player> requests a blob: URL.

设置正确的内容类型

🌐 Setting the right content type

从互联网加载的文件应使用适当的内容类型提供，例如，MP4 文件应使用 video/mp4。当文件被加载到 blob URL 中时，文件扩展名会被移除，浏览器会丢失关于内容类型的信息。

🌐 Files loaded from the internet should be served with a proper content type, e.g. video/mp4 for an MP4 file. When the file gets loaded into a blob URL, the file extension gets removed and the browser loses the information about the content type.

这可能导致视频文件在浏览器中无法正确播放。如果你无法影响服务器，你也可以使用 contentType 选项手动设置内容类型。

🌐 This can lead to the video file not playing correctly in the browser. If you cannot influence the server, you can also set the content type manually using the contentType option.

此问题可能特别在 Safari 中出现。我们建议在编码完成后在 Safari 中测试你的实现。

🌐 This issue may arise in Safari specifically. We recommend testing your implementation in Safari after you coded it.

兼容性

🌐 Compatibility

Browsers			Servers			Environments
Chrome	Firefox	Safari	Node.js	Bun	Serverless Functions	Client-side rendering	Server-side rendering	Player	Studio
			No-op	No-op	No-op	No-op	No-op

另请参阅

🌐 See also

• @remotion/preload
• @remotion/preload 对 prefetch()
• 此函数的源代码