takomi 2.5.1 → 2.5.4

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

@@ -1,102 +1,172 @@
 ---
 name: transitions
-description: Fullscreen scene transitions for Remotion.
+description: Scene transitions and overlays for Remotion using TransitionSeries.
 metadata:
-  tags: transitions, fade, slide, wipe, scenes
+  tags: transitions, overlays, fade, slide, wipe, scenes
 ---
 
-## Fullscreen transitions
+## TransitionSeries
 
-Using `<TransitionSeries>` to animate between multiple scenes or clips.  
-This will absolutely position the children.
+`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
 
-## Prerequisites
+- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
 
-First, the @remotion/transitions package needs to be installed.  
-If it is not, use the following command:
+## Prerequisites
 
 ```bash
-npx remotion add @remotion/transitions # If project uses npm
-bunx remotion add @remotion/transitions # If project uses bun
-yarn remotion add @remotion/transitions # If project uses yarn
-pnpm exec remotion add @remotion/transitions # If project uses pnpm
+npx remotion add @remotion/transitions
 ```
 
-## Example usage
+## Transition example
 
 ```tsx
-import {TransitionSeries, linearTiming} from '@remotion/transitions';
-import {fade} from '@remotion/transitions/fade';
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
 
 <TransitionSeries>
   <TransitionSeries.Sequence durationInFrames={60}>
     <SceneA />
   </TransitionSeries.Sequence>
-  <TransitionSeries.Transition presentation={fade()} timing={linearTiming({durationInFrames: 15})} />
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
   <TransitionSeries.Sequence durationInFrames={60}>
     <SceneB />
   </TransitionSeries.Sequence>
 </TransitionSeries>;
 ```
 
-## Available Transition Types
+## Overlay example
 
-Import transitions from their respective modules:
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={20}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
 
 ```tsx
-import {fade} from '@remotion/transitions/fade';
-import {slide} from '@remotion/transitions/slide';
-import {wipe} from '@remotion/transitions/wipe';
-import {flip} from '@remotion/transitions/flip';
-import {clockWipe} from '@remotion/transitions/clock-wipe';
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneC />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
 ```
 
-## Slide Transition with Direction
+## Transition props
+
+`<TransitionSeries.Transition>` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`<TransitionSeries.Overlay>` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
 
-Specify slide direction for enter/exit animations.
+## Slide transition with direction
 
 ```tsx
-import {slide} from '@remotion/transitions/slide';
+import { slide } from "@remotion/transitions/slide";
 
-<TransitionSeries.Transition presentation={slide({direction: 'from-left'})} timing={linearTiming({durationInFrames: 20})} />;
+<TransitionSeries.Transition
+  presentation={slide({ direction: "from-left" })}
+  timing={linearTiming({ durationInFrames: 20 })}
+/>;
 ```
 
 Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
 
-## Timing Options
+## Timing options
 
 ```tsx
-import {linearTiming, springTiming} from '@remotion/transitions';
+import { linearTiming, springTiming } from "@remotion/transitions";
 
 // Linear timing - constant speed
-linearTiming({durationInFrames: 20});
+linearTiming({ durationInFrames: 20 });
 
 // Spring timing - organic motion
-springTiming({config: {damping: 200}, durationInFrames: 25});
+springTiming({ config: { damping: 200 }, durationInFrames: 25 });
 ```
 
 ## Duration calculation
 
-Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations.
+Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
 
 For example, with two 60-frame sequences and a 15-frame transition:
 
 - Without transitions: `60 + 60 = 120` frames
 - With transition: `60 + 60 - 15 = 105` frames
 
-The transition duration is subtracted because both scenes play simultaneously during the transition.
+Adding an overlay between two other sequences does not change the total.
 
 ### Getting the duration of a transition
 
 Use the `getDurationInFrames()` method on the timing object:
 
 ```tsx
-import {linearTiming, springTiming} from '@remotion/transitions';
+import { linearTiming, springTiming } from "@remotion/transitions";
 
-const linearDuration = linearTiming({durationInFrames: 20}).getDurationInFrames({fps: 30});
+const linearDuration = linearTiming({
+  durationInFrames: 20,
+}).getDurationInFrames({ fps: 30 });
 // Returns 20
 
-const springDuration = springTiming({config: {damping: 200}}).getDurationInFrames({fps: 30});
+const springDuration = springTiming({
+  config: { damping: 200 },
+}).getDurationInFrames({ fps: 30 });
 // Returns calculated duration based on spring physics
 ```
 
@@ -105,18 +175,23 @@ For `springTiming` without an explicit `durationInFrames`, the duration depends
 ### Calculating total composition duration
 
 ```tsx
-import {linearTiming} from '@remotion/transitions';
+import { linearTiming } from "@remotion/transitions";
 
 const scene1Duration = 60;
 const scene2Duration = 60;
 const scene3Duration = 60;
 
-const timing1 = linearTiming({durationInFrames: 15});
-const timing2 = linearTiming({durationInFrames: 20});
+const timing1 = linearTiming({ durationInFrames: 15 });
+const timing2 = linearTiming({ durationInFrames: 20 });
 
-const transition1Duration = timing1.getDurationInFrames({fps: 30});
-const transition2Duration = timing2.getDurationInFrames({fps: 30});
+const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
+const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
 
