@uploadfilm/sdk 0.1.0 → 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/README.md +26 -6
- package/dist/copy/types.d.ts +29 -2
- package/dist/index.js +1 -1
- package/dist/index.mjs +1 -1
- package/dist/player.js +1 -1
- package/dist/player.mjs +1 -1
- package/dist/server/media/client.d.ts +34 -1
- package/dist/server/media/protocol.d.ts +242 -4
- package/dist/server/r2/client.d.ts +18 -4
- package/dist/server/storage/chunked.d.ts +6 -2
- package/dist/server/storage/s3.d.ts +51 -0
- package/dist/server/testing/fake-r2.d.ts +22 -2
- package/dist/server/transfer/handler.d.ts +50 -0
- package/dist/server/transfer/protocol.d.ts +53 -4
- package/dist/server-media.js +1 -1
- package/dist/server-media.mjs +1 -1
- package/dist/server-testing.js +1 -1
- package/dist/server-testing.mjs +1 -1
- package/dist/server.js +1 -1
- package/dist/server.mjs +1 -1
- package/dist/transfer/client.d.ts +13 -2
- package/dist/transfer/engine.d.ts +22 -2
- 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 +1 -0
- package/dist/transfer/protocol.d.ts +5 -0
- package/dist/transfer/storage.d.ts +28 -3
- 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/package.json +51 -3
package/README.md
CHANGED
|
@@ -39,7 +39,7 @@ npm install @uploadfilm/sdk
|
|
|
39
39
|
|
|
40
40
|
## 🧭 Entry points
|
|
41
41
|
|
|
42
|
-
Every entry point is a subpath of this one package, ESM + CJS with types, `sideEffects: false`.
|
|
42
|
+
Every entry point is a subpath of this one package, ESM + CJS with types (the Workers: ESM only), `sideEffects: false`.
|
|
43
43
|
|
|
44
44
|
| Import | What you get | Runs in |
|
|
45
45
|
|---|---|---|
|
|
@@ -54,9 +54,12 @@ Every entry point is a subpath of this one package, ESM + CJS with types, `sideE
|
|
|
54
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
55
|
| `@uploadfilm/sdk/cards` | Camera cards: mounted volumes, camera folder layouts read into clips (spanned clips, proxies, sidecars, LUTs), the upload plan | Node |
|
|
56
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 |
|
|
57
59
|
|
|
58
60
|
**Optional peer dependencies**, only for what you use: `react`, `@videojs/react`, `hls.js`, `undici`, `ioredis`,
|
|
59
|
-
`@upstash/redis`, `inngest`, `@cloudflare/workers-types
|
|
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
|
|
60
63
|
pass `undici`, `hls.js` or Electron's `net` in.
|
|
61
64
|
|
|
62
65
|
## 🚀 Quick start: uploads (Node or Electron)
|
|
@@ -342,8 +345,25 @@ From your own code: `new EmbedController(iframe)`, `defineEmbedElement()` for `<
|
|
|
342
345
|
## ⚙️ The media pipeline on Cloudflare Workers
|
|
343
346
|
|
|
344
347
|
You run your own media Worker (Worker + Durable Object + FFmpeg Container) on your own Cloudflare account, against
|
|
345
|
-
your own bucket.
|
|
346
|
-
|
|
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.
|
|
347
367
|
|
|
348
368
|
```
|
|
349
369
|
your site ──signed job (HMAC)──▶ media Worker ──▶ Durable Object (one per job) ──▶ FFmpeg Container: ONE decode
|
|
@@ -417,8 +437,8 @@ export async function streamUrl(prefix: string) {
|
|
|
417
437
|
RAW source fails with code `unsupported`, so store it and flag it "no preview".
|
|
418
438
|
|
|
419
439
|
Also server-side: `copy()` with `r2()` / `s3()` replicates objects to S3 (backup, archive, Object Lock) with byte
|
|
420
|
-
verification, driven by `createPipeline`; a ZIP Worker (`@uploadfilm/zip
|
|
421
|
-
straight from R2.
|
|
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.
|
|
422
442
|
|
|
423
443
|
## 🧪 Testing your integration
|
|
424
444
|
|
package/dist/copy/types.d.ts
CHANGED
|
@@ -112,7 +112,10 @@ export interface WriteOptions {
|
|
|
112
112
|
size?: number;
|
|
113
113
|
/** User metadata to store with the object (lowercase keys). */
|
|
114
114
|
meta: Record<string, string>;
|
|
115
|
-
/**
|
|
115
|
+
/**
|
|
116
|
+
* The CRC-32 (hex) the object must have. publish(): the staged object must still have it. put(): a destination
|
|
117
|
+
* that can check it (s3: sent as the trailer's checksum) refuses other bytes, so nothing else is stored.
|
|
118
|
+
*/
|
|
116
119
|
crc32?: string;
|
|
117
120
|
}
|
|
118
121
|
export interface UploadInfo {
|
|
@@ -227,10 +230,28 @@ export interface CopyOptions {
|
|
|
227
230
|
* e.g. the last part stored but its answer lost): complete that upload as the old version's copy instead of
|
|
228
231
|
* abandoning it (default false). Where the source keeps no old versions (R2), it may be the only copy of those
|
|
229
232
|
* bytes. Proven like any copy: against the old version's known checksum. Needs a destination that lists parts.
|
|
233
|
+
* true: never over another version's copy that is already the current object, and in a resumed upload only parts
|
|
234
|
+
* this run sent or checked. "keepAll", for a destination that keeps every version (a versioned bucket): completed
|
|
235
|
+
* over another version's copy too (that one becomes non-current), and a resumed upload's other parts count when
|
|
236
|
+
* they have the right size and a CRC (the completed object must carry this version's source-etag). The backup
|
|
237
|
+
* Worker's rule.
|
|
230
238
|
*/
|
|
231
|
-
salvage?: boolean;
|
|
239
|
+
salvage?: boolean | "keepAll";
|
|
232
240
|
/** Part size (bytes). Default: the source's own part size when known, else the destination's preference. */
|
|
233
241
|
partSize?: number;
|
|
242
|
+
/**
|
|
243
|
+
* How the copy is written: "auto" (default) is one PUT when the object fits one part, else a multipart upload;
|
|
244
|
+
* "always" is a multipart upload whatever the size (an empty object is one empty part); "never" is one PUT, and an
|
|
245
|
+
* object over the destination's largest PUT fails with TooLarge. A product whose existing copies were made one way
|
|
246
|
+
* keeps making them that way (the backup Worker: originals always multipart, manifest revisions one PUT), so the
|
|
247
|
+
* stored ETags stay the same.
|
|
248
|
+
*/
|
|
249
|
+
multipart?: "auto" | "always" | "never";
|
|
250
|
+
/**
|
|
251
|
+
* Write the `verify` label (`verify=unverified|etag|read`) when no expected CRC-32 is known (default true). false: no
|
|
252
|
+
* label (the backup Worker's manifest revisions carry none). `expected-crc32` is written either way when known.
|
|
253
|
+
*/
|
|
254
|
+
verifyMeta?: boolean;
|
|
234
255
|
/** Most parts a copy may be cut into (e.g. ≤ 900 when every part is an Inngest step). */
|
|
235
256
|
maxParts?: number;
|
|
236
257
|
/** A source body that sends no byte for this long is a failed read, retried (default 120 s). */
|
|
@@ -265,6 +286,12 @@ export interface CopyOptions {
|
|
|
265
286
|
* lifecycle rule (a writer key without abort permission; the backup worker never aborts).
|
|
266
287
|
*/
|
|
267
288
|
abandon?: "abort" | "leave";
|
|
289
|
+
/**
|
|
290
|
+
* An existing copy of this version that holds other bytes than its known checksum: "recopy" (default) copies again
|
|
291
|
+
* once, labelled `attempt=recopy`, and a mismatch then fails; "copy" copies again as an ordinary first copy (it may
|
|
292
|
+
* resume an unfinished upload), then recopies once if that mismatches too: the backup Worker's rule.
|
|
293
|
+
*/
|
|
294
|
+
existingMismatch?: "recopy" | "copy";
|
|
268
295
|
/** Recopy even though an earlier recopy of this version mismatched the expected CRC (send by hand once fixed). */
|
|
269
296
|
force?: boolean;
|
|
270
297
|
hasher?: CopyHasher;
|