Rendley SDK

Appearance

Settings ​

Global configuration for the SDK, encoder, decoder, render loop, media processing, subtitles, and canvas behavior. Access through:

typescript
const settings = Engine.getInstance().getSettings();

Every setting has a paired getter and setter. This page groups them by domain and lists defaults inline. For deep-dive explanations of settings tied to a specific feature (filmstrip, audio samples, chunked output), follow the link at the end of each section to the topical guide where they're used.

Encoder ​

Controls the codec, quality, and acceleration used when exporting the final video.

SettingDefaultDescription
setEncoderCodec(codec)"h264"Output codec: "h264", "vp8", or "vp9".
setEncoderBitrate(bitsPerSecond)Target bitrate in bits per second.
setEncoderCrf(crf)Constant Rate Factor (0 = lossless, higher = smaller).
setEncoderKeyframeInterval(frames)How often keyframes are inserted (shorter = easier to seek, bigger file).
setEncoderUseWebCodecs(bool)trueUse WebCodecs for hardware acceleration. Disable for the WASM fallback.
setEncoderUseAlpha(bool)falseInclude alpha channel in the output. Requires vp8 or vp9 and WASM rendering.
setEncoderPreferredAcceleration(preference)"prefer-hardware" or "prefer-software".

Alpha Channel Output ​

typescript
settings.setEncoderUseWebCodecs(false);
settings.setEncoderUseAlpha(true);
settings.setEncoderCodec("vp8");

Decoder ​

Controls how video files are decoded during playback and export.

SettingDefaultDescription
setDecoderPreferredAcceleration(preference)"prefer-hardware" or "prefer-software".
setDecoderUseSeparateWorker(bool)falseDecode videos in individual workers. Useful when compositions have many videos on multiple layers. Not always faster, benchmark first.
setDecoderUseSubImage(bool)falseFill the old texture instead of creating a new one per frame. Benchmark for your use case.

Render Loop ​

Controls the preview and export render loop.

SettingDefaultDescription
setRenderShowPreview(bool)trueShow frames on the canvas while exporting.
setRenderAudioUseWorker(bool)trueMix audio in a Web Worker instead of the main thread.
setRenderVideoUseDirectFrames(bool)trueUse a direct frame-grab path. Faster on most devices. Default value should be the prefered value, unless settings it to false might fix some issues.
setRenderMaxQueueSize(size)Max queue of frames to add to the encoder before throttling.
setRenderThrottleFactor(factor)Back-pressure throttle factor (A wait multiplier based on the number of unprocessed frames.
setRenderCancelFailTimeout(ms)Failsafe for Engine.cancelExport.
setRenderUseChunkedOutput(bool)falseSplit output into chunks for files >2GB. See chunked output.
setRenderChunkedOutputMaxSize(bytes)Max size of each chunk when chunked output is on.

Clip Audio ​

Controls audio sample handling and fade behavior.

SettingDefaultDescription
setClipAudioStoreSamples(bool)falseCache normalized samples per media entry. Required for waveforms.
setClipAudioSampleRate(hz)Sample rate at which audio is extracted (lower = smaller memory footprint).
setClipAudioSampleForceMono(bool)Downmix stereo to mono during extraction.
setClipAudioMonoMixType(type)How channels combine on mono mix: "average", "max", or "min".
setClipAudioMonoChannelsWeight(weights)[1, 1]Per-channel weight array applied before the mono mix.
setClipAudioSeekThreshold(seconds)Precision for audio seeking. Smaller = more precise, more expensive.

See Filmstrip & Waveforms for the full sample extraction workflow.

Clip Video ​

Controls video decoding, filmstrip thumbnails, and dynamic loading.

SettingDefaultDescription
setClipVideoSeekThreshold(seconds)Precision for video seeking.
setClipVideoStoreSamples(bool)falseCache audio samples extracted from videos.
setClipVideoStoreFilmstrip(bool)falseGenerate timeline thumbnails for each video.
setClipVideoFilmstripInterval(seconds)Thumbnail sampling interval.
setClipVideoFilmstripMaxFrames(count)Maximum number of thumbnails per video.
setClipVideoFilmstripMaxWidth(px)Thumbnail max width.
setClipVideoFilmstripMaxHeight(px)Thumbnail max height.
setClipVideoFilmstripMaxWorkers(count)Parallel thumbnail workers.
setClipVideoFilmstripKeyframesOnly(bool)Only sample on keyframes (faster, lower precision).
setClipVideoDynamicLoad(bool)falseLazy-load video decoders. Enable only for 128+ videos in the timeline.
setClipVideoDynamicLoadTime(seconds)Look-ahead window for dynamic loading.

See Filmstrip & Waveforms for the full filmstrip setup.

View ​

Controls how the canvas responds to resolution changes.

SettingDefaultDescription
setViewAutoLayoutOnResize(mode)NONEReposition/resize existing clips when the display resolution changes. See AutoLayoutMode.

Subtitles ​

SettingDefaultDescription
setSubtitlesScaleOnResize(bool)falseAuto-scale subtitles when the display resolution changes.
setSubtitlesAutoWrapOnResize(bool)falseAuto-rewrap subtitles when the display resolution changes.

Media ​

SettingDefaultDescription
setMediaHashAlgorithm(algorithm)SHA_256Algorithm used for content hashing. Use XXHash64 / XXHash128 for files larger than a few hundred MB. See HashAlgorithmEnum.
setM3u8MaxResolution(width, height)Cap the resolution picked from HLS/m3u8 sources.
setUseInternalTranscoder(bool)trueUse the SDK's built-in transcoder. Set to false when providing a custom ITranscodeProvider.

Settings and Projects ​

Settings are saved with the project: Engine.serialize() writes them into the payload, and loading a project (Engine.deserialize() or the project init option) applies them again. This lets one side hand its choices to another through the project itself. For example, an editor sets the codec, bitrate and chunked output, and a generic render server that loads the project exports with exactly those values.

The order of precedence on a project load, lowest to highest:

  1. The SDK defaults.
  2. The settings stored in the project.
  3. The host-only settings the engine is currently running with (see below).
  4. forcedSettings.

Forced Settings ​

Settings passed at init time take precedence over anything stored in a project, on the initial load and on every later Engine.deserialize():

typescript
await Engine.getInstance().init({
  forcedSettings: {
    renderVideoUseDirectFrames: false,
    encoderBitrate: 8_000_000,
  },
  // ...license, display
});

Use them for everything your deployment depends on, regardless of what a saved project requested: software encoding on a specific server, no filmstrips or waveforms on a headless renderer, your own timeouts and worker counts.

Host-Only Settings ​

A few settings choose an implementation based on what the host and its browser support, so they are never saved into projects and a loaded project never changes them:

useMediaBunnyAsVideoPlayer, mediaBunnySeekForwardScanMax, mediaBunnyCatchupThreshold, mediaBunnyCatchupCooldown, mediaBunnyAudioScheduleAhead, mediaBunnyAudioResyncThreshold, mediaBunnyAudioInWorker, clipVideoFilmstripUseMediaBunny

Set them through their setters or through forcedSettings; the value stays in place across project loads.

Ignoring Project Settings ​

Because a project can configure the engine that loads it, a payload you do not control can change how your host behaves: timeouts, worker counts, encoder limits, the render path. When you load projects from a source you do not trust to do that, typically a server rendering projects submitted by third parties, turn the project's settings off:

typescript
await Engine.getInstance().init({
  ignoreProjectSettings: true,
  forcedSettings: {
    // the configuration of this host
  },
  // ...license, display
});

With ignoreProjectSettings the settings stored in a loaded project are skipped entirely: the engine keeps the settings it runs with (defaults and setters) and applies forcedSettings on top. It covers the project init option and every later Engine.deserialize(). It is off by default, so projects keep carrying their settings unless you opt out.

See Render on Server for the rest of the checklist.

See Also ​