Add video upload and playback to SvelteKit

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 SvelteKit server.

This guide uses the FastPix React Uploader inside a small Svelte wrapper because the uploader is currently available as a React component. The FastPix Player is a web component, so it works directly in Svelte without React. If you’d rather not add React at all, resumable uploads for web shows the underlying @fastpix/resumable-uploads engine, which is plain JavaScript: you build the UI in Svelte and drive the engine yourself.

How it works

The upload workflow is straightforward:

1. Your SvelteKit 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 SvelteKit 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 SvelteKit application with server-side rendering enabled.
• Node.js.

Install

From your project directory:

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

The Node SDK talks to the FastPix API from your server and the Web Player plays the result. react and react-dom are peer dependencies of the React Uploader. They’re used only by the upload component, not by the rest of your app.

Add your credentials to .env:

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

Create the SDK client in a .server.ts file, reading them through $env/static/private. SvelteKit refuses to import that module into client code, so the credentials can’t reach the browser even by accident:

1
// src/lib/fastpix.server.ts (or fastpix.server.js)
2
import { Fastpix } from "@fastpix/fastpix-node";
3
import { FASTPIX_USERNAME, FASTPIX_PASSWORD } from "$env/static/private";
4
5
export const fastpix = new Fastpix({
6
  security: { username: FASTPIX_USERNAME, password: FASTPIX_PASSWORD },
7
});

Create an upload URL

Signed upload URLs are created with your Secret Key, so this belongs on the server. A +server.ts file gives you an endpoint the browser can call:

src/routes/api/upload-url/+server.ts

1
import { json } from "@sveltejs/kit";
2
import { fastpix } from "$lib/fastpix.server";
3
4
export async function POST() {
5
  const upload = await fastpix.inputVideo.upload(
6
    { corsOrigin: "*", pushMediaSettings: { accessPolicy: "public" } },
7
    { headers: { "X-Client-Type": "web-browser" } },
8
  );
9
10
  if (!("data" in upload)) throw new Error("Could not create an upload.");
11
12
  return json({ url: upload.data!.url, mediaId: upload.data!.uploadId });
13
}

src/routes/api/upload-url/+server.js

1
import { json } from "@sveltejs/kit";
2
import { fastpix } from "$lib/fastpix.server";
3
4
export async function POST() {
5
  const upload = await fastpix.inputVideo.upload(
6
    { corsOrigin: "*", pushMediaSettings: { accessPolicy: "public" } },
7
    { headers: { "X-Client-Type": "web-browser" } },
8
  );
9
10
  return json({ url: upload.data.url, mediaId: upload.data.uploadId });
11
}

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. It identifies the media everywhere else in the API, and you’ll use it later to play 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

The uploader is a React component, so mount it into a <div> your Svelte component owns. onMount runs only in the browser, which also keeps the component out of server rendering:

src/lib/Uploader.svelte (TypeScript)

1
<script lang="ts">
2
  import { onMount, onDestroy } from "svelte";
3
  import { createElement } from "react";
4
  import { createRoot, type Root } from "react-dom/client";
5
  import { FastPixUploader } from "@fastpix/fp-react-uploader";
6
  import "@fastpix/fp-react-uploader/styles.css";
7
8
  let container: HTMLDivElement;
9
  let root: Root | undefined;
10
11
  async function createUpload() {
12
    const response = await fetch("/api/upload-url", { method: "POST" });
13
    const { url } = await response.json();
14
    return url as string;
15
  }
16
17
  onMount(() => {
18
    root = createRoot(container);
19
    root.render(createElement(FastPixUploader, { endpoint: createUpload, accept: "video/*" }));
20
  });
21
22
  onDestroy(() => root?.unmount());
23
</script>
24
25
<div bind:this={container}></div>

src/lib/Uploader.svelte (JavaScript)

1
<script>
2
  import { onMount, onDestroy } from "svelte";
3
  import { createElement } from "react";
4
  import { createRoot } from "react-dom/client";
5
  import { FastPixUploader } from "@fastpix/fp-react-uploader";
6
  import "@fastpix/fp-react-uploader/styles.css";
7
8
  let container;
9
  let root;
10
11
  async function createUpload() {
12
    const response = await fetch("/api/upload-url", { method: "POST" });
13
    const { url } = await response.json();
14
    return url;
15
  }
