packages/docs/docs/4-0-migration.mdx
When upgrading from Remotion 3 to Remotion 4, note the following changes and apply them to your project.
See the changelog to find the latest version.
Upgrade remotion and all packages starting with @remotion to the latest version, e.g. 4.0.0:
- "remotion": "^3.3.43"
- "@remotion/bundler": "^3.3.43"
- "@remotion/eslint-config": "^3.3.43"
- "@remotion/eslint-plugin": "^3.3.43"
- "@remotion/cli": "^3.3.43"
- "@remotion/renderer": "^3.3.43"
+ "remotion": "4.0.0"
+ "@remotion/bundler": "4.0.0"
+ "@remotion/eslint-config": "4.0.0"
+ "@remotion/eslint-plugin": "4.0.0"
+ "@remotion/cli": "4.0.0"
+ "@remotion/renderer": "4.0.0"
Run npm i , yarn or pnpm i respectively afterwards.
The minimum Node version is now 16.0.0.
Only the following platforms are supported: Windows (x64 only), macOS, Linux.
Linux distros with glibc need to have at least version 2.35. See here for more information.
The CLI configuration file has been moved out from the core Remotion package to @remotion/cli/config. Update your imports like this:
- import {Config} from 'remotion';
+ import {Config} from '@remotion/cli/config';
The options have been flattened. For example, instead of Config.Bundling.overrideWebpackConfig, you now use Config.overrideWebpackConfig.
- Config.Bundling.overrideWebpackConfig()
+ Config.overrideWebpackConfig()
- Config.Output.setOverwriteOutput(true);
+ Config.setOverwriteOutput(true);
Apply this to all configuration calls.
ImageFormatPreviously, the imageFormat option would be used for both stills and videos. While for stills, PNG is often preferrable, for videos it is overall faster to use JPEG as a default. In Remotion 4.0, the image formats are being separated so you can set defaults for videos and stills separately.
Config.setImageFormat got replaced by Config.setVideoImageFormat() and Config.setStillImageFormat().- Config.setImageFormat('jpeg');
+ Config.setVideoImageFormat('jpeg');
--image-format for all commands.imageFormat.ImageFormat has been separated into StillImageFormat and VideoImageFormat.StillImageFormat now also supports webp and pdf!For getCompositions(), renderMedia(), renderStill(), getCompositionsOnLambda(), renderMediaOnLambda() and renderStillOnLambda():
verbose and dumpBrowserLogs have been deprecated in favor of "logLevel": "verbose". This makes the options equivalent to the CLI options.
architectureWhen deploying a Lambda, you were previously able to choose between the arm64 and x86_64 architecture.
From v4.0 on, only arm64 is supported. It should be faster, cheaper and not have any different behavior than x86_64.
How to upgrade:
architecture option from estimatePrice() and deployFunction().The option to use the "Rich timeline" has been removed due to performance problems.
The timeline is now always in simple mode, but supports more timeline layers at once.
Previously, the aac audio codec was the default for ProRes exports. The default is now pcm_s16le which stands for uncompressed 16-bit low-endian PCM audio.
This change was made since users export ProRes mainly for getting high-quality footage to be further used in video editing programs.
quality option to jpegQualityTo clarify the meaning of this option, it is now universally called "JPEG Quality". Adjust the following options:
npx remotion render: Use --jpeg-quality insted of --qualitynpx remotion still: Use --jpeg-quality insted of --qualitynpx remotion benchmark: Use --jpeg-quality insted of --qualitynpx remotion lambda render: Use --jpeg-quality insted of --qualitynpx remotion lambda still: Use --jpeg-quality insted of --qualityrenderFrames(): Use jpegQuality instead of qualityrenderMedia(): Use jpegQuality instead of qualityrenderStill(): Use jpegQuality instead of qualityrenderMediaOnLambda(): Use jpegQuality instead of qualityrenderStillOnLambda(): Use jpegQuality instead of qualityffmpegExecutable option removedFFmpeg is now baked into the @remotion/renderer package. Therefore, the ffmpegExecutable and ffprobeExecutable options have been removed.
Furthermore, the npx remotion install ffmpeg and npx remotion install ffprobe commands no longer exist.
How to upgrade:
ffmpegExecutable option from renderMedia(), renderStill(), getCompositions(), renderFrames() and stitchFramesToVideo() calls.ffprobeExecutable option from renderMedia(), renderStill(), getCompositions(), renderFrames() and stitchFramesToVideo() calls.ensureFfmpeg().ensureFfprobe().--ffmpeg-executable flag from npx remotion render, npx remotion still and npx remotion benchmark--ffprobe-executable flag from npx remotion render, npx remotion still and npx remotion benchmarknpx remotion install command anymorenpx remotion ffmpeg and npx remotion ffprobeSince FFmpeg and FFprobe no longer have to be installed, the ffmpeg and ffprobe commands might also not be in your environment anymore. In order to still be able to use some of FFmpeg's handy commands, we introduced npx remotion ffmpeg and npx remotion ffprobe.
Note that in order to keep the binary size small, those FFmpeg binaries only understand the codecs that Remotion itself supports: H.264, H.265, VP8, VP9 and ProRes.
A binary from the 6.0 release line of FFmpeg is used.
onSlowestFrames APIIn V3, onSlowestFrames has been a callback function that you could pass to renderMedia().
In V4, this data has been moved to the return value.
The @remotion/renderer ImageFormat Type got replaced by the more specific Types VideoImageFormat and StillImageFormat.
Config.setOutputFormat() was deprecated in v1.4 and has now been removed. Use setImageSequence(), setVideoImageFormat() and setCodec() in combination instead.
downloadVideo() alias has been removed, use downloadMedia() with the same API instead.
<MotionBlur> has been removed. Use <Trail> instead.
getParts() has been removed. Use getSubpaths() instead:
import {getLength, getPointAtLength, getSubpaths, getTangentAtLength} from '@remotion/paths';
const path = 'M 0 0 L 100 100';
const parts = getSubpaths(path[0]);
const length = getLength(parts[0]);
const start = getPointAtLength(parts[0], 0);
const end = getPointAtLength(parts[0], length);
const tangent = getTangentAtLength(parts[0], length / 2);
webpackBundle has been removed from renderFrames() and renderMedia() - rename it to serveUrl insteadparallelism has been removed from renderFrames() and renderMedia() - rename it to concurrency instead.config has been removed from renderFrames() - rename it to composition instead.onBucketEnsured option has been removedThe onBucketEnsured() option of getOrCreateBucket() has been removed because creating the bucket is the only operation of getOrCreateBucket(). Therefore, you can just await the function itself.
imageFormat removed from <OffthreadVideo>Until now, you could optionally pass the imageFormat prop into <OffthreadVideo>. This option was introduced in order to make transparent videos possible.
Now, you can instead use the optional transparent prop.
Due to this this change, the OffthreadVideoImageFormat type is no longer neccessary and has therefore been removed.
OffthreadVideoImageFormat removedBefore, `` would only log to the console if an image cannot be loaded and inevitably lead to a timeout if the error is not handled.
If this happens now and the error is not handled, the render will be aborted and the error reported.
crf is not allowed for GIFs anymorePreviously you were able to set a value for crf when rendering a GIF. This was a mistake and GIF does not support them.
staticFile() URI-unsafe characters handlingPreviously, staticFile() did not handle URI-unsafe characters contained in the provided path:
staticFile('my-image#portrait.png'); //output: "my-image#portrait.png"
This could lead to problems, when unsafe characters such as #, ? and & were part of the filename.
Now, staticFile() encodes the filename using encodeURIComponent:
staticFile('my-image#portrait.png'); // "my-image%23portrait.png"
WebpackOverrideFn movedThe WebpackOverrideFn type useful for overriding the Webpack config in the config file and in bundle() has moved from the remotion to the @remotion/bundler package.
How to upgrade:
If you encoded the path by yourself until now, don't do so anymore to avoid double encoding.
react-native no longer aliases to react-native-webRemotion no longer aliases react-native automatically to react-native-web.
If you are using react-native-web, override the Webpack config like this to restore the previous behavior:
import {Config} from '@remotion/cli/config';
Config.overrideWebpackConfig((config) => {
return {
...config,
resolve: {
...config.resolve,
alias: {
...config.resolve?.alias,
'react-native$': 'react-native-web',
},
},
};
});
The @remotion/skia package does not require react-native or react-native-web anymore.
TComposition type now includes a Zod schemaThe TComposition type now has two generic arguments:
export type TComposition<Schema extends AnyZodObject, Props> = {};
If you need a type for a generic composition, you can use the new AnyComposition type:
import {AnyComposition} from 'remotion';
const composition: AnyComposition = {
width: 1920,
height: 1080,
// ...
};
getCanExtractFramesFast() function has been removedThe getCanExtractFramesFast() function has been removed, since frames can always be extracted fast now using <OffthreadVideo>.
How to upgrade:
You can now remove your re-encoding logic!
Since the input props are passed to a React component, they must not explicitly be objects ({}). You can still use other data structures such as arrays, but they must be wrapped in an object.
interface for propsThe following code now gives a type error:
interface MyProps {
title: string;
}
const Hi = (props: MyProps) => {
return <div>{props.title}</div>;
};
<Still component={Hi} id="interface-props" defaultProps={{title: 'hi'}} height={1080} width={1080} />;
This is because props must now be an object and satisfy the shape Record<string, unknown>.
interface's do not satisfy this shape, so you must use a type instead:
type MyProps = {
title: string;
};
See also: Input props must be an object
defaultProps is required if the component has propsIf you register a composition with a component that requires some props, you now are required to provide a defaultProps object.
inputProps option of renderMedia() now works differentlyrenderMedia() accepts a VideoConfig object for the composition option, which now has a props field:
import {renderMedia} from '@remotion/renderer';
const options = {
codec: 'h264',
serveUrl: 'https://example.com',
} as const;
const composition = {
width: 1920,
height: 1080,
fps: 30,
durationInFrames: 30 * 5,
id: 'comp-name',
defaultProps: {},
defaultCodec: null,
defaultOutName: null,
defaultVideoImageFormat: null,
defaultPixelFormat: null,
defaultProResProfile: null,
defaultSampleRate: null,
} as const;
// ---cut---
await renderMedia({
...options,
composition: {
...composition,
props: {
title: 'Hello world',
},
},
inputProps: {
title: 'Hi there',
},
});
The composition.props are now the effective props that get passed to the component, while inputProps are what can be retrieved using getInputProps().
Previously, inputProps would override the default props and be passed to the component.
The recommended way is to get the composition object using selectComposition() or getCompositions(). However, for the purpose of starting renders faster, the composition object may be constructed manually.
defaultProps of a <Composition> is now mandatory if the component accepts props<Composition> now accepts a schema<Composition> now accepts a calculateMetadata propOffthreadVideoImageFormat type has been removed.imageFormat has been removed from <OffthreadVideo>transparent has been added to <OffthreadVideo>.<Html5Audio> tag cannot be loaded, it will cancel the render.TComposition type now requires a Zod schema as a generic.WebpackOverrideFn moved from remotion to @remotion/bundlerstaticFile() now supports URI-unsafe characters by defaultsrc is required for an `` tag--bundle-cache=false.react-native no longer aliases to react-native-web5.83.1npx remotion preview is deprecated for npx remotion studionpx remotion ffmpeg commandnpx remotion ffprobe command@remotion/cli/configConfig.*.setOption() syntax has been removed.Config.setOutputFormat() has now been removed.○) or newly created (+)Cmd/Ctrl+BDate objects now work properly in defaultPropseslint-plugin-react has been updated to 7.32.2eslint-plugin-react-hooks has been updated to 4.6.0downloadVideo() alias has been removed.estimatePrice() does not accept architecture anymore.<MotionBlur> has been removedgetParts() has been removedselectComposition() APIgetCanExtractFramesFast() has been removedonSlowestFrames has been removedrenderMedia() now returns an object instead of a Buffer.ImageFormat type has been removed in favor of StillImageFormat and VideoImageFormatquality is now jpegQualityensureFfmpeg() and ensureFfprobe()<OffthreadVideo> now uses a Rust-based frame extractorconsole.log statements in your React app now get printed in a tidy format, contain location, use colors and object previews are printed out.8.42.05.59.90.18.6pnpm to 8.5.1ffmpeg anymore