@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,6 @@
1
+ /**
2
+ * @uploadfilm/sdk/workers/media/config: the configuration types and defaults, without the Worker runtime. Safe to import from
3
+ * Node (your site shares config.ts with the Worker: the key layout, the grant policy, the HMAC domains).
4
+ */
5
+ export { DEFAULT_BINDINGS, DEFAULT_TIMING, segmentNamesOf, stepSettingsOf, versionFor, type Bindings, type CapRule, type LayoutConfig, type MediaWorkerConfig } from "../../src/config.mjs";
6
+ export { SETTINGS_ENV, readSettings, settingsEnv, type ContainerSettings } from "./settings.mjs";
@@ -0,0 +1,43 @@
1
+ /**
2
+ * @uploadfilm/sdk/workers/media: a product's media Worker in three lines.
3
+ *
4
+ * import { createMediaWorker } from "@uploadfilm/sdk/workers/media";
5
+ * import { config } from "./config";
6
+ * export default createMediaWorker(config);
7
+ * export { Transcoder, ContainerProxy } from "@uploadfilm/sdk/workers/media";
8
+ *
9
+ * `Transcoder` (the Durable Object class wrangler.toml names) is defined by createMediaWorker(config) when your
10
+ * worker.ts loads, from the same config: the export is a live binding, so it's the configured class by the time the
11
+ * runtime reads your module's exports. One media Worker config per Worker script.
12
+ */
13
+ import { Container } from "@cloudflare/containers";
14
+ import type { MediaWorkerConfig } from "../../src/config.mjs";
15
+ import { type TranscoderMethods } from "../../src/transcoder.mjs";
16
+ import { type WorkerDeps } from "../../src/worker.mjs";
17
+ /** This package's version (the container image built from it carries the same). */
18
+ export declare const PACKAGE_VERSION: string;
19
+ export { ContainerProxy } from "@cloudflare/containers";
20
+ export { DEFAULT_BINDINGS, DEFAULT_TIMING, type Bindings, type CapRule, type LayoutConfig, type MediaWorkerConfig } from "../../src/config.mjs";
21
+ export { defineTranscoder, type TranscoderMethods } from "../../src/transcoder.mjs";
22
+ export { createViewer, type Viewer } from "../../src/serve.mjs";
23
+ export type { JobSpec } from "../../src/jobs.mjs";
24
+ export { PACKAGE_HEADER, SETTINGS_ENV, readSettings, settingsEnv, type ContainerSettings } from "./settings.mjs";
25
+ /** The configured Durable Object class (one container per job). Defined by createMediaWorker(config). */
26
+ export declare let Transcoder: typeof Container & (new (...args: any[]) => TranscoderMethods);
27
+ /**
28
+ * A /status answer from another package version's image reads as stale-image (see PACKAGE_HEADER). Only answers of
29
+ * the program itself (2xx) are checked: the containers library's own failures (503 no instance free, 429, 500 a start
30
+ * that failed) carry no header and pass through unchanged, so the Durable Object keeps treating them as a container not
31
+ * there yet (it waits, within timing.queueTimeoutMs) and not as an older image.
32
+ */
33
+ export declare function checkedStatus(r: Response, version?: string): Promise<Response>;
34
+ export interface MediaWorkerOptions {
35
+ /** The edge cache (default: caches.default). */
36
+ cache?: WorkerDeps["cache"];
37
+ /** @cloudflare/containers' getContainer (tests). */
38
+ getContainer?: WorkerDeps["getContainer"];
39
+ }
40
+ /** The Worker's fetch handler (viewers: GET /h/…, your site's jobs: POST /jobs), and the Transcoder class. */
41
+ export declare function createMediaWorker(config: MediaWorkerConfig, options?: MediaWorkerOptions): {
42
+ fetch(req: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;
43
+ };
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The media container's program: the SDK runner with the settings the Worker passes in its environment (./settings.ts),
3
+ * naming this package's version on every request it makes and every answer it gives (PACKAGE_HEADER). The published
4
+ * image runs it as is (container/runner.mjs); a custom image (decoder plugins) calls it with its plugins.
5
+ */
6
+ import type { Server } from "node:http";
7
+ import { type ContainerOptions } from "../../src/runner/container.mjs";
8
+ export interface MediaContainerOptions extends Pick<ContainerOptions, "plugins" | "store" | "workDir" | "port"> {
9
+ /** Default: process.env. */
10
+ env?: Record<string, string | undefined>;
11
+ }
12
+ /** Start the container program. Exits the process (code 1) when the Worker's settings are missing or malformed. */
13
+ export declare function startMediaContainer(o?: MediaContainerOptions): Server;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @uploadfilm/sdk/workers/media/runner (Node): the same job code outside Cloudflare.
3
+ *
4
+ * - pullLoop: a self-hosted runner pulling jobs from your queue over HTTP (any machine with Node and FFmpeg).
5
+ * - startContainer: the container program, for your own image (with decoder plugins, or other settings).
6
+ * - runJob: one job on local files.
7
+ */
8
+ export { pullLoop, hostExec, boundThreads, RUNNER_DEFAULT_VERSION, type PullOptions, type PulledJob, type PulledResult, type RunnerHostSettings } from "../../src/runner/node.mjs";
9
+ export { startContainer, storeIO, fetchRetry, type ContainerOptions } from "../../src/runner/container.mjs";
10
+ export { runJob, spawnExec, JobError, type RunSpec, type RunIO, type Exec } from "../../src/runner/job.mjs";
11
+ export type { DecoderPlugin, DecodedSource, SourceSignature } from "../../src/runner/plugins.mjs";
12
+ export { startMediaContainer, type MediaContainerOptions } from "./program.mjs";
@@ -0,0 +1,40 @@
1
+ /**
2
+ * What the published container image learns from the Worker: the product's ladder, default steps and step settings,
3
+ * passed as one environment variable when the Durable Object starts the container. The image itself is the same for
4
+ * every product (no config baked in), so it can be built from node_modules or pulled prebuilt.
5
+ *
6
+ * The package version rides along. The image and the Worker come from the same package version (wrangler builds both
7
+ * from node_modules); during a rollout an older image can still be started by a newer Worker. Such a container runs
8
+ * with a version no Worker stores ("<ladder> (image X, Worker Y)"), so the runner's existing stale-image check stops
9
+ * it before the download and the Worker retries on the new image (timing.imageRetryS). A container that was already
10
+ * running when the Worker was upgraded is caught by PACKAGE_HEADER instead: its output PUTs are refused (409) and its
11
+ * status reads as stale-image. Either way, only a container of the Worker's own package version stores outputs or
12
+ * ends a job.
13
+ */
14
+ import type { LadderSettings, Step, StepSettings } from "@uploadfilm/sdk/server/media";
15
+ import type { MediaWorkerConfig } from "../../src/config.mjs";
16
+ export declare const SETTINGS_ENV = "UPLOADFILM_MEDIA_SETTINGS";
17
+ /**
18
+ * The image's package version, on every request the container makes (storage) and every answer it gives (status).
19
+ * The Worker refuses outputs and results from another version: also from a container that was already running when
20
+ * the Worker was upgraded (its environment still matches its own image).
21
+ */
22
+ export declare const PACKAGE_HEADER = "x-uploadfilm-media-package";
23
+ export interface ContainerSettings {
24
+ /** Format of this variable. */
25
+ v: 1;
26
+ /** @uploadfilm/sdk/workers/media version of the Worker that started the container. */
27
+ pkg: string;
28
+ ladder: LadderSettings;
29
+ defaultSteps: Step[];
30
+ stepSettings?: StepSettings;
31
+ }
32
+ export declare function settingsEnv(cfg: Pick<MediaWorkerConfig, "ladder" | "steps" | "stepSettings">, pkg: string): string;
33
+ /** The container's settings, or why it can't run. `imagePkg`: the package version this image was built from. */
34
+ export declare function readSettings(raw: string | undefined, imagePkg: string): {
35
+ ladder: LadderSettings;
36
+ defaultSteps: Step[];
37
+ stepSettings?: StepSettings;
38
+ } | {
39
+ error: string;
40
+ };
@@ -0,0 +1,135 @@
1
+ /**
2
+ * What a product configures when it deploys its own media worker. Nothing here has a default that names a product:
3
+ * the key layout, the callback allowlist, the HMAC domains and the grant policy are always the product's.
4
+ *
5
+ * Loaded by plain Node (worker tests, the container, the self-hosted runner) as well as workerd: explicit .ts imports,
6
+ * erasable TypeScript only.
7
+ */
8
+ import type { GrantSealer } from "@uploadfilm/sdk/server";
9
+ import { type LadderSettings, type RenderJob, type Step, type StepSettings } from "@uploadfilm/sdk/server/media";
10
+ import type { Transcriber } from "@uploadfilm/sdk/ai";
11
+ /** A cap a job may ask for (`maxShort`): the top rung's short side at most this. */
12
+ export interface CapRule {
13
+ /** Names the outputs apart from an uncapped ladder of the same source (part of the prefix's hash). */
14
+ variant?: string;
15
+ /** The biggest source such a job downloads. */
16
+ maxSourceBytes: number;
17
+ }
18
+ /** Binding and variable names in the Worker's env. */
19
+ export interface Bindings {
20
+ /** R2 bucket binding. */
21
+ bucket: string;
22
+ /** Secret shared with the site (job and report HMAC, grant sealing). */
23
+ secret: string;
24
+ /** Durable Object namespace of the Transcoder class. */
25
+ transcoder: string;
26
+ /** Optional var: prepended to every key (a shared test bucket); "" in production. */
27
+ keyPrefix: string;
28
+ /** Optional var, the kill switch: "1" answers 404 to every viewer request, so players fall back to the MP4. */
29
+ paused: string;
30
+ /** Optional var: "1" lets the callback be http://localhost (a dev site). */
31
+ allowLocalCallback: string;
32
+ /** Workers AI binding, for the `transcript` step (default "AI"). Only needed when transcript is allowed. */
33
+ ai?: string;
34
+ }
35
+ export interface LayoutConfig {
36
+ /** The output prefix a job for this source must use (null: no outputs can be named after this key). */
37
+ prefixFor(sourceKey: string, sourceEtag: string, variant?: string): Promise<string | null>;
38
+ /** The job id for a prefix (the Durable Object's name): one job per prefix. */
39
+ idOf(prefix: string): string;
40
+ }
41
+ export interface MediaWorkerConfig {
42
+ /** The rungs, segment timing, encoder presets and the settings version every output is stamped with. */
43
+ ladder: LadderSettings;
44
+ /** Steps a job gets when it names none, and the steps a job may ask for. */
45
+ steps: {
46
+ default: Step[];
47
+ allowed: Step[];
48
+ };
49
+ /**
50
+ * Settings of the optional steps (audio, transcript, frame-check), with their own version: a job running one is
51
+ * stamped jobVersion(ladder.version, steps, stepSettings.version). Default DEFAULT_STEP_SETTINGS. Only matters when
52
+ * `steps.allowed` names one of them.
53
+ */
54
+ stepSettings?: StepSettings;
55
+ /** Biggest source an uncapped job downloads. */
56
+ maxSourceBytes: number;
57
+ /** maxShort values a job may ask for (anything else is refused). */
58
+ caps: Record<number, CapRule>;
59
+ layout: LayoutConfig;
60
+ /** A source ETag the Worker accepts (R2's: an MD5 hex, or a multipart one). */
61
+ etag: RegExp;
62
+ /**
63
+ * Where reports may be sent. A URL passes when it matches and is https (http only with the allowLocalCallback var,
64
+ * for a dev site on localhost). Keep it anchored: an open callback is a request-forgery primitive.
65
+ */
66
+ callbacks: RegExp;
67
+ hmac: {
68
+ header: string;
69
+ jobDomain: string;
70
+ doneDomain: string;
71
+ };
72
+ /** Opens viewers' grants (the auth kit's grantSealer with the product's policy). */
73
+ grants: Pick<GrantSealer, "openGrant">;
74
+ bindings: Bindings;
75
+ timing: {
76
+ /** A job may run this long once a container picked it up (not counted from the request: a queue isn't a hang). */
77
+ jobTimeoutMs: number;
78
+ /** …and may wait this long for a free container. */
79
+ queueTimeoutMs: number;
80
+ heartbeatS: number;
81
+ /** Containers that really started and were lost before the job is failed. */
82
+ maxStarts: number;
83
+ /**
84
+ * A container refused as an older image (a rollout under way) is not a lost one: it doesn't count toward
85
+ * maxStarts, the next container starts this many seconds later (by then the new image runs), and after
86
+ * maxStaleStarts such runs the job fails with code "stale-image". Defaults 300 s and 6.
87
+ */
88
+ imageRetryS?: number;
89
+ maxStaleStarts?: number;
90
+ /** Report deliveries before giving up (backoff 30 s … 10 min). */
91
+ reportTries: number;
92
+ /** The container's sleepAfter: a backstop only, the container is destroyed once its result is in. */
93
+ sleepAfter: string;
94
+ };
95
+ serve: {
96
+ /** How long a "still there" answer is trusted on one isolate. */
97
+ liveTtlMs: number;
98
+ /** Longest a browser may keep a file (the grant's own expiry wins when sooner). */
99
+ maxAgeS: number;
100
+ /** Host of the edge-cache keys (never fetched). */
101
+ cacheHost: string;
102
+ /** Steps whose files viewers may fetch with a grant. */
103
+ steps: Step[];
104
+ };
105
+ /** Biggest single output file (a 4 s 1080p segment at the peak rate is ~4 MB). */
106
+ maxPutBytes: number;
107
+ /**
108
+ * The `transcript` step's transcriber, built from the Worker's env on each run (its own secrets and bindings: e.g.
109
+ * openAiCompatibleTranscriber({ baseUrl, model, apiKey: env.GROQ_KEY })). Absent, or returning undefined: Workers AI
110
+ * through the AI binding (bindings.ai) with stepSettings.transcript.model, exactly as without this option.
111
+ */
112
+ transcriber?: (env: Record<string, unknown>) => Transcriber | undefined;
113
+ /**
114
+ * The `render` step (docs/platform/MEDIA-STEPS.md): where a render's outputs go. Required for a render job (with
115
+ * "render" in steps.allowed); absent, every render is refused. `prefixFor` gets the checked sources and edit list and
116
+ * names the prefix the job must use (null: refused), e.g. from renderHash(job): one job, one output, per edit list.
117
+ * `sourceAllowed` (optional): may a render read this key? (Default: any key the site signed.)
118
+ */
119
+ render?: {
120
+ prefixFor(job: RenderJob): Promise<string | null>;
121
+ sourceAllowed?(key: string): boolean;
122
+ };
123
+ }
124
+ /** The variant a `prep` job's prefix is named with (with the cap's own, if any): never a ladder's prefix. */
125
+ export declare const prepVariant: (capVariant?: string) => string;
126
+ export declare const DEFAULT_BINDINGS: Bindings;
127
+ export declare const DEFAULT_TIMING: MediaWorkerConfig["timing"];
128
+ /** Segment names the server accepts for this ladder (current first). */
129
+ export declare const segmentNamesOf: (l: LadderSettings) => string[];
130
+ /** The settings of a config's optional steps. */
131
+ export declare const stepSettingsOf: (cfg: Pick<MediaWorkerConfig, "stepSettings">) => StepSettings;
132
+ /** The version a job with these steps is stamped with (the ladder's own unless it runs an optional step). */
133
+ export declare const versionFor: (cfg: Pick<MediaWorkerConfig, "ladder" | "stepSettings">, steps: readonly Step[]) => string;
134
+ /** Read a binding by its configured name. */
135
+ export declare const bind: <T>(env: unknown, name: string) => T;
@@ -0,0 +1,73 @@
1
+ import { type DoneReport, type EditList, type JobRequest, type Step } from "@uploadfilm/sdk/server/media";
2
+ import { type MediaWorkerConfig } from "./config.mjs";
3
+ /** R2's single-PUT limit is 5 GiB; a remux is about its source's size (a little headroom for the moved index). */
4
+ export declare const MAX_STREAM_PUT: number;
5
+ export declare const MAX_FASTSTART_SOURCE: number;
6
+ /**
7
+ * How far a job request's `issuedAt` may be from the Worker's clock, seconds, either way (O-3). Wide enough for clock
8
+ * skew and a slow request; a captured request replayed later than this is refused. A request without the stamp (a site
9
+ * from before it) is accepted; requiring it is a follow-up (BACKLOG.md).
10
+ */
11
+ export declare const JOB_WINDOW_S: number;
12
+ /** A verified job. `steps` only when the request named them (absent: the config's default). */
13
+ export type JobSpec = JobRequest;
14
+ type JobConfig = Pick<MediaWorkerConfig, "etag" | "caps" | "maxSourceBytes" | "layout" | "callbacks" | "hmac" | "steps"> & Partial<Pick<MediaWorkerConfig, "render" | "stepSettings">>;
15
+ /** The site's job request, verified: signature, shape, and a prefix that really is the source's own. */
16
+ export declare function readJob(req: Request, cfg: JobConfig, secret: string, allowLocalCallback?: boolean): Promise<JobSpec | {
17
+ error: string;
18
+ status: number;
19
+ }>;
20
+ /**
21
+ * The body as text when it is at most `max` bytes: Content-Length checked first, then counted while reading (a body
22
+ * without one, or lying about it, is cut off as soon as it passes `max`). Null when bigger.
23
+ */
24
+ export declare function readCapped(req: Request, max: number): Promise<string | null>;
25
+ /** What the gatekeeper lets one container do: read its source, write its steps' files under its prefix. */
26
+ export interface Gate {
27
+ src: string;
28
+ etag: string;
29
+ prefix: string;
30
+ keyPrefix?: string;
31
+ /** Absent: the config's default steps. */
32
+ steps?: Step[];
33
+ /** The job's expected length: its outputs must come from a runner that checked it (EXPECT_HEADER). */
34
+ expectDurationS?: number;
35
+ /** A prep job: its source's size and cap (its prep.json is checked against them). */
36
+ prep?: {
37
+ bytes: number;
38
+ maxShort?: number;
39
+ };
40
+ /** A render job: the sources it may read (GET /source/<i>, each pinned to its ETag) and the edit list its result must match. */
41
+ render?: {
42
+ sources: {
43
+ src: string;
44
+ etag: string;
45
+ }[];
46
+ editList: EditList;
47
+ };
48
+ }
49
+ export interface GateBucket {
50
+ /** Is a stored output there, and its size (the editor steps' results check the files they name). */
51
+ head?(key: string): Promise<{
52
+ size: number;
53
+ } | null>;
54
+ get(key: string, o?: {
55
+ onlyIf?: {
56
+ etagMatches: string;
57
+ };
58
+ }): Promise<{
59
+ size: number;
60
+ body?: ReadableStream<Uint8Array> | null;
61
+ } | null>;
62
+ /** A ReadableStream only with a known length (the request's content-length): R2 refuses a mismatch. */
63
+ put(key: string, body: ArrayBuffer | ReadableStream<Uint8Array>, o?: {
64
+ httpMetadata?: {
65
+ contentType?: string;
66
+ };
67
+ }): Promise<unknown>;
68
+ }
69
+ type GateConfig = Pick<MediaWorkerConfig, "ladder" | "steps" | "maxPutBytes" | "stepSettings">;
70
+ export declare function gatekeep(req: Request, bucket: GateBucket, g: Gate | undefined, cfg: GateConfig): Promise<Response>;
71
+ /** Tell the site how a job ended (it records the outputs, or the failure, and checks the file is still there). */
72
+ export declare function reportDone(secret: string, url: string, r: DoneReport, cfg: Pick<MediaWorkerConfig, "hmac">, f?: typeof fetch): Promise<boolean>;
73
+ export {};
@@ -0,0 +1,32 @@
1
+ import { type Server } from "node:http";
2
+ import { type LadderSettings, type Step, type StepSettings } from "@uploadfilm/sdk/server/media";
3
+ import { type RunIO } from "./job.mjs";
4
+ import type { DecoderPlugin } from "./plugins.mjs";
5
+ /** fetch with retries for transient failures (network, 5xx); a 4xx is final. */
6
+ export declare function fetchRetry(url: string, init: RequestInit | (() => RequestInit), tries?: number, baseMs?: number): Promise<Response>;
7
+ /**
8
+ * Storage over the gatekeeper's protocol (GET <store>/source, PUT <store>/out/<rel>): the Worker's r2.internal, a pull
9
+ * queue's store, a test's fake. A render job's sources: GET <store>/source/<i>.
10
+ */
11
+ export declare function storeIO(store: string, version: string, o?: {
12
+ retryBaseMs?: number;
13
+ expectDurationS?: number;
14
+ }): Pick<RunIO, "download" | "downloadSource" | "upload">;
15
+ export interface ContainerOptions {
16
+ ladder: LadderSettings;
17
+ /** Steps of a job that names none. */
18
+ defaultSteps: Step[];
19
+ /** The optional steps' settings (audio, transcript, frame-check): the same as the Worker's config. */
20
+ stepSettings?: StepSettings;
21
+ plugins?: readonly DecoderPlugin[];
22
+ /** Default: STORE_URL, else http://r2.internal. */
23
+ store?: string;
24
+ /** Default: WORK_DIR, else /work. */
25
+ workDir?: string;
26
+ /** Default: PORT, else 8080. */
27
+ port?: number;
28
+ /** Exit on SIGTERM/SIGINT (default true: PID 1 in a container). */
29
+ exitOnSignal?: boolean;
30
+ }
31
+ /** Start the container's HTTP program. */
32
+ export declare function startContainer(o: ContainerOptions): Server;
@@ -0,0 +1,227 @@
1
+ /**
2
+ * The ffmpeg command for a job, from what ffprobe said about the source. Pure, so it's tested without ffmpeg and the
3
+ * runner only runs it.
4
+ *
5
+ * ONE ffmpeg process per job reads (and decodes) the source once and writes every output: each ladder rung, the
6
+ * poster and the storyboard are branches of one filter graph (`split`); a copied top rung and the fast-start remux take
7
+ * the source's packets without decoding them.
8
+ */
9
+ import { type LadderSettings, type Step } from "@uploadfilm/sdk/server/media";
10
+ export interface Probe {
11
+ /** Which video stream (v:<n>) is the picture: cover art attached as an earlier video stream is skipped. */
12
+ video: number;
13
+ width: number;
14
+ height: number;
15
+ /** Displayed rotation in degrees (phone clips): the picture is turned before scaling, so sizes follow what's shown. */
16
+ rotation: number;
17
+ videoCodec: string;
18
+ pixFmt: string;
19
+ /** Overall bits per second, 0 when unknown. */
20
+ bitrate: number;
21
+ hasAudio: boolean;
22
+ /** Which audio stream (a:<n>) carries the sound, when not the first: the first one FFmpeg can decode (an iPhone's
23
+ * spatial audio comes first as APAC, which it can't; an AAC track follows). */
24
+ audio?: number;
25
+ /** The other audio streams that may decode (a:<n>, in order): fallen back on when FFmpeg says it has no decoder for
26
+ * the chosen one. Absent when there's no other. */
27
+ audioFallbacks?: number[];
28
+ /** Audio streams exist but none can be decoded here (an APAC-only clip): the ladder is made without sound and the
29
+ * report says so; the audio/transcript steps refuse it; fast start still remuxes them. */
30
+ audioUndecodable?: boolean;
31
+ /** Keyframe times in seconds, in order (empty when not scanned). */
32
+ keyframes: number[];
33
+ /** Seconds, 0 when unknown. */
34
+ duration: number;
35
+ /** The picture's own length (its stream's), when the container says: audio may run longer than the picture. */
36
+ videoDuration?: number;
37
+ /** Interlaced (ffprobe's field_order tt/bb/tb/bt): deinterlaced before anything else. */
38
+ interlaced?: boolean;
39
+ /** The picture's colour (ffprobe's color_transfer, color_primaries, color_space): HLG/PQ is tone-mapped to BT.709. */
40
+ transfer?: string;
41
+ primaries?: string;
42
+ matrix?: string;
43
+ /** Pixel aspect (width/height of one pixel) when it isn't square: anamorphic. */
44
+ sar?: number;
45
+ /** Frames aren't evenly spaced (phones, screen recordings; duplicate timestamps): from the header's rates or packets. */
46
+ vfr?: boolean;
47
+ /**
48
+ * Sparse frames: the frames come at under half the nominal rate (a screen recording's still stretches). Then the
49
+ * nominal rate (frames per second, at most 60), which the ladder's rungs are made at.
50
+ */
51
+ sparseRate?: number;
52
+ /** The last presented frame's time (from the packet index, read for sparse sources): the filled rungs end one frame after it. */
53
+ lastFrameAt?: number;
54
+ /** The file's start time (FFmpeg starts every output there: filter times are relative to it). */
55
+ fileStart?: number;
56
+ /** An edit list hides some of the stream's packets (a stream-copy trim): from the packet index's discard flags. */
57
+ editList?: boolean;
58
+ /** Errors the packet index logged (damaged packets): a copy would carry them. */
59
+ packetErrors?: boolean;
60
+ /** Where the picture and the (first) sound start, and how long the sound runs: a rung's sound is padded to its picture. */
61
+ videoStart?: number;
62
+ audioStart?: number;
63
+ audioDuration?: number;
64
+ /** A still picture (an image demuxer, or one frame with no length): not a video. */
65
+ still?: boolean;
66
+ }
67
+ /** HDR transfers: tone-mapped to SDR (BT.709) for every output. */
68
+ export declare const isHdr: (p: Pick<Probe, "transfer">) => boolean;
69
+ /** A BT.2020 matrix without an HDR transfer (Apple Log ProRes, BT.2020 SDR): the ladder's matrix becomes BT.709 (what
70
+ * players assume); no gamut map without a known transfer. */
71
+ export declare const isWideSdr: (p: Pick<Probe, "matrix" | "transfer">) => boolean;
72
+ /**
73
+ * Can this FFmpeg decode an audio stream with this codec name? Unnamed ones can't. Named ones usually can, except
74
+ * those it identifies but has no decoder for (FFmpeg 9 names Apple's APAC spatial audio "apple_apac").
75
+ */
76
+ export declare const decodableAudio: (codec: unknown) => boolean;
77
+ /** The audio input label for a probe: the decodable track (0 unless the first can't be decoded). */
78
+ export declare const audioIn: (p: Pick<Probe, "audio">) => string;
79
+ /**
80
+ * The deinterlace and HDR→SDR steps, before the decode is split into branches (so every rung, the poster and the
81
+ * storyboard get them, once). "" when the source needs neither (the command is then what it always was).
82
+ * interlaced bwdif, one frame per frame (send_frame): the frame count and timing stay the source's
83
+ * HDR zimg (zscale) to linear light (reference white, 203 nits, at 1.0: BT.2408), BT.2020 → BT.709 primaries,
84
+ * Möbius tone map (linear up to 0.8, highlights rolled off; Hable darkened every SDR-level picture by
85
+ * ~85 of 255 in the format lab), BT.709 transfer and matrix, limited range, 8-bit 4:2:0. FFmpeg's
86
+ * zscale+tonemap recipe; the image's FFmpeg has zimg. A build without it: "unsupported" (job.ts).
87
+ */
88
+ export declare function preChain(p: Probe): string;
89
+ /** The picture as a viewer sees it, in square pixels (rotation and pixel aspect applied): the poster's and storyboard's size. */
90
+ export declare function shown(p: Pick<Probe, "width" | "height" | "rotation" | "sar">): {
91
+ width: number;
92
+ height: number;
93
+ };
94
+ /** Could the top rung be the source's own stream, keyframes aside? (When not, the keyframe scan is skipped.) */
95
+ export declare function copyCandidate(p: Probe, l: Pick<LadderSettings, "copyMaxBps">): boolean;
96
+ /**
97
+ * Can the top rung be the source's own video stream, untouched? Never when the copy would be wrong or break the ladder:
98
+ * - its keyframes are far apart (a long segment), or it would be ONE segment: FFmpeg's HLS muxer then writes a master
99
+ * playlist with no variant at all, exit status 0 (UPSTREAM.md U1: a 2-second clip that buffered forever);
100
+ * - an edit list hides packets (the copy would play the trimmed-out part, and shift every rung's start);
101
+ * - the packet index logged errors (the copy would carry the damaged packets: browsers refuse that rung);
102
+ * - and what copyCandidate refuses (interlaced, HDR, VFR, …).
103
+ */
104
+ export declare function canCopyTop(p: Probe, l: Pick<LadderSettings, "copyMaxBps" | "copyMaxGopS"> & Partial<Pick<LadderSettings, "firstSegmentS">>): boolean;
105
+ /** Displayed size (a 90°/270° rotation swaps the sides). */
106
+ export declare function displayed(p: Pick<Probe, "width" | "height" | "rotation">): {
107
+ width: number;
108
+ height: number;
109
+ };
110
+ /**
111
+ * Does this job need the source's keyframe times? Only to decide whether the top rung can be copied: not for a capped
112
+ * ladder of a bigger picture (every rung is scaled), nor for a source that couldn't be copied anyway (another codec,
113
+ * 4:2:2, rotated, too heavy), nor without a ladder at all.
114
+ */
115
+ export declare function needsKeyframes(p: Probe, l: LadderSettings, steps: readonly Step[], maxShort?: number): boolean;
116
+ /** Storyboard layout: one tile every `interval` s, `cols`×`rows` tiles per sheet, each `width`×`height`. */
117
+ export interface StoryboardPlan {
118
+ interval: number;
119
+ cols: number;
120
+ rows: number;
121
+ width: number;
122
+ height: number;
123
+ }
124
+ /** How long the picture runs: its stream's length when known, else the file's. */
125
+ export declare const pictureSeconds: (p: Pick<Probe, "duration" | "videoDuration">) => number;
126
+ export declare function storyboardPlan(p: Probe): StoryboardPlan;
127
+ export interface JobArgsOptions {
128
+ ladder: LadderSettings;
129
+ maxShort?: number;
130
+ /** Default ["ladder"]. */
131
+ steps?: readonly Step[];
132
+ /** A decoder plugin's stream on stdin: these input options, and the input is "pipe:0". */
133
+ inputArgs?: string[];
134
+ /** Where storyboard thumbnails go before they are tiled (default <out>/../thumbs). */
135
+ thumbs?: string;
136
+ /**
137
+ * The optional steps' part of the command (audio, frame-check: src/steps/runner.ts stepArgs): more branches of the
138
+ * one decode, chains of their own, outputs after every other. Absent: the command is what it always was.
139
+ */
140
+ stepArgs?: {
141
+ videoBranches(first: number): string[];
142
+ chains: string[];
143
+ outputs: string[];
144
+ };
145
+ /**
146
+ * The storyboard made with StepSettings.storyboard (src/storyboard: WebP sheets + VTT): its branch of the one decode,
147
+ * in the old storyboard's place, and its outputs. Absent: the old storyboard (JPEG sheets), byte for byte.
148
+ */
149
+ storyboard?: {
150
+ branch(input: string): string;
151
+ outputs: string[];
152
+ };
153
+ }
154
+ /** Tile storyboard thumbnails into sheets (small JPEGs in, no source involved). */
155
+ export declare function sheetArgs(thumbs: string, out: string, plan: StoryboardPlan): string[];
156
+ /**
157
+ * Arguments for one ffmpeg run that writes every output of the job into `out/`:
158
+ * ladder out/master.m3u8, out/v<i>/index.m3u8, out/v<i>/init_<i>.mp4, out/v<i>/<seg>-NNNNN.m4s
159
+ * poster out/poster.jpg
160
+ * storyboard out/storyboard/sb-NNN.jpg
161
+ * faststart out/faststart.mp4
162
+ * audio, frame-check their outputs, from o.stepArgs (src/steps/runner.ts)
163
+ * Every rung keyframes at the same times (the source's own when the top rung is copied, else keyframeExpr: 0, first
164
+ * segment, then every keyframeS), so all rungs cut their segments at the same moments and the player can switch
165
+ * between any two segments.
166
+ */
167
+ export declare function jobArgs(input: string, out: string, p: Probe, o: JobArgsOptions): string[];
168
+ /**
169
+ * The sound's length in the rungs (seconds from its own start): the picture's end +0.1 s (the encoded picture starts
170
+ * x264's B-frame delay late in the fMP4, no edit list in FFmpeg's HLS, so it ends that much after the source's). Sound
171
+ * already ending there (to within 0.1 s past it) is left as it is. Sound ending with the picture is fitted too: it
172
+ * then ends before the rung's picture, and a clip whose last segment is short (one segment and a frame) never ends in
173
+ * Chromium with hls.js 1.7 (the buffer stops at the sound's end; no end of stream).
174
+ * - shorter (a truncated transport stream): padded with silence, or a seek near the end never completes in Chromium
175
+ * (MSE waits for sound that never comes);
176
+ * - longer (sound recorded past the picture): cut, or the player runs on with a frozen picture and reports the
177
+ * sound's length as the video's.
178
+ * 0: nothing to fit (or the header doesn't say). The picture's end: its header's, or one frame past its last frame
179
+ * when the packet index was read and says more (B-frames understate a sparse stream's header).
180
+ */
181
+ export declare function audioFitTo(p: Pick<Probe, "videoStart" | "videoDuration" | "audioStart" | "audioDuration" | "lastFrameAt" | "sparseRate">): number;
182
+ /** Does this job give ffmpeg anything to write? (Not: audio alone, of a source without audio.) */
183
+ export declare const ffmpegHasWork: (steps: readonly Step[], p: Pick<Probe, "hasAudio">) => boolean;
184
+ /**
185
+ * The fast-start copy as its own process (gap 3 of the ClipMe adoption): the source's own packets, its index (moov)
186
+ * first. A remux: `-c copy`, nothing decoded or re-encoded, so the job still decodes the source once. On its own so a
187
+ * source the MP4 muxer refuses (VP8) fails this alone, never the ladder made in the main run.
188
+ */
189
+ export declare function fastStartArgs(input: string, out: string, p: Pick<Probe, "video" | "hasAudio">): string[];
190
+ /** The ladder alone (the args every ladder job has had). */
191
+ export declare function ladderArgs(input: string, out: string, p: Probe, ladder: LadderSettings, maxShort?: number): string[];
192
+ /** ffprobe's JSON (-show_streams -show_format) and keyframe list → a Probe. null when there's no video stream. */
193
+ export declare function parseProbe(json: string, keyframeCsv: string, audioChoice?: number): Probe | null;
194
+ export declare function packetFacts(csv: string): {
195
+ keyframes: string;
196
+ editList: boolean;
197
+ vfr: boolean;
198
+ last?: number;
199
+ minGap?: number;
200
+ maxGap?: number;
201
+ end?: number;
202
+ };
203
+ /**
204
+ * Keyframe times from ffprobe's packet list (`-show_entries packet=pts_time,flags -of csv=p=0`): the container's own
205
+ * index (MP4's sync samples), read without decoding a frame. → "t1,t2,…" for parseProbe.
206
+ */
207
+ export declare function keyframesFromPackets(csv: string): string;
208
+ /**
209
+ * A fragmented MP4's picture, measured from its packet index: `last` its last frame's time, `end` where that frame
210
+ * ends (pts + its own duration, from keyframeProbeArgs(…, true); a 1 fps or long-tailed VFR stream's last frame lasts
211
+ * far longer than a nominal frame). FFmpeg 7.1's mov demuxer (7.1.1 and 7.1.5, the production image's) gives a stream
212
+ * of a multi-fragment MP4 with a sidx per fragment (an HLS/DASH rendition joined into one file) a length one fragment
213
+ * short: video 3.0 s of a 4 s picture when the picture is the second track. 9.x reads it right. The header's short
214
+ * picture cut the sound a fragment early (audioFitTo) and held the ladder to the short length. Only ever lengthens it.
215
+ */
216
+ export declare function withPacketEnd(p: Probe, facts: {
217
+ last: number;
218
+ end?: number;
219
+ }): Probe;
220
+ /** The ffprobe arguments for that packet list. */
221
+ export declare const keyframeProbeArgs: (src: string, video: number, durations?: boolean) => string[];
222
+ /**
223
+ * The master playlist with its best variant first. Safari (and other native HLS players) start on the first variant
224
+ * listed, and ffmpeg lists them smallest first: the picture would start at the bottom and climb. Best first, it starts
225
+ * at the top and steps down only if the connection can't keep up. Variant order doesn't matter to anything else.
226
+ */
227
+ export declare function bestFirst(master: string): string;