takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/remotion/rules/effects.md

@@ -0,0 +1,235 @@
+---
+name: effects
+description: Canvas/WebGL visual effects for Remotion using effects arrays and createEffect().
+metadata:
+  tags: effects, visual-effects, webgl, canvas, video, create-effect
+---
+
+Use 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.
+
+Docs: https://www.remotion.dev/docs/effects
+Custom effect docs: https://www.remotion.dev/docs/create-effect
+
+## Usage
+
+Install the package that provides the chosen effect:
+
+```bash
+npx remotion add @remotion/effects
+```
+
+Use `npx remotion add @remotion/light-leaks` for `lightLeak()` and `npx remotion add @remotion/starburst` for `starburst()`.
+
+Effects are functions passed to the `effects` prop of canvas-based components such as `<Video>` from `@remotion/media`, `<Solid>`, `<CanvasImage>`, and `<HtmlInCanvas>`.
+
+```tsx
+import {Video} from '@remotion/media';
+import {blur} from '@remotion/effects/blur';
+
+<Video src="https://remotion.media/video.mp4" effects={[blur({radius: 8})]} />;
+```
+
+Use 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`.
+
+These effects use WebGL2. During renders, enable WebGL with:
+
+```ts
+import {Config} from '@remotion/cli/config';
+
+Config.setChromiumOpenGlRenderer('angle');
+```
+
+## Custom effects
+
+Use `createEffect()` from `remotion` when the user wants a reusable effect factory that works in the same `effects` array as `@remotion/effects`.
+
+Prefer a custom effect over `<HtmlInCanvas onPaint>` when the transformation should be reusable, parameterized, editable in Studio, or stackable with other effects.
+
+For 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.
+
+`createEffect()` expects:
+
+- `type`: stable reverse-DNS identifier, for example `com.example.paletteMap`.
+- `label`: Studio label, commonly `paletteMap()`.
+- `documentationLink`: URL or `null`.
+- `backend`: `"2d"`, `"webgl2"` or `"webgpu"`.
+- `calculateKey(params)`: stable string containing every resolved parameter that changes output.
+- `setup(target)`: create reusable backend state, or return `null`.
+- `apply({source, target, width, height, params, state, flipSourceY})`: draw the transformed result into `target`.
+- `cleanup(state)`: free resources created by `setup()`.
+- `schema`: an `InteractivitySchema` for Studio controls. `disabled` is added automatically.
+- `validateParams(params)`: throw on missing or invalid values.
+
+Use `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.
+
+```ts
+import {createEffect, type InteractivitySchema} from 'remotion';
+
+type MyEffectParams = {
+  readonly amount?: number;
+};
+
+const myEffectSchema = {
+  amount: {
+    type: 'number',
+    min: 0,
+    max: 1,
+    step: 0.01,
+    default: 1,
+    description: 'Amount',
+  },
+} as const satisfies InteractivitySchema;
+
+const resolve = (params: MyEffectParams) => ({
+  amount: params.amount ?? 1,
+});
+
+export const myEffect = createEffect<MyEffectParams, null>({
+  type: 'com.example.myEffect',
+  label: 'myEffect()',
+  documentationLink: null,
+  backend: '2d',
+  calculateKey: (params) => {
+    const {amount} = resolve(params);
+    return `my-effect-${amount}`;
+  },
+  setup: () => null,
+  apply: ({source, target, width, height, params}) => {
+    const ctx = target.getContext('2d');
+    if (!ctx) {
+      throw new Error('Could not get a 2D context for myEffect().');
+    }
+
+    const {amount} = resolve(params);
+
+    ctx.clearRect(0, 0, width, height);
+    ctx.filter = `opacity(${amount * 100}%)`;
+    ctx.drawImage(source, 0, 0, width, height);
+    ctx.filter = 'none';
+  },
+  cleanup: () => undefined,
+  schema: myEffectSchema,
+  validateParams: ({amount = 1}) => {
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 1) {
+      throw new TypeError('amount must be a number between 0 and 1');
+    }
+  },
+});
+```
+
+For 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:
+
+```ts
+import {createEffect, type InteractivitySchema} from 'remotion';
+
+type RgbShiftParams = {
+  readonly amount?: number;
+};
+
+type RgbShiftState = {
+  readonly gl: WebGL2RenderingContext;
+  readonly program: WebGLProgram;
+  readonly vao: WebGLVertexArrayObject;
+  readonly vbo: WebGLBuffer;
+  readonly texture: WebGLTexture;
+  readonly uSource: WebGLUniformLocation | null;
+  readonly uOffset: WebGLUniformLocation | null;
+};
+
+const rgbShiftSchema = {
+  amount: {
+    type: 'number',
+    min: 0,
+    max: 80,
+    step: 1,
+    default: 12,
+    description: 'Amount',
+  },
+} as const satisfies InteractivitySchema;
+
+export const rgbShift = createEffect<RgbShiftParams, RgbShiftState>({
+  type: 'com.example.rgbShift',
+  label: 'rgbShift()',
+  documentationLink: null,
+  backend: 'webgl2',
+  calculateKey: ({amount = 12}) => `rgb-shift-${amount}`,
+  setup: (target) => {
+    const gl = target.getContext('webgl2', {
+      premultipliedAlpha: true,
+      alpha: true,
+      preserveDrawingBuffer: true,
+    });
+    if (!gl) {
+      throw new Error('Could not get a WebGL2 context for rgbShift().');
+    }
+
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+
+    // Compile/link shaders, create a fullscreen quad VAO/VBO, create a
+    // CLAMP_TO_EDGE RGBA texture, and get uSource/uOffset uniform locations.
+    return createRgbShiftState(gl);
+  },
+  apply: ({source, width, height, params, state, flipSourceY}) => {
+    const amount = params.amount ?? 12;
+    const {gl} = state;
+
+    gl.viewport(0, 0, width, height);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flipSourceY);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, state.texture);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      gl.RGBA,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      source as TexImageSource,
+    );
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.useProgram(state.program);
+    if (state.uSource) gl.uniform1i(state.uSource, 0);
+    if (state.uOffset) gl.uniform2f(state.uOffset, amount / width, 0);
+    gl.bindVertexArray(state.vao);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  },
+  cleanup: ({gl, program, vao, vbo, texture}) => {
+    gl.deleteTexture(texture);
+    gl.deleteBuffer(vbo);
+    gl.deleteProgram(program);
+    gl.deleteVertexArray(vao);
+  },
+  schema: rgbShiftSchema,
+  validateParams: ({amount = 12}) => {
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 80) {
+      throw new TypeError('amount must be a number between 0 and 80');
+    }
+  },
+});
+```
+
+For 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`.
+
+Use the returned factory in an `effects` array:
+
+```tsx
+import {CanvasImage, staticFile} from 'remotion';
+import {myEffect} from './effects/my-effect';
+
+export const MyComp: React.FC = () => {
+  return (
+    <CanvasImage
+      src={staticFile('image.png')}
+      effects={[myEffect({amount: 0.8})]}
+    />
+  );
+};
+```
+
+When generating a custom effect, also:
+
+- Include `disabled?: boolean` only through the returned factory; do not add it to the custom params type or schema.
+- Validate required parameters at factory-call time with `validateParams`.
+- Include all defaults in both `schema` and the `resolve()` helper.
+- Reset mutable 2D context state such as `filter`, `globalAlpha`, transforms, and compositing after drawing.
+- Preserve alpha unless the requested effect intentionally changes transparency.

package/assets/.agent/skills/remotion/rules/ffmpeg.md

@@ -0,0 +1,34 @@
+---
+name: ffmpeg
+description: Using FFmpeg and FFprobe in Remotion
+metadata:
+  tags: ffmpeg, ffprobe, video, trimming
+---
+
+## FFmpeg in Remotion
+
+`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `npx remotion ffmpeg` and `npx remotion ffprobe`:
+
+```bash
+npx remotion ffmpeg -i input.mp4 output.mp3
+npx remotion ffprobe input.mp4
+```
+
+### Trimming videos
+
+You have 2 options for trimming videos:
+
+1. **Preferred**: Use the `trimBefore` and `trimAfter` props of the `<Video>` component. This is non-destructive, requires no re-encoding, and you can change the trim at any time.
+
+```tsx
+import {Video} from '@remotion/media';
+
+<Video src={staticFile('video.mp4')} trimBefore={5 * fps} trimAfter={10 * fps} />;
+```
+
+2. Use the FFmpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video. Only use this if you need a standalone trimmed file (e.g. for upload or external use).
+
+```bash
+# Re-encodes from the exact frame
+npx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
+```