16
17
  onMount(() => {
18
    root = createRoot(container);
19
    root.render(createElement(FastPixUploader, { endpoint: createUpload, accept: "video/*" }));
20
  });
21
22
  onDestroy(() => root?.unmount());
23
</script>
24
25
<div bind:this={container}></div>

Then use it like any other Svelte component:

1
<!-- src/routes/upload/+page.svelte -->
2
<script lang="ts">
3
  import Uploader from "$lib/Uploader.svelte";
4
</script>
5
6
<Uploader />

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

You can select or drag a video into the uploader and the upload begins with visible progress.

createElement is used instead of JSX so the project needs no JSX tooling. onDestroy unmounts the React root. Without it, navigating away leaves the root attached and leaks.

Build your own layout instead

The sub-components read upload state through React context, which can’t cross into Svelte markup. Compose them inside the same root.render call so they stay in one React tree:

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
root.render(
13
  createElement(
14
    FastPixUploader,
15
    { endpoint: createUpload, accept: "video/*", autoStart: false },
16
    createElement(FastPixDropZone, { overlay: true }, "Drag a video here, or click to browse"),
17
    createElement(FastPixStatus),
18
    createElement(FastPixTrack, { showLabel: true }),
19
    createElement(FastPixStartButton),
20
    createElement(FastPixPauseButton),
21
    createElement(FastPixResumeButton),
22
    createElement(FastPixAbortButton),
23
  ),
24
);

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

Passing Svelte elements as children of a React component doesn’t work. They render outside the provider and the sub-components fail to find their state. Everything that needs upload state has to be created with createElement.

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 callbacks. Pass them in the same props object you give createElement: onProgress, onSuccess, onError, and more are all optional:

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

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.

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 in another +server.ts:

src/routes/api/fastpix/webhook/+server.ts

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

src/routes/api/fastpix/webhook/+server.js

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

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 check the status directly:

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

Play the video

<fastpix-player> is a web component, so it needs no React and goes straight into Svelte markup. It registers itself against customElements, a browser-only API, so import it from onMount rather than at module scope.

Fetch the media in a server load. That runs on the server, so your credentials stay there and only the playback ID reaches the browser:

src/routes/play/[mediaId]/+page.server.ts

1
import { error } from "@sveltejs/kit";
2
import { fastpix } from "$lib/fastpix.server";
3
4
export async function load({ params }) {
5
  /* Read the playback ID from your own database, or from FastPix like below. */
6
  const media = await fastpix.manageVideos.get({ mediaId: params.mediaId });
7
8
  if (!("data" in media)) throw error(404, "Media not found.");
9
10
  return { playbackId: media.data!.playbackIds![0].id! };
11
}

src/routes/play/[mediaId]/+page.server.js

1
import { error } from "@sveltejs/kit";
2
import { fastpix } from "$lib/fastpix.server";
3
4
export async function load({ params }) {
5
  const media = await fastpix.manageVideos.get({ mediaId: params.mediaId });
6
7
  if (!("data" in media)) throw error(404, "Media not found.");
8
9
  return { playbackId: media.data.playbackIds[0].id };
10
}

src/routes/play/[mediaId]/+page.svelte (TypeScript)

1
<script lang="ts">
2
  import { onMount } from "svelte";
3
4
  let { data } = $props();
5
6
  onMount(() => {
7
    import("@fastpix/fp-player");
8
  });
9
</script>
10
11
<fastpix-player playback-id={data.playbackId} stream-type="on-demand"></fastpix-player>

src/routes/play/[mediaId]/+page.svelte (JavaScript)

1
<script>
2
  import { onMount } from "svelte";
3
4
  let { data } = $props();
5
6
  onMount(() => {
7
    import("@fastpix/fp-player");
8
  });
9
</script>
10
11
<fastpix-player playback-id={data.playbackId} stream-type="on-demand"></fastpix-player>

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

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

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. 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.

Sub-components render but show no state, or throw about a missing provider.

They’re being created outside the React tree, usually by writing them as Svelte markup. Build every component that needs upload state with createElement inside the same root.render call.

document is not defined, or the uploader breaks the server render.

React DOM is being touched during SSR. Create the root inside onMount, which never runs on the server.

ReferenceError: window is not defined on the play page.

The player is being imported at module scope. Import it inside onMount, as above.

Cannot import $env/static/private into client-side code.

A component that runs in the browser is importing your server module. Only +server.ts, +page.server.ts, and other server files may import fastpix.server.ts.

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.