@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.
Files changed (75) hide show
  1. package/README.md +26 -6
  2. package/dist/copy/types.d.ts +29 -2
  3. package/dist/index.js +1 -1
  4. package/dist/index.mjs +1 -1
  5. package/dist/player.js +1 -1
  6. package/dist/player.mjs +1 -1
  7. package/dist/server/media/client.d.ts +34 -1
  8. package/dist/server/media/protocol.d.ts +242 -4
  9. package/dist/server/r2/client.d.ts +18 -4
  10. package/dist/server/storage/chunked.d.ts +6 -2
  11. package/dist/server/storage/s3.d.ts +51 -0
  12. package/dist/server/testing/fake-r2.d.ts +22 -2
  13. package/dist/server/transfer/handler.d.ts +50 -0
  14. package/dist/server/transfer/protocol.d.ts +53 -4
  15. package/dist/server-media.js +1 -1
  16. package/dist/server-media.mjs +1 -1
  17. package/dist/server-testing.js +1 -1
  18. package/dist/server-testing.mjs +1 -1
  19. package/dist/server.js +1 -1
  20. package/dist/server.mjs +1 -1
  21. package/dist/transfer/client.d.ts +13 -2
  22. package/dist/transfer/engine.d.ts +22 -2
  23. package/dist/transfer/growing/bytes.d.ts +17 -0
  24. package/dist/transfer/growing/index.d.ts +12 -0
  25. package/dist/transfer/growing/parts.d.ts +157 -0
  26. package/dist/transfer/growing/retry.d.ts +38 -0
  27. package/dist/transfer/growing/store.d.ts +66 -0
  28. package/dist/transfer/growing/upload.d.ts +126 -0
  29. package/dist/transfer/index.d.ts +1 -0
  30. package/dist/transfer/protocol.d.ts +5 -0
  31. package/dist/transfer/storage.d.ts +28 -3
  32. package/dist/workers/cli.mjs +115 -0
  33. package/dist/workers/media/config.mjs +53 -0
  34. package/dist/workers/media/container/Dockerfile +19 -0
  35. package/dist/workers/media/container/FFMPEG.md +129 -0
  36. package/dist/workers/media/container/runner.mjs +2690 -0
  37. package/dist/workers/media/index.mjs +1011 -0
  38. package/dist/workers/media/init/config.ts +52 -0
  39. package/dist/workers/media/init/worker.ts +8 -0
  40. package/dist/workers/media/init/wrangler.toml +44 -0
  41. package/dist/workers/media/runner.mjs +2656 -0
  42. package/dist/workers/media/types/build/entry/config.d.mts +6 -0
  43. package/dist/workers/media/types/build/entry/index.d.mts +43 -0
  44. package/dist/workers/media/types/build/entry/program.d.mts +13 -0
  45. package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
  46. package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
  47. package/dist/workers/media/types/src/config.d.mts +135 -0
  48. package/dist/workers/media/types/src/jobs.d.mts +73 -0
  49. package/dist/workers/media/types/src/runner/container.d.mts +32 -0
  50. package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
  51. package/dist/workers/media/types/src/runner/job.d.mts +107 -0
  52. package/dist/workers/media/types/src/runner/node.d.mts +71 -0
  53. package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
  54. package/dist/workers/media/types/src/serve.d.mts +107 -0
  55. package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
  56. package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
  57. package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
  58. package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
  59. package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
  60. package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
  61. package/dist/workers/media/types/src/steps/render.d.mts +40 -0
  62. package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
  63. package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
  64. package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
  65. package/dist/workers/media/types/src/transcoder.d.mts +30 -0
  66. package/dist/workers/media/types/src/worker.d.mts +30 -0
  67. package/dist/workers/zip/index.mjs +589 -0
  68. package/dist/workers/zip/init/config.ts +22 -0
  69. package/dist/workers/zip/init/worker.ts +5 -0
  70. package/dist/workers/zip/init/wrangler.toml +25 -0
  71. package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
  72. package/dist/workers/zip/types/src/config.d.mts +35 -0
  73. package/dist/workers/zip/types/src/serve.d.mts +86 -0
  74. package/dist/workers/zip/types/src/worker.d.mts +12 -0
  75. package/package.json +51 -3