package/assets/.agent/skills/remotion/rules/get-audio-duration.md

@@ -11,7 +11,7 @@ Mediabunny can extract the duration of an audio file. It works in browser, Node.
 
 ## Getting audio duration
 
-```tsx
+```tsx title="get-audio-duration.ts"
 import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
 
 export const getAudioDuration = async (src: string) => {
@@ -34,25 +34,25 @@ const duration = await getAudioDuration("https://remotion.media/audio.mp3");
 console.log(duration); // e.g. 180.5 (seconds)
 ```
 
-## Using with local files
+## Using with staticFile in Remotion
 
-For local files, use `FileSource` instead of `UrlSource`:
+Make sure to wrap the file path in `staticFile()`:
 
 ```tsx
-import { Input, ALL_FORMATS, FileSource } from "mediabunny";
-
-const input = new Input({
-  formats: ALL_FORMATS,
-  source: new FileSource(file), // File object from input or drag-drop
-});
+import { staticFile } from "remotion";
 
-const durationInSeconds = await input.computeDuration();
+const duration = await getAudioDuration(staticFile("audio.mp3"));
 ```
 
-## Using with staticFile in Remotion
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
 
 ```tsx
-import { staticFile } from "remotion";
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
 
-const duration = await getAudioDuration(staticFile("audio.mp3"));
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
 ```

package/assets/.agent/skills/remotion/rules/get-video-dimensions.md

@@ -38,7 +38,7 @@ export const getVideoDimensions = async (src: string) => {
 
 ```tsx
 const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
-console.log(dimensions.width);  // e.g. 1920
+console.log(dimensions.width); // e.g. 1920
 console.log(dimensions.height); // e.g. 1080
 ```
 

package/assets/.agent/skills/remotion/rules/get-video-duration.md

@@ -34,9 +34,19 @@ const duration = await getVideoDuration("https://remotion.media/video.mp4");
 console.log(duration); // e.g. 10.5 (seconds)
 ```
 
-## Using with local files
+## Video files from the public/ directory
 
-For local files, use `FileSource` instead of `UrlSource`:
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
 
 ```tsx
 import { Input, ALL_FORMATS, FileSource } from "mediabunny";
@@ -48,11 +58,3 @@ const input = new Input({
 
 const durationInSeconds = await input.computeDuration();
 ```
-
-## Using with staticFile in Remotion
-
-```tsx
-import { staticFile } from "remotion";
-
-const duration = await getVideoDuration(staticFile("video.mp4"));
-```

package/assets/.agent/skills/remotion/rules/gifs.md

@@ -12,17 +12,23 @@ metadata:
 Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
 
 ```tsx
-import {AnimatedImage, staticFile} from 'remotion';
+import { AnimatedImage, staticFile } from "remotion";
 
 export const MyComposition = () => {
-  return <AnimatedImage src={staticFile('animation.gif')} width={500} height={500} />;
+  return (
+    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
+  );
 };
 ```
 
 Remote URLs are also supported (must have CORS enabled):
 
 ```tsx
-<AnimatedImage src="https://example.com/animation.gif" width={500} height={500} />
+<AnimatedImage
+  src="https://example.com/animation.gif"
+  width={500}
+  height={500}
+/>
 ```
 
 ## Sizing and fit
@@ -70,12 +76,12 @@ Use the `style` prop for additional CSS (use `width` and `height` props for sizi
 
 ```tsx
 <AnimatedImage
-  src={staticFile('animation.gif')}
+  src={staticFile("animation.gif")}
   width={500}
   height={500}
   style={{
     borderRadius: 20,
-    position: 'absolute',
+    position: "absolute",
     top: 100,
     left: 50,
   }}
@@ -87,28 +93,25 @@ Use the `style` prop for additional CSS (use `width` and `height` props for sizi
 Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
 
 ```bash
-npx remotion add @remotion/gif # If project uses npm
-bunx remotion add @remotion/gif # If project uses bun
-yarn remotion add @remotion/gif # If project uses yarn
-pnpm exec remotion add @remotion/gif # If project uses pnpm
+npx remotion add @remotion/gif
 ```
 
 ```tsx
-import {getGifDurationInSeconds} from '@remotion/gif';
-import {staticFile} from 'remotion';
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile } from "remotion";
 
-const duration = await getGifDurationInSeconds(staticFile('animation.gif'));
+const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
 console.log(duration); // e.g. 2.5
 ```
 
 This is useful for setting the composition duration to match the GIF:
 
 ```tsx
-import {getGifDurationInSeconds} from '@remotion/gif';
-import {staticFile, CalculateMetadataFunction} from 'remotion';
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile, CalculateMetadataFunction } from "remotion";
 
 const calculateMetadata: CalculateMetadataFunction = async () => {
-  const duration = await getGifDurationInSeconds(staticFile('animation.gif'));
+  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
   return {
     durationInFrames: Math.ceil(duration * 30),
   };
@@ -127,11 +130,11 @@ pnpm exec remotion add @remotion/gif # If project uses pnpm
 ```
 
 ```tsx
-import {Gif} from '@remotion/gif';
-import {staticFile} from 'remotion';
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
 
 export const MyComposition = () => {
-  return <Gif src={staticFile('animation.gif')} width={500} height={500} />;
+  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
 };
 ```
 

package/assets/.agent/skills/remotion/rules/google-fonts.md

@@ -0,0 +1,72 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+  tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily }}>Hello World</div>;
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <h1
+      style={{
+        fontFamily,
+        fontSize: 80,
+        fontWeight: "bold",
+      }}
+    >
+      {text}
+    </h1>
+  );
+};
+```

package/assets/.agent/skills/remotion/rules/html-in-canvas.md

@@ -0,0 +1,122 @@
+# Using `<HtmlInCanvas>` in Remotion
+
+Renders children into a `<canvas>` so you can post-process them with the Canvas 2D API or WebGL.
+
+Only works in Chrome 149+ with the `chrome://flags/#canvas-draw-element` flag enabled.  
+Give the user a notice.
+
+## Nesting
+
+Do not nest `<HtmlInCanvas>` inside another `<HtmlInCanvas>`. Remotion throws:
+
+```
+<HtmlInCanvas> effects cannot be nested together. Chrome will only display the outer effect. Consider merging the effects into one if you can.
+```
+
+## Enabling WebGL during renders
+
+If you make use of WebGL during renders, you need to enable it:
+
+From the CLI:
+
+```bash
+npx remotion render --gl=angle
+```
+
+Set it as the default for Studio and CLI (advised):
+
+```ts
+import { Config } from "@remotion/cli/config";
+
+Config.setChromiumOpenGlRenderer("angle");
+```
+
+## Basic usage
+
+By default, draws to canvas with no effect applied:
+
+```tsx
+import { HtmlInCanvas } from "remotion";
+
+export const MyComp = () => {
+  return (
+    <HtmlInCanvas width={1280} height={720}>
+      <div style={{ fontSize: 80 }}>Hello</div>
+    </HtmlInCanvas>
+  );
+};
+```
+
+## 2D effect with `onPaint`
+
+`onPaint` runs whenever the content updates. Call `ctx.drawElementImage(elementImage, 0, 0)` to draw the captured DOM, and assign the returned transform to `element.style.transform` so DOM selection still aligns with the painted output.
+
+```tsx
+import {
+  AbsoluteFill,
+  HtmlInCanvas,
+  type HtmlInCanvasOnPaint,
+  useCurrentFrame,
+  useVideoConfig,
+} from "remotion";
+import { useCallback } from "react";
+
+export const Blur = () => {
+  const frame = useCurrentFrame();
+  const { width, height, fps } = useVideoConfig();
+
+  const onPaint: HtmlInCanvasOnPaint = useCallback(
+    ({ canvas, element, elementImage }) => {
+      const ctx = canvas.getContext("2d");
+      if (!ctx) throw new Error("Failed to acquire 2D context");
+
+      const blurPx = 4 + 18 * (0.5 + 0.5 * Math.sin((frame / fps) * Math.PI));
+
+      ctx.reset();
+      ctx.filter = `blur(${blurPx}px)`;
+      const transform = ctx.drawElementImage(elementImage, 0, 0);
+      element.style.transform = transform.toString();
+    },
+    [frame, fps],
+  );
+
+  return (
+    <HtmlInCanvas width={width} height={height} onPaint={onPaint}>
+      <AbsoluteFill style={{ justifyContent: "center", alignItems: "center", fontSize: 120 }}>
+        <h1>Hello</h1>
+      </AbsoluteFill>
+    </HtmlInCanvas>
+  );
+};
+```
+
+## WebGL effects
+
+For WebGL, set up the context, program, and texture in `onInit` and return a cleanup function. Inside `onPaint`, upload the captured DOM with `gl.texElementImage2D(...)` and draw.
+
+```tsx
+const onInit: HtmlInCanvasOnInit = useCallback(({ canvas }) => {
+  const gl = canvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true });
+  if (!gl) {
+    throw new Error(
+      "WebGL2 unavailable. Try rendering with the --gl=angle option. See https://remotion.dev/docs/gl-options.",
+    );
+  }
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+  // compile program, create texture, set up VAO...
+  return () => {
+    // delete program, texture, buffers...
+  };
+}, []);
+
+const onPaint: HtmlInCanvasOnPaint = useCallback(({ elementImage }) => {
+  gl.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, elementImage);
+  gl.drawArrays(gl.TRIANGLES, 0, 6);
+}, []);
+```
+
+For a fully working minimal example, see https://github.com/remotion-dev/remotion/blob/main/packages/docs/components/demos/HtmlInCanvasDocsDemoWebGL.tsx.
+
+## Async `onPaint`
+
+`onPaint` may be `async`. Remotion holds the frame open via `delayRender()` until the promise resolves. Useful for multi-pass effects with `createImageBitmap`.