Skip to main content

renderMediaOnLambda()

Kicks off a render process on Remotion Lambda. The progress can be tracked using getRenderProgress().

Requires a function to already be deployed to execute the render.
A site or a Serve URL needs to be specified to determine what will be rendered.

Example​

tsx
import { renderMediaOnLambda } from "@remotion/lambda/client";
 
const { bucketName, renderId } = await renderMediaOnLambda({
  region: "us-east-1",
  functionName: "remotion-render-bds9aab",
  composition: "MyVideo",
  serveUrl:
    "https://remotionlambda-qg35eyp1s1.s3.eu-central-1.amazonaws.com/sites/bf2jrbfkw",
  codec: "h264",
});
tsx
import { renderMediaOnLambda } from "@remotion/lambda/client";
 
const { bucketName, renderId } = await renderMediaOnLambda({
  region: "us-east-1",
  functionName: "remotion-render-bds9aab",
  composition: "MyVideo",
  serveUrl:
    "https://remotionlambda-qg35eyp1s1.s3.eu-central-1.amazonaws.com/sites/bf2jrbfkw",
  codec: "h264",
});
note

Preferrably import this function from @remotion/lambda/client to avoid problems inside serverless functions.

Arguments​

An object with the following properties:

region​

In which region your Lambda function is deployed. It's highly recommended that your Remotion site is also in the same region.

privacy​

optional since v3.2.27

One of:

  • "public" (default): The rendered media is publicly accessible under the S3 URL.
  • "private": The rendered media is not publicly available, but signed links can be created using presignUrl().
  • "no-acl" (available from v.3.1.7): The ACL option is not being set at all, this option is useful if you are writing to another bucket that does not support ACL using outName.

functionName​

The name of the deployed Lambda function. Use deployFunction() to create a new function and getFunctions() to obtain currently deployed Lambdas.

framesPerLambda?​

optional

The video rendering process gets distributed across multiple Lambda functions. This setting controls how many frames are rendered per Lambda invocation. The lower the number you pass, the more Lambdas get spawned.

Default value: Dependant on video length
Minimum value: 4

note

The framesPerLambda parameter cannot result in more than 200 functions being spawned. See: Concurrency

frameRange?​

number | [number, number] - optional

Specify a single frame (passing a number) or a range of frames (passing a tuple [number, number]) to render a subset of a video. Example: [0, 9] to select the first 10 frames. By passing null (default) all frames of a composition get rendered. To render a still, use renderStillOnLambda().

serveUrl​

A URL pointing to a Remotion project. Use deploySite() to deploy a Remotion project.

composition​

The id of the composition you want to render.

inputProps​

optional since v3.2.27

Input Props to pass to the selected composition of your video..
Must be a JSON object.
From the root component the props can be read using getInputProps().
You may transform input props using calculateMetadata().

codec​

Which codec should be used to encode the video.

Video codecs h264, and vp8 are supported, prores is supported since v3.2.0. h265 support has been added in v4.0.32.

Audio codecs mp3, aac and wav are also supported.

The option h264-mkv has been renamed to just h264 since v3.3.34. Use h264 to get the same behavior.

See also renderMedia() -> codec.

audioCodec?​

optional "pcm-16" | "aac" | "mp3" | "opus", available from v3.3.41

Choose the encoding of your audio.

  • Each Lambda chunk might actually choose an uncompressed codec and convert it in the final encoding stage to prevent audio artifacts.
  • The default is dependent on the chosen codec.
  • Choose pcm-16 if you need uncompressed audio.
  • Not all video containers support all audio codecs.
  • This option takes precedence if the codec option also specifies an audio codec.

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

forceHeight?​

optional, available from v3.2.40

Overrides default composition height.

forceWidth?​

optional, available from v3.2.40

Overrides default composition width.

muted?​

optional

Disables audio output. See also renderMedia() -> muted.

imageFormat​

optional since v3.2.27

See renderMedia() -> imageFormat.

crf?​

optional

See renderMedia() -> crf.

envVariables?​

optional

See renderMedia() -> envVariables.

pixelFormat?​

optional

See renderMedia() -> pixelFormat.

proResProfile?​

optional

See renderMedia() -> proResProfile.

x264Preset?​

optional

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

jpegQuality​

See renderMedia() -> jpegQuality.

quality​

Renamed to jpegQuality in v4.0.0.

audioBitrate?​

optional

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?​

optional

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.

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.

maxRetries​

optional since v3.2.27, default 1

How often a chunk may be retried to render in case the render fails. If a rendering of a chunk is failed, the error will be reported in the getRenderProgress() object and retried up to as many times as you specify using this option.

note

A retry only gets executed if a the error is in the list of flaky errors.

scale?​

optional

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

outName?​

optional

The file name of the media output.

