@uploadfilm/sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +4 -0
- package/README.md +529 -2
- package/dist/ai/embed.d.ts +58 -0
- package/dist/ai/fake.d.ts +41 -0
- package/dist/ai/http.d.ts +17 -0
- package/dist/ai/index.d.ts +27 -0
- package/dist/ai/languages.d.ts +2 -0
- package/dist/ai/ollama.d.ts +23 -0
- package/dist/ai/openaiCompatible.d.ts +54 -0
- package/dist/ai/passages.d.ts +28 -0
- package/dist/ai/transcribe.d.ts +84 -0
- package/dist/ai/types.d.ts +141 -0
- package/dist/ai/usage.d.ts +66 -0
- package/dist/ai/whisperJson.d.ts +15 -0
- package/dist/ai/workersAi.d.ts +56 -0
- package/dist/ai.js +1 -0
- package/dist/ai.mjs +1 -0
- package/dist/cards/files.d.ts +91 -0
- package/dist/cards/index.d.ts +15 -0
- package/dist/cards/layouts.d.ts +121 -0
- package/dist/cards/probe.d.ts +69 -0
- package/dist/cards/proxies.d.ts +70 -0
- package/dist/cards/select.d.ts +68 -0
- package/dist/cards/volumes.d.ts +170 -0
- package/dist/cards/xml.d.ts +80 -0
- package/dist/cards.js +1 -0
- package/dist/cards.mjs +1 -0
- package/dist/copy/checksums.d.ts +66 -0
- package/dist/copy/engine.d.ts +24 -0
- package/dist/copy/errors.d.ts +109 -0
- package/dist/copy/index.d.ts +15 -0
- package/dist/copy/steps.d.ts +28 -0
- package/dist/copy/sweep.d.ts +24 -0
- package/dist/copy/types.d.ts +363 -0
- package/dist/embed/player.js +2 -0
- package/dist/host/adapters.d.ts +107 -0
- package/dist/host/detect.d.ts +68 -0
- package/dist/host/encoders.d.ts +34 -0
- package/dist/host/environment.d.ts +53 -0
- package/dist/host/index.d.ts +20 -0
- package/dist/host/linux.d.ts +94 -0
- package/dist/host/mac.d.ts +47 -0
- package/dist/host/network.d.ts +54 -0
- package/dist/host/node.d.ts +13 -0
- package/dist/host/policy.d.ts +101 -0
- package/dist/host/tuner.d.ts +48 -0
- package/dist/host/types.d.ts +118 -0
- package/dist/host-node.js +1 -0
- package/dist/host-node.mjs +1 -0
- package/dist/host.js +1 -0
- package/dist/host.mjs +1 -0
- package/dist/images/index.d.ts +11 -0
- package/dist/images/settings.d.ts +43 -0
- package/dist/images/types.d.ts +83 -0
- package/dist/images/url.d.ts +65 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +1 -0
- package/dist/player/adapters/hlsjs.d.ts +28 -0
- package/dist/player/bandwidthMemory.d.ts +28 -0
- package/dist/player/captions/index.d.ts +55 -0
- package/dist/player/embed/code.d.ts +195 -0
- package/dist/player/embed/constants.d.ts +4 -0
- package/dist/player/embed/controller.d.ts +62 -0
- package/dist/player/embed/element.d.ts +32 -0
- package/dist/player/embed/frame.d.ts +65 -0
- package/dist/player/embed/global.d.ts +14 -0
- package/dist/player/embed/index.d.ts +15 -0
- package/dist/player/embed/loader.d.ts +1 -0
- package/dist/player/embed/oembed.d.ts +74 -0
- package/dist/player/embed/protocol.d.ts +64 -0
- package/dist/player/engine.d.ts +215 -0
- package/dist/player/index.d.ts +18 -0
- package/dist/player/start.d.ts +62 -0
- package/dist/player/store.d.ts +10 -0
- package/dist/player/storyboard/index.d.ts +161 -0
- package/dist/player/stream.d.ts +206 -0
- package/dist/player/tracks.d.ts +41 -0
- package/dist/player.js +1 -0
- package/dist/player.mjs +1 -0
- package/dist/proxies/args.d.ts +19 -0
- package/dist/proxies/budget.d.ts +57 -0
- package/dist/proxies/camera.d.ts +104 -0
- package/dist/proxies/formats.d.ts +36 -0
- package/dist/proxies/index.d.ts +18 -0
- package/dist/proxies/jobs.d.ts +98 -0
- package/dist/proxies/node.d.ts +32 -0
- package/dist/proxies/plan.d.ts +89 -0
- package/dist/proxies/probe.d.ts +39 -0
- package/dist/proxies/render.d.ts +104 -0
- package/dist/proxies/safety.d.ts +45 -0
- package/dist/proxies/types.d.ts +83 -0
- package/dist/proxies/upload.d.ts +14 -0
- package/dist/react/BigPlay.d.ts +26 -0
- package/dist/react/Player.d.ts +58 -0
- package/dist/react/embed/index.d.ts +45 -0
- package/dist/react/examples/CustomControls.d.ts +8 -0
- package/dist/react/images/Image.d.ts +16 -0
- package/dist/react/images/index.d.ts +4 -0
- package/dist/react/images/useImage.d.ts +47 -0
- package/dist/react/index.d.ts +17 -0
- package/dist/react/storyboard/index.d.ts +58 -0
- package/dist/react/theme.d.ts +37 -0
- package/dist/react/useAdapterErrors.d.ts +8 -0
- package/dist/react/usePlaybackStart.d.ts +18 -0
- package/dist/react/usePlayer.d.ts +28 -0
- package/dist/react/useReducedMotion.d.ts +2 -0
- package/dist/react/useTimedTrack.d.ts +22 -0
- package/dist/react.js +1 -0
- package/dist/react.mjs +1 -0
- package/dist/server/auth/apiKeys.d.ts +30 -0
- package/dist/server/auth/cache.d.ts +21 -0
- package/dist/server/auth/deviceTokens.d.ts +38 -0
- package/dist/server/auth/envelope.d.ts +15 -0
- package/dist/server/auth/grants.d.ts +76 -0
- package/dist/server/auth/index.d.ts +19 -0
- package/dist/server/auth/jwt.d.ts +65 -0
- package/dist/server/auth/keyring.d.ts +31 -0
- package/dist/server/auth/kv.d.ts +12 -0
- package/dist/server/auth/repository.d.ts +45 -0
- package/dist/server/auth/revocations.d.ts +21 -0
- package/dist/server/auth/scope.d.ts +4 -0
- package/dist/server/auth/serviceAuth.d.ts +24 -0
- package/dist/server/auth/signedUrls.d.ts +28 -0
- package/dist/server/embed/index.d.ts +36 -0
- package/dist/server/embed/lifecycle.d.ts +53 -0
- package/dist/server/embed/playerScript.d.ts +4 -0
- package/dist/server/images/index.d.ts +15 -0
- package/dist/server/images/job.d.ts +80 -0
- package/dist/server/images/layout.d.ts +24 -0
- package/dist/server/images/params.d.ts +90 -0
- package/dist/server/images/route.d.ts +101 -0
- package/dist/server/images/sign.d.ts +55 -0
- package/dist/server/index.d.ts +42 -0
- package/dist/server/media/client.d.ts +99 -0
- package/dist/server/media/frameCheck.d.ts +62 -0
- package/dist/server/media/index.d.ts +10 -0
- package/dist/server/media/protocol.d.ts +556 -0
- package/dist/server/media/storyboard.d.ts +144 -0
- package/dist/server/media/transcript.d.ts +143 -0
- package/dist/server/pipeline/index.d.ts +12 -0
- package/dist/server/pipeline/match.d.ts +10 -0
- package/dist/server/pipeline/pipeline.d.ts +182 -0
- package/dist/server/pipeline/queues.d.ts +108 -0
- package/dist/server/pipeline/sources.d.ts +54 -0
- package/dist/server/r2/client.d.ts +164 -0
- package/dist/server/r2/crc32.d.ts +24 -0
- package/dist/server/r2/encoding.d.ts +35 -0
- package/dist/server/r2/errors.d.ts +9 -0
- package/dist/server/r2/integrity.d.ts +25 -0
- package/dist/server/r2/parts.d.ts +46 -0
- package/dist/server/r2/sign.d.ts +47 -0
- package/dist/server/redis/index.d.ts +39 -0
- package/dist/server/state/memory.d.ts +18 -0
- package/dist/server/state/r2.d.ts +73 -0
- package/dist/server/state/types.d.ts +57 -0
- package/dist/server/storage/chunked.d.ts +25 -0
- package/dist/server/storage/index.d.ts +12 -0
- package/dist/server/storage/r2.d.ts +96 -0
- package/dist/server/storage/s3.d.ts +144 -0
- package/dist/server/testing/fake-r2.d.ts +410 -0
- package/dist/server/testing/index.d.ts +10 -0
- package/dist/server/testing/kv-contract.d.ts +14 -0
- package/dist/server/transfer/handler.d.ts +217 -0
- package/dist/server/transfer/keys.d.ts +45 -0
- package/dist/server/transfer/protocol.d.ts +190 -0
- package/dist/server/zip/client.d.ts +32 -0
- package/dist/server/zip/generations.d.ts +83 -0
- package/dist/server/zip/index.d.ts +12 -0
- package/dist/server/zip/planner.d.ts +94 -0
- package/dist/server/zip/sign.d.ts +22 -0
- package/dist/server-media.js +1 -0
- package/dist/server-media.mjs +1 -0
- package/dist/server-redis.js +1 -0
- package/dist/server-redis.mjs +1 -0
- package/dist/server-testing.js +1 -0
- package/dist/server-testing.mjs +1 -0
- package/dist/server.js +1 -0
- package/dist/server.mjs +1 -0
- package/dist/storage/browserFile.d.ts +19 -0
- package/dist/storage/index.d.ts +12 -0
- package/dist/storage/local.d.ts +9 -0
- package/dist/storage/presigned.d.ts +22 -0
- package/dist/sync/ffmpeg.d.ts +44 -0
- package/dist/sync/index.d.ts +17 -0
- package/dist/sync/match.d.ts +28 -0
- package/dist/sync/probe.d.ts +30 -0
- package/dist/sync/timecode.d.ts +50 -0
- package/dist/sync/transcript.d.ts +35 -0
- package/dist/sync/types.d.ts +172 -0
- package/dist/sync/waveform.d.ts +89 -0
- package/dist/sync.js +1 -0
- package/dist/sync.mjs +1 -0
- package/dist/transfer/claims.d.ts +41 -0
- package/dist/transfer/client.d.ts +267 -0
- package/dist/transfer/download.d.ts +192 -0
- package/dist/transfer/engine.d.ts +402 -0
- package/dist/transfer/errors.d.ts +50 -0
- package/dist/transfer/growing/bytes.d.ts +17 -0
- package/dist/transfer/growing/index.d.ts +12 -0
- package/dist/transfer/growing/parts.d.ts +157 -0
- package/dist/transfer/growing/retry.d.ts +38 -0
- package/dist/transfer/growing/store.d.ts +66 -0
- package/dist/transfer/growing/upload.d.ts +126 -0
- package/dist/transfer/index.d.ts +40 -0
- package/dist/transfer/integrity.d.ts +93 -0
- package/dist/transfer/limits.d.ts +34 -0
- package/dist/transfer/node.d.ts +63 -0
- package/dist/transfer/pool.d.ts +83 -0
- package/dist/transfer/protocol.d.ts +172 -0
- package/dist/transfer/signer.d.ts +29 -0
- package/dist/transfer/storage.d.ts +135 -0
- package/dist/transfer/timing.d.ts +132 -0
- package/dist/transfer/transports/electronNet.d.ts +62 -0
- package/dist/transfer/transports/fetch.d.ts +15 -0
- package/dist/transfer/transports/retryAfter.d.ts +12 -0
- package/dist/transfer/transports/undici.d.ts +72 -0
- package/dist/transfer/tuner.d.ts +56 -0
- package/dist/workers/cli.mjs +115 -0
- package/dist/workers/media/config.mjs +53 -0
- package/dist/workers/media/container/Dockerfile +19 -0
- package/dist/workers/media/container/FFMPEG.md +129 -0
- package/dist/workers/media/container/runner.mjs +2690 -0
- package/dist/workers/media/index.mjs +1011 -0
- package/dist/workers/media/init/config.ts +52 -0
- package/dist/workers/media/init/worker.ts +8 -0
- package/dist/workers/media/init/wrangler.toml +44 -0
- package/dist/workers/media/runner.mjs +2656 -0
- package/dist/workers/media/types/build/entry/config.d.mts +6 -0
- package/dist/workers/media/types/build/entry/index.d.mts +43 -0
- package/dist/workers/media/types/build/entry/program.d.mts +13 -0
- package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
- package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
- package/dist/workers/media/types/src/config.d.mts +135 -0
- package/dist/workers/media/types/src/jobs.d.mts +73 -0
- package/dist/workers/media/types/src/runner/container.d.mts +32 -0
- package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
- package/dist/workers/media/types/src/runner/job.d.mts +107 -0
- package/dist/workers/media/types/src/runner/node.d.mts +71 -0
- package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
- package/dist/workers/media/types/src/serve.d.mts +107 -0
- package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
- package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
- package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
- package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
- package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
- package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
- package/dist/workers/media/types/src/steps/render.d.mts +40 -0
- package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
- package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
- package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
- package/dist/workers/media/types/src/transcoder.d.mts +30 -0
- package/dist/workers/media/types/src/worker.d.mts +30 -0
- package/dist/workers/zip/index.mjs +589 -0
- package/dist/workers/zip/init/config.ts +22 -0
- package/dist/workers/zip/init/worker.ts +5 -0
- package/dist/workers/zip/init/wrangler.toml +25 -0
- package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
- package/dist/workers/zip/types/src/config.d.mts +35 -0
- package/dist/workers/zip/types/src/serve.d.mts +86 -0
- package/dist/workers/zip/types/src/worker.d.mts +12 -0
- package/dist/zip/index.d.ts +13 -0
- package/dist/zip/layout.d.ts +129 -0
- package/dist/zip/names.d.ts +34 -0
- package/dist/zip/plan.d.ts +115 -0
- package/dist/zip/sw.d.ts +7 -0
- package/package.json +313 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
Copyright (c) 2026 UploadFilm. All rights reserved.
|
|
2
|
+
|
|
3
|
+
This software is proprietary and confidential. It is not open source. No licence to use, copy, modify, merge,
|
|
4
|
+
publish, distribute, sublicense or sell copies of it is granted except by a separate written agreement with UploadFilm.
|
package/README.md
CHANGED
|
@@ -1,3 +1,530 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 🎞️ @uploadfilm/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**One engine for moving camera footage into your own storage, processing it on your own Cloudflare account, and
|
|
4
|
+
playing it back in your own app.** Resumable, verified uploads to your R2 bucket; a headless video player with embeds;
|
|
5
|
+
React hooks over it; and the server side: presigning, an auth kit, media jobs, verified copies to S3.
|
|
6
|
+
|
|
7
|
+
It's a **library, not a service**: no central API, no hosted keys, no shared logging, no billing. You run your own
|
|
8
|
+
bucket, routes, auth and media Worker, and import only the entry points you need. UploadFilm runs on it in production.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install @uploadfilm/sdk
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
- [✨ Features](#-features)
|
|
15
|
+
- [🧭 Entry points](#-entry-points)
|
|
16
|
+
- [🚀 Quick start: uploads](#-quick-start-uploads-node-or-electron)
|
|
17
|
+
- [🔐 Quick start: the server route](#-quick-start-the-server-route)
|
|
18
|
+
- [🎬 The player](#-the-player)
|
|
19
|
+
- [⚙️ The media pipeline on Cloudflare Workers](#️-the-media-pipeline-on-cloudflare-workers)
|
|
20
|
+
- [🧪 Testing your integration](#-testing-your-integration)
|
|
21
|
+
- [🛡️ Guarantees](#️-guarantees)
|
|
22
|
+
- [🚧 Not built yet](#-not-built-yet)
|
|
23
|
+
|
|
24
|
+
## ✨ Features
|
|
25
|
+
|
|
26
|
+
| | |
|
|
27
|
+
|---|---|
|
|
28
|
+
| ✅ **Bytes verified** | An upload resolves `verified` only after storage confirmed a checksum of the bytes read from your file: Content-MD5 for a single PUT, every part's MD5 ETag plus the composite ETag for a multipart, or SHA-256 receipts in `integrity: "sha256"` mode. |
|
|
29
|
+
| 🚫 **Never a false "done"** | Storage that stored something without a checksum to compare gives `failed` / `Unverified`, never success. The media Worker writes its completion file last and refuses a ladder shorter than the source. |
|
|
30
|
+
| 🔁 **Resumable** | The multipart record is saved after every part. After a crash, `upload()` with the same id proves the saved parts against `ListParts` and a re-read of the file before sending anything new. |
|
|
31
|
+
| 🎥 **Originals first** | Upload lanes keep ⌈2/3⌉ of the connections for originals while they have work; proxies borrow the rest and hand it back. |
|
|
32
|
+
| 🔑 **No storage credentials on clients** | Clients get per-part presigned URLs from your server, signed with [aws4fetch](https://github.com/mhart/aws4fetch). No AWS S3 SDK anywhere. |
|
|
33
|
+
| ⬇️ **Verified downloads** | Parallel ranged downloads pinned to one version (`If-Match`), checked against the uploader's ETag or SHA-256, resumable, never overwriting. |
|
|
34
|
+
| ▶️ **A player that keeps playing** | HLS or MP4, recovery with fresh URLs, fallback from the same spot, offline wait, stall and frozen-playhead detection (WebKit), bandwidth memory. Headless: a store your UI renders from. |
|
|
35
|
+
| 🪟 **Embeds** | `<uploadfilm-player>`, an iframe postMessage control API, snippets, oEmbed, and a tiny `<script>` build your server serves from its own domain. |
|
|
36
|
+
| 🔐 **Auth kit** | JWTs with `kid` rotation, device tokens, API keys (hashed, prefix + last4), signed URLs, AES-GCM sealed grants and envelopes, revocation lists. All WebCrypto, every compare constant-time, every verifier fails closed. |
|
|
37
|
+
| ⚙️ **Media pipeline** | Signed jobs to your own media Worker: HLS ladder 360/720/1080, poster, storyboard hover previews, fast-start MP4, audio and transcript, from **one decode** per job. |
|
|
38
|
+
| 🧩 **Yours to own** | No hardcoded hosts, buckets or tables. State goes through adapters you pass in (memory, Redis, R2, your database); records reach you as events and hooks. |
|
|
39
|
+
|
|
40
|
+
## 🧭 Entry points
|
|
41
|
+
|
|
42
|
+
Every entry point is a subpath of this one package, ESM + CJS with types (the Workers: ESM only), `sideEffects: false`.
|
|
43
|
+
|
|
44
|
+
| Import | What you get | Runs in |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| `@uploadfilm/sdk` | The client transfer engine: `createTransferEngine` (resumable verified uploads, lanes, claims, dedupe), `downloadObject`, transports (`createUndiciTransport`, `createFetchTransport`, `createElectronNetTransport`), `createHttpSigner`, `createEngineCore`, part math and integrity helpers, streaming-ZIP layout, image URL helpers, `copy()` with client-side modules | Node 20.16+ or 22.3+, Electron main |
|
|
47
|
+
| `@uploadfilm/sdk/player` | Headless player (`createPlayer`), its store, timed tracks (markers, chapters, captions), WebVTT captions, storyboard hover previews, embeds (options, snippets, oEmbed, `<uploadfilm-player>`, the postMessage control API) | Browsers |
|
|
48
|
+
| `@uploadfilm/sdk/react` | Hooks first: `usePlayer`, `usePlayerState`, `useTimedTrack`, `useCaptions`, `useTimelinePreview`, `useEmbedController`, `useImage`. Optional components: `<Player>` (a Video.js 10 skin over the engine), `<TimelinePreview>`, `<EmbedFrame>`, `<Image>` | React ≥ 18 |
|
|
49
|
+
| `@uploadfilm/sdk/server` | R2 presign, multipart and integrity (`createR2Client`), the key-layout guard (`createKeyGuard`), the sign route handler (`createSignHandler` with authorize / quota / dedupe hooks), the auth kit, state stores (`createMemoryStore`, `createR2Store`), `servePlayerScript()`, `copy()` with `r2()` / `s3()`, the upload-completed pipeline (`createPipeline` + Inngest / Cloudflare Queues / in-memory), the ZIP planner, the media job client | Node 20.16+ or 22.3+, Cloudflare Workers |
|
|
50
|
+
| `@uploadfilm/sdk/server/media` | Only the media Worker's protocol and job client (`mediaJobClient`, `refuseStale`, `ladderSettings`, `stepSettings`, `sourceHash`) | Node, Workers |
|
|
51
|
+
| `@uploadfilm/sdk/server/redis` | `createRedisStore(client)`: a `KeyValueStore` with atomic `incr` / `compareAndSet` over **your** `ioredis` or `@upstash/redis` client | Node, Workers |
|
|
52
|
+
| `@uploadfilm/sdk/server/testing` | `createFakeR2()`: a fake R2 that checks SigV4, serves presigned URLs and injects faults; `keyValueStoreContract` for your own state adapter | Node (tests) |
|
|
53
|
+
| `@uploadfilm/sdk/ai` | Pluggable speech-to-text and embeddings: Workers AI, any OpenAI-compatible server, Ollama, fakes | Node, Workers |
|
|
54
|
+
| `@uploadfilm/sdk/host` · `/host/node` | Host profile (CPU, memory, disk, power, thermal, network, hardware encoders) and how hard to drive it; `bindEngine` tunes uploads live | `/host` anywhere, `/host/node` Node |
|
|
55
|
+
| `@uploadfilm/sdk/cards` | Camera cards: mounted volumes, camera folder layouts read into clips (spanned clips, proxies, sidecars, LUTs), the upload plan | Node |
|
|
56
|
+
| `@uploadfilm/sdk/sync` | Dual-system audio sync: which recorder file belongs to which clip, and at what offset | Node (runs FFmpeg) |
|
|
57
|
+
| `@uploadfilm/sdk/workers/media` · `/config` · `/runner` | Your media Worker: `createMediaWorker(config)`, the `Transcoder` Durable Object, `ContainerProxy`; `/config` (types and defaults, safe in Node); `/runner` (self-hosted runner, the container program for a custom image). The container files: `/workers/media/container/Dockerfile`, `runner.mjs`. ESM only | Cloudflare Workers (`/runner`: Node 22.3+) |
|
|
58
|
+
| `@uploadfilm/sdk/workers/zip` | Your zip download Worker: `createZipWorker(config)`, `createZipHandler`. ESM only | Cloudflare Workers |
|
|
59
|
+
|
|
60
|
+
**Optional peer dependencies**, only for what you use: `react`, `@videojs/react`, `hls.js`, `undici`, `ioredis`,
|
|
61
|
+
`@upstash/redis`, `inngest`, `@cloudflare/workers-types`, `@cloudflare/containers` (the media Worker only). The SDK
|
|
62
|
+
never imports them itself where it can avoid it: you
|
|
63
|
+
pass `undici`, `hls.js` or Electron's `net` in.
|
|
64
|
+
|
|
65
|
+
## 🚀 Quick start: uploads (Node or Electron)
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import * as undici from "undici";
|
|
69
|
+
import { createHttpSigner, createTiming, createTransferEngine, createUndiciTransport, fileStore } from "@uploadfilm/sdk";
|
|
70
|
+
|
|
71
|
+
const timing = createTiming();
|
|
72
|
+
const engine = createTransferEngine({
|
|
73
|
+
// Batches the engine's ops into POST {ops} → {results} against your sign route (next section).
|
|
74
|
+
signer: createHttpSigner({
|
|
75
|
+
url: (scope) => `https://app.example.com/api/projects/${scope}/sign`,
|
|
76
|
+
headers: async () => ({ authorization: `Bearer ${await getSessionToken()}` }),
|
|
77
|
+
}),
|
|
78
|
+
transport: createUndiciTransport(undici, timing, {
|
|
79
|
+
allowedOrigins: ["https://ACCOUNT_ID.r2.cloudflarestorage.com"], // nothing else is ever PUT to
|
|
80
|
+
}),
|
|
81
|
+
timing,
|
|
82
|
+
store: fileStore("./.upload-state"), // survives a crash: upload() again with the same id resumes
|
|
83
|
+
lanes: [
|
|
84
|
+
{ name: "original", minShare: 2 / 3 }, // originals keep ⌈2/3⌉ of the connections
|
|
85
|
+
{ name: "proxy", yieldable: true }, // proxies borrow the rest
|
|
86
|
+
],
|
|
87
|
+
});
|
|
88
|
+
engine.start();
|
|
89
|
+
|
|
90
|
+
const upload = engine.upload({
|
|
91
|
+
scope: "project-42",
|
|
92
|
+
key: "p/project-42/orig/A001_C003.mov",
|
|
93
|
+
path: "/Volumes/CARD/A001_C003.mov",
|
|
94
|
+
lane: "original",
|
|
95
|
+
immutable: true, // written once: a different object at this key is a conflict, never overwritten
|
|
96
|
+
});
|
|
97
|
+
upload.on("progress", (sent, size) => console.log(`${((100 * sent) / size).toFixed(1)}%`));
|
|
98
|
+
upload.on("state", (s) => console.log("state:", s)); // queued | waiting | sending | verified | failed
|
|
99
|
+
|
|
100
|
+
const result = await upload.done;
|
|
101
|
+
if (result.state === "verified") console.log("stored and verified", result.etag);
|
|
102
|
+
else console.error(result.code, result.error, result.retryable ? "(try again later)" : "");
|
|
103
|
+
engine.stop();
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Electron main process:** the same engine over Chromium's network stack. The SDK never imports Electron; you pass
|
|
107
|
+
`net` in: `transport: createElectronNetTransport(net, timing)`.
|
|
108
|
+
|
|
109
|
+
Useful extras: `engine.pause()` / `engine.resume()`, `engine.stats()`, `connections: { min, max }`, `inflightBytes`,
|
|
110
|
+
`shareUploads: true`, `claims` (two processes never send the same key twice), `dedupe: true`, `integrity: "sha256"`,
|
|
111
|
+
and `source: ByteSource` (`bufferSource`, `fileSource`) for something that isn't a path.
|
|
112
|
+
|
|
113
|
+
**A verified download** (ranged, parallel, pinned to one version):
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import { createTiming, downloadObject } from "@uploadfilm/sdk";
|
|
117
|
+
|
|
118
|
+
const result = await downloadObject({
|
|
119
|
+
url: () => signedGetUrl("p/project-42/orig/A001_C003.mov"), // re-signed after a 403
|
|
120
|
+
dest: "/Users/me/Downloads/A001_C003.mov", // bytes go to .part first; never overwrites
|
|
121
|
+
size: 734_003_200,
|
|
122
|
+
etag: "9b2cf535f27731c974343645a3985328-44", // the uploader's verified ETag
|
|
123
|
+
timing: createTiming(),
|
|
124
|
+
onProgress: (done, size) => console.log(done, size),
|
|
125
|
+
});
|
|
126
|
+
console.log(result.state); // "verified" | "unverified" (with a reason)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Pass `state: { load, save, remove }` to resume a download after a restart.
|
|
130
|
+
|
|
131
|
+
> 🌐 The transfer engine reads files with `node:fs`, so it runs in Node and Electron, not in a browser (yet). The
|
|
132
|
+
> player, embeds and image helpers do run in browsers.
|
|
133
|
+
|
|
134
|
+
## 🔐 Quick start: the server route
|
|
135
|
+
|
|
136
|
+
The server side of uploads is one route. Here as a Next.js route handler (on a Worker it's the same
|
|
137
|
+
`(req) => Response`), with the auth kit verifying a short-lived token your app issued:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
// app/api/projects/[id]/sign/route.ts
|
|
141
|
+
import { createKeyGuard, createR2Client, createSignHandler, keyring, verifyToken } from "@uploadfilm/sdk/server";
|
|
142
|
+
|
|
143
|
+
const r2 = createR2Client({
|
|
144
|
+
endpoint: process.env.R2_ENDPOINT!, // https://<account>.r2.cloudflarestorage.com
|
|
145
|
+
bucket: process.env.R2_BUCKET!, // "bucket" or "bucket/prefix"
|
|
146
|
+
accessKeyId: process.env.R2_ACCESS_KEY_ID!,
|
|
147
|
+
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
|
|
148
|
+
fetch: (url, init) => fetch(url, { ...init, cache: "no-store" }), // Next.js: never cache storage calls
|
|
149
|
+
});
|
|
150
|
+
const keys = keyring({ current: { kid: "2026-11", secret: process.env.TOKEN_SECRET! } });
|
|
151
|
+
|
|
152
|
+
type Kind = "original" | "proxy";
|
|
153
|
+
// The only keys this route signs: p/<projectId>/orig/<name> and p/<projectId>/proxy/<name>.
|
|
154
|
+
const classify = createKeyGuard<Kind>([
|
|
155
|
+
(s) => (s[0] === "orig" && s.length === 2 ? "original" : null),
|
|
156
|
+
(s) => (s[0] === "proxy" && s.length === 2 ? "proxy" : null),
|
|
157
|
+
]);
|
|
158
|
+
|
|
159
|
+
const handler = createSignHandler<Kind, { userId: string; projectId: string }>({
|
|
160
|
+
r2,
|
|
161
|
+
classify: (key, ctx) => classify(`p/${ctx.projectId}/`, key),
|
|
162
|
+
immutable: (kind) => kind === "original",
|
|
163
|
+
hooks: {
|
|
164
|
+
// Quota that can't be raced: charge before a write is signed, bind it to the multipart, check it at complete.
|
|
165
|
+
reserve: async (ctx, w) => ((await reserveBytes(ctx.userId, w.key, w.size, w.uploadId)) ? "ok" : "quota"),
|
|
166
|
+
bindUpload: (_ctx, key, uploadId) => bindReservation(key, uploadId),
|
|
167
|
+
reservation: (ctx, key, uploadId) => reservedBytes(ctx.userId, key, uploadId),
|
|
168
|
+
},
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
|
|
172
|
+
const { id } = await params;
|
|
173
|
+
const auth = await verifyToken(keys, req.headers.get("authorization")?.replace(/^Bearer /, ""), {
|
|
174
|
+
aud: "uploads",
|
|
175
|
+
scope: `project:${id}:write`,
|
|
176
|
+
});
|
|
177
|
+
if (!auth.ok) return Response.json({ error: "unauthorized" }, { status: 401 });
|
|
178
|
+
const answer = await handler.handle(await req.json(), { userId: auth.claims.sub, projectId: id });
|
|
179
|
+
return Response.json(answer.body, { status: answer.status });
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Issuing that token, with key rotation:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
import { issueToken, keyring } from "@uploadfilm/sdk/server";
|
|
187
|
+
|
|
188
|
+
const keys = keyring({
|
|
189
|
+
current: { kid: "2026-11", secret: process.env.TOKEN_SECRET! },
|
|
190
|
+
previous: [{ kid: "2026-10", secret: process.env.TOKEN_SECRET_PREVIOUS! }], // old tokens still verify
|
|
191
|
+
});
|
|
192
|
+
export const uploadToken = (userId: string, projectId: string) =>
|
|
193
|
+
issueToken(keys, { sub: userId, aud: "uploads", scope: [`project:${projectId}:write`], ttl: "15m" });
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The hooks are where your policy lives: `guard`, `grant`, `reserve` / `bindUpload` / `confirm` / `release` /
|
|
197
|
+
`reservation`, `dedupe`, `onError`, and custom `ops`. More of the auth kit:
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
import { createMemoryStore, generateApiKey, grantSealer, keyring, revocationList, signUrl, verifySignedUrl } from "@uploadfilm/sdk/server";
|
|
201
|
+
import { createRedisStore } from "@uploadfilm/sdk/server/redis";
|
|
202
|
+
|
|
203
|
+
const keys = keyring({ current: { kid: "k1", secret: process.env.TOKEN_SECRET! } });
|
|
204
|
+
|
|
205
|
+
const { raw, hash, prefix, last4 } = await generateApiKey({ prefix: "cm_live_" }); // show raw once, store hash
|
|
206
|
+
const url = await signUrl(keys, "https://app.example.com/files/123", { ttl: "10m" });
|
|
207
|
+
const check = await verifySignedUrl(keys, url); // { ok: true, exp, kid } | { ok: false, reason }
|
|
208
|
+
|
|
209
|
+
const kv = redisClient ? createRedisStore(redisClient) : createMemoryStore(); // ioredis or @upstash/redis
|
|
210
|
+
await revocationList(kv).revoke("token-jti", Math.floor(Date.now() / 1000) + 3600);
|
|
211
|
+
|
|
212
|
+
// Sealed grants (AES-GCM): read access to one folder until `exp`; what viewers of the media Worker carry.
|
|
213
|
+
const grants = grantSealer({ salt: "myproduct-stream", isValid: (g) => /^media\/[0-9a-f]{32}\/$/.test(g.prefix) });
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
> With `@upstash/redis`, create the client with `automaticDeserialization: false` (values come back as stored).
|
|
217
|
+
|
|
218
|
+
## 🎬 The player
|
|
219
|
+
|
|
220
|
+
The player is **headless**: an engine that owns the hard part (staying playing) and a store your UI renders from. The
|
|
221
|
+
React components are thin renders of public hooks, so you can replace any of them.
|
|
222
|
+
|
|
223
|
+
**React, default skin** (Video.js 10's skin over the SDK's engine; `react`, `@videojs/react` and `hls.js` are yours):
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
import "@videojs/react/video/skin.css";
|
|
227
|
+
import { Video, VideoPlayer, VideoSkin } from "@videojs/react/video";
|
|
228
|
+
import { HlsJsVideo } from "@videojs/react/media/hlsjs-video";
|
|
229
|
+
import { Player, type VideoJsComponents } from "@uploadfilm/sdk/react";
|
|
230
|
+
|
|
231
|
+
const VIDEOJS: VideoJsComponents = { Video, VideoPlayer, VideoSkin, HlsJsVideo };
|
|
232
|
+
|
|
233
|
+
export function Watch({ hls, mp4, poster }: { hls: string | null; mp4: string; poster?: string }) {
|
|
234
|
+
return (
|
|
235
|
+
<div style={{ position: "relative", aspectRatio: "16 / 9" }}>
|
|
236
|
+
<Player
|
|
237
|
+
sources={{ hls, mp4 }}
|
|
238
|
+
components={VIDEOJS}
|
|
239
|
+
poster={poster}
|
|
240
|
+
title="Day 3, scene 12"
|
|
241
|
+
theme={{ accentColor: "#ffb800", accentTextColor: "#000", borderRadius: "12px" }}
|
|
242
|
+
storyboard="https://media.example.com/h/GRANT/storyboard/storyboard.vtt"
|
|
243
|
+
bigPlay
|
|
244
|
+
onReady={() => console.log("playing with a buffer")}
|
|
245
|
+
onFailed={() => console.log("out of tries")}
|
|
246
|
+
/>
|
|
247
|
+
</div>
|
|
248
|
+
);
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Without `components`, `<Player>` renders a plain `<video controls>` loaded by the engine. The package ships no CSS.
|
|
253
|
+
|
|
254
|
+
**Vanilla:**
|
|
255
|
+
|
|
256
|
+
```ts
|
|
257
|
+
import Hls from "hls.js";
|
|
258
|
+
import { captionsTrack, createPlayer, hlsJsLoader } from "@uploadfilm/sdk/player";
|
|
259
|
+
|
|
260
|
+
const player = createPlayer({
|
|
261
|
+
sources: { hls: "https://media.example.com/h/GRANT/master.m3u8", mp4: "https://cdn.example.com/clip.mp4" },
|
|
262
|
+
stream: hlsJsLoader(Hls), // the SDK never imports hls.js itself
|
|
263
|
+
refreshSource: async ({ mode, attempt }) => freshSignedUrl(mode, attempt), // a new URL for a recovery
|
|
264
|
+
tracks: [captionsTrack("https://media.example.com/h/GRANT/transcript.vtt", { language: "en", label: "English" })],
|
|
265
|
+
});
|
|
266
|
+
player.attach(document.querySelector("video")!);
|
|
267
|
+
player.on("fallback", ({ from }) => console.log(`${from} gave up; the MP4 plays from the same spot`));
|
|
268
|
+
player.subscribe((s) => (document.title = `${s.status} · ${Math.round(s.currentTime)}s`));
|
|
269
|
+
await player.play(); // "sound" | "muted" | "failed" | "aborted"
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
What it does for you:
|
|
273
|
+
|
|
274
|
+
- 📡 **HLS or MP4.** The stream where the browser can (MediaSource, ManagedMediaSource or native HLS), the MP4 otherwise.
|
|
275
|
+
- 🩹 **Recovery.** A stream failing before it played becomes the MP4 from the same spot; later failures load a fresh URL
|
|
276
|
+
and carry on, in the same paused/playing state, with backoff.
|
|
277
|
+
- 📴 **Offline.** It waits for the network instead of spending tries.
|
|
278
|
+
- 🧊 **Stalls.** A stalled MP4 or a frozen HLS playhead (WebKit: no error, no stall event) is reloaded.
|
|
279
|
+
- ✋ **The viewer's pause wins**, through fallbacks and recoveries.
|
|
280
|
+
|
|
281
|
+
Events: `ready`, `stall`, `error`, `recover`, `fallback`, `cantplay`, `failed`, `offline` / `online`, `cuechange`,
|
|
282
|
+
`sourcechange`, plus the element's own. In React, `usePlayer({ …, onReady, onStall, onFailed, onEvent })` and
|
|
283
|
+
`usePlayerState(player, selector)`.
|
|
284
|
+
|
|
285
|
+
**Tracks, captions and hover previews.** Markers, chapters and captions are `TimedTrack`s
|
|
286
|
+
(`player.setTracks([...])`, `loadCaptions`, `captionsFromVtt`, `cuePosition`, `nextCue`). Storyboard previews come from
|
|
287
|
+
the media Worker's `storyboard.vtt`: `createTimelinePreviews(url)` + `spriteStyle(preview, 160)`, or in React
|
|
288
|
+
`useTimelinePreview(url, hoverTime, { width: 160 })` and `<TimelinePreview>`.
|
|
289
|
+
|
|
290
|
+
**Your own controls**, no Video.js:
|
|
291
|
+
|
|
292
|
+
```tsx
|
|
293
|
+
import Hls from "hls.js";
|
|
294
|
+
import { hlsJsLoader } from "@uploadfilm/sdk/player";
|
|
295
|
+
import { usePlayer, usePlayerState } from "@uploadfilm/sdk/react";
|
|
296
|
+
|
|
297
|
+
const stream = hlsJsLoader(Hls);
|
|
298
|
+
|
|
299
|
+
export function MiniPlayer({ hls, mp4 }: { hls: string; mp4: string }) {
|
|
300
|
+
const { player, videoRef } = usePlayer({ sources: { hls, mp4 }, stream, autoplay: false });
|
|
301
|
+
const { paused, currentTime, duration } = usePlayerState(player, (s) => ({
|
|
302
|
+
paused: s.paused,
|
|
303
|
+
currentTime: s.currentTime,
|
|
304
|
+
duration: s.duration,
|
|
305
|
+
}));
|
|
306
|
+
return (
|
|
307
|
+
<div>
|
|
308
|
+
<video ref={videoRef} playsInline style={{ width: "100%" }} />
|
|
309
|
+
<button onClick={() => (paused ? void player.play() : player.pause())}>{paused ? "▶️" : "⏸️"}</button>
|
|
310
|
+
<span>{Math.round(currentTime)} / {Math.round(duration)} s</span>
|
|
311
|
+
</div>
|
|
312
|
+
);
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### 🪟 Embeds
|
|
317
|
+
|
|
318
|
+
Serve the embed script from your own domain:
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
// app/embeds/v1/player.js/route.ts
|
|
322
|
+
import { servePlayerScript } from "@uploadfilm/sdk/server";
|
|
323
|
+
|
|
324
|
+
const serve = servePlayerScript(); // 200 with an ETag, then cheap 304s
|
|
325
|
+
export const GET = serve;
|
|
326
|
+
export const HEAD = serve;
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Your customers' pages then do:
|
|
330
|
+
|
|
331
|
+
```html
|
|
332
|
+
<iframe id="reel" src="https://app.example.com/e/EMBED_ID" allow="autoplay; fullscreen; picture-in-picture"></iframe>
|
|
333
|
+
<script src="https://app.example.com/embeds/v1/player.js"></script>
|
|
334
|
+
<script>
|
|
335
|
+
const player = new UploadFilm.Player(document.getElementById("reel"));
|
|
336
|
+
player.on("ready", () => player.seek(12.5).play());
|
|
337
|
+
</script>
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
From your own code: `new EmbedController(iframe)`, `defineEmbedElement()` for `<uploadfilm-player src="…">`,
|
|
341
|
+
`iframeSnippet(…)` for the copy-paste snippet, `parseOEmbedRequest` + `buildOEmbed`, and on the frame side
|
|
342
|
+
`serveEmbedControl(player, { embedId })`. Your product's name on the global (`MyApp.Player`):
|
|
343
|
+
`servePlayerScript({ script: renameEmbedGlobal(PLAYER_SCRIPT, "MyApp") })`; the tag too: `defineEmbedElement("myapp-player")`.
|
|
344
|
+
|
|
345
|
+
## ⚙️ The media pipeline on Cloudflare Workers
|
|
346
|
+
|
|
347
|
+
You run your own media Worker (Worker + Durable Object + FFmpeg Container) on your own Cloudflare account, against
|
|
348
|
+
your own bucket. The Worker ships **in this package** at `@uploadfilm/sdk/workers/media` (same version as the job client
|
|
349
|
+
your site imports, so they never drift):
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
npm install @uploadfilm/sdk @cloudflare/containers@^0.3.7 @cloudflare/workers-types wrangler # the peers only the Worker needs
|
|
353
|
+
npx @uploadfilm/sdk init media-worker workers/media # worker.ts, config.ts, wrangler.toml (never overwrites)
|
|
354
|
+
cd workers/media && npx wrangler secret put MEDIA_SECRET && npx wrangler deploy # set a Cloudflare budget alert first
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
```ts
|
|
358
|
+
// workers/media/worker.ts
|
|
359
|
+
import { createMediaWorker } from "@uploadfilm/sdk/workers/media";
|
|
360
|
+
import { config } from "./config";
|
|
361
|
+
export default createMediaWorker(config);
|
|
362
|
+
export { Transcoder, ContainerProxy } from "@uploadfilm/sdk/workers/media";
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
The container image is built from the installed package (`dist/workers/media/container/Dockerfile`: a pinned base image
|
|
366
|
+
and FFmpeg 7.1.5, no product settings baked in). Your site uses the job client and the protocol below.
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
your site ──signed job (HMAC)──▶ media Worker ──▶ Durable Object (one per job) ──▶ FFmpeg Container: ONE decode
|
|
370
|
+
▲ │
|
|
371
|
+
└────────── signed report ◀── destroy() the container once the result is in ◀───────┘ outputs ──▶ your R2
|
|
372
|
+
viewers ──▶ /h/<sealed grant>/master.m3u8 (served by the Worker)
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
| Step | Outputs |
|
|
376
|
+
|---|---|
|
|
377
|
+
| `ladder` | HLS fMP4, 360 / 720 / 1080; `master.m3u8` is written last: it is the "done" file |
|
|
378
|
+
| `poster` | the poster frame |
|
|
379
|
+
| `storyboard` | WebP sprite sheets + `storyboard.vtt` for hover previews |
|
|
380
|
+
| `faststart` | `faststart.mp4`, index first (a remux, no decode) |
|
|
381
|
+
| `audio` / `transcript` | audio chunks with silences found; `transcript.json` + `transcript.vtt` (Workers AI Whisper or any `@uploadfilm/sdk/ai` Transcriber) |
|
|
382
|
+
|
|
383
|
+
From your site:
|
|
384
|
+
|
|
385
|
+
```ts
|
|
386
|
+
import { grantSealer, jobVersion, mediaJobClient, refuseStale, sourceHash, stepSettings, type Step } from "@uploadfilm/sdk/server";
|
|
387
|
+
|
|
388
|
+
const VERSION = "360-720-1080/2"; // the same as the Worker's config: stamped on every output
|
|
389
|
+
const SETTINGS = stepSettings("steps-sb/1", { storyboard: {} });
|
|
390
|
+
const STEPS: Step[] = ["ladder", "poster", "storyboard"];
|
|
391
|
+
const STAMP = jobVersion(VERSION, STEPS, SETTINGS);
|
|
392
|
+
|
|
393
|
+
const media = mediaJobClient({
|
|
394
|
+
url: process.env.MEDIA_URL!,
|
|
395
|
+
secret: () => process.env.MEDIA_SECRET!,
|
|
396
|
+
jobDomain: "media-job-1",
|
|
397
|
+
doneDomain: "media-done-1",
|
|
398
|
+
signatureHeader: "x-media-sig",
|
|
399
|
+
issuedAt: true, // a captured request can't be replayed later
|
|
400
|
+
});
|
|
401
|
+
|
|
402
|
+
export async function requestMedia(src: string, etag: string, bytes: number, attempt: number) {
|
|
403
|
+
const prefix = `media/${(await sourceHash(src, etag, VERSION)).slice(0, 32)}/`;
|
|
404
|
+
await media.request({ id: prefix.split("/")[1], attempt, src, etag, bytes, prefix, done: "https://app.example.com/api/media/done", steps: STEPS });
|
|
405
|
+
return prefix;
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
// POST /api/media/done: the Worker's signed report.
|
|
409
|
+
export async function POST(req: Request) {
|
|
410
|
+
const checked = await media.readReport(await req.text(), req.headers.get("x-media-sig") ?? "");
|
|
411
|
+
if (!checked.ok) return new Response(checked.body, { status: checked.status });
|
|
412
|
+
const r = checked.report;
|
|
413
|
+
if (r.state === "done" && refuseStale({ state: "done", ladder: r.ladder as string | undefined }, STAMP))
|
|
414
|
+
return new Response("stale image", { status: 409 });
|
|
415
|
+
// Update your record only where id, attempt AND prefix still match: a late report of an older attempt changes nothing.
|
|
416
|
+
await markReadyIfCurrent({ id: String(r.id), attempt: Number(r.attempt), prefix: String(r.prefix), ok: r.state === "done" });
|
|
417
|
+
return new Response("ok");
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
// A viewer's URL: a sealed grant to the outputs' folder, valid 6 hours.
|
|
421
|
+
const grants = grantSealer({ salt: "myproduct-stream", isValid: (g) => /^media\/[0-9a-f]{32}\/$/.test(g.prefix) });
|
|
422
|
+
export async function streamUrl(prefix: string) {
|
|
423
|
+
const token = await grants.sealGrant(process.env.MEDIA_SECRET!, { prefix, exp: Math.floor(Date.now() / 1000) + 6 * 3600 });
|
|
424
|
+
return `${process.env.MEDIA_URL}/h/${token}/master.m3u8`;
|
|
425
|
+
}
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
- 🔏 **Signed both ways**, with different HMAC domains; with `issuedAt` a request outside ±15 min is refused.
|
|
429
|
+
- 📁 **A job writes only where its source's outputs belong**; reads are pinned to the source ETag; callbacks are
|
|
430
|
+
allowlisted (https only).
|
|
431
|
+
- 🏷️ **The settings version is the idempotency key**: the same id + version is the same job, joined while it runs and
|
|
432
|
+
answered from its result once done. Outputs stamped by an older image are refused.
|
|
433
|
+
- 💸 **Containers never idle**: the Durable Object calls `destroy()` as soon as the result is collected, and the
|
|
434
|
+
container exits on SIGTERM. An idle-container bug once cost about $77 in a week. **Set a budget alert on your
|
|
435
|
+
Cloudflare account before the first deploy.**
|
|
436
|
+
- 🎞️ The container runs a pinned FFmpeg 7.1.5. Proprietary RAW never goes in the core image: without a decoder plugin a
|
|
437
|
+
RAW source fails with code `unsupported`, so store it and flag it "no preview".
|
|
438
|
+
|
|
439
|
+
Also server-side: `copy()` with `r2()` / `s3()` replicates objects to S3 (backup, archive, Object Lock) with byte
|
|
440
|
+
verification, driven by `createPipeline`; a ZIP Worker (`@uploadfilm/sdk/workers/zip`,
|
|
441
|
+
`npx @uploadfilm/sdk init zip-worker`) streams folder downloads of any size straight from R2.
|
|
442
|
+
|
|
443
|
+
## 🧪 Testing your integration
|
|
444
|
+
|
|
445
|
+
`@uploadfilm/sdk/server/testing` gives you a fake R2 that checks SigV4 like the real one, serves presigned URLs and
|
|
446
|
+
injects faults. Wire your real sign handler to it and run the real engine end to end:
|
|
447
|
+
|
|
448
|
+
```ts
|
|
449
|
+
import { mkdtempSync, writeFileSync } from "node:fs";
|
|
450
|
+
import { tmpdir } from "node:os";
|
|
451
|
+
import { join } from "node:path";
|
|
452
|
+
import { createFetchTransport, createHttpSigner, createTiming, createTransferEngine } from "@uploadfilm/sdk";
|
|
453
|
+
import { createKeyGuard, createR2Client, createSignHandler } from "@uploadfilm/sdk/server";
|
|
454
|
+
import { createFakeR2 } from "@uploadfilm/sdk/server/testing";
|
|
455
|
+
|
|
456
|
+
const fake = await createFakeR2(); // a random local port
|
|
457
|
+
const guard = createKeyGuard((s) => (s[0] === "orig" ? "original" : null));
|
|
458
|
+
const handler = createSignHandler({
|
|
459
|
+
r2: createR2Client(fake.config),
|
|
460
|
+
classify: (key, ctx: { project: string }) => guard(`p/${ctx.project}/`, key),
|
|
461
|
+
immutable: () => true,
|
|
462
|
+
});
|
|
463
|
+
const timing = createTiming({ scale: 0.01 }); // timeouts and backoffs 100× shorter
|
|
464
|
+
const engine = createTransferEngine({
|
|
465
|
+
signer: createHttpSigner({
|
|
466
|
+
url: "http://test/sign",
|
|
467
|
+
fetch: async (_url, init) => {
|
|
468
|
+
const answer = await handler.handle(JSON.parse(String(init?.body)), { project: "p1" });
|
|
469
|
+
return Response.json(answer.body, { status: answer.status });
|
|
470
|
+
},
|
|
471
|
+
}),
|
|
472
|
+
transport: createFetchTransport(timing),
|
|
473
|
+
timing,
|
|
474
|
+
scope: "p1",
|
|
475
|
+
});
|
|
476
|
+
engine.start();
|
|
477
|
+
|
|
478
|
+
// Storage stores a corrupted part: the engine must resend it, never say "verified" on bad bytes.
|
|
479
|
+
fake.fault({ target: "partPut", action: "storeCorrupted", times: 1 });
|
|
480
|
+
|
|
481
|
+
const file = join(mkdtempSync(join(tmpdir(), "sdk-")), "clip.mov");
|
|
482
|
+
writeFileSync(file, Buffer.alloc(40 * 1024 * 1024, 7));
|
|
483
|
+
const r = await engine.upload({ key: "p/p1/orig/clip.mov", path: file, immutable: true }).done;
|
|
484
|
+
console.assert(r.state === "verified");
|
|
485
|
+
console.assert(fake.object("p/p1/orig/clip.mov")!.body.equals(Buffer.alloc(40 * 1024 * 1024, 7))); // the bytes
|
|
486
|
+
engine.stop();
|
|
487
|
+
await fake.close();
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
Faults: `drop`, `reset`, `dropResponse`, `holdResponse`, `delay`, `status`, `stall`, `noSuchUpload`, `expire`,
|
|
491
|
+
`corruptInTransit`, `storeCorrupted`, `wrongEtag` (aim them with `times`, `after`, `match`), and `fake.outage(true)` for
|
|
492
|
+
a pulled cable. ✅ **Make every test check the stored bytes, not just the result.** Writing your own `KeyValueStore`?
|
|
493
|
+
Run `keyValueStoreContract` against it.
|
|
494
|
+
|
|
495
|
+
## 🛡️ Guarantees
|
|
496
|
+
|
|
497
|
+
- 🔒 **Security.** Tokens, signed URLs, routes and embeds are attacked by a red team (forge, steal, replay, escalate,
|
|
498
|
+
cross-access, inject); every hole closed has a regression test. Verifiers fail closed, secret compares are
|
|
499
|
+
constant-time, every token kind is domain-separated, revocation stores that can't answer mean "revoked", and the key
|
|
500
|
+
guard refuses traversal, encoding tricks, invisible and bidi characters. Signed URLs never appear in results or errors.
|
|
501
|
+
- 🧱 **Reliability.** Fault-injecting fake servers, property-based tests, kill-and-resume and soak runs, with every
|
|
502
|
+
test upload's bytes checked against the stored object: zero tolerance for silent corruption or a false "done".
|
|
503
|
+
- 🎥 **Formats.** Cameras, phones, codecs and containers probe, process and play correctly, or are rejected or flagged
|
|
504
|
+
gracefully (HDR tone-mapped, interlaced deinterlaced, VFR, edit lists, RAW flagged "no preview" without a plugin).
|
|
505
|
+
|
|
506
|
+
## ❓ Good to know
|
|
507
|
+
|
|
508
|
+
- **Node:** `^20.16.0 || >=22.3.0` (the SDK uses `zlib.crc32` and `process.getBuiltinModule`).
|
|
509
|
+
- **Why not the AWS S3 SDK?** Write credentials on a laptop would bypass immutability and quota, so clients only get
|
|
510
|
+
per-part presigned URLs. Lighter too.
|
|
511
|
+
- **Workers' ~100 MiB request cap:** `s3()` and `r2()` over the S3 API cap requests at 96 MiB inside a Worker by
|
|
512
|
+
themselves. Client uploads go straight to R2 with presigned URLs and never pass through a Worker.
|
|
513
|
+
- **Next.js caches storage calls:** pass `fetch: (url, init) => fetch(url, { ...init, cache: "no-store" })` to
|
|
514
|
+
`createR2Client`.
|
|
515
|
+
- **Keep your own uploader?** Fine: take the transports, signing or player alone. Everything is an independent import.
|
|
516
|
+
|
|
517
|
+
## 🚧 Not built yet
|
|
518
|
+
|
|
519
|
+
| Not yet | Today |
|
|
520
|
+
|---|---|
|
|
521
|
+
| A browser build of the transfer engine (File source, wasm hasher) | Node and Electron only |
|
|
522
|
+
| Growing-source uploads (a file still being recorded) | upload once the file is closed |
|
|
523
|
+
| An async `ResumeStore` | `fileStore`, `memoryStore` (synchronous) |
|
|
524
|
+
| SHA-256 receipts through `createSignHandler` | it fails closed (`Unverified`); sign `x-amz-checksum-sha256` in a route of your own |
|
|
525
|
+
| Job bookkeeping helpers (claims, attempts, backoff for media jobs) | your own |
|
|
526
|
+
| RAW plugins for R3D, ARRIRAW, Canon Cinema RAW Light | BRAW only |
|
|
527
|
+
|
|
528
|
+
## License
|
|
529
|
+
|
|
530
|
+
Proprietary (`UNLICENSED`): see `LICENSE` in the package. Use requires a written agreement with UploadFilm.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Vectors for a transcript's passages (or a video's frames), delivered batch by batch to the product's `onEmbeddings`
|
|
3
|
+
* hook. The SDK NEVER stores them: the product writes them to its own pgvector table or Vectorize index (keyed by its
|
|
4
|
+
* asset id + passage index), and decides what to do when its write fails.
|
|
5
|
+
*
|
|
6
|
+
* Never throws: the outcome says what was delivered, so an embedding that can't be made never fails a video job.
|
|
7
|
+
*/
|
|
8
|
+
import { type Passage, type PassageOptions } from "./passages";
|
|
9
|
+
import type { Transcript } from "../server/media/transcript";
|
|
10
|
+
import type { AiUsage, Embedder, ImageInput } from "./types";
|
|
11
|
+
export interface EmbeddingBatch<T> {
|
|
12
|
+
/** What was embedded (passages, or frames' times), in order. */
|
|
13
|
+
items: T[];
|
|
14
|
+
/** One vector per item. */
|
|
15
|
+
vectors: number[][];
|
|
16
|
+
adapter: string;
|
|
17
|
+
model: string;
|
|
18
|
+
dimensions: number;
|
|
19
|
+
usage: AiUsage;
|
|
20
|
+
/** Which batch (0-based) of how many. */
|
|
21
|
+
batch: number;
|
|
22
|
+
batches: number;
|
|
23
|
+
}
|
|
24
|
+
export type EmbedOutcome = {
|
|
25
|
+
state: "done";
|
|
26
|
+
items: number;
|
|
27
|
+
batches: number;
|
|
28
|
+
dimensions: number;
|
|
29
|
+
usage: AiUsage[];
|
|
30
|
+
} | {
|
|
31
|
+
state: "error";
|
|
32
|
+
reason: string;
|
|
33
|
+
permanent: boolean;
|
|
34
|
+
/** Batches already handed to onEmbeddings. */ delivered: number;
|
|
35
|
+
usage: AiUsage[];
|
|
36
|
+
};
|
|
37
|
+
export interface EmbedRunOptions<T> {
|
|
38
|
+
embedder: Embedder;
|
|
39
|
+
/** Gets each batch's vectors. A throw (the product's store failed) stops the run: state "error". */
|
|
40
|
+
onEmbeddings(batch: EmbeddingBatch<T>): void | Promise<void>;
|
|
41
|
+
/** Items per call (default and maximum: the embedder's maxBatch). */
|
|
42
|
+
batchSize?: number;
|
|
43
|
+
signal?: AbortSignal;
|
|
44
|
+
onUsage?: (u: AiUsage) => void;
|
|
45
|
+
}
|
|
46
|
+
/** A transcript → passages → vectors, handed over batch by batch. */
|
|
47
|
+
export declare function embedTranscript(o: EmbedRunOptions<Passage> & {
|
|
48
|
+
transcript: Pick<Transcript, "segments">;
|
|
49
|
+
passages: PassageOptions;
|
|
50
|
+
}): Promise<EmbedOutcome>;
|
|
51
|
+
/** Passages (from transcriptPassages, or the product's own) → vectors. */
|
|
52
|
+
export declare function embedPassages(o: EmbedRunOptions<Passage> & {
|
|
53
|
+
passages: Passage[];
|
|
54
|
+
}): Promise<EmbedOutcome>;
|
|
55
|
+
/** Frames (storyboard tiles, keyframes) → vectors; each frame's `t` comes back with its vector. */
|
|
56
|
+
export declare function embedFrames(o: EmbedRunOptions<ImageInput> & {
|
|
57
|
+
frames: ImageInput[];
|
|
58
|
+
}): Promise<EmbedOutcome>;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fakes for tests: a transcriber answering from a script (recorded answers, errors, delays) and a deterministic
|
|
3
|
+
* embedder (the same text always gives the same unit vector). Both report usage like a real adapter.
|
|
4
|
+
*/
|
|
5
|
+
import { type AudioInput, type EmbedInput, type Embedder, type TranscribeOptions, type Transcriber, type Transcription } from "./types";
|
|
6
|
+
export type FakeAnswer = Omit<Transcription, "usage" | "text"> & {
|
|
7
|
+
text?: string;
|
|
8
|
+
};
|
|
9
|
+
export interface FakeTranscriberOptions {
|
|
10
|
+
/**
|
|
11
|
+
* The answer to call n (0-based): a Transcription-like value, an Error to throw, or a function of the audio. Past the
|
|
12
|
+
* end of a list, the last entry repeats.
|
|
13
|
+
*/
|
|
14
|
+
answers: (FakeAnswer | Error)[] | ((audio: AudioInput, n: number, o: TranscribeOptions) => FakeAnswer | Error | Promise<FakeAnswer | Error>);
|
|
15
|
+
model?: string;
|
|
16
|
+
maxBytes?: number;
|
|
17
|
+
/** Simulated latency (ms) reported in usage. */
|
|
18
|
+
latencyMs?: number;
|
|
19
|
+
/** Simulated price per audio minute. */
|
|
20
|
+
perAudioMinuteUsd?: number;
|
|
21
|
+
}
|
|
22
|
+
export declare function fakeTranscriber(o: FakeTranscriberOptions): Transcriber & {
|
|
23
|
+
calls: {
|
|
24
|
+
audio: AudioInput;
|
|
25
|
+
options: TranscribeOptions;
|
|
26
|
+
}[];
|
|
27
|
+
};
|
|
28
|
+
/** A deterministic unit vector for a string (tests: equal texts → equal vectors; different texts → different). */
|
|
29
|
+
export declare function fakeVector(s: string, dims: number): number[];
|
|
30
|
+
export interface FakeEmbedderOptions {
|
|
31
|
+
dimensions?: number;
|
|
32
|
+
model?: string;
|
|
33
|
+
maxBatch?: number;
|
|
34
|
+
images?: boolean;
|
|
35
|
+
/** Throw this on call n (0-based). */
|
|
36
|
+
failOn?: (n: number) => Error | undefined;
|
|
37
|
+
latencyMs?: number;
|
|
38
|
+
}
|
|
39
|
+
export declare function fakeEmbedder(o?: FakeEmbedderOptions): Embedder & {
|
|
40
|
+
calls: EmbedInput[];
|
|
41
|
+
};
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
|
|
2
|
+
/** A key, or a function giving one (rotated secrets, a vault): asked for on every call, never kept. */
|
|
3
|
+
export type Credential = string | (() => string | Promise<string>);
|
|
4
|
+
export declare const credential: (c: Credential | undefined) => Promise<string | undefined>;
|
|
5
|
+
/** Biggest answer read (bytes): an endpoint answering garbage can't fill memory. */
|
|
6
|
+
export declare const MAX_ANSWER_BYTES: number;
|
|
7
|
+
/** POST and read a JSON answer. Network errors, timeouts, 408/429/5xx: not permanent; other 4xx and bad JSON: permanent/not. */
|
|
8
|
+
export declare function requestJson(adapter: string, f: FetchLike, url: string, init: RequestInit, o: {
|
|
9
|
+
timeoutMs: number;
|
|
10
|
+
signal?: AbortSignal;
|
|
11
|
+
}): Promise<{
|
|
12
|
+
json: unknown;
|
|
13
|
+
headers: Headers;
|
|
14
|
+
}>;
|
|
15
|
+
/** Bytes → base64 in slices (no Buffer in workerd without nodejs_compat; one spread of a whole chunk overflows the stack). */
|
|
16
|
+
export declare function toBase64(b: Uint8Array): string;
|
|
17
|
+
export declare const trimSlash: (u: string) => string;
|