@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/templates/default/.claude/skills/remotion-best-practices/remotion-markup/audio.md

@@ -0,0 +1,171 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `<Audio>` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Audio src="https://remotion.media/audio.mp3" />
+```
+
+By default, audio plays from the start, at full volume and full length.
+Multiple audio tracks can be layered by adding multiple `<Audio>` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+The audio still starts playing at the beginning of the composition - only the specified portion is played.
+
+## Delaying
+
+Wrap the audio in a `<Sequence>` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Audio src={staticFile("audio.mp3")} />
+  </Sequence>
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Audio src={staticFile("audio.mp3")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+  />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+// 2x speed
+<Audio src={staticFile("audio.mp3")} playbackRate={2} />
+// Half speed
+<Audio src={staticFile("audio.mp3")} playbackRate={0.5} />
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the audio indefinitely:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (default)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

package/templates/default/.claude/skills/remotion-best-practices/remotion-markup/calculate-metadata.md

@@ -0,0 +1,136 @@
+---
+name: calculate-metadata
+description: Dynamically set composition duration, dimensions, and props
+metadata:
+  tags: calculateMetadata, duration, dimensions, props, dynamic
+---
+
+# Using calculateMetadata
+
+Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
+Use it when metadata depends on input props, fetched data, or asset metadata.
+For static dimensions, duration, FPS, and initial props, inline the values on `<Composition>` instead.
+
+```tsx
+<Composition
+  id="MyComp"
+  component={MyComponent}
+  durationInFrames={300}
+  fps={30}
+  width={1920}
+  height={1080}
+  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
+  calculateMetadata={calculateMetadata}
+/>
+```
+
+## Setting duration based on a video
+
+Use the [`getVideoDuration`](../remotion-multimedia/get-video-duration.md) and [`getVideoDimensions`](../remotion-multimedia/get-video-dimensions.md) skills to get the video duration and dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+  return {
+    durationInFrames: Math.ceil(durationInSeconds * 30),
+  };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](../remotion-multimedia/get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const dimensions = await getVideoDimensions(props.videoSrc);
+
+  return {
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const metadataPromises = props.videos.map((video) =>
+    getVideoDuration(video.src),
+  );
+  const allMetadata = await Promise.all(metadataPromises);
+
+  const totalDuration = allMetadata.reduce(
+    (sum, durationInSeconds) => sum + durationInSeconds,
+    0,
+  );
+
+  return {
+    durationInFrames: Math.ceil(totalDuration * 30),
+  };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultOutName: `video-${props.id}`, // .mp4 is added automatically
+  };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+  abortSignal,
+}) => {
+  const response = await fetch(props.dataUrl, { signal: abortSignal });
+  const data = await response.json();
+
+  return {
+    props: {
+      ...props,
+      fetchedData: data,
+    },
+  };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `<Composition>` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering

package/templates/default/.claude/skills/remotion-best-practices/remotion-markup/compositions.md

@@ -0,0 +1,117 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+  tags: composition, still, folder, props, metadata
+---
+
+A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
+
+## Default Props and scaffold metadata
+
+Pass `defaultProps` to provide initial values for your component.  
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+Use `defaultProps` for composition-wide values that should be visible and editable before the video renders.
+
+For Studio editing, keep `defaultProps` as an inline object literal on `<Composition>` or `<Still>`.
+Do not store it in a variable, import it, spread it, create it with a helper, or wrap it in `satisfies`.
+When scaffolding, keep the component and `<Composition>` registration in the same file so `width`, `height`, `fps`, `durationInFrames`, and `defaultProps` are visible next to the code that uses them.
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+```tsx
+type Props = {
+  readonly title: string;
+};
+
+export const MyComposition = ({ title }: Props) => (
+  <h1>
+    {title}
+  </h1>
+);
+
+const defaultProps = { title: "Hello World" };
+
+// 👍 Inline metadata and defaults
+<Composition
+  id="MyComposition"
+  component={MyComposition}
+  durationInFrames={100}
+  fps={30}
+  width={1080}
+  height={1080}
+  defaultProps={{ title: "Hello World" }}
+/>;
+
+// 👎 Hidden defaults cannot be saved back by Studio
+<Composition
+  id="OtherComposition"
+  component={MyComposition}
+  durationInFrames={100}
+  fps={30}
+  width={1080}
+  height={1080}
+  defaultProps={defaultProps}
+/>;
+```
+
+## Folders
+
+Use `<Folder>` to organize compositions in the sidebar.  
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+  return (
+    <>
+      <Folder name="Marketing">
+        <Composition id="Promo" /* ... */ />
+        <Composition id="Ad" /* ... */ />
+      </Folder>
+      <Folder name="Social">
+        <Folder name="Instagram">
+          <Composition id="Story" /* ... */ />
+          <Composition id="Reel" /* ... */ />
+        </Folder>
+      </Folder>
+    </>
+  );
+};
+```
+
+## Stills
+
+Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+  return (
+    <Still
+      id="Thumbnail"
+      component={Thumbnail}
+      width={1280}
+      height={720}
+    />
+  );
+};
+```
+
+## Dynamic duration, width, and height
+
+Use [`calculateMetadata`](./calculate-metadata.md) to make dimensions, duration, or props dynamic based on input props, fetched data, or asset metadata.
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```

package/templates/default/.claude/skills/remotion-best-practices/remotion-markup/cropping.md

@@ -0,0 +1,34 @@
+# Cropping
+
+Preferably, the `cropLeft`, `cropRight`, `cropTop` and `cropBottom` props are used to crop content.
+It allows for interactively dragging the components and adapting the outlines in the canvas to the crop.
+
+The following components support `crop*` props:
+
+- `<Sequence>` from `remotion`, when `layout="absolute-fill"`
+- `<CanvasImage>` from `remotion`
+- `<Img>` from `remotion`
+- `<AnimatedImage>` from `remotion`
+- `<HtmlInCanvas>` from `remotion`
+- `<Solid>` from `remotion`
+- `<Video>` from `@remotion/media`
+- `<Gif>` from `@remotion/gif`
+- `<RemotionRiveCanvas>` from `@remotion/rive`
+
+Crop values are ratios between `0` and `1`.
+A value of `0` applies no crop on that edge.
+A value of `1` is a full crop.
+Keep [Interactivity Best Practices](../remotion-interactivity/REFERENCE.md) also for cropping, to keep it editable and keyframable.
+
+```tsx
+<CanvasImage
+  src={staticFile("photo.png")}
+  cropLeft={interpolate(frame, [0, 30], [0, 0.25], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  })}
+  cropBottom={0.1}
+/>
+```
+
+Do not use `clipPath` together with crop props.

package/templates/default/.claude/skills/remotion-best-practices/remotion-markup/effects.md

@@ -0,0 +1,251 @@
+---
+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
+```
+
+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`.
+
+These effects use WebGL2. During renders, enable WebGL with:
+
+```ts
+import {Config} from '@remotion/cli/config';
+
+Config.setChromiumOpenGlRenderer('angle');
+```
+
+## Available effects
+
+`brightness()`, `contrast()`, `colorKey()`, `duotone()`, `grayscale()`, `hue()`, `invert()`, `saturation()`, `tint()`, `linearGradient()`, `linearGradientTint()`, `thermalVision()`, `blur()`, `linearProgressiveBlur()`, `radialProgressiveBlur()`, `zoomBlur()`, `dropShadow()`, `glow()`, `lightTrail()`, `evolve()`, `venetianBlinds()`, `mirror()`, `scale()`, `uvTranslate()`, `xyTranslate()`, `barrelDistortion()`, `chromaticAberration()`, `fisheye()`, `cornerPin()`, `wave()`, `burlap()`, `emboss()`, `dotGrid()`, `halftone()`, `noise()`, `noiseDisplacement()`, `paper()`, `roughenEdges()`, `pattern()`, `pixelate()`, `pixelDissolve()`, `scanlines()`, `speckle()`, `shine()`, `shrinkwrap()`, `vignette()`, `contourLines()`, `checkerboard()`, `halftoneLinearGradient()`, `gridlines()`, `whiteNoise()`, `tvSignalOff()`, `lines()`, `rings()`, `waves()`, `zigzag()`, `lightLeak()`, `starburst()`.
+
+Example:
+
+```tsx
+import {brightness} from "@remotion/effects";
+
+<Video
+  src="https://remotion.media/video.mp4"
+  effects={[brightness({})]}
+/>;
+```
+
+## 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.