1---
2name: effects
3description: Canvas/WebGL visual effects for Remotion using effects arrays and createEffect().
4metadata:
5  tags: effects, visual-effects, webgl, canvas, video, create-effect
6---
7 
8Use this rule only when the top-level skill lists an effect that matches the requested look, or when the user asks to create a reusable custom effect.
9 
10Docs: https://www.remotion.dev/docs/effects
11Custom effect docs: https://www.remotion.dev/docs/create-effect
12 
13## Usage
14 
15Install the package that provides the chosen effect:
16 
17```bash
18npx remotion add @remotion/effects
19```
20 
21Use `npx remotion add @remotion/light-leaks` for `lightLeak()` and `npx remotion add @remotion/starburst` for `starburst()`.
22 
23Effects are functions passed to the `effects` prop of canvas-based components such as `<Video>` from `@remotion/media`, `<Solid>`, `<CanvasImage>`, and `<HtmlInCanvas>`.
24 
25```tsx
26import {Video} from '@remotion/media';
27import {blur} from '@remotion/effects/blur';
28 
29<Video src="https://remotion.media/video.mp4" effects={[blur({radius: 8})]} />;
30```
31 
32Use the effect docs for exact props and imports. Most `@remotion/effects` imports use `@remotion/effects/<effect-slug>`; `uvTranslate()` and `xyTranslate()` use `@remotion/effects/translate`; `lightLeak()` uses `@remotion/light-leaks`; `starburst()` uses `@remotion/starburst`.
33 
34These effects use WebGL2. During renders, enable WebGL with:
35 
36```ts
37import {Config} from '@remotion/cli/config';
38 
39Config.setChromiumOpenGlRenderer('angle');
40```
41 
42## Custom effects
43 
44Use `createEffect()` from `remotion` when the user wants a reusable effect factory that works in the same `effects` array as `@remotion/effects`.
45 
46Prefer a custom effect over `<HtmlInCanvas onPaint>` when the transformation should be reusable, parameterized, editable in Studio, or stackable with other effects.
47 
48For quick project-specific effects, keep the effect next to the composition, for example `src/effects/palette-map.ts`. For library effects intended for `@remotion/effects`, follow the repository's `add-effect` skill instead.
49 
50`createEffect()` expects:
51 
52- `type`: stable reverse-DNS identifier, for example `com.example.paletteMap`.
53- `label`: Studio label, commonly `paletteMap()`.
54- `documentationLink`: URL or `null`.
55- `backend`: `"2d"`, `"webgl2"` or `"webgpu"`.
56- `calculateKey(params)`: stable string containing every resolved parameter that changes output.
57- `setup(target)`: create reusable backend state, or return `null`.
58- `apply({source, target, width, height, params, state, flipSourceY})`: draw the transformed result into `target`.
59- `cleanup(state)`: free resources created by `setup()`.
60- `schema`: an `InteractivitySchema` for Studio controls. `disabled` is added automatically.
61- `validateParams(params)`: throw on missing or invalid values.
62 
63Use `backend: "2d"` for simple pixel, filter, drawImage, or image-data effects. Use WebGL2 only when shader math or GPU performance is needed; during renders, enable WebGL as shown above.
64 
65```ts
66import {createEffect, type InteractivitySchema} from 'remotion';
67 
68type MyEffectParams = {
69  readonly amount?: number;
70};
71 
72const myEffectSchema = {
73  amount: {
74    type: 'number',
75    min: 0,
76    max: 1,
77    step: 0.01,
78    default: 1,
79    description: 'Amount',
80  },
81} as const satisfies InteractivitySchema;
82 
83const resolve = (params: MyEffectParams) => ({
84  amount: params.amount ?? 1,
85});
86 
87export const myEffect = createEffect<MyEffectParams, null>({
88  type: 'com.example.myEffect',
89  label: 'myEffect()',
90  documentationLink: null,
91  backend: '2d',
92  calculateKey: (params) => {
93    const {amount} = resolve(params);
94    return `my-effect-${amount}`;
95  },
96  setup: () => null,
97  apply: ({source, target, width, height, params}) => {
98    const ctx = target.getContext('2d');
99    if (!ctx) {
100      throw new Error('Could not get a 2D context for myEffect().');
101    }
102 
103    const {amount} = resolve(params);
104 
105    ctx.clearRect(0, 0, width, height);
106    ctx.filter = `opacity(${amount * 100}%)`;
107    ctx.drawImage(source, 0, 0, width, height);
108    ctx.filter = 'none';
109  },
110  cleanup: () => undefined,
111  schema: myEffectSchema,
112  validateParams: ({amount = 1}) => {
113    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 1) {
114      throw new TypeError('amount must be a number between 0 and 1');
115    }
116  },
117});
118```
119 
120For a WebGL2 effect, compile/link shaders in `setup()`, keep the program, fullscreen quad, texture, and uniform locations in state, upload `source` in `apply()`, and free GPU resources in `cleanup()`. Minimal shape:
121 
122```ts
123import {createEffect, type InteractivitySchema} from 'remotion';
124 
125type RgbShiftParams = {
126  readonly amount?: number;
127};
128 
129type RgbShiftState = {
130  readonly gl: WebGL2RenderingContext;
131  readonly program: WebGLProgram;
132  readonly vao: WebGLVertexArrayObject;
133  readonly vbo: WebGLBuffer;
134  readonly texture: WebGLTexture;
135  readonly uSource: WebGLUniformLocation | null;
136  readonly uOffset: WebGLUniformLocation | null;
137};
138 
139const rgbShiftSchema = {
140  amount: {
141    type: 'number',
142    min: 0,
143    max: 80,
144    step: 1,
145    default: 12,
146    description: 'Amount',
147  },
148} as const satisfies InteractivitySchema;
149 
150export const rgbShift = createEffect<RgbShiftParams, RgbShiftState>({
151  type: 'com.example.rgbShift',
152  label: 'rgbShift()',
153  documentationLink: null,
154  backend: 'webgl2',
155  calculateKey: ({amount = 12}) => `rgb-shift-${amount}`,
156  setup: (target) => {
157    const gl = target.getContext('webgl2', {
158      premultipliedAlpha: true,
159      alpha: true,
160      preserveDrawingBuffer: true,
161    });
162    if (!gl) {
163      throw new Error('Could not get a WebGL2 context for rgbShift().');
164    }
165 
166    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
167 
168    // Compile/link shaders, create a fullscreen quad VAO/VBO, create a
169    // CLAMP_TO_EDGE RGBA texture, and get uSource/uOffset uniform locations.
170    return createRgbShiftState(gl);
171  },
172  apply: ({source, width, height, params, state, flipSourceY}) => {
173    const amount = params.amount ?? 12;
174    const {gl} = state;
175 
176    gl.viewport(0, 0, width, height);
177    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flipSourceY);
178    gl.activeTexture(gl.TEXTURE0);
179    gl.bindTexture(gl.TEXTURE_2D, state.texture);
180    gl.texImage2D(
181      gl.TEXTURE_2D,
182      0,
183      gl.RGBA,
184      gl.RGBA,
185      gl.UNSIGNED_BYTE,
186      source as TexImageSource,
187    );
188 
189    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
190    gl.useProgram(state.program);
191    if (state.uSource) gl.uniform1i(state.uSource, 0);
192    if (state.uOffset) gl.uniform2f(state.uOffset, amount / width, 0);
193    gl.bindVertexArray(state.vao);
194    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
195  },
196  cleanup: ({gl, program, vao, vbo, texture}) => {
197    gl.deleteTexture(texture);
198    gl.deleteBuffer(vbo);
199    gl.deleteProgram(program);
200    gl.deleteVertexArray(vao);
201  },
202  schema: rgbShiftSchema,
203  validateParams: ({amount = 12}) => {
204    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 80) {
205      throw new TypeError('amount must be a number between 0 and 80');
206    }
207  },
208});
209```
210 
211For a complete 2D and WebGL2 pair, see `packages/example/src/EffectsTestbed/sample-posterize-2d.ts` and `packages/example/src/EffectsTestbed/sample-rgb-shift-webgl.ts`.
212 
213Use the returned factory in an `effects` array:
214 
215```tsx
216import {CanvasImage, staticFile} from 'remotion';
217import {myEffect} from './effects/my-effect';
218 
219export const MyComp: React.FC = () => {
220  return (
221    <CanvasImage
222      src={staticFile('image.png')}
223      effects={[myEffect({amount: 0.8})]}
224    />
225  );
226};
227```
228 
229When generating a custom effect, also:
230 
231- Include `disabled?: boolean` only through the returned factory; do not add it to the custom params type or schema.
232- Validate required parameters at factory-call time with `validateParams`.
233- Include all defaults in both `schema` and the `resolve()` helper.
234- Reset mutable 2D context state such as `filter`, `globalAlpha`, transforms, and compositing after drawing.
235- Preserve alpha unless the requested effect intentionally changes transparency.
236