-const totalDuration = scene1Duration + scene2Duration + scene3Duration - transition1Duration - transition2Duration;
+const totalDuration =
+  scene1Duration +
+  scene2Duration +
+  scene3Duration -
+  transition1Duration -
+  transition2Duration;
 // 60 + 60 + 60 - 15 - 20 = 145 frames
 ```

package/assets/.agent/skills/remotion/rules/transparent-videos.md

@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+  tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "prores",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva444p10le",
+    defaultProResProfile: "4444",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
+
+## Transparent WebM (VP9)
+
+Ideal for when playing in a browser.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp9");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "vp8",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva420p",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```

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

@@ -18,7 +18,7 @@ const fps = useVideoConfig();
 
 <Sequence from={-0.5 * fps}>
   <MyAnimation />
-</Sequence>
+</Sequence>;
 ```
 
 The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
@@ -29,7 +29,6 @@ Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
 Use `durationInFrames` to unmount content after a specified duration:
 
 ```tsx
-
 <Sequence durationInFrames={1.5 * fps}>
   <MyAnimation />
 </Sequence>
@@ -50,4 +49,3 @@ Nest sequences to both trim the beginning and delay when it appears:
 ```
 
 The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.
-

package/assets/.agent/skills/remotion/rules/video-layout.md

@@ -0,0 +1,68 @@
+---
+name: video-layout
+description: Video-first layout, composition, and text sizing guidance for Remotion.
+metadata:
+  tags: layout, composition, typography, text, motion graphics, promo
+---
+
+# Video layout
+
+Videos are watched differently than web pages are read. Design for quick understanding from the full frame, not for a dense UI that rewards close inspection.
+
+## Start from the frame
+
+- Decide what the viewer should notice first in each scene. Build the frame around that one thing.
+- Keep important content inside a generous safe area. For 1080px-wide videos, keep key text at least 80px from the sides and 100px from the top and bottom.
+- Prefer centered, stacked, or strongly aligned layouts. Avoid scattered dashboard-like layouts.
+- Use empty space intentionally. A video frame with one strong message is usually better than a frame full of widgets.
+- Do not place objects side by side just because there is room. If two elements compete, show them one after another or make one clearly secondary.
+
+## Default scene structure
+
+For promos, explainers, and motion graphics, a good default scene is:
+
+- One main text message
+- One supporting visual, such as an icon, product card, shape, or screenshot-style mockup
+- One or two background accents
+
+Avoid defaulting to many cards, badges, borders, pills, or tiny labels. Those are web UI patterns and often make videos feel cluttered.
+
+## Prevent overlap by construction
+
+- Do not manually position every readable element with independent `top`, `left`, `right`, or `bottom` values.
+- Put readable content in normal layout containers using `flex`, `grid`, `gap`, `justifyContent`, and `alignItems`.
+- Use absolute positioning mainly for backgrounds, decorative shapes, glows, particles, and elements that are meant to layer behind the content.
+- Reserve a slot for each major element in the scene. For example, a vertical promo scene can use a centered column with `gap` for headline, card, and CTA.
+- Animate elements from their reserved slot using `opacity`, `transform`, and `scale`; do not animate them into a space occupied by another element.
+- If an element enters from offscreen or from another part of the frame, its final resting position must still belong to a layout slot.
+- When text length is unknown or user-provided, assume it may wrap. Give the text block enough width and vertical room instead of placing another object immediately under it.
+
+## Text in video
+
+- Text must be readable at video-viewing distance. If unsure, make it larger, not smaller.
+- Treat small text as decorative unless the user explicitly needs it to be read.
+- For 1080px-wide compositions, use these rough minimums:
+  - Main headline: 84px
+  - Important supporting text: 44px
+  - Labels or short callouts: 32px
+- Scale those values with the composition width. For example, a 1920px-wide composition needs larger text than a 1080px-wide composition.
+- Keep line lengths short. Break long ideas into multiple scenes instead of shrinking the font.
+- Use strong contrast between text and background. Add a subtle backing shape or simplify the background if the text is hard to read.
+- Do not stack many text blocks in the same area. Give each message its own moment or clearly separated region.
+
+## Solve crowding with time
+
+- Let time solve layout problems. Instead of showing every feature at once, reveal them one after another.
+- If a frame feels crowded, remove an element, enlarge the focal element, or move the secondary element to another scene.
+- Favor centered or strongly aligned compositions over scattered UI layouts.
+- Use background shapes, gradients, and cards to support the message, not to create visual noise.
+- Keep the visual system consistent across scenes: repeated spacing, repeated alignment, and a small set of shapes/colors.
+
+## Pre-render check
+
+Before rendering, inspect a representative frame at normal size:
+
+- Can the main message be read quickly?
+- Is there one obvious focal point?
+- Are any objects touching, overlapping, or awkwardly sitting next to each other?
+- Would the frame still make sense if seen for less than one second?

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

@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using TTS
+metadata:
+  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+By default this guide uses **ElevenLabs** as the TTS provider (`ELEVENLABS_API_KEY` environment variable). Users may substitute any TTS service that can produce an audio file.
+
+If the user has not specified a TTS provider, recommend ElevenLabs and ask for their API key.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+  {
+    method: "POST",
+    headers: {
+      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify({
+      text: "Welcome to the show.",
+      model_id: "eleven_multilingual_v2",
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+      },
+    }),
+  },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+  "voiceover/my-comp/scene-01-intro.mp3",
+  "voiceover/my-comp/scene-02-main.mp3",
+  "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durations = await Promise.all(
+    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+  );
+
+  const sceneDurations = durations.map((durationInSeconds) => {
+    return durationInSeconds * FPS;
+  });
+
+  return {
+    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+  };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.