Skip to content

🎥 Make videos programmatically with React

Skills: Replace `volume` callbacks with inline keyframes

Jonny Burger6457ebb491d0
diff --git a/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/audio.md b/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/audio.md
index 0c14aff021..04093597bd 100644
--- a/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/audio.md
+++ b/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/audio.md
@@ -87,25 +87,51 @@ import { Audio } from "@remotion/media";
<Audio src={staticFile("audio.mp3")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
import { Audio } from "@remotion/media";
-import { interpolate } from "remotion";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
+```
+
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Audio>` does not reset this frame. Offset the keyframes to match when the audio starts:
+
+```tsx
+import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Audio
src={staticFile("audio.mp3")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ from={1 * fps}
+ premountFor={fps}
+ volume={interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
-The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+This fades in during the first second of playback. `trimBefore` and `playbackRate` on the audio change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
## Muting
@@ -147,25 +173,35 @@ Use `loop` to loop the audio indefinitely:
```tsx
import { Audio } from "@remotion/media";
-<Audio src={staticFile("audio.mp3")} loop />
+<Audio src={staticFile("audio.mp3")} loop premountFor={fps} />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+Put `name`, `from`, `loop`, `volume`, and `premountFor` directly on `<Audio>`.
-- `"repeat"`: Frame count resets to 0 each loop (default)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-<Audio
- src={staticFile("audio.mp3")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/embedding-videos.md b/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/embedding-videos.md
index fd0dd42fce..c3d8deab8b 100644
--- a/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/embedding-videos.md
+++ b/packages/codex-plugin/skills/remotion-best-practices/remotion-markup/embedding-videos.md
@@ -95,23 +95,32 @@ Set a static volume (0 to 1):
<Video src={staticFile("video.mp4")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
-import { interpolate } from "remotion";
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Video
src={staticFile("video.mp4")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Video>` does not reset this frame. For a video starting at `from={1 * fps}`, fade in with `interpolate(frame, [1 * fps, 2 * fps], [0, 1], {...})`.
+
+`trimBefore` and `playbackRate` on the video change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
+
Use `muted` to silence the video entirely:
```tsx
@@ -139,20 +148,30 @@ Use `loop` to loop the video indefinitely:
<Video src={staticFile("video.mp4")} loop />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
-<Video
- src={staticFile("video.mp4")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Video
+ src={staticFile("video.mp4")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/codex-plugin/skills/remotion-markup/audio.md b/packages/codex-plugin/skills/remotion-markup/audio.md
index 0c14aff021..04093597bd 100644
--- a/packages/codex-plugin/skills/remotion-markup/audio.md
+++ b/packages/codex-plugin/skills/remotion-markup/audio.md
@@ -87,25 +87,51 @@ import { Audio } from "@remotion/media";
<Audio src={staticFile("audio.mp3")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
import { Audio } from "@remotion/media";
-import { interpolate } from "remotion";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
+```
+
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Audio>` does not reset this frame. Offset the keyframes to match when the audio starts:
+
+```tsx
+import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Audio
src={staticFile("audio.mp3")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ from={1 * fps}
+ premountFor={fps}
+ volume={interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
-The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+This fades in during the first second of playback. `trimBefore` and `playbackRate` on the audio change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
## Muting
@@ -147,25 +173,35 @@ Use `loop` to loop the audio indefinitely:
```tsx
import { Audio } from "@remotion/media";
-<Audio src={staticFile("audio.mp3")} loop />
+<Audio src={staticFile("audio.mp3")} loop premountFor={fps} />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+Put `name`, `from`, `loop`, `volume`, and `premountFor` directly on `<Audio>`.
-- `"repeat"`: Frame count resets to 0 each loop (default)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-<Audio
- src={staticFile("audio.mp3")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/codex-plugin/skills/remotion-markup/embedding-videos.md b/packages/codex-plugin/skills/remotion-markup/embedding-videos.md
index fd0dd42fce..c3d8deab8b 100644
--- a/packages/codex-plugin/skills/remotion-markup/embedding-videos.md
+++ b/packages/codex-plugin/skills/remotion-markup/embedding-videos.md
@@ -95,23 +95,32 @@ Set a static volume (0 to 1):
<Video src={staticFile("video.mp4")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
-import { interpolate } from "remotion";
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Video
src={staticFile("video.mp4")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Video>` does not reset this frame. For a video starting at `from={1 * fps}`, fade in with `interpolate(frame, [1 * fps, 2 * fps], [0, 1], {...})`.
+
+`trimBefore` and `playbackRate` on the video change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
+
Use `muted` to silence the video entirely:
```tsx
@@ -139,20 +148,30 @@ Use `loop` to loop the video indefinitely:
<Video src={staticFile("video.mp4")} loop />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
-<Video
- src={staticFile("video.mp4")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Video
+ src={staticFile("video.mp4")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/docs/docs/audio/volume.mdx b/packages/docs/docs/audio/volume.mdx
index 02ce8fe81d..6a3eccc09c 100644
--- a/packages/docs/docs/audio/volume.mdx
+++ b/packages/docs/docs/audio/volume.mdx
@@ -26,7 +26,7 @@ export const MyComposition = () => {
## Changing volume over time
-You can also change volume over time using [`useCurrentFrame()`](/docs/use-current-frame) and [`interpolate()`](/docs/interpolate).
+To animate volume, use [`useCurrentFrame()`](/docs/use-current-frame) and pass the result of [`interpolate()`](/docs/interpolate) directly to `volume`. This is the recommended pattern for audio and video.
```tsx twoslash {6,11} title="MyComp.tsx"
import {Audio} from '@remotion/media';
@@ -50,23 +50,41 @@ Select an audio or video timeline row and press <kbd>V</kbd> to select its `volu
Note that because values below 0 are not allowed, we need to set the [`extrapolateLeft: 'clamp'`](/docs/interpolate#extrapolateleft) option to ensure no negative values.
-## Media-relative and procedural volume
+## Timing volume keyframes
-The `volume` prop also accepts a callback. Use it when the volume should be relative to the start of the media or when the curve cannot be expressed as editable keyframes:
+[`useCurrentFrame()`](/docs/use-current-frame) returns the frame in the component where it is called: the composition frame at the root, or the local frame inside a [`<Sequence>`](/docs/sequence). Setting `from` on the media does not reset the frame used to calculate its props.
-```tsx twoslash {9} title="MyComp.tsx"
+For audio starting after 1 second, move the volume keyframes to `[1 * fps, 2 * fps]` to fade in during its first second of playback:
+
+```tsx twoslash {11,14} title="MyComp.tsx"
import {Audio} from '@remotion/media';
-import {interpolate, staticFile, useVideoConfig} from 'remotion';
+import {interpolate, staticFile, useCurrentFrame, useVideoConfig} from 'remotion';
export const MyComposition = () => {
+ const frame = useCurrentFrame();
const {fps} = useVideoConfig();
return (
- <Audio src={staticFile('audio.mp3')} volume={(mediaFrame) => interpolate(mediaFrame, [0, 1 * fps], [0, 1], {extrapolateRight: 'clamp'})} />
+ <Audio
+ src={staticFile('audio.mp3')}
+ from={1 * fps}
+ trimBefore={2 * fps}
+ premountFor={fps}
+ volume={interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ })}
+ />
);
};
```
-The callback frame starts at `0` when the media begins to play and is not necessarily the same as [`useCurrentFrame()`](/docs/use-current-frame). For looped media, [`loopVolumeCurveBehavior`](/docs/media/audio#loopvolumecurvebehavior) controls whether it resets on every loop.
+`trimBefore` changes which source frame plays first; it does not move the volume keyframes. Likewise, `playbackRate` on the media changes its playback speed without scaling keyframes evaluated in the parent. An enclosing sequence's [timing props](/docs/timing) affect `useCurrentFrame()` in its children.
+
+When migrating an existing `volume` callback, its frame starts at `0` when the media first becomes visible. If the media's start is visible in the caller's timeline, offset the keyframes by `from`, as above, to preserve the fade timing. If the media has already started when the caller becomes visible, for example due to a negative `from` or an enclosing trim, start the fade at its first visible frame to preserve the callback's timing.
+
+## Volume across loops
+
+With `volume={interpolate(frame, ...)}`, the media's `loop` prop does not reset the caller's `frame`. The volume envelope continues across media loops. [`loopVolumeCurveBehavior`](/docs/media/audio#loopvolumecurvebehavior) only affects callbacks.
-Callback volume curves are also drawn in the [Studio](/docs/studio), but they are not editable as keyframes.
+To repeat a volume envelope each loop, render the component that calls `useCurrentFrame()` inside a looping [`<Sequence>`](/docs/sequence#loop) or [`<Loop>`](/docs/loop). Match the loop duration to the media's played duration, accounting for trimming and playback speed. To fade across all iterations of an enclosing loop, calculate volume in a component outside that loop and pass the value down.
diff --git a/packages/docs/docs/audiobuffertodataurl.mdx b/packages/docs/docs/audiobuffertodataurl.mdx
index dd79decb1c..9630573294 100644
--- a/packages/docs/docs/audiobuffertodataurl.mdx
+++ b/packages/docs/docs/audiobuffertodataurl.mdx
@@ -25,11 +25,11 @@ const str = audioBufferToDataUrl(audioBuffer);
The following composition will render a sine tone with a C4 pitch.
-```tsx twoslash
+```tsx twoslash title="OfflineAudioBufferExample.tsx"
import {audioBufferToDataUrl} from '@remotion/media-utils';
import {Audio} from '@remotion/media';
import {useCallback, useEffect, useState} from 'react';
-import {cancelRender, continueRender, delayRender, interpolate, useVideoConfig} from 'remotion';
+import {cancelRender, continueRender, delayRender, interpolate, useCurrentFrame, useVideoConfig} from 'remotion';
const C4_FREQUENCY = 261.63;
const sampleRate = 44100;
@@ -37,6 +37,7 @@ const sampleRate = 44100;
export const OfflineAudioBufferExample: React.FC = () => {
const [handle] = useState(() => delayRender());
const [audioBuffer, setAudioBuffer] = useState<string | null>(null);
+ const frame = useCurrentFrame();
const {fps, durationInFrames} = useVideoConfig();
const lengthInSeconds = durationInFrames / fps;
@@ -73,12 +74,10 @@ export const OfflineAudioBufferExample: React.FC = () => {
<Audio
src={audioBuffer}
durationInFrames={100}
- volume={(f) =>
- interpolate(f, [0, 50, 100], [0, 1, 0], {
- extrapolateLeft: 'clamp',
- extrapolateRight: 'clamp',
- })
- }
+ volume={interpolate(frame, [0, 50, 100], [0, 1, 0], {
+ extrapolateLeft: 'clamp',
+ extrapolateRight: 'clamp',
+ })}
/>
) : null;
};
diff --git a/packages/docs/docs/html5-audio.mdx b/packages/docs/docs/html5-audio.mdx
index 14d92d5186..75ffb71b7c 100644
--- a/packages/docs/docs/html5-audio.mdx
+++ b/packages/docs/docs/html5-audio.mdx
@@ -39,7 +39,7 @@ Selects this many source frames starting at `trimBefore`. The audio occupies `du
### `volume?`
-Allows you to control the volume of the audio in it's entirety or frame by frame. Read the page on [using audio](/docs/using-audio) to learn more.
+Allows you to control the volume of the audio in its entirety or frame by frame. Read the [volume guide](/docs/audio/volume) for keyframes and timing.
```tsx twoslash title="Setting a static volume"
import {Html5Audio, staticFile} from 'remotion';
@@ -54,12 +54,14 @@ export const MyVideo = () => {
```
```tsx twoslash title="Changing the volume over time"
-import {Html5Audio, interpolate, staticFile} from 'remotion';
+import {Html5Audio, interpolate, staticFile, useCurrentFrame} from 'remotion';
export const MyVideo = () => {
+ const frame = useCurrentFrame();
+
return (
<>
- <Html5Audio volume={(f) => interpolate(f, [0, 30], [0, 1], {extrapolateLeft: 'clamp'})} src={staticFile('voice.mp3')} />
+ <Html5Audio volume={interpolate(frame, [0, 30], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('voice.mp3')} />
</>
);
};
@@ -73,6 +75,8 @@ Controls the `frame` which is returned when using the [`volume`](#volume) callba
Can be either `"repeat"` (default, start from 0 on each iteration) or `"extend"` (keep increasing frames).
+This prop only affects callbacks. For the recommended `volume={interpolate(frame, ...)}` pattern, the caller's frame controls the envelope. See [volume across loops](/docs/audio/volume#volume-across-loops).
+
### `trimBefore?`<AvailableFrom v="4.0.319"/>
Removes a portion of the audio at the beginning (left side).
diff --git a/packages/docs/docs/html5-video.mdx b/packages/docs/docs/html5-video.mdx
index 6953a120e9..a6e7fca26d 100644
--- a/packages/docs/docs/html5-video.mdx
+++ b/packages/docs/docs/html5-video.mdx
@@ -124,7 +124,7 @@ export const MyComposition = () => {
### `volume?`
-Allows you to control the volume for the whole track or change it on a per-frame basis. Refer to the [using audio](/docs/audio/volume) guide to learn how to use it.
+Allows you to control the volume for the whole track or change it on a per-frame basis. Refer to the [volume guide](/docs/audio/volume) for keyframes and timing.
```tsx twoslash title="Example using static volume"
import {staticFile, Html5Video} from 'remotion';
@@ -140,13 +140,15 @@ export const MyComposition = () => {
```
```tsx twoslash title="Example of a ramp up over 100 frames"
-import {interpolate, staticFile, Html5Video} from 'remotion';
+import {interpolate, staticFile, Html5Video, useCurrentFrame} from 'remotion';
// ---cut---
export const MyComposition = () => {
+ const frame = useCurrentFrame();
+
return (
<>
- <Html5Video volume={(f) => interpolate(f, [0, 100], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('video.webm')} />
+ <Html5Video volume={interpolate(frame, [0, 100], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('video.webm')} />
</>
);
};
@@ -160,6 +162,8 @@ Controls the `frame` which is returned when using the [`volume`](#volume) callba
Can be either `"repeat"` (default, start from 0 on each iteration) or `"extend"` (keep increasing frames).
+This prop only affects callbacks. For the recommended `volume={interpolate(frame, ...)}` pattern, the caller's frame controls the envelope. See [volume across loops](/docs/audio/volume#volume-across-loops).
+
### `name?`<AvailableFrom v="4.0.71"/>
A name and that will be shown as the label of the sequence in the timeline of the Remotion Studio. This property is purely for helping you keep track of items in the timeline.
diff --git a/packages/docs/docs/media/audio.mdx b/packages/docs/docs/media/audio.mdx
index 5b64700a32..eacef88833 100644
--- a/packages/docs/docs/media/audio.mdx
+++ b/packages/docs/docs/media/audio.mdx
@@ -113,8 +113,8 @@ Removes a portion of the audio at the end (right side). If `durationInFrames` en
### `volume?`
-Allows you to control the volume of the audio in it's entirety or frame by frame.
-Read the page on [using audio](/docs/using-audio) to learn more.
+Allows you to control the volume of the audio in its entirety or frame by frame.
+Read the [volume guide](/docs/audio/volume) for keyframes and timing.
```tsx twoslash title="Setting a static volume"
import {staticFile} from 'remotion';
@@ -222,6 +222,8 @@ Controls the `frame` which is returned when using the [`volume`](#volume) callba
Can be either `"repeat"` (default, start from 0 on each iteration) or `"extend"` (keep increasing frames).
+This prop only affects callbacks. For the recommended `volume={interpolate(frame, ...)}` pattern, the caller's frame controls the envelope. See [volume across loops](/docs/audio/volume#volume-across-loops).
+
### `muted?`
The `muted` prop will be respected. It will lead to no audio being played while still keeping the audio tag mounted. It's value may change over time, for example to only mute a certain section of the audio.
diff --git a/packages/docs/docs/media/video.mdx b/packages/docs/docs/media/video.mdx
index 712da35ee1..b1cf17c8e5 100644
--- a/packages/docs/docs/media/video.mdx
+++ b/packages/docs/docs/media/video.mdx
@@ -161,8 +161,8 @@ Removes a portion of the video at the end (right side). If `durationInFrames` en
### `volume?`
-Allows you to control the volume of the audio in it's entirety or frame by frame.
-Read the page on [using audio](/docs/using-audio) to learn more.
+Allows you to control the volume of the audio in its entirety or frame by frame.
+Read the [volume guide](/docs/audio/volume) for keyframes and timing.
```tsx twoslash title="Setting a static volume"
import {staticFile} from 'remotion';
@@ -372,6 +372,8 @@ Controls the `frame` which is returned when using the [`volume`](#volume) callba
Can be either `"repeat"` (default, start from 0 on each iteration) or `"extend"` (keep increasing frames).
+This prop only affects callbacks. For the recommended `volume={interpolate(frame, ...)}` pattern, the caller's frame controls the envelope. See [volume across loops](/docs/audio/volume#volume-across-loops).
+
### `showInTimeline?`
If set to `false`, no layer will be shown in the timeline of the Remotion Studio. The default is `true`.
diff --git a/packages/docs/docs/offthreadvideo.mdx b/packages/docs/docs/offthreadvideo.mdx
index 2644aadbc9..7cc6680875 100644
--- a/packages/docs/docs/offthreadvideo.mdx
+++ b/packages/docs/docs/offthreadvideo.mdx
@@ -109,7 +109,7 @@ If set to `false` (_default_), frames will be extracted as bitmap (BMP), which i
### `volume?`
-Allows you to control the volume for the whole track or change it on a per-frame basis. Refer to the [using audio](/docs/audio/volume) guide to learn how to use it.
+Allows you to control the volume for the whole track or change it on a per-frame basis. Refer to the [volume guide](/docs/audio/volume) for keyframes and timing.
```tsx twoslash title="Example using static volume"
import {OffthreadVideo, staticFile} from 'remotion';
@@ -125,13 +125,15 @@ export const MyComposition = () => {
```
```tsx twoslash title="Example of a ramp up over 100 frames"
-import {interpolate, staticFile, OffthreadVideo} from 'remotion';
+import {interpolate, staticFile, OffthreadVideo, useCurrentFrame} from 'remotion';
// ---cut---
export const MyComposition = () => {
+ const frame = useCurrentFrame();
+
return (
<>
- <OffthreadVideo volume={(f) => interpolate(f, [0, 100], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('video.webm')} />
+ <OffthreadVideo volume={interpolate(frame, [0, 100], [0, 1], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})} src={staticFile('video.webm')} />
</>
);
};
@@ -145,6 +147,8 @@ Controls the `frame` which is returned when using the [`volume`](#volume) callba
Can be either `"repeat"` (default, start from 0 on each iteration) or `"extend"` (keep increasing frames).
+This prop only affects callbacks. For the recommended `volume={interpolate(frame, ...)}` pattern, the caller's frame controls the envelope. See [volume across loops](/docs/audio/volume#volume-across-loops).
+
### `style?`
You can pass any style you can pass to a native HTML element. Keep in mind that during rendering, `<OffthreadVideo>` renders an [`<Img>`](/docs/img) tag, but a `<video>` tag is used during preview.
diff --git a/packages/example/.agents/skills/remotion-markup/audio.md b/packages/example/.agents/skills/remotion-markup/audio.md
index 0c14aff021..04093597bd 100644
--- a/packages/example/.agents/skills/remotion-markup/audio.md
+++ b/packages/example/.agents/skills/remotion-markup/audio.md
@@ -87,25 +87,51 @@ import { Audio } from "@remotion/media";
<Audio src={staticFile("audio.mp3")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
import { Audio } from "@remotion/media";
-import { interpolate } from "remotion";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
+```
+
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Audio>` does not reset this frame. Offset the keyframes to match when the audio starts:
+
+```tsx
+import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Audio
src={staticFile("audio.mp3")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ from={1 * fps}
+ premountFor={fps}
+ volume={interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
-The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+This fades in during the first second of playback. `trimBefore` and `playbackRate` on the audio change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
## Muting
@@ -147,25 +173,35 @@ Use `loop` to loop the audio indefinitely:
```tsx
import { Audio } from "@remotion/media";
-<Audio src={staticFile("audio.mp3")} loop />
+<Audio src={staticFile("audio.mp3")} loop premountFor={fps} />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+Put `name`, `from`, `loop`, `volume`, and `premountFor` directly on `<Audio>`.
-- `"repeat"`: Frame count resets to 0 each loop (default)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-<Audio
- src={staticFile("audio.mp3")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/example/.agents/skills/remotion-markup/embedding-videos.md b/packages/example/.agents/skills/remotion-markup/embedding-videos.md
index fd0dd42fce..c3d8deab8b 100644
--- a/packages/example/.agents/skills/remotion-markup/embedding-videos.md
+++ b/packages/example/.agents/skills/remotion-markup/embedding-videos.md
@@ -95,23 +95,32 @@ Set a static volume (0 to 1):
<Video src={staticFile("video.mp4")} volume={0.5} />
```
-Or use a callback for dynamic volume based on the current frame:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
-import { interpolate } from "remotion";
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+const frame = useCurrentFrame();
const { fps } = useVideoConfig();
return (
<Video
src={staticFile("video.mp4")}
- volume={(f) =>
- interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
- }
+ volume={interpolate(frame, [0, 1 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
/>
);
```
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Video>` does not reset this frame. For a video starting at `from={1 * fps}`, fade in with `interpolate(frame, [1 * fps, 2 * fps], [0, 1], {...})`.
+
+`trimBefore` and `playbackRate` on the video change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
+
Use `muted` to silence the video entirely:
```tsx
@@ -139,20 +148,30 @@ Use `loop` to loop the video indefinitely:
<Video src={staticFile("video.mp4")} loop />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
-<Video
- src={staticFile("video.mp4")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Video
+ src={staticFile("video.mp4")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/skills/skills/remotion-markup/audio.md b/packages/skills/skills/remotion-markup/audio.md
index 9760336528..8499acb29a 100644
--- a/packages/skills/skills/remotion-markup/audio.md
+++ b/packages/skills/skills/remotion-markup/audio.md
@@ -87,11 +87,11 @@ import { Audio } from "@remotion/media";
<Audio src={staticFile("audio.mp3")} volume={0.5} />
```
-Use `useCurrentFrame()` and `interpolate()` for keyframed volume:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
import { Audio } from "@remotion/media";
-import { interpolate, useCurrentFrame } from "remotion";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
@@ -109,17 +109,30 @@ return (
With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
-The `volume` prop also accepts a callback for procedural or media-relative volume. The callback frame starts at 0 when the audio begins to play, not at the composition frame:
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Audio>` does not reset this frame. Offset the keyframes to match when the audio starts:
```tsx
import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-<Audio
- src={staticFile("audio.mp3")}
- volume={(mediaFrame) => interpolate(mediaFrame, [0, 30], [0, 1])}
-/>
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ from={1 * fps}
+ premountFor={fps}
+ volume={interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+This fades in during the first second of playback. `trimBefore` and `playbackRate` on the audio change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
+
## Muting
Use `muted` to silence the audio. It can be set dynamically:
@@ -165,22 +178,30 @@ import { Audio } from "@remotion/media";
Put `name`, `from`, `loop`, `volume`, and `premountFor` directly on `<Audio>`.
-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
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
import { Audio } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
-<Audio
- src={staticFile("audio.mp3")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Audio
+ src={staticFile("audio.mp3")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
diff --git a/packages/skills/skills/remotion-markup/embedding-videos.md b/packages/skills/skills/remotion-markup/embedding-videos.md
index 63c09f262d..1c957b3e93 100644
--- a/packages/skills/skills/remotion-markup/embedding-videos.md
+++ b/packages/skills/skills/remotion-markup/embedding-videos.md
@@ -95,10 +95,11 @@ Set a static volume (0 to 1):
<Video src={staticFile("video.mp4")} volume={0.5} />
```
-Use `useCurrentFrame()` and `interpolate()` for keyframed volume:
+Animate volume with `useCurrentFrame()` and pass the result of `interpolate()` directly to `volume`. Keep the keyframes inline so Studio can edit them:
```tsx
-import { interpolate, useCurrentFrame } from "remotion";
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
@@ -114,7 +115,11 @@ return (
);
```
-With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline. A callback is still supported when the curve should be procedural or relative to the start of the media.
+With Studio interactivity enabled, these keyframes can be edited and are shown as a volume curve in the timeline.
+
+`frame` is relative to the component that calls `useCurrentFrame()`: the composition frame at the root, or the local frame inside a `<Sequence>`. Setting `from` on `<Video>` does not reset this frame. For a video starting at `from={1 * fps}`, fade in with `interpolate(frame, [1 * fps, 2 * fps], [0, 1], {...})`.
+
+`trimBefore` and `playbackRate` on the video change the source playback, but do not shift or scale these parent-timeline keyframes. When migrating a volume callback, start the keyframes at the media's first visible frame, where the callback frame started at 0. See [Timing and trimming](https://www.remotion.dev/docs/timing) for how enclosing timing affects `useCurrentFrame()`.
Use `muted` to silence the video entirely:
@@ -143,20 +148,30 @@ Use `loop` to loop the video indefinitely:
<Video src={staticFile("video.mp4")} loop />
```
-Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
-
-- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
-- `"extend"`: Frame count continues incrementing
+Volume keyframes based on the parent component's `frame` continue across media loops. A fade over multiple loops needs no `loopVolumeCurveBehavior`:
```tsx
-<Video
- src={staticFile("video.mp4")}
- loop
- loopVolumeCurveBehavior="extend"
- volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
-/>
+import { Video } from "@remotion/media";
+import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+ <Video
+ src={staticFile("video.mp4")}
+ loop
+ premountFor={fps}
+ volume={interpolate(frame, [0, 10 * fps], [1, 0], {
+ extrapolateLeft: "clamp",
+ extrapolateRight: "clamp",
+ })}
+ />
+);
```
+To repeat the volume envelope each loop, put the component that calls `useCurrentFrame()` inside a looping `<Sequence>` or `<Loop>`. Match its loop duration to the media's played duration, accounting for trimming and playback speed. The media's own `loop` prop does not reset the parent's `frame`.
+
## Pitch
Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2: