1---
2name: extract-frames
3description: Extract frames from videos at specific timestamps using Mediabunny
4metadata:
5  tags: frames, extract, video, thumbnail, filmstrip, canvas
6---
7 
8# Extracting frames from videos
9 
10Use Mediabunny to extract frames from videos at specific timestamps. This is useful for generating thumbnails, filmstrips, or processing individual frames.
11 
12## The `extractFrames()` function
13 
14This function can be copy-pasted into any project.
15 
16```tsx
17import {
18  ALL_FORMATS,
19  Input,
20  UrlSource,
21  VideoSample,
22  VideoSampleSink,
23} from "mediabunny";
24 
25type Options = {
26  track: { width: number; height: number };
27  container: string;
28  durationInSeconds: number | null;
29};
30 
31export type ExtractFramesTimestampsInSecondsFn = (
32  options: Options,
33) => Promise<number[]> | number[];
34 
35export type ExtractFramesProps = {
36  src: string;
37  timestampsInSeconds: number[] | ExtractFramesTimestampsInSecondsFn;
38  onVideoSample: (sample: VideoSample) => void;
39  signal?: AbortSignal;
40};
41 
42export async function extractFrames({
43  src,
44  timestampsInSeconds,
45  onVideoSample,
46  signal,
47}: ExtractFramesProps): Promise<void> {
48  using input = new Input({
49    formats: ALL_FORMATS,
50    source: new UrlSource(src),
51  });
52 
53  const [durationInSeconds, format, videoTrack] = await Promise.all([
54    input.computeDuration(),
55    input.getFormat(),
56    input.getPrimaryVideoTrack(),
57  ]);
58 
59  if (!videoTrack) {
60    throw new Error("No video track found in the input");
61  }
62 
63  if (signal?.aborted) {
64    throw new Error("Aborted");
65  }
66 
67  const timestamps =
68    typeof timestampsInSeconds === "function"
69      ? await timestampsInSeconds({
70          track: {
71            width: videoTrack.displayWidth,
72            height: videoTrack.displayHeight,
73          },
74          container: format.name,
75          durationInSeconds,
76        })
77      : timestampsInSeconds;
78 
79  if (timestamps.length === 0) {
80    return;
81  }
82 
83  if (signal?.aborted) {
84    throw new Error("Aborted");
85  }
86 
87  const sink = new VideoSampleSink(videoTrack);
88 
89  for await (using videoSample of sink.samplesAtTimestamps(timestamps)) {
90    if (signal?.aborted) {
91      break;
92    }
93 
94    if (!videoSample) {
95      continue;
96    }
97 
98    onVideoSample(videoSample);
99  }
100}
101```
102 
103## Basic usage
104 
105Extract frames at specific timestamps:
106 
107```tsx
108await extractFrames({
109  src: "https://remotion.media/video.mp4",
110  timestampsInSeconds: [0, 1, 2, 3, 4],
111  onVideoSample: (sample) => {
112    const canvas = document.createElement("canvas");
113    canvas.width = sample.displayWidth;
114    canvas.height = sample.displayHeight;
115    const ctx = canvas.getContext("2d");
116    sample.draw(ctx!, 0, 0);
117  },
118});
119```
120 
121## Creating a filmstrip
122 
123Use a callback function to dynamically calculate timestamps based on video metadata:
124 
125```tsx
126const canvasWidth = 500;
127const canvasHeight = 80;
128const fromSeconds = 0;
129const toSeconds = 10;
130 
131await extractFrames({
132  src: "https://remotion.media/video.mp4",
133  timestampsInSeconds: async ({ track, durationInSeconds }) => {
134    const aspectRatio = track.width / track.height;
135    const amountOfFramesFit = Math.ceil(
136      canvasWidth / (canvasHeight * aspectRatio),
137    );
138    const segmentDuration = toSeconds - fromSeconds;
139    const timestamps: number[] = [];
140 
141    for (let i = 0; i < amountOfFramesFit; i++) {
142      timestamps.push(
143        fromSeconds + (segmentDuration / amountOfFramesFit) * (i + 0.5),
144      );
145    }
146 
147    return timestamps;
148  },
149  onVideoSample: (sample) => {
150    console.log(`Frame at ${sample.timestamp}s`);
151 
152    const canvas = document.createElement("canvas");
153    canvas.width = sample.displayWidth;
154    canvas.height = sample.displayHeight;
155    const ctx = canvas.getContext("2d");
156    sample.draw(ctx!, 0, 0);
157  },
158});
159```
160 
161## Cancellation with AbortSignal
162 
163Cancel frame extraction after a timeout:
164 
165```tsx
166const controller = new AbortController();
167 
168setTimeout(() => controller.abort(), 5000);
169 
170try {
171  await extractFrames({
172    src: "https://remotion.media/video.mp4",
173    timestampsInSeconds: [0, 1, 2, 3, 4],
174    onVideoSample: (sample) => {
175      using frame = sample;
176      const canvas = document.createElement("canvas");
177      canvas.width = frame.displayWidth;
178      canvas.height = frame.displayHeight;
179      const ctx = canvas.getContext("2d");
180      frame.draw(ctx!, 0, 0);
181    },
182    signal: controller.signal,
183  });
184 
185  console.log("Frame extraction complete!");
186} catch (error) {
187  console.error("Frame extraction was aborted or failed:", error);
188}
189```
190 
191## Timeout with Promise.race
192 
193```tsx
194const controller = new AbortController();
195 
196const timeoutPromise = new Promise<never>((_, reject) => {
197  const timeoutId = setTimeout(() => {
198    controller.abort();
199    reject(new Error("Frame extraction timed out after 10 seconds"));
200  }, 10000);
201 
202  controller.signal.addEventListener("abort", () => clearTimeout(timeoutId), {
203    once: true,
204  });
205});
206 
207try {
208  await Promise.race([
209    extractFrames({
210      src: "https://remotion.media/video.mp4",
211      timestampsInSeconds: [0, 1, 2, 3, 4],
212      onVideoSample: (sample) => {
213        using frame = sample;
214        const canvas = document.createElement("canvas");
215        canvas.width = frame.displayWidth;
216        canvas.height = frame.displayHeight;
217        const ctx = canvas.getContext("2d");
218        frame.draw(ctx!, 0, 0);
219      },
220      signal: controller.signal,
221    }),
222    timeoutPromise,
223  ]);
224 
225  console.log("Frame extraction complete!");
226} catch (error) {
227  console.error("Frame extraction was aborted or failed:", error);
228}
229```
230