@uploadfilm/sdk 0.0.0-stage → 0.1.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 (218) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +509 -2
  3. package/dist/ai/embed.d.ts +58 -0
  4. package/dist/ai/fake.d.ts +41 -0
  5. package/dist/ai/http.d.ts +17 -0
  6. package/dist/ai/index.d.ts +27 -0
  7. package/dist/ai/languages.d.ts +2 -0
  8. package/dist/ai/ollama.d.ts +23 -0
  9. package/dist/ai/openaiCompatible.d.ts +54 -0
  10. package/dist/ai/passages.d.ts +28 -0
  11. package/dist/ai/transcribe.d.ts +84 -0
  12. package/dist/ai/types.d.ts +141 -0
  13. package/dist/ai/usage.d.ts +66 -0
  14. package/dist/ai/whisperJson.d.ts +15 -0
  15. package/dist/ai/workersAi.d.ts +56 -0
  16. package/dist/ai.js +1 -0
  17. package/dist/ai.mjs +1 -0
  18. package/dist/cards/files.d.ts +91 -0
  19. package/dist/cards/index.d.ts +15 -0
  20. package/dist/cards/layouts.d.ts +121 -0
  21. package/dist/cards/probe.d.ts +69 -0
  22. package/dist/cards/proxies.d.ts +70 -0
  23. package/dist/cards/select.d.ts +68 -0
  24. package/dist/cards/volumes.d.ts +170 -0
  25. package/dist/cards/xml.d.ts +80 -0
  26. package/dist/cards.js +1 -0
  27. package/dist/cards.mjs +1 -0
  28. package/dist/copy/checksums.d.ts +66 -0
  29. package/dist/copy/engine.d.ts +24 -0
  30. package/dist/copy/errors.d.ts +109 -0
  31. package/dist/copy/index.d.ts +15 -0
  32. package/dist/copy/steps.d.ts +28 -0
  33. package/dist/copy/sweep.d.ts +24 -0
  34. package/dist/copy/types.d.ts +336 -0
  35. package/dist/embed/player.js +2 -0
  36. package/dist/host/adapters.d.ts +107 -0
  37. package/dist/host/detect.d.ts +68 -0
  38. package/dist/host/encoders.d.ts +34 -0
  39. package/dist/host/environment.d.ts +53 -0
  40. package/dist/host/index.d.ts +20 -0
  41. package/dist/host/linux.d.ts +94 -0
  42. package/dist/host/mac.d.ts +47 -0
  43. package/dist/host/network.d.ts +54 -0
  44. package/dist/host/node.d.ts +13 -0
  45. package/dist/host/policy.d.ts +101 -0
  46. package/dist/host/tuner.d.ts +48 -0
  47. package/dist/host/types.d.ts +118 -0
  48. package/dist/host-node.js +1 -0
  49. package/dist/host-node.mjs +1 -0
  50. package/dist/host.js +1 -0
  51. package/dist/host.mjs +1 -0
  52. package/dist/images/index.d.ts +11 -0
  53. package/dist/images/settings.d.ts +43 -0
  54. package/dist/images/types.d.ts +83 -0
  55. package/dist/images/url.d.ts +65 -0
  56. package/dist/index.d.ts +16 -0
  57. package/dist/index.js +1 -0
  58. package/dist/index.mjs +1 -0
  59. package/dist/player/adapters/hlsjs.d.ts +28 -0
  60. package/dist/player/bandwidthMemory.d.ts +28 -0
  61. package/dist/player/captions/index.d.ts +55 -0
  62. package/dist/player/embed/code.d.ts +195 -0
  63. package/dist/player/embed/constants.d.ts +4 -0
  64. package/dist/player/embed/controller.d.ts +62 -0
  65. package/dist/player/embed/element.d.ts +32 -0
  66. package/dist/player/embed/frame.d.ts +65 -0
  67. package/dist/player/embed/global.d.ts +14 -0
  68. package/dist/player/embed/index.d.ts +15 -0
  69. package/dist/player/embed/loader.d.ts +1 -0
  70. package/dist/player/embed/oembed.d.ts +74 -0
  71. package/dist/player/embed/protocol.d.ts +64 -0
  72. package/dist/player/engine.d.ts +215 -0
  73. package/dist/player/index.d.ts +18 -0
  74. package/dist/player/start.d.ts +62 -0
  75. package/dist/player/store.d.ts +10 -0
  76. package/dist/player/storyboard/index.d.ts +161 -0
  77. package/dist/player/stream.d.ts +206 -0
  78. package/dist/player/tracks.d.ts +41 -0
  79. package/dist/player.js +1 -0
  80. package/dist/player.mjs +1 -0
  81. package/dist/proxies/args.d.ts +19 -0
  82. package/dist/proxies/budget.d.ts +57 -0
  83. package/dist/proxies/camera.d.ts +104 -0
  84. package/dist/proxies/formats.d.ts +36 -0
  85. package/dist/proxies/index.d.ts +18 -0
  86. package/dist/proxies/jobs.d.ts +98 -0
  87. package/dist/proxies/node.d.ts +32 -0
  88. package/dist/proxies/plan.d.ts +89 -0
  89. package/dist/proxies/probe.d.ts +39 -0
  90. package/dist/proxies/render.d.ts +104 -0
  91. package/dist/proxies/safety.d.ts +45 -0
  92. package/dist/proxies/types.d.ts +83 -0
  93. package/dist/proxies/upload.d.ts +14 -0
  94. package/dist/react/BigPlay.d.ts +26 -0
  95. package/dist/react/Player.d.ts +58 -0
  96. package/dist/react/embed/index.d.ts +45 -0
  97. package/dist/react/examples/CustomControls.d.ts +8 -0
  98. package/dist/react/images/Image.d.ts +16 -0
  99. package/dist/react/images/index.d.ts +4 -0
  100. package/dist/react/images/useImage.d.ts +47 -0
  101. package/dist/react/index.d.ts +17 -0
  102. package/dist/react/storyboard/index.d.ts +58 -0
  103. package/dist/react/theme.d.ts +37 -0
  104. package/dist/react/useAdapterErrors.d.ts +8 -0
  105. package/dist/react/usePlaybackStart.d.ts +18 -0
  106. package/dist/react/usePlayer.d.ts +28 -0
  107. package/dist/react/useReducedMotion.d.ts +2 -0
  108. package/dist/react/useTimedTrack.d.ts +22 -0
  109. package/dist/react.js +1 -0
  110. package/dist/react.mjs +1 -0
  111. package/dist/server/auth/apiKeys.d.ts +30 -0
  112. package/dist/server/auth/cache.d.ts +21 -0
  113. package/dist/server/auth/deviceTokens.d.ts +38 -0
  114. package/dist/server/auth/envelope.d.ts +15 -0
  115. package/dist/server/auth/grants.d.ts +76 -0
  116. package/dist/server/auth/index.d.ts +19 -0
  117. package/dist/server/auth/jwt.d.ts +65 -0
  118. package/dist/server/auth/keyring.d.ts +31 -0
  119. package/dist/server/auth/kv.d.ts +12 -0
  120. package/dist/server/auth/repository.d.ts +45 -0
  121. package/dist/server/auth/revocations.d.ts +21 -0
  122. package/dist/server/auth/scope.d.ts +4 -0
  123. package/dist/server/auth/serviceAuth.d.ts +24 -0
  124. package/dist/server/auth/signedUrls.d.ts +28 -0
  125. package/dist/server/embed/index.d.ts +36 -0
  126. package/dist/server/embed/lifecycle.d.ts +53 -0
  127. package/dist/server/embed/playerScript.d.ts +4 -0
  128. package/dist/server/images/index.d.ts +15 -0
  129. package/dist/server/images/job.d.ts +80 -0
  130. package/dist/server/images/layout.d.ts +24 -0
  131. package/dist/server/images/params.d.ts +90 -0
  132. package/dist/server/images/route.d.ts +101 -0
  133. package/dist/server/images/sign.d.ts +55 -0
  134. package/dist/server/index.d.ts +42 -0
  135. package/dist/server/media/client.d.ts +66 -0
  136. package/dist/server/media/frameCheck.d.ts +62 -0
  137. package/dist/server/media/index.d.ts +10 -0
  138. package/dist/server/media/protocol.d.ts +318 -0
  139. package/dist/server/media/storyboard.d.ts +144 -0
  140. package/dist/server/media/transcript.d.ts +143 -0
  141. package/dist/server/pipeline/index.d.ts +12 -0
  142. package/dist/server/pipeline/match.d.ts +10 -0
  143. package/dist/server/pipeline/pipeline.d.ts +182 -0
  144. package/dist/server/pipeline/queues.d.ts +108 -0
  145. package/dist/server/pipeline/sources.d.ts +54 -0
  146. package/dist/server/r2/client.d.ts +150 -0
  147. package/dist/server/r2/crc32.d.ts +24 -0
  148. package/dist/server/r2/encoding.d.ts +35 -0
  149. package/dist/server/r2/errors.d.ts +9 -0
  150. package/dist/server/r2/integrity.d.ts +25 -0
  151. package/dist/server/r2/parts.d.ts +46 -0
  152. package/dist/server/r2/sign.d.ts +47 -0
  153. package/dist/server/redis/index.d.ts +39 -0
  154. package/dist/server/state/memory.d.ts +18 -0
  155. package/dist/server/state/r2.d.ts +73 -0
  156. package/dist/server/state/types.d.ts +57 -0
  157. package/dist/server/storage/chunked.d.ts +21 -0
  158. package/dist/server/storage/index.d.ts +12 -0
  159. package/dist/server/storage/r2.d.ts +96 -0
  160. package/dist/server/storage/s3.d.ts +93 -0
  161. package/dist/server/testing/fake-r2.d.ts +390 -0
  162. package/dist/server/testing/index.d.ts +10 -0
  163. package/dist/server/testing/kv-contract.d.ts +14 -0
  164. package/dist/server/transfer/handler.d.ts +167 -0
  165. package/dist/server/transfer/keys.d.ts +45 -0
  166. package/dist/server/transfer/protocol.d.ts +141 -0
  167. package/dist/server/zip/client.d.ts +32 -0
  168. package/dist/server/zip/generations.d.ts +83 -0
  169. package/dist/server/zip/index.d.ts +12 -0
  170. package/dist/server/zip/planner.d.ts +94 -0
  171. package/dist/server/zip/sign.d.ts +22 -0
  172. package/dist/server-media.js +1 -0
  173. package/dist/server-media.mjs +1 -0
  174. package/dist/server-redis.js +1 -0
  175. package/dist/server-redis.mjs +1 -0
  176. package/dist/server-testing.js +1 -0
  177. package/dist/server-testing.mjs +1 -0
  178. package/dist/server.js +1 -0
  179. package/dist/server.mjs +1 -0
  180. package/dist/storage/browserFile.d.ts +19 -0
  181. package/dist/storage/index.d.ts +12 -0
  182. package/dist/storage/local.d.ts +9 -0
  183. package/dist/storage/presigned.d.ts +22 -0
  184. package/dist/sync/ffmpeg.d.ts +44 -0
  185. package/dist/sync/index.d.ts +17 -0
  186. package/dist/sync/match.d.ts +28 -0
  187. package/dist/sync/probe.d.ts +30 -0
  188. package/dist/sync/timecode.d.ts +50 -0
  189. package/dist/sync/transcript.d.ts +35 -0
  190. package/dist/sync/types.d.ts +172 -0
  191. package/dist/sync/waveform.d.ts +89 -0
  192. package/dist/sync.js +1 -0
  193. package/dist/sync.mjs +1 -0
  194. package/dist/transfer/claims.d.ts +41 -0
  195. package/dist/transfer/client.d.ts +256 -0
  196. package/dist/transfer/download.d.ts +192 -0
  197. package/dist/transfer/engine.d.ts +382 -0
  198. package/dist/transfer/errors.d.ts +50 -0
  199. package/dist/transfer/index.d.ts +39 -0
  200. package/dist/transfer/integrity.d.ts +93 -0
  201. package/dist/transfer/limits.d.ts +34 -0
  202. package/dist/transfer/node.d.ts +63 -0
  203. package/dist/transfer/pool.d.ts +83 -0
  204. package/dist/transfer/protocol.d.ts +167 -0
  205. package/dist/transfer/signer.d.ts +29 -0
  206. package/dist/transfer/storage.d.ts +110 -0
  207. package/dist/transfer/timing.d.ts +132 -0
  208. package/dist/transfer/transports/electronNet.d.ts +62 -0
  209. package/dist/transfer/transports/fetch.d.ts +15 -0
  210. package/dist/transfer/transports/retryAfter.d.ts +12 -0
  211. package/dist/transfer/transports/undici.d.ts +72 -0
  212. package/dist/transfer/tuner.d.ts +56 -0
  213. package/dist/zip/index.d.ts +13 -0
  214. package/dist/zip/layout.d.ts +129 -0
  215. package/dist/zip/names.d.ts +34 -0
  216. package/dist/zip/plan.d.ts +115 -0
  217. package/dist/zip/sw.d.ts +7 -0
  218. package/package.json +265 -4
@@ -0,0 +1,55 @@
1
+ import { type Keyring } from "../auth/keyring";
2
+ import type { ImageSource } from "../../images/types";
3
+ import { outputBox, type PolicyProblem, type ResolvedPolicy, type TransformParams, type TransformPolicy } from "./params";
4
+ export interface ImageSignerOptions {
5
+ keys: Keyring;
6
+ /** Where the route is mounted: an absolute URL ("https://img.example.com/img") or a path ("/img"). */
7
+ base: string;
8
+ /** Product domain tag, mixed into every MAC (two products sharing a secret still can't mint each other's URLs). */
9
+ domain: string;
10
+ policy?: TransformPolicy;
11
+ /** Which object keys may be transformed at all (checked when signing and when verifying). Default: any. */
12
+ keyAllowed?: (key: string) => boolean;
13
+ }
14
+ export type ImageUrlVerdict = {
15
+ ok: true;
16
+ key: string;
17
+ params: TransformParams;
18
+ canonical: string;
19
+ kid: string;
20
+ } | {
21
+ ok: false;
22
+ reason: "malformed" | "key" | "kid" | "signature" | "expired" | "policy";
23
+ problem?: PolicyProblem;
24
+ };
25
+ /** A preset name, or explicit params (format defaults to "auto"). */
26
+ export type ImagePresetArg = string | (Omit<TransformParams, "format"> & {
27
+ format?: TransformParams["format"];
28
+ });
29
+ export interface ImageSigner {
30
+ readonly policy: ResolvedPolicy;
31
+ /** Signed URL for one transform. Throws when the params are outside the policy or the key isn't allowed. */
32
+ url(key: string, preset: ImagePresetArg): Promise<string>;
33
+ /**
34
+ * An ImageSource for `<Image>` / `imageUrl`: signed URLs for each allowed width up to the image's own width, in
35
+ * each format (explicit formats, so `<picture>` can switch on type without relying on Vary: Accept).
36
+ */
37
+ source(key: string, size: {
38
+ width: number;
39
+ height: number;
40
+ }, o?: {
41
+ widths?: readonly number[];
42
+ formats?: readonly ("avif" | "webp" | "jpeg" | "png")[];
43
+ colourHex?: string;
44
+ /** The image version (manifest.version): versioned URLs are cached immutably. */
45
+ version?: string;
46
+ }): Promise<ImageSource>;
47
+ /** Checks a request URL (absolute, or a path with optional query). */
48
+ verify(url: string | URL, o?: {
49
+ now?: number;
50
+ }): Promise<ImageUrlVerdict>;
51
+ }
52
+ /** Whether a key is safe to carry in a path: no empty, "." or ".." segments, no control characters or backslashes. */
53
+ export declare function isSafeImageKey(key: string): boolean;
54
+ export declare function imageSigner(o: ImageSignerOptions): ImageSigner;
55
+ export { outputBox };
@@ -0,0 +1,42 @@
1
+ /**
2
+ * `@uploadfilm/sdk/server`: Node or Cloudflare Workers. R2 presign/multipart/integrity, the key-layout guard, the
3
+ * sign-batch handler (with authorize/quota/grant/dedupe hooks), and the state adapters (memory here; Redis in
4
+ * `@uploadfilm/sdk/server/redis`; both also fit the auth kit's KeyValueStore), and the media-worker protocol and job
5
+ * client (also on their own as `@uploadfilm/sdk/server/media`). RFC §2.4. Still to come: servePlayerScript(), the
6
+ * upload-completed pipeline.
7
+ */
8
+ export declare const SDK_ENTRY: "server";
9
+ export { createR2Client, contentDisposition, COPY_PART, COPY_SINGLE_MAX, PRESIGN_MAX_SECONDS } from "./r2/client";
10
+ export type { R2Client, R2Config, PresignGetOptions, PresignPutOptions, SignedFetchOptions } from "./r2/client";
11
+ export { amzDate, assertHeaderValue, presignUrl, sha256Hex, signRequest, UnsignableHeaderError } from "./r2/sign";
12
+ export type { SignedRequest, SigningCredentials } from "./r2/sign";
13
+ export { assertSignableKey, bareEtag, canonicalQueryString, isWellFormed, objectPath, UnsignableKeyError, uriEncode, xmlEscape, xmlUnescape, } from "./r2/encoding";
14
+ export type { Query } from "./r2/encoding";
15
+ export { R2Error, expectOk } from "./r2/errors";
16
+ export { checkCompletion, MIB, partCount, partRange, partSizeFor, S3_MAX_OBJECT, S3_MAX_PART, S3_MAX_PARTS, S3_MIN_PART, } from "./r2/parts";
17
+ export type { CompletionProblem, PartPlanOptions } from "./r2/parts";
18
+ export { etagOfContentMd5, md5, multipartEtag, toBase64, toHex, verifyStored } from "./r2/integrity";
19
+ export type { Verdict } from "./r2/integrity";
20
+ export { crc32Combine, crc32CombineAll, crcHex, parseCrcHex } from "./r2/crc32";
21
+ export { createKeyGuard, keySegments } from "./transfer/keys";
22
+ export type { KeyGuardOptions, KeyLayout } from "./transfer/keys";
23
+ export { WRITE_OP_NAMES } from "./transfer/protocol";
24
+ export type { TransferOp, TransferOpName, TransferRequest, TransferResponse, TransferResult, } from "./transfer/protocol";
25
+ export { createSignHandler, MD5_B64 } from "./transfer/handler";
26
+ export type { CustomOp, GrantEntry, GuardOutcome, HandlerAnswer, ReserveOutcome, SignHandlerOptions, } from "./transfer/handler";
27
+ export { checkBy, checkTtl, checkValue, namespaced, StateError, ttlMsOf } from "./state/types";
28
+ export type { AtomicKeyValueStore, KeyValueStore, SetOptions, Ttl } from "./state/types";
29
+ export { createMemoryStore } from "./state/memory";
30
+ export type { MemoryStoreOptions } from "./state/memory";
31
+ export { createR2Store, r2BindingBackend, r2ClientBackend, r2KeyOf } from "./state/r2";
32
+ export type { R2BindingLike, R2KvBackend, R2StoreOptions } from "./state/r2";
33
+ export * from "./auth";
34
+ export { ifNoneMatchHits, PLAYER_SCRIPT, PLAYER_SCRIPT_CACHE_CONTROL, PLAYER_SCRIPT_CONTENT_TYPE, PLAYER_SCRIPT_PATH, PLAYER_SCRIPT_SHA256, playerScriptEtag, servePlayerScript, } from "./embed";
35
+ export type { ServePlayerScriptOptions } from "./embed";
36
+ export { EMBED_EDGE_REDIRECT_S, EMBED_ORPHAN_AFTER_MS, EMBED_RETIRE_SLACK_S, EMBED_SIGNED_URL_TTL_S, copiesToDelete, embedRedirect, retireGraceMs } from "./embed";
37
+ export type { EmbedCopy, RetireTiming } from "./embed";
38
+ export * from "./zip";
39
+ export * from "./media";
40
+ export * from "./images";
41
+ export * from "./storage";
42
+ export * from "./pipeline";
@@ -0,0 +1,66 @@
1
+ import { type DoneReport, type JobRequest } from "./protocol";
2
+ export interface MediaJobClientOptions {
3
+ /** The media Worker's origin, e.g. https://media.example.com. */
4
+ url: string;
5
+ /** Shared with the Worker (≥ 32 characters). A function: read when used (env set after import). */
6
+ secret: string | (() => string);
7
+ /** HMAC domain of job requests, and of reports: one kind of signed message never passes as the other. */
8
+ jobDomain: string;
9
+ doneDomain: string;
10
+ /** Header the signature travels in. */
11
+ signatureHeader: string;
12
+ /** Per request. Default 30 s. */
13
+ timeoutMs?: number;
14
+ fetch?: typeof fetch;
15
+ /**
16
+ * Stamp every request with `issuedAt` (now, unix seconds) so the Worker can refuse a replay outside its window (O-3 in
17
+ * docs/platform/SECURITY.md). Off by default: the body stays byte for byte what it was. A Worker from before the stamp
18
+ * ignores it. A job that sets `issuedAt` itself is sent as given.
19
+ */
20
+ issuedAt?: boolean;
21
+ /** Milliseconds clock for the stamp (tests). */
22
+ now?: () => number;
23
+ }
24
+ export type ReportCheck = {
25
+ ok: true;
26
+ report: Partial<DoneReport> & Record<string, unknown>;
27
+ } | {
28
+ ok: false;
29
+ status: number;
30
+ body: string;
31
+ };
32
+ export interface MediaJobClient {
33
+ /** Ask the Worker for a job. Throws on anything but a 2xx (the caller records the failure and retries later). */
34
+ request(job: JobRequest): Promise<void>;
35
+ /**
36
+ * A report from the Worker: size, signature (constant time) and JSON checked. On failure, the status and body to
37
+ * answer with. The fields are the Worker's: check `id`, `attempt` and `prefix` against your own record.
38
+ */
39
+ readReport(body: string, signature: string): Promise<ReportCheck>;
40
+ /** Sign a body as the Worker would (tests, and products running their own runner host). */
41
+ sign(domain: "job" | "done", body: string): Promise<string>;
42
+ }
43
+ /**
44
+ * A job request that failed. `reached`: the Worker answered (with `status`); false: it was never reached or didn't
45
+ * answer in time (network down, a deploy, DNS, the timeout), so the product shouldn't count it as a try (UploadFilm
46
+ * d5186f8: an unreachable Worker is re-queued in 5 min without using one up). The message is what it always was.
47
+ */
48
+ export declare class MediaJobError extends Error {
49
+ readonly reached: boolean;
50
+ readonly status?: number;
51
+ readonly timedOut: boolean;
52
+ constructor(message: string, o: {
53
+ reached: boolean;
54
+ status?: number;
55
+ timedOut?: boolean;
56
+ cause?: unknown;
57
+ });
58
+ }
59
+ export declare function mediaJobClient(o: MediaJobClientOptions): MediaJobClient;
60
+ /**
61
+ * A finished job's outputs, made with other settings than the site's (a container still on an older image during a
62
+ * rollout): refuse them (delete, ask again once the rollout is through), never serve them. `version`: the version the
63
+ * job is stamped with, jobVersion(ladder version, the job's steps, step settings version) (the ladder's own for a job
64
+ * without optional steps).
65
+ */
66
+ export declare function refuseStale(report: Pick<DoneReport, "state" | "ladder">, version: string): boolean;
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The `frame-check` step: are the source's frames evenly spaced, with nothing missing, nothing repeated and nothing the
3
+ * decoder had to conceal? The container decodes the source once (the same decode as every other step), writes each
4
+ * decoded frame's timestamp (FFmpeg's framecrc of a 16×16 thumbnail, so nearly free) and collects the decoder's errors;
5
+ * its analysis (sdks/media-worker/src/runner/steps/frameCheck.ts) makes the small report stored as frame-check.json. A
6
+ * site reads it with readFrameCheck().
7
+ *
8
+ * What it can and cannot tell: a camera that drops a frame leaves a hole in the timestamps (a gap); a muxer or editor
9
+ * that writes two frames for one moment leaves a repeated timestamp (a duplicate); a frame earlier than the one before
10
+ * it is out of order; damage the decoder had to conceal shows up as decoder errors. Variable frame rate (phones) is
11
+ * reported as such: uneven spacing is then expected, so it isn't flagged frame by frame, only real gaps are.
12
+ *
13
+ * SELF-CONTAINED ON PURPOSE (like ./protocol.ts): no imports, erasable TypeScript only.
14
+ */
15
+ export interface FrameCheckSettings {
16
+ /** A step this many times the usual frame interval (or more) is a gap: frames missing. */
17
+ gapFactor: number;
18
+ /** A frame is "evenly spaced" within this fraction of the usual interval. */
19
+ jitter: number;
20
+ /** Lines of decoder errors kept in the report. */
21
+ maxErrorLines: number;
22
+ }
23
+ export interface FrameGap {
24
+ /** Seconds: the last frame before the hole. */
25
+ at: number;
26
+ /** Seconds the hole lasts beyond one usual interval. */
27
+ seconds: number;
28
+ /** Frames that would have fit in it (rounded). */
29
+ missing: number;
30
+ }
31
+ export interface FrameCheckReport {
32
+ /** Report format. */
33
+ format: 1;
34
+ /** True when nothing below is wrong: no gaps, duplicates, out-of-order frames or decoder errors (and some frames). */
35
+ ok: boolean;
36
+ frames: number;
37
+ /** Seconds from the first frame to the end of the last. */
38
+ seconds: number;
39
+ /** The usual interval (median), seconds; 0 with fewer than two frames. */
40
+ interval: number;
41
+ /** 1 / interval, rounded to 3 decimals. */
42
+ fps: number;
43
+ /** Share of intervals within `jitter` of the usual one (1 = perfectly even). */
44
+ even: number;
45
+ /** Uneven by design (phones): less than 90 % of intervals are the usual one, and no gap explains it. */
46
+ variable: boolean;
47
+ gaps: FrameGap[];
48
+ /** How many gaps there are, and how many frames they miss (gaps lists the first 100). */
49
+ gapCount: number;
50
+ missingFrames: number;
51
+ /** Frames with the same timestamp as the one before (seconds of the first 100). */
52
+ duplicates: number[];
53
+ duplicateCount: number;
54
+ /** Frames earlier than the one before (seconds of the first 100). */
55
+ outOfOrder: number[];
56
+ outOfOrderCount: number;
57
+ /** Lines the decoder logged as errors (the first maxErrorLines) and how many there were. */
58
+ decodeErrors: string[];
59
+ decodeErrorCount: number;
60
+ }
61
+ /** A stored frame-check.json, checked: null when it isn't a report this version knows. */
62
+ export declare function readFrameCheck(json: string): FrameCheckReport | null;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * `@uploadfilm/sdk/server/media`: the media worker's protocol (jobs, ladder settings, output names, reports) and the
3
+ * site's job client. The Worker itself is the deploy template in sdks/media-worker.
4
+ */
5
+ export declare const SDK_ENTRY: "server/media";
6
+ export * from "./protocol";
7
+ export * from "./transcript";
8
+ export * from "./frameCheck";
9
+ export { MediaJobError, mediaJobClient, refuseStale, type MediaJobClient, type MediaJobClientOptions, type ReportCheck } from "./client";
10
+ export { DEFAULT_STORYBOARD_SETTINGS, STORYBOARD_DIR, STORYBOARD_INDEX, STORYBOARD_VTT, checkSettings as checkStoryboardSettings, isStoryboardIndex, planStoryboard, sheetCount as storyboardSheetCount, storyboardCues, storyboardDescriptor, storyboardFile, storyboardIndex, storyboardSettings, storyboardSheetName, storyboardVtt, type StoryboardCue, type StoryboardDescriptor, type StoryboardIndex, type StoryboardPlan, type StoryboardSettings, } from "./storyboard";
@@ -0,0 +1,318 @@
1
+ /**
2
+ * The media-worker protocol: what a job is, what a ladder looks like, which files a job may write, and the report a
3
+ * job ends with. Shared by the site (the job client, ./client.ts), the media Worker (sdks/media-worker) and the runner
4
+ * inside the ffmpeg container.
5
+ *
6
+ * SELF-CONTAINED ON PURPOSE (like ../auth/grants.ts): no imports and only erasable TypeScript, so plain Node (type
7
+ * stripping, no loader), workerd, a bundler and the ffmpeg container all load this one file by path.
8
+ *
9
+ * Nothing here is a product's: the rungs, the settings version, the key layout and the HMAC domains are configuration
10
+ * (UploadFilm's live in shared/stream.ts and worker/media/src/config.ts).
11
+ */
12
+ /** One rung: its short side (the long side follows the picture), video bitrate and peak. */
13
+ export interface Rung {
14
+ short: number;
15
+ /** Video kbps (average) for an encoded rung. */
16
+ kbps: number;
17
+ /** Peak kbps (maxrate); bufsize is twice the average. */
18
+ peak: number;
19
+ }
20
+ /** The default ladder: 360p for a weak link, 720p everyday, 1080p the big screen. */
21
+ export declare const DEFAULT_RUNGS: readonly Rung[];
22
+ /**
23
+ * Everything that decides what a job's outputs look like. `version` names these settings: every output is stamped with
24
+ * it, outputs stamped otherwise are refused, and (with the source's identity) it is the job's idempotency key. Change
25
+ * it whenever anything here changes, AND whenever the media worker's runner changes what it makes of the same settings
26
+ * (see RUNNER_OUTPUT_REVISION): old outputs are then refused and remade, never served as current.
27
+ */
28
+ export interface LadderSettings {
29
+ version: string;
30
+ rungs: readonly Rung[];
31
+ /** Stereo AAC in every rung (muxed, so any rung plays on its own). */
32
+ audioKbps: number;
33
+ /** ffmpeg's hls_init_time: the first segments are cut at the first keyframe past this. */
34
+ firstSegmentS: number;
35
+ /** ffmpeg's hls_time: the upper bound, reached only by a copied top rung's own longer GOPs. */
36
+ segmentS: number;
37
+ /** Encoded rungs keyframe at 0, firstSegmentS, then every keyframeS. */
38
+ keyframeS: number;
39
+ /** Segment files are <segmentName>-NNNNN.m4s; a new name never shares a path with an edge-cached older ladder. */
40
+ segmentName: string;
41
+ /** Older segment names the server still serves (ladders made before a rename). */
42
+ legacySegmentNames?: readonly string[];
43
+ /** The top rung keeps the source's own stream when its keyframes are at most this far apart. */
44
+ copyMaxGopS: number;
45
+ /** …and its overall bitrate is at most this (a heavier camera original is re-encoded). */
46
+ copyMaxBps: number;
47
+ /** x264 preset for a full ladder, and for a capped one (a cloud preview: decoding the original is the slow part). */
48
+ preset: string;
49
+ cappedPreset: string;
50
+ }
51
+ /**
52
+ * The media worker runner's output revision. It changes when the runner makes different outputs from the same
53
+ * settings; each product then changes its own `version` (its ladder id) so outputs from the older runner are remade.
54
+ * 1 the runner as moved into the SDK
55
+ * 2 the format lab's fixes (docs/platform/FORMATS.md F1–F11): HDR → SDR BT.709, deinterlacing, square-pixel poster
56
+ * and storyboard, edit lists, padded short sound, sparse VFR, copy rules, runner-written master, the done check
57
+ */
58
+ export declare const RUNNER_OUTPUT_REVISION = 2;
59
+ /** The default settings with the given version (and any overrides). */
60
+ export declare function ladderSettings(version: string, over?: Partial<Omit<LadderSettings, "version">>): LadderSettings;
61
+ /** Encoded rungs' keyframes: at 0, at `first`, then every `every` seconds (an ffmpeg force_key_frames expression). */
62
+ export declare const keyframeExpr: (first: number, every: number) => string;
63
+ export interface RungSize {
64
+ width: number;
65
+ height: number;
66
+ kbps: number;
67
+ peak: number;
68
+ top: boolean;
69
+ }
70
+ /**
71
+ * The rungs to make for a picture of this size: every rung smaller than it, then the picture's own size on top.
72
+ * `maxShort` (a capped ladder, e.g. a preview of a camera original): a bigger picture is treated as scaled down to it.
73
+ */
74
+ export declare function rungsFor(rungs: readonly Rung[], width: number, height: number, maxShort?: number): RungSize[];
75
+ /**
76
+ * What a job makes. One container run and one decode of the source make all of them:
77
+ * ladder HLS fMP4 ladder: master.m3u8, v<i>/index.m3u8, v<i>/init_<i>.mp4, v<i>/<seg>-NNNNN.m4s
78
+ * poster poster.jpg (a frame near the start, the top rung's size at most 1080p)
79
+ * storyboard storyboard/sb-NNN.jpg tiles + storyboard/storyboard.json (scrubbing previews); with
80
+ * StepSettings.storyboard set: WebP sheets storyboard/sb-NNN.webp, a WebVTT thumbnails track
81
+ * storyboard/storyboard.vtt and storyboard/storyboard.json (./storyboard.ts), from the same decode
82
+ * faststart faststart.mp4: the source remuxed with its index first (no re-encode, no decode)
83
+ */
84
+ export type Step = "ladder" | "poster" | "storyboard" | "faststart" | "audio" | "transcript" | "frame-check";
85
+ export declare const STEPS: readonly Step[];
86
+ /**
87
+ * Optional steps, off unless a product allows them (its config's `steps.allowed`) and a job asks for them:
88
+ * audio audio/a-NNN.ogg (Opus, mono, 16 kHz, chunks of StepSettings.audio.chunkS) + audio/audio.json (the chunks
89
+ * and the silences found in them); from the same decode as everything else
90
+ * transcript transcript.vtt + transcript.json: speech-to-text of the audio chunks, made by the media Worker (not the
91
+ * container) after the container is done; implies `audio`
92
+ * frame-check frame-check.json: are the source's frames evenly spaced, with no gaps, duplicates or decode errors?
93
+ * Timestamps of every decoded frame, from the same decode
94
+ * A job naming any of them is stamped with jobVersion() (the ladder's version + the step settings' version): a job
95
+ * without them keeps the ladder's version, byte for byte.
96
+ */
97
+ export declare const EXTRA_STEPS: readonly Step[];
98
+ /** Does this job run any optional step? */
99
+ export declare const hasExtraSteps: (steps: readonly Step[]) => boolean;
100
+ /** Does the container write audio chunks for this job? (`transcript` needs them.) */
101
+ export declare const wantsAudio: (steps: readonly Step[]) => boolean;
102
+ /**
103
+ * Everything that decides what the optional steps make. `version` names these settings: a job with an optional step is
104
+ * stamped with jobVersion(ladder.version, steps, version). Change it whenever anything here changes.
105
+ */
106
+ export interface StepSettings {
107
+ version: string;
108
+ audio: {
109
+ /** Opus kbps (mono speech). */
110
+ kbps: number;
111
+ /** Chunk length in seconds: each chunk is one speech-to-text request. */
112
+ chunkS: number;
113
+ };
114
+ /** Voice activity: audio quieter than `noiseDb` for at least `minSilenceS` is silence. */
115
+ vad: {
116
+ noiseDb: number;
117
+ minSilenceS: number;
118
+ /** A transcript segment within a silence (give or take this many seconds at either end) is dropped. */
119
+ edgeS: number;
120
+ };
121
+ transcript: {
122
+ /** Workers AI model id. */
123
+ model: string;
124
+ /** BCP 47 language to force; absent: detected. */
125
+ language?: string;
126
+ };
127
+ frameCheck: {
128
+ /** A step this many times the usual frame interval (or more) is a gap: frames missing. */
129
+ gapFactor: number;
130
+ /** A frame is "evenly spaced" within this fraction of the usual interval. */
131
+ jitter: number;
132
+ /** Lines of decoder errors kept in the report. */
133
+ maxErrorLines: number;
134
+ };
135
+ /**
136
+ * Timeline hover previews (./storyboard.ts): set, the `storyboard` step makes WebP sheets and a WebVTT thumbnails
137
+ * track (a thumbnail every intervalS, at most maxFrames, within a byte budget) and its jobs are stamped with these
138
+ * settings' version; absent, the step makes what it always made (JPEG sheets, no VTT), byte for byte. Any field left
139
+ * out takes ./storyboard.ts's default.
140
+ */
141
+ storyboard?: {
142
+ intervalS?: number;
143
+ maxFrames?: number;
144
+ size?: number;
145
+ cols?: number;
146
+ rows?: number;
147
+ quality?: number;
148
+ minQuality?: number;
149
+ maxSheetBytes?: number;
150
+ maxBytes?: number;
151
+ };
152
+ }
153
+ /** The default optional-step settings with the given version (and any overrides, merged per group). */
154
+ export declare function stepSettings(version: string, over?: {
155
+ [K in keyof Omit<StepSettings, "version">]?: Partial<StepSettings[K]>;
156
+ }): StepSettings;
157
+ /** The settings a product gets when its config names none. */
158
+ export declare const DEFAULT_STEP_SETTINGS: StepSettings;
159
+ /** Does this job's storyboard use the step settings (WebP sheets + VTT, StepSettings.storyboard)? */
160
+ export declare const storyboardV2: (steps: readonly Step[], settings: Pick<StepSettings, "storyboard"> | undefined) => boolean;
161
+ /**
162
+ * The version a job's outputs are stamped with (and checked against): the ladder's own for a job without optional
163
+ * steps (unchanged), else `<ladder>+<step settings>`. Given the settings themselves (not only their version), a
164
+ * storyboard made with StepSettings.storyboard counts as an optional step too.
165
+ */
166
+ export declare const jobVersion: (ladderVersion: string, steps: readonly Step[], settings?: string | Pick<StepSettings, "version" | "storyboard">) => string;
167
+ /** The optional steps' fixed file names under a job's prefix. */
168
+ export declare const AUDIO_INDEX = "audio/audio.json";
169
+ export declare const TRANSCRIPT_VTT = "transcript.vtt";
170
+ export declare const TRANSCRIPT_JSON = "transcript.json";
171
+ export declare const FRAME_CHECK_FILE = "frame-check.json";
172
+ export declare const audioChunkName: (i: number) => string;
173
+ /** Steps in their canonical order, deduplicated; null when anything isn't a known step or the list is empty. */
174
+ export declare function parseSteps(x: unknown, allowed?: readonly Step[]): Step[] | null;
175
+ /** Is `rel` a name the transcoder writes inside a ladder (and the Worker serves)? `seg`: the segment names in use. */
176
+ export declare function ladderFile(rel: string, seg: readonly string[]): "playlist" | "init" | "segment" | null;
177
+ export type OutputKind = "playlist" | "init" | "segment" | "poster" | "storyboard" | "storyboard-index" | "faststart" | "audio" | "audio-index" | "transcript" | "transcript-json" | "frame-check";
178
+ /** Is `rel` a file one of these steps writes? (The gatekeeper refuses anything else.) */
179
+ export declare function outputFile(rel: string, steps: readonly Step[], seg: readonly string[]): OutputKind | null;
180
+ /**
181
+ * The file a job's container writes last: while it is missing the job's outputs don't exist for anyone. The master
182
+ * playlist for a ladder; else the last step's own file. A transcript is written after it (by the Worker).
183
+ */
184
+ export declare function completionFile(steps: readonly Step[]): string;
185
+ export declare const contentTypeOf: (rel: string) => "application/json" | "image/webp" | "image/jpeg" | "audio/ogg" | "video/mp4" | "application/vnd.apple.mpegurl" | "video/iso.segment" | "text/vtt; charset=utf-8";
186
+ /**
187
+ * The hash a job's outputs are named by: SHA-256 (hex) of `<sourceKey>#<sourceEtag>[#<variant>]`. A new version of the
188
+ * source (another ETag) or another variant (other settings) gets other outputs; the same ones always the same name.
189
+ */
190
+ export declare function sourceHash(sourceKey: string, sourceEtag: string, variant?: string): Promise<string>;
191
+ /** A job request's body is at most this long; so is a report's. */
192
+ export declare const MAX_BODY = 4096;
193
+ /**
194
+ * A job request, as the site sends it (signed: HMAC over the body under the product's job domain).
195
+ * The job's id names its output prefix: one Durable Object (and one container) per id, so a repeated request joins the
196
+ * running job. With the settings version it is the idempotency key.
197
+ */
198
+ export interface JobRequest {
199
+ id: string;
200
+ /** The site's attempt number, echoed in the report (a late report of an older attempt is ignored). */
201
+ attempt: number;
202
+ /** Source key, and the ETag the job is pinned to (a source replaced meanwhile is refused, not transcoded). */
203
+ src: string;
204
+ etag: string;
205
+ bytes: number;
206
+ /** Where the outputs go. */
207
+ prefix: string;
208
+ /** The site's callback URL for the report. */
209
+ done: string;
210
+ /** A capped ladder: the top rung's short side at most this. Absent: the source's size. */
211
+ maxShort?: number;
212
+ /** Absent: the Worker's default steps (so a site from before steps keeps working, byte for byte). */
213
+ steps?: Step[];
214
+ /**
215
+ * When the site signed the request (unix seconds). The Worker refuses a request stamped outside its window (±15 min,
216
+ * JOB_WINDOW_S): a captured request can't be replayed later. Absent: accepted (a site from before the stamp).
217
+ */
218
+ issuedAt?: number;
219
+ /**
220
+ * Seconds the source is known to last, measured by whoever made or checked it (a recorder's own clock, the Mac's
221
+ * probe of the original). The "done" invariant refuses a ladder (and a fast-start copy) shorter than this, as it
222
+ * does against the header's duration: the check that catches a truncated file whose header has no duration (a
223
+ * MediaRecorder WebM). Absent: only the header's duration is checked, as before (the body is byte for byte the same).
224
+ */
225
+ expectDurationS?: number;
226
+ }
227
+ /** The longest expected length a job may carry (a week of footage: anything longer is a mistake, not a video). */
228
+ export declare const MAX_EXPECT_DURATION_S: number;
229
+ /** A valid `expectDurationS`: a finite number of seconds, > 0, at most MAX_EXPECT_DURATION_S. */
230
+ export declare const validExpectDuration: (x: unknown) => x is number;
231
+ /** The job's body, its fields always in this order (the signature is over these bytes). */
232
+ export declare function jobBody(j: JobRequest): string;
233
+ export interface DoneReport {
234
+ id: string;
235
+ attempt: number;
236
+ prefix: string;
237
+ state: "done" | "error";
238
+ /** Rungs in the ladder. */
239
+ rungs?: number;
240
+ error?: string;
241
+ /**
242
+ * Why a failed job failed, when known (the runner's RunnerStatus.code): "unsupported" (nothing decodes the source:
243
+ * store it, flag "no preview", don't ask again), "stale-image" (every container ran an older image: a rollout, ask
244
+ * again later without counting a try), "source" (the source couldn't be read or is damaged). Absent: a lost
245
+ * container, a timeout, or a Worker from before the field.
246
+ */
247
+ code?: RunnerStatus["code"];
248
+ /** The settings version the outputs were made with (the container image's): see {@link stampMatches}. */
249
+ ladder?: string;
250
+ /** Seconds: waited for a container, then the container's phases (download, probe, encode, upload); decode passes. */
251
+ timings?: Record<string, number>;
252
+ /**
253
+ * A job with the `transcript` step: whether its transcript was made. A transcript that can't be made doesn't fail the
254
+ * job (its other outputs are done): state "error" and why. Absent for a job without the step.
255
+ */
256
+ transcript?: {
257
+ state: "done" | "error";
258
+ reason?: string;
259
+ };
260
+ /**
261
+ * A job with the `faststart` step and a ladder: whether the fast-start copy was made. A source that can't be remuxed
262
+ * into an MP4 (VP8, ProRes, a RAW plugin's) or a remux that fails doesn't fail the job (the ladder is done): state
263
+ * "skipped" and why, and no faststart.mp4. Absent for a job without the step. (A fast-start-only job fails instead.)
264
+ */
265
+ faststart?: {
266
+ state: "done" | "skipped";
267
+ reason?: string;
268
+ };
269
+ /**
270
+ * The expected length (JobRequest.expectDurationS) the outputs were checked against: echoed only by a runner that
271
+ * enforces it. A job that asked for the check and gets a done without this echo was run by an older image that
272
+ * ignored the field: the Worker never reports that done (it runs the job again), and a site can check it too.
273
+ */
274
+ expectDurationS?: number;
275
+ }
276
+ /**
277
+ * Were these outputs made with the settings the site expects? During a rollout the Worker (and the site) can be new
278
+ * while some containers still run the old image: their outputs are refused and remade, never served.
279
+ */
280
+ export declare const stampMatches: (r: Pick<DoneReport, "ladder">, version: string) => boolean;
281
+ /** The container's answer to GET /status. */
282
+ export interface RunnerStatus {
283
+ state: "idle" | "running" | "done" | "error";
284
+ phase?: string;
285
+ progress: number;
286
+ error?: string;
287
+ /** Why it failed, when the runner knows: "unsupported" (nothing decodes it: stored, flagged no preview),
288
+ * "stale-image" (the Worker refused this image's outputs), "source" (the source couldn't be read), "disk" (the
289
+ * source and the copies the job keeps of it can't fit the runner's free disk: checked before the download). */
290
+ code?: "unsupported" | "stale-image" | "source" | "disk";
291
+ rungs?: number;
292
+ timings?: Record<string, number>;
293
+ /** The settings version this runner makes. */
294
+ ladder?: string;
295
+ /**
296
+ * A job with the `faststart` step and a ladder: whether the fast-start copy was made. A source that can't be remuxed
297
+ * into an MP4 (VP8, ProRes, a RAW plugin's) or a remux that fails doesn't fail the job (the ladder is done): state
298
+ * "skipped" and why, and no faststart.mp4. Absent for a job without the step. (A fast-start-only job fails instead.)
299
+ */
300
+ faststart?: {
301
+ state: "done" | "skipped";
302
+ reason?: string;
303
+ };
304
+ /**
305
+ * The expected length (JobRequest.expectDurationS) the outputs were checked against: echoed only by a runner that
306
+ * enforces it. A job that asked for the check and gets a done without this echo was run by an older image that
307
+ * ignored the field: the Worker never reports that done (it runs the job again), and a site can check it too.
308
+ */
309
+ expectDurationS?: number;
310
+ }
311
+ /**
312
+ * Header a runner that enforces JobRequest.expectDurationS sends on every output of a job that has one: the length it
313
+ * checks against. The gatekeeper refuses outputs of such a job without it (an older image that ignores the field), so
314
+ * nothing it made is stored, completion file included.
315
+ */
316
+ export declare const EXPECT_HEADER = "x-media-expect-duration";
317
+ /** Header the runner sends its settings version in, on every output it writes (the gatekeeper refuses another). */
318
+ export declare const VERSION_HEADER = "x-media-version";