It can either be:

  • undefined - it will default to out plus the appropriate file extension, for example: renders/${renderId}/out.mp4.
  • A string - it will get saved to the same S3 bucket as your site under the key renders/{renderId}/{outName}. Make sure to include the file extension at the end of the string.
  • An object if you want to render to a different bucket or cloud provider - see here for detailed instructions.

timeoutInMilliseconds?​

optional

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

concurrencyPerLambda?​

optional, available from v3.0.30

By default, each Lambda function renders with concurrency 1 (one open browser tab). You may use the option to customize this value.

everyNthFrame?​

optional, available from v3.1

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?​

optional, available since v3.1

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.

downloadBehavior?​

optional, available since v3.1.5

How the output file should behave when accessed through the S3 output link in the browser.
Either:

  • {"type": "play-in-browser"} - the default. The video will play in the browser.
  • {"type": "download", fileName: null} or {"type": "download", fileName: "download.mp4"} - a Content-Disposition header will be added which makes the browser download the file. You can optionally override the filename.

chromiumOptions?​

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

disableWebSecurity​

boolean - default false

This will most notably disable CORS among other security features.

ignoreCertificateErrors​

boolean - default false

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

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"

overwrite?​

available from v3.2.25

If a custom out name is specified and a file already exists at this key in the S3 bucket, decide whether that file will be deleted before the render begins. Default false.

An existing file at the output S3 key will conflict with the render and must be deleted beforehand. If this setting is false and a conflict occurs, an error will be thrown.

rendererFunctionName?​

optional, available from v3.3.38

If specified, this function will be used for rendering the individual chunks. This is useful if you want to use a function with higher or lower power for rendering the chunks than the main orchestration function.

If you want to use this option, the function must be in the same region, the same account and have the same version as the main function.

webhook?​

optional, available from v3.2.30

If specified, Remotion will send a POST request to the provided endpoint to notify your application when the Lambda rendering process finishes, errors out or times out.

tsx
import { RenderMediaOnLambdaInput } from "@remotion/lambda";
 
const webhook: RenderMediaOnLambdaInput["webhook"] = {
  url: "https://mapsnap.app/api/webhook",
  secret: process.env.WEBHOOK_SECRET as string,
  // Optionally pass up to 1024 bytes of custom data
  customData: {
    id: 42,
  },
};
tsx
import { RenderMediaOnLambdaInput } from "@remotion/lambda";
 
const webhook: RenderMediaOnLambdaInput["webhook"] = {
  url: "https://mapsnap.app/api/webhook",
  secret: process.env.WEBHOOK_SECRET as string,
  // Optionally pass up to 1024 bytes of custom data
  customData: {
    id: 42,
  },
};

If you don't want to set up validation, you can set secret to null:

tsx
import { RenderMediaOnLambdaInput } from "@remotion/lambda";
 
const webhook: RenderMediaOnLambdaInput["webhook"] = {
  url: "https://mapsnap.app/api/webhook",
  secret: null,
};
tsx
import { RenderMediaOnLambdaInput } from "@remotion/lambda";
 
const webhook: RenderMediaOnLambdaInput["webhook"] = {
  url: "https://mapsnap.app/api/webhook",
  secret: null,
};

See here for detailed instructions on how to set up your webhook.

forceBucketName?​

optional, available from v3.3.42

Specify a specific bucket name to be used. This is not recommended, instead let Remotion discover the right bucket automatically.

logLevel?​

One of verbose, info, warn, error.
Determines how much is being logged to the console.
verbose will also log console.log's from the browser.
Default info.

If the logLevel is set to verbose, the Lambda function will not clean up artifacts, to aid debugging. Do not use it unless you are debugging a problem.

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

colorSpace?v4.0.28​

Color space to use for the video. Acceptable values: "default"(default since 5.0), "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.

deleteAfter?v4.0.32​

Automatically delete the render after a certain period. Accepted values are 1-day, 3-days, 7-days and 30-days.
For this to work, your bucket needs to have lifecycles enabled.

preferLossless?v4.0.123​

Uses a lossless audio codec, if one is available for the codec. If you setaudioCodec, it takes priority over preferLossless.

dumpBrowserLogs?​

optional - default false, deprecated in v4.0

Deprecated in favor of logLevel.

Return value​

Returns a promise resolving to an object containing four properties. Of these, renderId, bucketName are useful for passing to getRenderProgress().

renderId​

A unique alphanumeric identifier for this render. Useful for obtaining status and finding the relevant files in the S3 bucket.

bucketName​

The S3 bucket name in which all files are being saved.

cloudWatchLogsv3.2.10​

A link to CloudWatch (if you haven't disabled it) that you can visit to see the logs for the render.

lambdaInsightsUrlv4.0.61​

A link to the Lambda Insights, if you enabled it.

folderInS3Consolev3.2.43​

A link to the folder in the AWS console where each chunk and render is located.

See also​