Add video upload and playback to Next.js

Uploading video is different from uploading other files. Large uploads need to resume after interruptions, and media must be processed into streaming formats before they can be played reliably across devices.

FastPix handles uploads, processing, and adaptive streaming. Your application only needs to create a signed upload URL on the server and render a player. Uploads go directly from the browser to FastPix, so video data never passes through your Next.js server.

This guide uses the Next.js App Router with React because the uploader is a React component. The FastPix Player is a web component and does not require React. If you’d rather not use React components, the quickstart covers the same workflow using the API directly, and resumable uploads for web covers the underlying @fastpix/resumable-uploads engine.

How it works

The upload workflow is straightforward:

1. Your Next.js server creates a signed upload URL using the FastPix Node SDK.
2. The React Uploader uploads the selected file directly to FastPix using the signed URL.
3. FastPix processes the uploaded media asynchronously.
4. FastPix sends a video.media.ready webhook when the media is ready for playback.
5. Your application retrieves the playback ID and plays the video using the FastPix Player.

What you’ll build

By the end of this guide, you’ll have:

• A Next.js application that uploads videos directly to FastPix.
• Resumable uploads with upload progress and retry support.
• A FastPix Player that streams the uploaded video.
• A workflow that waits for media processing before playback.

Before you begin

• A FastPix account with an Access Token ID and Secret Key. See get your Access Token ID and Secret Key.
• A Next.js application using the App Router.
• React 18 or later.
• Node.js.

Install

From your project directory:

$
cd your-nextjs-project
$
npm install @fastpix/fastpix-node @fastpix/fp-react-uploader @fastpix/fp-player

Each package covers one part of the flow: the Node SDK talks to the FastPix API from your server, the React Uploader is the browser-side upload UI, and the Web Player plays the result.

Add your credentials to .env.local:

$
FASTPIX_USERNAME=your-access-token-id
$
FASTPIX_PASSWORD=your-secret-key

WARNING:
Never prefix these with NEXT_PUBLIC_. That inlines them into the browser bundle and publishes your Secret Key to every visitor.

Then import the uploader stylesheet once, in app/layout.tsx:

1
import "@fastpix/fp-react-uploader/styles.css";

Without it the components render as an unstyled skeleton and you supply the entire look yourself. With it you get the default drop zone, progress track, status text, and buttons, which you can then adjust through the appearance prop or the --fastpix-* CSS variables, both documented in the uploader README.

Create an upload URL

Signed upload URLs are created with your Secret Key, so this belongs on the server. Put it in a route handler:

app/api/upload-url/route.ts

1
import { Fastpix } from "@fastpix/fastpix-node";
2
3
const fastpix = new Fastpix({
4
  security: {
5
    username: process.env.FASTPIX_USERNAME,
6
    password: process.env.FASTPIX_PASSWORD,
7
  },
8
});
9
10
export async function POST() {
11
  const upload = await fastpix.inputVideo.upload(
12
    {
13
      corsOrigin: "*",
14
      pushMediaSettings: { accessPolicy: "public" },
15
    },
16
    { headers: { "X-Client-Type": "web-browser" } },
17
  );
18
19
  if (!("data" in upload)) throw new Error("Could not create an upload.");
20
21
  return Response.json({ url: upload.data!.url, mediaId: upload.data!.uploadId });
22
}

app/api/upload-url/route.js

1
import { Fastpix } from "@fastpix/fastpix-node";
2
3
const fastpix = new Fastpix({
4
  security: {
5
    username: process.env.FASTPIX_USERNAME,
6
    password: process.env.FASTPIX_PASSWORD,
7
  },
8
});
9
10
export async function POST() {
11
  const upload = await fastpix.inputVideo.upload(
12
    {
13
      corsOrigin: "*",
14
      pushMediaSettings: { accessPolicy: "public" },
15
    },
16
    { headers: { "X-Client-Type": "web-browser" } },
17
  );
18
19
  return Response.json({ url: upload.data.url, mediaId: upload.data.uploadId });
20
}

NOTE: X-Client-Type: web-browser tells FastPix that a browser will perform the upload, so the signed URL is issued for browser use. Send it whenever the file is uploaded from a browser, including this setup, where your server requests the URL and the browser uploads to it.

Leave it out when your own server, a CLI, or a native Android or iOS app uploads the bytes. See upload videos from device.

Keep the mediaId. You’ll use the media ID to retrieve the playback ID after FastPix finishes processing the video. Full options are in upload videos from device, or use create media from a URL to import video you already host.

Add the uploader

