Skip to content

🎥 Make videos programmatically with React

@remotion/effects: Add LUT effect

Jonny Burger2f5dd17ae0cc
diff --git a/packages/docs/components/effects-demos/registry.ts b/packages/docs/components/effects-demos/registry.ts
index 1d70036827..fc525bb864 100644
--- a/packages/docs/components/effects-demos/registry.ts
+++ b/packages/docs/components/effects-demos/registry.ts
@@ -33,6 +33,7 @@ import {linearProgressiveBlur} from '@remotion/effects/linear-progressive-blur';
import {linearProgressivePixelate} from '@remotion/effects/linear-progressive-pixelate';
import {lines} from '@remotion/effects/lines';
import {liquidContours} from '@remotion/effects/liquid-contours';
+import {lut} from '@remotion/effects/lut';
import {mirror} from '@remotion/effects/mirror';
import {noise} from '@remotion/effects/noise';
import {noiseDisplacement} from '@remotion/effects/noise-displacement';
@@ -108,6 +109,10 @@ import {EffectsLinearProgressiveBlurPreview} from '../effects/effects-linear-pro
import {EffectsLinearProgressivePixelatePreview} from '../effects/effects-linear-progressive-pixelate-preview';
import {EffectsLinesPreview} from '../effects/effects-lines-preview';
import {EffectsLiquidContoursPreview} from '../effects/effects-liquid-contours-preview';
+import {
+ EffectsLutPreview,
+ LUT_PREVIEW_CONTENT,
+} from '../effects/effects-lut-preview';
import {EffectsMirrorPreview} from '../effects/effects-mirror-preview';
import {
EffectsNoiseDisplacementPreview,
@@ -367,6 +372,17 @@ export const effectsDemos: EffectsDemoType[] = [
comp: EffectsLevelsPreview,
schema: levels().definition.schema,
},
+ {
+ ...defaults,
+ id: 'effects-lut',
+ effectName: 'lut',
+ effectImportPath: '@remotion/effects/lut',
+ comp: EffectsLutPreview,
+ schema: lut({content: LUT_PREVIEW_CONTENT}).definition.schema,
+ initialValues: {
+ content: LUT_PREVIEW_CONTENT,
+ },
+ },
{
...defaults,
id: 'effects-saturation',
diff --git a/packages/docs/components/effects/effects-lut-preview.tsx b/packages/docs/components/effects/effects-lut-preview.tsx
new file mode 100644
index 0000000000..f254be5672
--- /dev/null
+++ b/packages/docs/components/effects/effects-lut-preview.tsx
@@ -0,0 +1,30 @@
+import {lut} from '@remotion/effects/lut';
+import React from 'react';
+import {CanvasImage} from 'remotion';
+import {EFFECTS_PREVIEW_IMAGE_SRC} from './effects-preview-image';
+
+export const LUT_PREVIEW_CONTENT = `TITLE "Teal and orange"
+LUT_3D_SIZE 2
+
+0.02 0.05 0.08
+0.95 0.12 0.06
+0.02 0.8 0.4
+1 0.9 0.18
+0.08 0.18 0.9
+0.95 0.2 0.75
+0.15 0.88 0.92
+1 0.92 0.78`;
+
+export const EffectsLutPreview: React.FC<{
+ readonly content: string;
+}> = ({content}) => {
+ return (
+ <CanvasImage
+ src={EFFECTS_PREVIEW_IMAGE_SRC}
+ width={1280}
+ height={720}
+ fit="cover"
+ effects={[lut({content})]}
+ />
+ );
+};
diff --git a/packages/docs/docs/effects/lut.mdx b/packages/docs/docs/effects/lut.mdx
new file mode 100644
index 0000000000..09176826c8
--- /dev/null
+++ b/packages/docs/docs/effects/lut.mdx
@@ -0,0 +1,79 @@
+---
+image: /generated/articles-docs-effects-lut.png
+slug: /effects/lut
+title: lut()
+sidebar_label: lut()
+crumb: '@remotion/effects'
+---
+
+# lut()<AvailableFrom v="4.0.526" />
+
+_Part of the [`@remotion/effects`](/docs/effects/api) package._
+
+Applies an inline 3D color lookup table in the `.cube` format.
+
+## Preview
+
+<EffectsDemo type="effects-lut" />
+
+## Example
+
+```tsx twoslash title="MyComp.tsx"
+import {lut} from '@remotion/effects/lut';
+import {Video} from '@remotion/media';
+
+const content = `
+TITLE "Teal and orange"
+LUT_3D_SIZE 2
+
+0.02 0.05 0.08
+0.95 0.12 0.06
+0.02 0.8 0.4
+1 0.9 0.18
+0.08 0.18 0.9
+0.95 0.2 0.75
+0.15 0.88 0.92
+1 0.92 0.78
+`;
+
+export const MyComp: React.FC = () => {
+ return (
+ <Video
+ src="https://remotion.media/video.mp4"
+ effects={[lut({content})]}
+ />
+ );
+};
+```
+
+## Supported Cube format
+
+`lut()` supports 3D `.cube` files with:
+
+- `LUT_3D_SIZE`, with a size from `2` to `256`
+- `TITLE`
+- `DOMAIN_MIN` and `DOMAIN_MAX`
+- Empty lines and `#` comments
+
+The content must contain the cube of `LUT_3D_SIZE` color rows. 1D LUTs are not supported.
+
+## API
+
+### `content`
+
+The complete `.cube` file as a string. Inline the content in your source code or import it as text using your bundler.
+
+### `disabled?`
+
+When `true`, the effect is skipped. Defaults to `false`.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering serverSideRendering player studio hideServers />
+
+## See also
+
+- [`@remotion/effects`](/docs/effects/api)
+- [`colorCorrection()`](/docs/effects/color-correction)
+- [`levels()`](/docs/effects/levels)
+- [Source code for this effect](https://github.com/remotion-dev/remotion/blob/main/packages/effects/src/lut.ts)
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index e4345b3068..d8c3ec97a1 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -308,6 +308,7 @@ const sidebars: SidebarsConfig = {
'effects/light-trail',
'effects/lines',
'effects/liquid-contours',
+ 'effects/lut',
'effects/mirror',
'effects/noise',
'effects/noise-displacement',
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index 9924050877..52276daedd 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -2177,6 +2177,15 @@ export const articles = [
noAi: false,
slug: 'effects/liquid-contours',
},
+ {
+ id: 'effects/lut',
+ title: 'lut()',
+ relativePath: 'docs/effects/lut.mdx',
+ compId: 'articles-docs-effects-lut',
+ crumb: '@remotion/effects',
+ noAi: false,
+ slug: 'effects/lut',
+ },
{
id: 'effects/mirror',
title: 'mirror()',
diff --git a/packages/docs/src/remotion/Root.tsx b/packages/docs/src/remotion/Root.tsx
index 020d0edaf4..50522e36c2 100644
--- a/packages/docs/src/remotion/Root.tsx
+++ b/packages/docs/src/remotion/Root.tsx
@@ -44,6 +44,10 @@ import {
} from '../../components/effects/effects-linear-progressive-pixelate-preview';
import {EffectsLinesPreview} from '../../components/effects/effects-lines-preview';
import {EffectsLiquidContoursPreview} from '../../components/effects/effects-liquid-contours-preview';
+import {
+ EffectsLutPreview,
+ LUT_PREVIEW_CONTENT,
+} from '../../components/effects/effects-lut-preview';
import {EffectsMirrorPreview} from '../../components/effects/effects-mirror-preview';
import {
EffectsNoiseDisplacementPreview,
@@ -345,6 +349,13 @@ export const RemotionRoot: React.FC = () => {
height={720}
defaultProps={{blackPoint: 0.1, whitePoint: 0.9, gamma: 1.4}}
/>
+ <Still
+ id="effects-lut-preview"
+ component={EffectsLutPreview}
+ width={1280}
+ height={720}
+ defaultProps={{content: LUT_PREVIEW_CONTENT}}
+ />
<Still
id="effects-shadows-highlights-preview"
component={EffectsShadowsHighlightsPreview}
diff --git a/packages/docs/static/generated/articles-docs-effects-lut.png b/packages/docs/static/generated/articles-docs-effects-lut.png
new file mode 100644
index 0000000000..726bdc0e4e
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-effects-lut.png differ
diff --git a/packages/docs/static/img/effects-lut-preview.png b/packages/docs/static/img/effects-lut-preview.png
new file mode 100644
index 0000000000..43bdec0a42
Binary files /dev/null and b/packages/docs/static/img/effects-lut-preview.png differ
diff --git a/packages/effects/bundle.ts b/packages/effects/bundle.ts
index 43e4cfaa8f..50450fe454 100644
--- a/packages/effects/bundle.ts
+++ b/packages/effects/bundle.ts
@@ -44,6 +44,7 @@ const effectEntrypoints = [
'src/light-leak.ts',
'src/light-trail.ts',
'src/levels.ts',
+ 'src/lut.ts',
'src/mirror.ts',
'src/noise.ts',
'src/noise-displacement.ts',
diff --git a/packages/effects/package.json b/packages/effects/package.json
index d8b6cb23c9..59f0335791 100644
--- a/packages/effects/package.json
+++ b/packages/effects/package.json
@@ -204,6 +204,11 @@
"module": "./dist/esm/levels.mjs",
"import": "./dist/esm/levels.mjs"
},
+ "./lut": {
+ "types": "./dist/lut.d.ts",
+ "module": "./dist/esm/lut.mjs",
+ "import": "./dist/esm/lut.mjs"
+ },
"./light-leak": {
"types": "./dist/light-leak.d.ts",
"module": "./dist/esm/light-leak.mjs",
@@ -500,6 +505,9 @@
"levels": [
"dist/levels.d.ts"
],
+ "lut": [
+ "dist/lut.d.ts"
+ ],
"light-leak": [
"dist/light-leak.d.ts"
],
diff --git a/packages/effects/src/lut.ts b/packages/effects/src/lut.ts
new file mode 100644
index 0000000000..758e15a072
--- /dev/null
+++ b/packages/effects/src/lut.ts
@@ -0,0 +1 @@
+export {lut, lutSchema, type LutParams} from './lut/index.js';
diff --git a/packages/effects/src/lut/index.ts b/packages/effects/src/lut/index.ts
new file mode 100644
index 0000000000..145258b440
--- /dev/null
+++ b/packages/effects/src/lut/index.ts
@@ -0,0 +1,116 @@
+import type {InteractivitySchema} from 'remotion';
+import {Internals} from 'remotion';
+import {applyLut, cleanupLut, setupLut, type LutState} from './lut-runtime.js';
+import {parseCubeLut, type ParsedCubeLut} from './parse-cube-lut.js';
+
+const {createEffect} = Internals;
+
+const DEFAULT_LUT_CONTENT = `TITLE "Identity"
+LUT_3D_SIZE 2
+
+0 0 0
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1`;
+
+export const lutSchema = {
+ content: {
+ type: 'text-content',
+ default: DEFAULT_LUT_CONTENT,
+ description: 'Cube LUT content',
+ keyframable: false,
+ },
+} as const satisfies InteractivitySchema;
+
+export type LutParams = {
+ /** The inline contents of a 3D `.cube` LUT file. */
+ readonly content: string;
+};
+
+type CachedLut = {
+ readonly parsed: ParsedCubeLut;
+ readonly effectKey: string;
+};
+
+const MAX_CACHED_LUTS = 4;
+const parsedLuts = new Map<string, CachedLut>();
+
+const getCachedLut = (content: string): CachedLut => {
+ const cached = parsedLuts.get(content);
+ if (cached) {
+ parsedLuts.delete(content);
+ parsedLuts.set(content, cached);
+ return cached;
+ }
+
+ let firstHash = 2166136261;
+ let secondHash = 5381;
+
+ for (let i = 0; i < content.length; i++) {
+ const character = content.charCodeAt(i);
+ firstHash ^= character;
+ firstHash = Math.imul(firstHash, 16777619);
+ secondHash = Math.imul(secondHash, 33) ^ character;
+ }
+
+ const created = {
+ parsed: parseCubeLut(content),
+ effectKey: `lut-${content.length}-${firstHash >>> 0}-${secondHash >>> 0}`,
+ };
+ parsedLuts.set(content, created);
+
+ if (parsedLuts.size > MAX_CACHED_LUTS) {
+ const oldestContent = parsedLuts.keys().next().value;
+ if (oldestContent !== undefined) {
+ parsedLuts.delete(oldestContent);
+ }
+ }
+
+ return created;
+};
+
+const validateLutParams = (params: LutParams): void => {
+ if (params === null || typeof params !== 'object') {
+ throw new TypeError(
+ `LUT effect requires a parameters object, but got ${JSON.stringify(params)}`,
+ );
+ }
+
+ if (
+ typeof params.content !== 'string' ||
+ params.content.trim().length === 0
+ ) {
+ throw new TypeError(
+ `"content" must be a non-empty string, but got ${JSON.stringify(params.content)}`,
+ );
+ }
+
+ getCachedLut(params.content);
+};
+
+export const lut = createEffect<LutParams, LutState>({
+ type: 'remotion/lut',
+ label: 'lut()',
+ documentationLink: 'https://www.remotion.dev/docs/effects/lut',
+ backend: 'webgl2',
+ calculateKey: (params) => getCachedLut(params.content).effectKey,
+ setup: setupLut,
+ apply: ({source, width, height, params, state, flipSourceY}) => {
+ applyLut({
+ state,
+ source,
+ width,
+ height,
+ content: params.content,
+ parsed: getCachedLut(params.content).parsed,
+ flipSourceY,
+ });
+ },
+ cleanup: cleanupLut,
+ schema: lutSchema,
+ validateParams: validateLutParams,
+});
diff --git a/packages/effects/src/lut/lut-runtime.ts b/packages/effects/src/lut/lut-runtime.ts
new file mode 100644
index 0000000000..3736832b29
--- /dev/null
+++ b/packages/effects/src/lut/lut-runtime.ts
@@ -0,0 +1,265 @@
+import {Internals} from 'remotion';
+import {LUT_FRAGMENT_SHADER, LUT_VERTEX_SHADER} from './lut-shaders.js';
+import type {ParsedCubeLut} from './parse-cube-lut.js';
+
+const {createWebGL2ContextError} = Internals;
+
+export type LutState = {
+ readonly gl: WebGL2RenderingContext;
+ readonly program: WebGLProgram;
+ readonly vao: WebGLVertexArrayObject;
+ readonly vbo: WebGLBuffer;
+ readonly sourceTexture: WebGLTexture;
+ readonly lutTexture: WebGLTexture;
+ readonly uniforms: {
+ readonly uSource: WebGLUniformLocation | null;
+ readonly uLut: WebGLUniformLocation | null;
+ readonly uLutSize: WebGLUniformLocation | null;
+ readonly uDomainMin: WebGLUniformLocation | null;
+ readonly uDomainMax: WebGLUniformLocation | null;
+ };
+ cachedContent: string | null;
+};
+
+const compileShader = (
+ gl: WebGL2RenderingContext,
+ type: number,
+ source: string,
+): WebGLShader => {
+ const shader = gl.createShader(type);
+ if (!shader) {
+ throw new Error('Failed to create LUT shader');
+ }
+
+ gl.shaderSource(shader, source);
+ gl.compileShader(shader);
+ if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+ const log = gl.getShaderInfoLog(shader);
+ gl.deleteShader(shader);
+ throw new Error(`LUT shader compile failed: ${log ?? '(no log)'}`);
+ }
+
+ return shader;
+};
+
+const createProgram = (gl: WebGL2RenderingContext): WebGLProgram => {
+ const vertexShader = compileShader(gl, gl.VERTEX_SHADER, LUT_VERTEX_SHADER);
+ const fragmentShader = compileShader(
+ gl,
+ gl.FRAGMENT_SHADER,
+ LUT_FRAGMENT_SHADER,
+ );
+ const program = gl.createProgram();
+ if (!program) {
+ throw new Error('Failed to create LUT shader program');
+ }
+
+ gl.attachShader(program, vertexShader);
+ gl.attachShader(program, fragmentShader);
+ gl.linkProgram(program);
+ gl.deleteShader(vertexShader);
+ gl.deleteShader(fragmentShader);
+
+ if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+ const log = gl.getProgramInfoLog(program);
+ gl.deleteProgram(program);
+ throw new Error(`LUT shader link failed: ${log ?? '(no log)'}`);
+ }
+
+ return program;
+};
+
+const createSourceTexture = (gl: WebGL2RenderingContext): WebGLTexture => {
+ const texture = gl.createTexture();
+ if (!texture) {
+ throw new Error('Failed to create LUT source texture');
+ }
+
+ gl.bindTexture(gl.TEXTURE_2D, texture);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+ gl.bindTexture(gl.TEXTURE_2D, null);
+ return texture;
+};
+
+const createLutTexture = (gl: WebGL2RenderingContext): WebGLTexture => {
+ const texture = gl.createTexture();
+ if (!texture) {
+ throw new Error('Failed to create LUT texture');
+ }
+
+ gl.bindTexture(gl.TEXTURE_3D, texture);
+ gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+ gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+ gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+ gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+ gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_R, gl.CLAMP_TO_EDGE);
+ gl.bindTexture(gl.TEXTURE_3D, null);
+ return texture;
+};
+
+export const setupLut = (target: HTMLCanvasElement): LutState => {
+ const gl = target.getContext('webgl2', {
+ premultipliedAlpha: true,
+ alpha: true,
+ preserveDrawingBuffer: true,
+ });
+ if (!gl) {
+ throw createWebGL2ContextError('LUT effect');
+ }
+
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+
+ const program = createProgram(gl);
+ const vao = gl.createVertexArray();
+ if (!vao) {
+ throw new Error('Failed to create LUT vertex array');
+ }
+
+ const vbo = gl.createBuffer();
+ if (!vbo) {
+ throw new Error('Failed to create LUT vertex buffer');
+ }
+
+ gl.bindVertexArray(vao);
+ gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+ gl.bufferData(
+ gl.ARRAY_BUFFER,
+ new Float32Array([-1, -1, 0, 0, 1, -1, 1, 0, -1, 1, 0, 1, 1, 1, 1, 1]),
+ gl.STATIC_DRAW,
+ );
+ gl.enableVertexAttribArray(0);
+ gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 16, 0);
+ gl.enableVertexAttribArray(1);
+ gl.vertexAttribPointer(1, 2, gl.FLOAT, false, 16, 8);
+ gl.bindVertexArray(null);
+
+ return {
+ gl,
+ program,
+ vao,
+ vbo,
+ sourceTexture: createSourceTexture(gl),
+ lutTexture: createLutTexture(gl),
+ uniforms: {
+ uSource: gl.getUniformLocation(program, 'uSource'),
+ uLut: gl.getUniformLocation(program, 'uLut'),
+ uLutSize: gl.getUniformLocation(program, 'uLutSize'),
+ uDomainMin: gl.getUniformLocation(program, 'uDomainMin'),
+ uDomainMax: gl.getUniformLocation(program, 'uDomainMax'),
+ },
+ cachedContent: null,
+ };
+};
+
+export const applyLut = ({
+ state,
+ source,
+ width,
+ height,
+ content,
+ parsed,
+ flipSourceY,
+}: {
+ readonly state: LutState;
+ readonly source: CanvasImageSource;
+ readonly width: number;
+ readonly height: number;
+ readonly content: string;
+ readonly parsed: ParsedCubeLut;
+ readonly flipSourceY: boolean;
+}): void => {
+ const {gl, program, sourceTexture, lutTexture, uniforms, vao} = state;
+
+ if (state.cachedContent !== content) {
+ const maxSize = gl.getParameter(gl.MAX_3D_TEXTURE_SIZE) as number;
+ if (parsed.size > maxSize) {
+ throw new Error(
+ `LUT_3D_SIZE ${parsed.size} exceeds this browser's maximum 3D texture size of ${maxSize}`,
+ );
+ }
+
+ gl.activeTexture(gl.TEXTURE1);
+ gl.bindTexture(gl.TEXTURE_3D, lutTexture);
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+ gl.texImage3D(
+ gl.TEXTURE_3D,
+ 0,
+ gl.RGBA16F,
+ parsed.size,
+ parsed.size,
+ parsed.size,
+ 0,
+ gl.RGBA,
+ gl.FLOAT,
+ parsed.data,
+ );
+ const uploadError = gl.getError();
+ if (uploadError !== gl.NO_ERROR) {
+ throw new Error(
+ `Failed to upload the 3D LUT texture (WebGL error ${uploadError})`,
+ );
+ }
+
+ gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+ state.cachedContent = content;
+ }
+
+ gl.viewport(0, 0, width, height);
+ gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+ gl.clearColor(0, 0, 0, 0);
+ gl.clear(gl.COLOR_BUFFER_BIT);
+
+ gl.activeTexture(gl.TEXTURE0);
+ gl.bindTexture(gl.TEXTURE_2D, sourceTexture);
+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flipSourceY);
+ gl.texImage2D(
+ gl.TEXTURE_2D,
+ 0,
+ gl.RGBA,
+ gl.RGBA,
+ gl.UNSIGNED_BYTE,
+ source as TexImageSource,
+ );
+
+ gl.activeTexture(gl.TEXTURE1);
+ gl.bindTexture(gl.TEXTURE_3D, lutTexture);
+
+ gl.useProgram(program);
+ if (uniforms.uSource) gl.uniform1i(uniforms.uSource, 0);
+ if (uniforms.uLut) gl.uniform1i(uniforms.uLut, 1);
+ if (uniforms.uLutSize) gl.uniform1i(uniforms.uLutSize, parsed.size);
+ if (uniforms.uDomainMin) {
+ gl.uniform3f(uniforms.uDomainMin, ...parsed.domainMin);
+ }
+
+ if (uniforms.uDomainMax) {
+ gl.uniform3f(uniforms.uDomainMax, ...parsed.domainMax);
+ }
+
+ gl.bindVertexArray(vao);
+ gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+ gl.bindVertexArray(null);
+ gl.bindTexture(gl.TEXTURE_3D, null);
+ gl.activeTexture(gl.TEXTURE0);
+ gl.bindTexture(gl.TEXTURE_2D, null);
+ gl.useProgram(null);
+};
+
+export const cleanupLut = ({
+ gl,
+ program,
+ vao,
+ vbo,
+ sourceTexture,
+ lutTexture,
+}: LutState): void => {
+ gl.deleteTexture(sourceTexture);
+ gl.deleteTexture(lutTexture);
+ gl.deleteBuffer(vbo);
+ gl.deleteProgram(program);
+ gl.deleteVertexArray(vao);
+};
diff --git a/packages/effects/src/lut/lut-shaders.ts b/packages/effects/src/lut/lut-shaders.ts
new file mode 100644
index 0000000000..ee7bd64639
--- /dev/null
+++ b/packages/effects/src/lut/lut-shaders.ts
@@ -0,0 +1,67 @@
+export const LUT_VERTEX_SHADER = /* glsl */ `#version 300 es
+layout(location = 0) in vec2 aPos;
+layout(location = 1) in vec2 aUv;
+out vec2 vUv;
+
+void main() {
+ vUv = aUv;
+ gl_Position = vec4(aPos, 0.0, 1.0);
+}
+`;
+
+export const LUT_FRAGMENT_SHADER = /* glsl */ `#version 300 es
+precision highp float;
+precision highp sampler3D;
+
+in vec2 vUv;
+out vec4 fragColor;
+
+uniform sampler2D uSource;
+uniform sampler3D uLut;
+uniform int uLutSize;
+uniform vec3 uDomainMin;
+uniform vec3 uDomainMax;
+
+vec3 sampleLut(vec3 color) {
+ vec3 normalizedColor = clamp(
+ (color - uDomainMin) / (uDomainMax - uDomainMin),
+ vec3(0.0),
+ vec3(1.0)
+ );
+ vec3 position = normalizedColor * float(uLutSize - 1);
+ ivec3 lower = ivec3(floor(position));
+ ivec3 upper = min(lower + ivec3(1), ivec3(uLutSize - 1));
+ vec3 fraction = fract(position);
+
+ vec3 c000 = texelFetch(uLut, ivec3(lower.x, lower.y, lower.z), 0).rgb;
+ vec3 c100 = texelFetch(uLut, ivec3(upper.x, lower.y, lower.z), 0).rgb;
+ vec3 c010 = texelFetch(uLut, ivec3(lower.x, upper.y, lower.z), 0).rgb;
+ vec3 c110 = texelFetch(uLut, ivec3(upper.x, upper.y, lower.z), 0).rgb;
+ vec3 c001 = texelFetch(uLut, ivec3(lower.x, lower.y, upper.z), 0).rgb;
+ vec3 c101 = texelFetch(uLut, ivec3(upper.x, lower.y, upper.z), 0).rgb;
+ vec3 c011 = texelFetch(uLut, ivec3(lower.x, upper.y, upper.z), 0).rgb;
+ vec3 c111 = texelFetch(uLut, ivec3(upper.x, upper.y, upper.z), 0).rgb;
+
+ vec3 c00 = mix(c000, c100, fraction.x);
+ vec3 c10 = mix(c010, c110, fraction.x);
+ vec3 c01 = mix(c001, c101, fraction.x);
+ vec3 c11 = mix(c011, c111, fraction.x);
+ vec3 c0 = mix(c00, c10, fraction.y);
+ vec3 c1 = mix(c01, c11, fraction.y);
+ return mix(c0, c1, fraction.z);
+}
+
+void main() {
+ vec4 sourceColor = texture(uSource, vUv);
+ float alpha = sourceColor.a;
+
+ if (alpha <= 0.0) {
+ fragColor = vec4(0.0);
+ return;
+ }
+
+ vec3 straightColor = sourceColor.rgb / alpha;
+ vec3 transformedColor = sampleLut(straightColor);
+ fragColor = vec4(transformedColor * alpha, alpha);
+}
+`;
diff --git a/packages/effects/src/lut/parse-cube-lut.ts b/packages/effects/src/lut/parse-cube-lut.ts
new file mode 100644
index 0000000000..c1667595fe
--- /dev/null
+++ b/packages/effects/src/lut/parse-cube-lut.ts
@@ -0,0 +1,238 @@
+export type ParsedCubeLut = {
+ readonly size: number;
+ readonly domainMin: readonly [number, number, number];
+ readonly domainMax: readonly [number, number, number];
+ readonly data: Float32Array;
+};
+
+const stripComment = (line: string): string => {
+ let insideQuotes = false;
+
+ for (let i = 0; i < line.length; i++) {
+ const character = line[i];
+ if (character === '"') {
+ insideQuotes = !insideQuotes;
+ } else if (character === '#' && !insideQuotes) {
+ return line.slice(0, i);
+ }
+ }
+
+ return line;
+};
+
+const parseTriplet = ({
+ values,
+ lineNumber,
+ label,
+}: {
+ readonly values: readonly string[];
+ readonly lineNumber: number;
+ readonly label: string;
+}): readonly [number, number, number] => {
+ if (values.length !== 3) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: ${label} must contain exactly 3 numbers`,
+ );
+ }
+
+ const parsed = values.map((value) => Number(value));
+ if (parsed.some((value) => !Number.isFinite(value))) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: ${label} must contain only finite numbers`,
+ );
+ }
+
+ return [parsed[0], parsed[1], parsed[2]];
+};
+
+const HEADER_DIRECTIVES = new Set([
+ 'TITLE',
+ 'LUT_3D_SIZE',
+ 'DOMAIN_MIN',
+ 'DOMAIN_MAX',
+]);
+
+export const parseCubeLut = (content: string): ParsedCubeLut => {
+ const lines = content.replace(/^\uFEFF/, '').split(/\r?\n/);
+ let size: number | null = null;
+ let domainMin: readonly [number, number, number] = [0, 0, 0];
+ let domainMax: readonly [number, number, number] = [1, 1, 1];
+ let hasDomainMin = false;
+ let hasDomainMax = false;
+ let hasTitle = false;
+ let dataRows = 0;
+ let dataStarted = false;
+
+ for (let index = 0; index < lines.length; index++) {
+ const lineNumber = index + 1;
+ const line = stripComment(lines[index]).trim();
+ if (line.length === 0) {
+ continue;
+ }
+
+ const [keyword, ...values] = line.split(/\s+/);
+
+ if (keyword === 'LUT_1D_SIZE') {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: 1D LUTs are not supported`,
+ );
+ }
+
+ if (HEADER_DIRECTIVES.has(keyword)) {
+ if (dataStarted) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: ${keyword} must appear before the color data`,
+ );
+ }
+
+ if (keyword === 'TITLE') {
+ if (hasTitle) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: TITLE may only be declared once`,
+ );
+ }
+
+ hasTitle = true;
+ continue;
+ }
+
+ if (keyword === 'LUT_3D_SIZE') {
+ if (size !== null) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: LUT_3D_SIZE may only be declared once`,
+ );
+ }
+
+ if (values.length !== 1) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: LUT_3D_SIZE must contain exactly one integer`,
+ );
+ }
+
+ const parsedSize = Number(values[0]);
+ if (
+ !Number.isInteger(parsedSize) ||
+ parsedSize < 2 ||
+ parsedSize > 256
+ ) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: LUT_3D_SIZE must be an integer from 2 to 256`,
+ );
+ }
+
+ size = parsedSize;
+ continue;
+ }
+
+ if (keyword === 'DOMAIN_MIN') {
+ if (hasDomainMin) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: DOMAIN_MIN may only be declared once`,
+ );
+ }
+
+ domainMin = parseTriplet({
+ values,
+ lineNumber,
+ label: 'DOMAIN_MIN',
+ });
+ hasDomainMin = true;
+ continue;
+ }
+
+ if (hasDomainMax) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: DOMAIN_MAX may only be declared once`,
+ );
+ }
+
+ domainMax = parseTriplet({
+ values,
+ lineNumber,
+ label: 'DOMAIN_MAX',
+ });
+ hasDomainMax = true;
+ continue;
+ }
+
+ if (/^[A-Z_]/i.test(keyword)) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: unsupported directive "${keyword}"`,
+ );
+ }
+
+ if (size === null) {
+ throw new TypeError(
+ `Invalid LUT content on line ${lineNumber}: LUT_3D_SIZE must be declared before the color data`,
+ );
+ }
+
+ parseTriplet({
+ values: [keyword, ...values],
+ lineNumber,
+ label: 'color row',
+ });
+ dataStarted = true;
+ dataRows++;
+
+ const maxDataRows = size ** 3;
+ if (dataRows > maxDataRows) {
+ throw new TypeError(
+ `Invalid LUT content: expected ${maxDataRows} color rows for LUT_3D_SIZE ${size}, but got more`,
+ );
+ }
+ }
+
+ if (size === null) {
+ throw new TypeError('Invalid LUT content: LUT_3D_SIZE is missing');
+ }
+
+ for (let channel = 0; channel < 3; channel++) {
+ if (domainMin[channel] >= domainMax[channel]) {
+ throw new TypeError(
+ `Invalid LUT content: DOMAIN_MIN must be smaller than DOMAIN_MAX for every channel`,
+ );
+ }
+ }
+
+ const expectedRows = size ** 3;
+ if (dataRows !== expectedRows) {
+ throw new TypeError(
+ `Invalid LUT content: expected ${expectedRows} color rows for LUT_3D_SIZE ${size}, but got ${dataRows}`,
+ );
+ }
+
+ const data = new Float32Array(expectedRows * 4);
+ let dataIndex = 0;
+
+ for (let index = 0; index < lines.length; index++) {
+ const line = stripComment(lines[index]).trim();
+ if (line.length === 0) {
+ continue;
+ }
+
+ const [keyword, ...values] = line.split(/\s+/);
+ if (HEADER_DIRECTIVES.has(keyword)) {
+ continue;
+ }
+
+ const [red, green, blue] = parseTriplet({
+ values: [keyword, ...values],
+ lineNumber: index + 1,
+ label: 'color row',
+ });
+ const offset = dataIndex * 4;
+ data[offset] = red;
+ data[offset + 1] = green;
+ data[offset + 2] = blue;
+ data[offset + 3] = 1;
+ dataIndex++;
+ }
+
+ return {
+ size,
+ domainMin,
+ domainMax,
+ data,
+ };
+};
diff --git a/packages/effects/src/test/effect-params.test.ts b/packages/effects/src/test/effect-params.test.ts
index 1d804b9488..f792f26f43 100644
--- a/packages/effects/src/test/effect-params.test.ts
+++ b/packages/effects/src/test/effect-params.test.ts
@@ -37,6 +37,7 @@ import {linearProgressiveBlur} from '../linear-progressive-blur/index.js';
import {linearProgressivePixelate} from '../linear-progressive-pixelate/index.js';
import {lines} from '../lines.js';
import {liquidContours, liquidContoursSchema} from '../liquid-contours.js';
+import {lut} from '../lut/index.js';
import {mirror} from '../mirror.js';
import {
noiseDisplacement,
@@ -99,6 +100,18 @@ const expectDefaultBlueColorArrayControl = (schema: {
});
};
+const IDENTITY_LUT = `TITLE "Identity"
+LUT_3D_SIZE 2
+
+0 0 0
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1`;
+
test('public UV coordinates convert to shader UV coordinates', () => {
expect(publicUvToShaderUv([0, 0])).toEqual([0, 1]);
expect(publicUvToShaderUv([0.25, 0.75])).toEqual([0.25, 0.25]);
@@ -198,6 +211,9 @@ test('@remotion/effects expose documentation links', () => {
expect(liquidContours().definition.documentationLink).toBe(
'https://www.remotion.dev/docs/effects/liquid-contours',
);
+ expect(lut({content: IDENTITY_LUT}).definition.documentationLink).toBe(
+ 'https://www.remotion.dev/docs/effects/lut',
+ );
expect(linearGradient().definition.documentationLink).toBe(
'https://www.remotion.dev/docs/effects/linear-gradient',
);
@@ -338,6 +354,7 @@ test('@remotion/effects expose API names as Studio labels', () => {
expect(contrast().definition.label).toBe('contrast()');
expect(contourLines().definition.label).toBe('contourLines()');
expect(liquidContours().definition.label).toBe('liquidContours()');
+ expect(lut({content: IDENTITY_LUT}).definition.label).toBe('lut()');
expect(duotone().definition.label).toBe('duotone()');
expect(evolve().definition.label).toBe('evolve()');
expect(exposure().definition.label).toBe('exposure()');
@@ -1177,6 +1194,37 @@ test('levels() parameters produce distinct effect keys', () => {
).toBe(3);
});
+test('lut() accepts valid inline Cube content', () => {
+ expect(() => lut({content: IDENTITY_LUT})).not.toThrow();
+});
+
+test('lut() requires content', () => {
+ expect(() => lut({} as Parameters<typeof lut>[0])).toThrow(
+ '"content" must be a non-empty string, but got undefined',
+ );
+ expect(() => lut({content: ''})).toThrow(
+ '"content" must be a non-empty string, but got ""',
+ );
+});
+
+test('lut() rejects invalid Cube content', () => {
+ expect(() =>
+ lut({
+ content: `LUT_3D_SIZE 2
+0 0 0`,
+ }),
+ ).toThrow('expected 8 color rows for LUT_3D_SIZE 2, but got 1');
+});
+
+test('lut() content produces distinct effect keys', () => {
+ const identity = lut({content: IDENTITY_LUT});
+ const warm = lut({
+ content: IDENTITY_LUT.replace('1 1 1', '1 0.8 0.6'),
+ });
+
+ expect(identity.effectKey).not.toBe(warm.effectKey);
+});
+
test('shadowsHighlights() accepts default params', () => {
expect(() => shadowsHighlights()).not.toThrow();
});
diff --git a/packages/effects/src/test/lut.test.ts b/packages/effects/src/test/lut.test.ts
new file mode 100644
index 0000000000..3577f45bed
--- /dev/null
+++ b/packages/effects/src/test/lut.test.ts
@@ -0,0 +1,73 @@
+import {expect, test} from 'bun:test';
+import {parseCubeLut} from '../lut/parse-cube-lut.js';
+
+const IDENTITY_LUT = `\uFEFF# Identity LUT
+TITLE "Identity #1"
+LUT_3D_SIZE 2
+DOMAIN_MIN -1 -0.5 0
+DOMAIN_MAX 1 1.5 2
+
+0 0 0 # black
+1 0 0
+0 1 0
+1 1 0
+0 0 1
+1 0 1
+0 1 1
+1 1 1`;
+
+test('parses a 3D Cube LUT', () => {
+ const parsed = parseCubeLut(IDENTITY_LUT);
+
+ expect(parsed.size).toBe(2);
+ expect(parsed.domainMin).toEqual([-1, -0.5, 0]);
+ expect(parsed.domainMax).toEqual([1, 1.5, 2]);
+ expect(Array.from(parsed.data.slice(0, 8))).toEqual([0, 0, 0, 1, 1, 0, 0, 1]);
+ expect(Array.from(parsed.data.slice(-8))).toEqual([0, 1, 1, 1, 1, 1, 1, 1]);
+});
+
+test('rejects unsupported 1D LUTs', () => {
+ expect(() =>
+ parseCubeLut(`LUT_1D_SIZE 2
+0 0 0
+1 1 1`),
+ ).toThrow('1D LUTs are not supported');
+});
+
+test('rejects malformed LUT sizes', () => {
+ expect(() => parseCubeLut('LUT_3D_SIZE 1')).toThrow(
+ 'LUT_3D_SIZE must be an integer from 2 to 256',
+ );
+ expect(() => parseCubeLut('LUT_3D_SIZE 2.5')).toThrow(
+ 'LUT_3D_SIZE must be an integer from 2 to 256',
+ );
+});
+
+test('rejects non-finite color values', () => {
+ expect(() =>
+ parseCubeLut(`LUT_3D_SIZE 2
+0 0 NaN`),
+ ).toThrow('color row must contain only finite numbers');
+});
+
+test('rejects invalid domains', () => {
+ expect(() =>
+ parseCubeLut(`LUT_3D_SIZE 2
+DOMAIN_MIN 0 0 0
+DOMAIN_MAX 0 1 1`),
+ ).toThrow('DOMAIN_MIN must be smaller than DOMAIN_MAX for every channel');
+});
+
+test('rejects directives after color data', () => {
+ expect(() =>
+ parseCubeLut(`LUT_3D_SIZE 2
+0 0 0
+DOMAIN_MIN 0 0 0`),
+ ).toThrow('DOMAIN_MIN must appear before the color data');
+});
+
+test('rejects unknown directives', () => {
+ expect(() => parseCubeLut('LUT_3D_SIZE 2\nFOO 1 2 3')).toThrow(
+ 'unsupported directive "FOO"',
+ );
+});
diff --git a/packages/studio-shared/src/effect-catalog.ts b/packages/studio-shared/src/effect-catalog.ts
index debe9edd92..33f9db2201 100644
--- a/packages/studio-shared/src/effect-catalog.ts
+++ b/packages/studio-shared/src/effect-catalog.ts
@@ -60,6 +60,18 @@ export const getEffectCatalogCategories = (
return categories;
};
+const DEFAULT_LUT_CONTENT = `TITLE "Teal and orange"
+LUT_3D_SIZE 2
+
+0.02 0.05 0.08
+0.95 0.12 0.06
+0.02 0.8 0.4
+1 0.9 0.18
+0.08 0.18 0.9
+0.95 0.2 0.75
+0.15 0.88 0.92
+1 0.92 0.78`;
+
export const EFFECT_CATALOG: readonly EffectCatalogItem[] = [
{
id: 'effects-brightness',
@@ -173,6 +185,19 @@ export const EFFECT_CATALOG: readonly EffectCatalogItem[] = [
config: {},
},
},
+ {
+ id: 'effects-lut',
+ category: 'Color',
+ label: 'lut()',
+ description: 'Apply an inline 3D Cube LUT',
+ effect: {
+ name: 'lut',
+ importPath: '@remotion/effects/lut',
+ config: {
+ content: DEFAULT_LUT_CONTENT,
+ },
+ },
+ },
{
id: 'effects-saturation',
category: 'Color',