@@ -0,0 +1,89 @@
1
+ /**
2
+ * The `transcript` step, run OUTSIDE the encoding container: by the media Worker's Durable Object once the container has
3
+ * stored the job's audio chunks (src/transcoder.ts), or by a self-hosted queue host with any bucket and any client that
4
+ * answers like Workers AI's binding. The container has no internet and no AI binding; this needs both.
5
+ *
6
+ * audio/audio.json → each chunk that isn't silence end to end → AI.run(model, { audio: <base64> }) → segments, offset
7
+ * by the chunk's start, inside-silence segments dropped → transcript.vtt, then transcript.json (the completion file)
8
+ *
9
+ * Long recordings span several invocations: each chunk's answer is kept (`progress`, the Durable Object's storage) as
10
+ * soon as it arrives, and a run stops starting new calls past `deadline` (a Durable Object alarm may run 15 minutes);
11
+ * the next run picks up at the first chunk without an answer. Every call has a timeout.
12
+ *
13
+ * Any transcriber: with `transcriber` (an @uploadfilm/sdk/ai Transcriber: OpenAI-compatible, a local whisper.cpp, …) each
14
+ * chunk goes to it instead of the AI binding; everything else (VAD, progress, limits, timeouts, files) is the same, and
15
+ * its per-call usage (latency, cost) comes back with the run. Without one, the AI binding path is exactly as before.
16
+ * Only types are imported from the SDK's ai folder: this file still loads in plain Node with nothing else.
17
+ */
18
+ import { type StepSettings } from "@uploadfilm/sdk/server/media";
19
+ import { type Transcript, type WhisperResult } from "@uploadfilm/sdk/server/media";
20
+ import type { AiUsage, Transcriber } from "@uploadfilm/sdk/ai";
21
+ /** The part of Workers AI's binding (env.AI) this uses. */
22
+ export interface AiLike {
23
+ run(model: string, input: Record<string, unknown>): Promise<unknown>;
24
+ }
25
+ export interface TranscriptBucket {
26
+ get(key: string): Promise<{
27
+ size?: number;
28
+ arrayBuffer(): Promise<ArrayBuffer>;
29
+ } | null>;
30
+ put(key: string, body: string, o?: {
31
+ httpMetadata?: {
32
+ contentType?: string;
33
+ };
34
+ }): Promise<unknown>;
35
+ }
36
+ /** A failure retrying won't fix (no audio index, a chunk missing, the AI binding missing). */
37
+ export declare class TranscriptError extends Error {
38
+ permanent: boolean;
39
+ constructor(message: string, permanent: boolean);
40
+ }
41
+ /** Bytes → base64, in slices (no Buffer in workerd without nodejs_compat; a whole chunk at once overflows the stack). */
42
+ export declare function toBase64(b: Uint8Array): string;
43
+ /** Biggest audio chunk sent (bytes): it is held, and base64'd, in a Worker's 128 MB (10 min at 24 kbps is ~1.8 MB). */
44
+ export declare const MAX_CHUNK_BYTES: number;
45
+ /** One model call may take this long (default). */
46
+ export declare const CALL_TIMEOUT_MS: number;
47
+ /**
48
+ * Longest audio transcribed (seconds of chunks sent): every chunk's answer is held to assemble the transcript, in a
49
+ * Worker's 128 MB. 12 hours of dense speech is ~25 MB of answers.
50
+ */
51
+ export declare const MAX_TRANSCRIPT_S: number;
52
+ /** The request body for this model: base64 for whisper-large-v3-turbo (and anything newer), a byte array for the older ones. */
53
+ export declare function modelInput(model: string, bytes: Uint8Array): Record<string, unknown>;
54
+ /** Where each chunk's answer is kept between runs. */
55
+ export interface TranscriptProgress {
56
+ get(i: number): Promise<WhisperResult | undefined>;
57
+ put(i: number, r: WhisperResult): Promise<void>;
58
+ }
59
+ export type TranscriptRun = {
60
+ done: true;
61
+ transcript: Transcript; /** Chunks sent to the model, in all runs. */
62
+ sent: number; /** Every chunk's transcriber call, this run's and those kept from earlier runs. */
63
+ usage?: AiUsage[];
64
+ }
65
+ /** Out of time with chunks left: run again (their answers so far are in `progress`). */
66
+ | {
67
+ done: false;
68
+ sent: number;
69
+ left: number;
70
+ usage?: AiUsage[];
71
+ };
72
+ export declare function runTranscript(o: {
73
+ bucket: TranscriptBucket;
74
+ ai: AiLike | undefined;
75
+ /** Any transcriber instead of the AI binding (`ai` is then not used). */
76
+ transcriber?: Transcriber;
77
+ /** Each transcriber call's usage, as it happens (a throwing hook is ignored). */
78
+ onUsage?: (u: AiUsage) => void;
79
+ /** The bucket key prefix (a shared test bucket) + the job's prefix. */
80
+ keyPrefix?: string;
81
+ prefix: string;
82
+ settings: StepSettings;
83
+ /** Answers kept between runs (default: this run only). */
84
+ progress?: TranscriptProgress;
85
+ /** Epoch ms: no new call starts after it. */
86
+ deadline?: number;
87
+ callTimeoutMs?: number;
88
+ now?: () => number;
89
+ }): Promise<TranscriptRun>;
@@ -0,0 +1,61 @@
1
+ import { planStoryboard, storyboardSettings, type StoryboardPlan, type StoryboardSettings } from "@uploadfilm/sdk/server/media";
2
+ export { planStoryboard, storyboardSettings, type StoryboardPlan, type StoryboardSettings };
3
+ /** A failure of the storyboard's own outputs (the job fails with code "source": the source didn't give a picture). */
4
+ export declare class StoryboardError extends Error {
5
+ code: "source";
6
+ }
7
+ /**
8
+ * The branch for one decoded stream labelled `input` (e.g. "[s3]"), output label [sb]. Picks the first frame at or
9
+ * after each i·interval (select on a fixed grid, not on the previous pick: no drift over a long video), never more than
10
+ * maxFrames. Also notes, in `work`, every decoded frame's time (sb-frames.txt: where the decode really ended, whatever
11
+ * the thumbnail count) and each picked one's (sb-picked.txt: which grid cells a sparse source's frames stand for).
12
+ */
13
+ export declare function storyboardBranch(input: string, plan: StoryboardPlan, work: string, label?: string): string;
14
+ /** The times (pts_time) metadata=print wrote, in order. */
15
+ export declare function printedTimes(text: string): number[];
16
+ /**
17
+ * The last `n` times in a metadata=print file, reading only its tail (it has a line for every frame of the video: never
18
+ * read whole). A line cut by where the tail starts is dropped; a file shorter than the tail is read from its start.
19
+ */
20
+ export declare function lastTimes(file: string, n?: number, tail?: number): number[];
21
+ /**
22
+ * Where the decoded picture ends: its last frame's time plus how long that frame is shown, taken as the SMALLEST gap
23
+ * between the last frames (a source cut after a jump in time, 0, 1, 40, must not be credited with another 39 s). A
24
+ * steady sparse source (a frame every 5 s) keeps its own 5 s.
25
+ */
26
+ export declare function pictureEnd(times: readonly number[]): number | null;
27
+ /**
28
+ * Which picked thumbnail stands for each grid cell [k·interval, (k+1)·interval): the last one picked before the cell
29
+ * ends (what the picture shows then). Dense video: thumbnail k for cell k. A sparse source (a frame every 5 s, a
30
+ * timelapse) holds a frame across several cells: it is repeated, not dropped.
31
+ */
32
+ export declare function cellsFor(picked: readonly number[], interval: number, cells: number): number[];
33
+ /** The thumbnails' output in the shared ffmpeg command: lossless PNGs (the sheets are encoded once, from these). */
34
+ export declare function storyboardOutput(thumbs: string, label?: string): string[];
35
+ /** Tile the thumbnails into WebP sheets at this quality (small PNGs in: no source involved, nothing re-decoded). */
36
+ export declare function sheetArgs(cells: string, out: string, plan: StoryboardPlan, quality: number): string[];
37
+ /** The quality steps tried, best first: quality, then 15 lower each time, ending at minQuality. */
38
+ export declare function qualitySteps(s: Pick<StoryboardSettings, "quality" | "minQuality">): number[];
39
+ export interface FinishStoryboard {
40
+ plan: StoryboardPlan;
41
+ settings: StoryboardSettings;
42
+ /** Work dir with the thumbnails (t-NNNNN.png), and the job's output dir (sheets go in <out>/storyboard). */
43
+ thumbs: string;
44
+ out: string;
45
+ /** Runs ffmpeg with these args (the runner's counted exec). */
46
+ ffmpeg: (args: string[]) => Promise<unknown>;
47
+ /** Seconds a damaged source's picture may fall short of its stated length (the runner's own allowance). */
48
+ shortfallAllowed: (seconds: number) => number;
49
+ }
50
+ export interface StoryboardResult {
51
+ count: number;
52
+ sheets: number;
53
+ bytes: number;
54
+ quality: number;
55
+ }
56
+ /**
57
+ * After the shared decode: check the decode reached the picture's end, give every grid cell its thumbnail, make the
58
+ * sheets within the budget, write the VTT and then the index (the step's completion file: a viewer never gets an index
59
+ * naming a file that isn't there).
60
+ */
61
+ export declare function finishStoryboard(j: FinishStoryboard): Promise<StoryboardResult>;
@@ -0,0 +1,30 @@
1
+ import { type MediaWorkerConfig } from "./config.mjs";
2
+ import { type JobSpec } from "./jobs.mjs";
3
+ /** The parts of @cloudflare/containers' Container a Transcoder uses. */
4
+ export interface ContainerLike {
5
+ ctx: {
6
+ storage: {
7
+ get<T>(key: string): Promise<T | undefined>;
8
+ put<T>(key: string, value: T): Promise<void>;
9
+ };
10
+ };
11
+ env: unknown;
12
+ schedule(when: number, callback: string): Promise<unknown>;
13
+ deleteSchedules(name: string): void;
14
+ setOutboundByHost<P>(host: string, method: string, params: P): Promise<void>;
15
+ startAndWaitForPorts(port: number): Promise<void>;
16
+ containerFetch(url: string, init: RequestInit, port: number): Promise<Response>;
17
+ renewActivityTimeout(): void;
18
+ destroy(): Promise<void>;
19
+ }
20
+ type ContainerCtor = new (...args: any[]) => object;
21
+ export interface TranscoderMethods {
22
+ /** Start (or join) the job. Idempotent: the same job asked for twice is one job. */
23
+ startJob(job: JobSpec): Promise<{
24
+ state: string;
25
+ }>;
26
+ heartbeat(): Promise<void>;
27
+ onActivityExpired(): Promise<void>;
28
+ }
29
+ export declare function defineTranscoder<B extends ContainerCtor>(Base: B, cfg: MediaWorkerConfig): B & (new (...args: any[]) => TranscoderMethods);
30
+ export {};
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The Worker's fetch handler: viewers (GET /h/…) and the site's job requests (POST /jobs). A product's entry is a few
3
+ * lines (template/worker.ts; UploadFilm's worker/media/src/index.ts):
4
+ *
5
+ * import { Container, ContainerProxy, getContainer } from "@cloudflare/containers";
6
+ * export const Transcoder = defineTranscoder(Container, config);
7
+ * export { ContainerProxy }; // the package routes the container's outbound requests through it
8
+ * export default createMediaWorker(config, { getContainer });
9
+ */
10
+ import { type MediaWorkerConfig } from "./config.mjs";
11
+ import { type JobSpec } from "./jobs.mjs";
12
+ import { type CacheLike } from "./serve.mjs";
13
+ export interface WorkerDeps {
14
+ /** @cloudflare/containers' getContainer. */
15
+ getContainer(ns: never, id: string): {
16
+ startJob(job: JobSpec): Promise<{
17
+ state: string;
18
+ }>;
19
+ };
20
+ /** The edge cache (workerd: caches.default). Default: globalThis.caches?.default. */
21
+ cache?: () => CacheLike | null;
22
+ }
23
+ interface Ctx {
24
+ waitUntil(p: Promise<unknown>): void;
25
+ }
26
+ export declare function createMediaWorker(cfg: MediaWorkerConfig, deps: WorkerDeps): {
27
+ viewer: import("./serve.mjs").Viewer;
28
+ fetch(req: Request, env: unknown, ctx: Ctx): Promise<Response>;
29
+ };
30
+ export {};