Give <FastPixUploader> a function instead of a URL. It runs when a file is picked, so a URL is minted per upload rather than per page view:

app/upload/page.tsx

1
"use client";
2
3
import { FastPixUploader } from "@fastpix/fp-react-uploader";
4
5
async function createUpload() {
6
  const response = await fetch("/api/upload-url", { method: "POST" });
7
  const { url } = await response.json();
8
  return url as string;
9
}
10
11
export default function Page() {
12
  return <FastPixUploader endpoint={createUpload} accept="video/*" />;
13
}

app/upload/page.jsx

1
"use client";
2
3
import { FastPixUploader } from "@fastpix/fp-react-uploader";
4
5
async function createUpload() {
6
  const response = await fetch("/api/upload-url", { method: "POST" });
7
  const { url } = await response.json();
8
  return url;
9
}
10
11
export default function Page() {
12
  return <FastPixUploader endpoint={createUpload} accept="video/*" />;
13
}

That’s a working uploader: drag and drop, a file picker, progress, and pause, resume, and cancel controls.

You can drag a video into the uploader and the upload begins automatically.

NOTE:
The uploader ships with its own "use client" banner, so the component itself needs no directive. The directive at the top of this page exists for the createUpload function: functions can’t cross the server-to-client boundary, so any file that passes one as a prop must be a client module.

Build your own layout instead

Pass the sub-components as children and arrange them yourself. Each reads upload state from the parent through context, so placement and order are yours:

1
import {
2
  FastPixUploader,
3
  FastPixDropZone,
4
  FastPixStatus,
5
  FastPixTrack,
6
  FastPixStartButton,
7
  FastPixPauseButton,
8
  FastPixResumeButton,
9
  FastPixAbortButton,
10
} from "@fastpix/fp-react-uploader";
11
12
<FastPixUploader endpoint={createUpload} autoStart={false} size="lg" appearance={{ accentColor: "#00d1ff" }}>
13
  <FastPixDropZone overlay>
14
    <p>Drag a video here, or click to browse</p>
15
  </FastPixDropZone>
16
17
  <FastPixStatus />
18
  <FastPixTrack showLabel />
19
20
  <FastPixStartButton />
21
  <FastPixPauseButton />
22
  <FastPixResumeButton />
23
  <FastPixAbortButton />
24
</FastPixUploader>

autoStart={false} holds the file until someone presses start, which is why a start button appears here and not in the default layout.

Tracking progress yourself, driving the uploader from a ref, reading live state with useUploaderContext(), and building a fully headless UI are covered in the uploader README.

Respond to upload events

The uploader reports its lifecycle through callback props: onProgress, onSuccess, onError, and more. All are optional:

1
<FastPixUploader
2
  endpoint={createUpload}
3
  accept="video/*"
4
  onProgress={(percent) => console.log(percent)}
5
  onSuccess={() => {
6
    /* the bytes are delivered; encoding continues */
7
  }}
8
  onError={(error) => console.error(error.message)}
9
/>

onSuccess fires when the bytes finish uploading. The media still has to be encoded before it can play, which is what the next section covers. The full callback list is in the uploader README.

At this point files upload successfully, but they aren’t playable yet. Next, learn how to know when a video has finished encoding and how to capture its playback ID.

Wait for the media to be ready

A finished upload isn’t a playable video yet. It still has to be encoded. FastPix sends a video.media.ready webhook once playback is available.

Register your endpoint under Org Settings > Webhooks (see Set up webhooks), then handle the event:

app/api/fastpix/webhook/route.ts

1
export async function POST(request: Request) {
2
  const { type, data } = await request.json();
3
4
  if (type === "video.media.ready") {
5
    /* data.id is the mediaId, data.playbackIds[0].id is the playback ID.
6
       Store them against your own record here. */
7
    await markVideoReady(data.id, data.playbackIds[0].id);
8
  }
9
10
  return Response.json({ message: "ok" });
11
}

app/api/fastpix/webhook/route.js

1
export async function POST(request) {
2
  const { type, data } = await request.json();
3
4
  if (type === "video.media.ready") {
5
    await markVideoReady(data.id, data.playbackIds[0].id);
6
  }
7
8
  return Response.json({ message: "ok" });
9
}

WARNING:
Verify the signature before trusting a payload. Your endpoint is a public URL, so anyone who finds it could claim a video is ready. Check the FastPix-Signature header, an HMAC-SHA256 of the raw body, as described in Set up webhooks. Read the body with request.text() and verify that exact string. A parsed and re-serialized body produces different bytes and never matches.

Other events, including video.media.failed, are in the webhook event reference.

Webhooks can’t reach localhost, so while developing either expose your dev server through a tunnel or poll instead:

1
const media = await fastpix.manageVideos.get({ mediaId });
2
// media.data.status === "Ready"

Play the video

<fastpix-player> is a web component, so it registers itself against customElements, a browser-only API. Next.js server-renders client components for the initial HTML, so import the player after mount rather than at module scope. The element upgrades itself as soon as the definition arrives:

app/components/Player.tsx

1
"use client";
2
3
import { useEffect } from "react";
4
5
export default function Player({ playbackId }: { playbackId: string }) {
6
  useEffect(() => {
7
    import("@fastpix/fp-player");
8
  }, []);
9
10
  return <fastpix-player playback-id={playbackId} stream-type="on-demand" />;
11
}

app/components/Player.jsx

1
"use client";
2
3
import { useEffect } from "react";
4
5
export default function Player({ playbackId }) {
6
  useEffect(() => {
7
    import("@fastpix/fp-player");
8
  }, []);
9
10
  return <fastpix-player playback-id={playbackId} stream-type="on-demand" />;
11
}

Give it a size, since it fills whatever container it sits in:

1
fastpix-player { width: 100%; aspect-ratio: 16 / 9; }

Then fetch the media and pass its playback ID in:

app/play/[mediaId]/page.tsx

1
import { Fastpix } from "@fastpix/fastpix-node";
2
import Player from "../../../app/components/Player";
3
4
const fastpix = new Fastpix({
5
  security: {
6
    username: process.env.FASTPIX_USERNAME,
7
    password: process.env.FASTPIX_PASSWORD,
8
  },
9
});
10
11
export default async function Page({ params }: { params: Promise<{ mediaId: string }> }) {
12
  /* Read the playback ID from your own database, or from FastPix like below. */
13
  const media = await fastpix.manageVideos.get({ mediaId: (await params).mediaId });
14
15
  if (!("data" in media)) throw new Error("Media not found.");
16
17
  return <Player playbackId={media.data!.playbackIds![0].id!} />;
18
}

app/play/[mediaId]/page.jsx

1
import { Fastpix } from "@fastpix/fastpix-node";
2
import Player from "../../../app/components/Player";
3
4
const fastpix = new Fastpix({
5
  security: {
6
    username: process.env.FASTPIX_USERNAME,
7
    password: process.env.FASTPIX_PASSWORD,
8
  },
9
});
10
11
export default async function Page({ params }) {
12
  const media = await fastpix.manageVideos.get({ mediaId: (await params).mediaId });
13
14
  return <Player playbackId={media.data.playbackIds[0].id} />;
15
}

A playback ID isn’t the same as a media ID. One media asset can carry several playback IDs with different access policies. This guide uses accessPolicy: "public", so the ID alone is enough to play the video. Private and DRM playback need a signed token, covered in play uploaded videos along with autoplay, captions, and the player’s full attribute and event surface.

Troubleshooting

Uploads fail with “error code 0” after 5 attempts, but the video still processes.

The signed URL was created without the X-Client-Type: web-browser header, so it isn’t valid for uploads started from a browser. Add it to your upload call as shown above, or send it on your POST /v1/on-demand/upload request if you call the API directly. The rule is about who uploads the bytes, not who requests the URL. A browser doing the upload needs the header even though your server is the one asking for the URL.

Every visitor gets the same upload URL.

The upload URL is being created while the page renders, so Next.js prerenders it into the HTML at build time. Create it in a route handler called from endpoint, as above, so each upload gets a fresh URL. Passing a URL string from a Server Component instead requires export const dynamic = "force-dynamic" on that page.

ReferenceError: window is not defined.

The player is being imported at module scope. Load it inside useEffect, as above. Adding "use client" alone doesn’t help, because client components are still server-rendered for the initial HTML.

Error: Functions cannot be passed directly to Client Components.

Your endpoint function or an on* callback is defined in a Server Component. Define them in a file marked "use client". Functions can’t cross the server-to-client boundary. Avoid passing a Server Action as endpoint. It receives the selected File and uploads it to your own server first.

The file picker does nothing over a tunnel.

Next.js rejects dev requests from unrecognized origins. Add the host to next.config.ts:

1
const nextConfig = { allowedDevOrigins: ["your-subdomain.ngrok-free.dev"] };

Chunk size is rejected.

chunkSize is in KB, between 5120 and 512000, in multiples of 256.

What’s next

• React Uploader, Web Player, Node SDK, and Web Uploads SDK.
• Upload videos from device, Resumable uploads for web, and Get media.
• Install the web player, Play uploaded videos, and Webhooks.