@uploadfilm/sdk 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (267) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +529 -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 +363 -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 +99 -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 +556 -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 +164 -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 +25 -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 +144 -0
  161. package/dist/server/testing/fake-r2.d.ts +410 -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 +217 -0
  165. package/dist/server/transfer/keys.d.ts +45 -0
  166. package/dist/server/transfer/protocol.d.ts +190 -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 +267 -0
  196. package/dist/transfer/download.d.ts +192 -0
  197. package/dist/transfer/engine.d.ts +402 -0
  198. package/dist/transfer/errors.d.ts +50 -0
  199. package/dist/transfer/growing/bytes.d.ts +17 -0
  200. package/dist/transfer/growing/index.d.ts +12 -0
  201. package/dist/transfer/growing/parts.d.ts +157 -0
  202. package/dist/transfer/growing/retry.d.ts +38 -0
  203. package/dist/transfer/growing/store.d.ts +66 -0
  204. package/dist/transfer/growing/upload.d.ts +126 -0
  205. package/dist/transfer/index.d.ts +40 -0
  206. package/dist/transfer/integrity.d.ts +93 -0
  207. package/dist/transfer/limits.d.ts +34 -0
  208. package/dist/transfer/node.d.ts +63 -0
  209. package/dist/transfer/pool.d.ts +83 -0
  210. package/dist/transfer/protocol.d.ts +172 -0
  211. package/dist/transfer/signer.d.ts +29 -0
  212. package/dist/transfer/storage.d.ts +135 -0
  213. package/dist/transfer/timing.d.ts +132 -0
  214. package/dist/transfer/transports/electronNet.d.ts +62 -0
  215. package/dist/transfer/transports/fetch.d.ts +15 -0
  216. package/dist/transfer/transports/retryAfter.d.ts +12 -0
  217. package/dist/transfer/transports/undici.d.ts +72 -0
  218. package/dist/transfer/tuner.d.ts +56 -0
  219. package/dist/workers/cli.mjs +115 -0
  220. package/dist/workers/media/config.mjs +53 -0
  221. package/dist/workers/media/container/Dockerfile +19 -0
  222. package/dist/workers/media/container/FFMPEG.md +129 -0
  223. package/dist/workers/media/container/runner.mjs +2690 -0
  224. package/dist/workers/media/index.mjs +1011 -0
  225. package/dist/workers/media/init/config.ts +52 -0
  226. package/dist/workers/media/init/worker.ts +8 -0
  227. package/dist/workers/media/init/wrangler.toml +44 -0
  228. package/dist/workers/media/runner.mjs +2656 -0
  229. package/dist/workers/media/types/build/entry/config.d.mts +6 -0
  230. package/dist/workers/media/types/build/entry/index.d.mts +43 -0
  231. package/dist/workers/media/types/build/entry/program.d.mts +13 -0
  232. package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
  233. package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
  234. package/dist/workers/media/types/src/config.d.mts +135 -0
  235. package/dist/workers/media/types/src/jobs.d.mts +73 -0
  236. package/dist/workers/media/types/src/runner/container.d.mts +32 -0
  237. package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
  238. package/dist/workers/media/types/src/runner/job.d.mts +107 -0
  239. package/dist/workers/media/types/src/runner/node.d.mts +71 -0
  240. package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
  241. package/dist/workers/media/types/src/serve.d.mts +107 -0
  242. package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
  243. package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
  244. package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
  245. package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
  246. package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
  247. package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
  248. package/dist/workers/media/types/src/steps/render.d.mts +40 -0
  249. package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
  250. package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
  251. package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
  252. package/dist/workers/media/types/src/transcoder.d.mts +30 -0
  253. package/dist/workers/media/types/src/worker.d.mts +30 -0
  254. package/dist/workers/zip/index.mjs +589 -0
  255. package/dist/workers/zip/init/config.ts +22 -0
  256. package/dist/workers/zip/init/worker.ts +5 -0
  257. package/dist/workers/zip/init/wrangler.toml +25 -0
  258. package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
  259. package/dist/workers/zip/types/src/config.d.mts +35 -0
  260. package/dist/workers/zip/types/src/serve.d.mts +86 -0
  261. package/dist/workers/zip/types/src/worker.d.mts +12 -0
  262. package/dist/zip/index.d.ts +13 -0
  263. package/dist/zip/layout.d.ts +129 -0
  264. package/dist/zip/names.d.ts +34 -0
  265. package/dist/zip/plan.d.ts +115 -0
  266. package/dist/zip/sw.d.ts +7 -0
  267. package/package.json +313 -4
@@ -0,0 +1,556 @@
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" | "prep" | "render";
85
+ /** The steps a job may name unless a product allows more (`prep` and `render` are allowed only by name: EDIT_STEPS). */
86
+ export declare const STEPS: readonly Step[];
87
+ /**
88
+ * The editor's steps (docs/platform/MEDIA-STEPS.md). Each is a job of its own (never named with another step) and is
89
+ * off unless a product names it in `steps.allowed`:
90
+ * prep an edit-ready source: edit/media.mp4 (fragmented MP4, H.264/AAC within a resolution cap; only when the
91
+ * source isn't one already), filmstrip sheets edit/sb-NNN.jpg, waveform peaks edit/peaks.bin, and
92
+ * edit/prep.json (PrepResult) written last. One decode.
93
+ * render an edit list (EditList: parts of several sources, JobRequest.render) baked into render/video.mp4
94
+ * (fragmented MP4, moov first, H.264 + AAC 48 kHz stereo), render/poster.jpg and render/result.json
95
+ * (RenderResult) written last.
96
+ */
97
+ export declare const EDIT_STEPS: readonly Step[];
98
+ /** Every step, in canonical order. */
99
+ export declare const ALL_STEPS: readonly Step[];
100
+ /**
101
+ * Optional steps, off unless a product allows them (its config's `steps.allowed`) and a job asks for them:
102
+ * audio audio/a-NNN.ogg (Opus, mono, 16 kHz, chunks of StepSettings.audio.chunkS) + audio/audio.json (the chunks
103
+ * and the silences found in them); from the same decode as everything else
104
+ * transcript transcript.vtt + transcript.json: speech-to-text of the audio chunks, made by the media Worker (not the
105
+ * container) after the container is done; implies `audio`
106
+ * frame-check frame-check.json: are the source's frames evenly spaced, with no gaps, duplicates or decode errors?
107
+ * Timestamps of every decoded frame, from the same decode
108
+ * A job naming any of them is stamped with jobVersion() (the ladder's version + the step settings' version): a job
109
+ * without them keeps the ladder's version, byte for byte.
110
+ */
111
+ export declare const EXTRA_STEPS: readonly Step[];
112
+ /** Does this job run any optional step? */
113
+ export declare const hasExtraSteps: (steps: readonly Step[]) => boolean;
114
+ /** Is this a prep or render job? (Those run alone: parseSteps refuses them with any other step.) */
115
+ export declare const isEditJob: (steps: readonly Step[]) => boolean;
116
+ /** Does the container write audio chunks for this job? (`transcript` needs them.) */
117
+ export declare const wantsAudio: (steps: readonly Step[]) => boolean;
118
+ /**
119
+ * Everything that decides what the optional steps make. `version` names these settings: a job with an optional step is
120
+ * stamped with jobVersion(ladder.version, steps, version). Change it whenever anything here changes.
121
+ */
122
+ export interface StepSettings {
123
+ version: string;
124
+ audio: {
125
+ /** Opus kbps (mono speech). */
126
+ kbps: number;
127
+ /** Chunk length in seconds: each chunk is one speech-to-text request. */
128
+ chunkS: number;
129
+ };
130
+ /** Voice activity: audio quieter than `noiseDb` for at least `minSilenceS` is silence. */
131
+ vad: {
132
+ noiseDb: number;
133
+ minSilenceS: number;
134
+ /** A transcript segment within a silence (give or take this many seconds at either end) is dropped. */
135
+ edgeS: number;
136
+ };
137
+ transcript: {
138
+ /** Workers AI model id. */
139
+ model: string;
140
+ /** BCP 47 language to force; absent: detected. */
141
+ language?: string;
142
+ };
143
+ frameCheck: {
144
+ /** A step this many times the usual frame interval (or more) is a gap: frames missing. */
145
+ gapFactor: number;
146
+ /** A frame is "evenly spaced" within this fraction of the usual interval. */
147
+ jitter: number;
148
+ /** Lines of decoder errors kept in the report. */
149
+ maxErrorLines: number;
150
+ };
151
+ /**
152
+ * Timeline hover previews (./storyboard.ts): set, the `storyboard` step makes WebP sheets and a WebVTT thumbnails
153
+ * track (a thumbnail every intervalS, at most maxFrames, within a byte budget) and its jobs are stamped with these
154
+ * settings' version; absent, the step makes what it always made (JPEG sheets, no VTT), byte for byte. Any field left
155
+ * out takes ./storyboard.ts's default.
156
+ */
157
+ storyboard?: {
158
+ intervalS?: number;
159
+ maxFrames?: number;
160
+ size?: number;
161
+ cols?: number;
162
+ rows?: number;
163
+ quality?: number;
164
+ minQuality?: number;
165
+ maxSheetBytes?: number;
166
+ maxBytes?: number;
167
+ };
168
+ /** The `prep` step (an edit-ready source). Any field left out takes DEFAULT_PREP's. */
169
+ prep?: Partial<PrepSettings>;
170
+ /** The `render` step (an edit list baked into one file). Any field left out takes DEFAULT_RENDER's. */
171
+ render?: Partial<RenderSettings>;
172
+ }
173
+ /** The default optional-step settings with the given version (and any overrides, merged per group). */
174
+ export declare function stepSettings(version: string, over?: {
175
+ [K in keyof Omit<StepSettings, "version">]?: Partial<StepSettings[K]>;
176
+ }): StepSettings;
177
+ /** The settings a product gets when its config names none. */
178
+ export declare const DEFAULT_STEP_SETTINGS: StepSettings;
179
+ /** Does this job's storyboard use the step settings (WebP sheets + VTT, StepSettings.storyboard)? */
180
+ export declare const storyboardV2: (steps: readonly Step[], settings: Pick<StepSettings, "storyboard"> | undefined) => boolean;
181
+ /**
182
+ * The version a job's outputs are stamped with (and checked against): the ladder's own for a job without optional
183
+ * steps (unchanged), else `<ladder>+<step settings>`. Given the settings themselves (not only their version), a
184
+ * storyboard made with StepSettings.storyboard counts as an optional step too.
185
+ */
186
+ export declare const jobVersion: (ladderVersion: string, steps: readonly Step[], settings?: string | Pick<StepSettings, "version" | "storyboard">) => string;
187
+ /** The optional steps' fixed file names under a job's prefix. */
188
+ export declare const AUDIO_INDEX = "audio/audio.json";
189
+ export declare const TRANSCRIPT_VTT = "transcript.vtt";
190
+ export declare const TRANSCRIPT_JSON = "transcript.json";
191
+ export declare const FRAME_CHECK_FILE = "frame-check.json";
192
+ export declare const audioChunkName: (i: number) => string;
193
+ /**
194
+ * Steps in their canonical order, deduplicated; null when anything isn't a known step or the list is empty, or when
195
+ * `prep` or `render` is named with any other step (each is a job of its own).
196
+ */
197
+ export declare function parseSteps(x: unknown, allowed?: readonly Step[]): Step[] | null;
198
+ /** Is `rel` a name the transcoder writes inside a ladder (and the Worker serves)? `seg`: the segment names in use. */
199
+ export declare function ladderFile(rel: string, seg: readonly string[]): "playlist" | "init" | "segment" | null;
200
+ export type OutputKind = "playlist" | "init" | "segment" | "poster" | "storyboard" | "storyboard-index" | "faststart" | "audio" | "audio-index" | "transcript" | "transcript-json" | "frame-check" | "edit-media" | "edit-filmstrip" | "edit-peaks" | "edit-result" | "render-video" | "render-poster" | "render-result";
201
+ /** Is `rel` a file one of these steps writes? (The gatekeeper refuses anything else.) */
202
+ export declare function outputFile(rel: string, steps: readonly Step[], seg: readonly string[]): OutputKind | null;
203
+ /**
204
+ * The file a job's container writes last: while it is missing the job's outputs don't exist for anyone. The master
205
+ * playlist for a ladder; else the last step's own file. A transcript is written after it (by the Worker).
206
+ */
207
+ export declare function completionFile(steps: readonly Step[]): string;
208
+ export declare const contentTypeOf: (rel: string) => "application/json" | "application/octet-stream" | "image/webp" | "image/jpeg" | "audio/ogg" | "video/mp4" | "application/vnd.apple.mpegurl" | "video/iso.segment" | "text/vtt; charset=utf-8";
209
+ /**
210
+ * The hash a job's outputs are named by: SHA-256 (hex) of `<sourceKey>#<sourceEtag>[#<variant>]`. A new version of the
211
+ * source (another ETag) or another variant (other settings) gets other outputs; the same ones always the same name.
212
+ */
213
+ export declare function sourceHash(sourceKey: string, sourceEtag: string, variant?: string): Promise<string>;
214
+ /** A job request's body is at most this long; so is a report's. */
215
+ export declare const MAX_BODY = 4096;
216
+ /**
217
+ * A job request, as the site sends it (signed: HMAC over the body under the product's job domain).
218
+ * The job's id names its output prefix: one Durable Object (and one container) per id, so a repeated request joins the
219
+ * running job. With the settings version it is the idempotency key.
220
+ */
221
+ export interface JobRequest {
222
+ id: string;
223
+ /** The site's attempt number, echoed in the report (a late report of an older attempt is ignored). */
224
+ attempt: number;
225
+ /** Source key, and the ETag the job is pinned to (a source replaced meanwhile is refused, not transcoded). */
226
+ src: string;
227
+ etag: string;
228
+ bytes: number;
229
+ /** Where the outputs go. */
230
+ prefix: string;
231
+ /** The site's callback URL for the report. */
232
+ done: string;
233
+ /** A capped ladder: the top rung's short side at most this. Absent: the source's size. */
234
+ maxShort?: number;
235
+ /** Absent: the Worker's default steps (so a site from before steps keeps working, byte for byte). */
236
+ steps?: Step[];
237
+ /**
238
+ * When the site signed the request (unix seconds). The Worker refuses a request stamped outside its window (±15 min,
239
+ * JOB_WINDOW_S): a captured request can't be replayed later. Absent: accepted (a site from before the stamp).
240
+ */
241
+ issuedAt?: number;
242
+ /**
243
+ * Seconds the source is known to last, measured by whoever made or checked it (a recorder's own clock, the Mac's
244
+ * probe of the original). The "done" invariant refuses a ladder (and a fast-start copy) shorter than this, as it
245
+ * does against the header's duration: the check that catches a truncated file whose header has no duration (a
246
+ * MediaRecorder WebM). Absent: only the header's duration is checked, as before (the body is byte for byte the same).
247
+ */
248
+ expectDurationS?: number;
249
+ /**
250
+ * A `render` job's sources and edit list (and only a render job's). The job's `src`, `etag` and `bytes` are its
251
+ * first source's; the body may be up to MAX_RENDER_BODY. Absent on every other job (its body is byte for byte what
252
+ * it always was).
253
+ */
254
+ render?: RenderJob;
255
+ }
256
+ /** The longest expected length a job may carry (a week of footage: anything longer is a mistake, not a video). */
257
+ export declare const MAX_EXPECT_DURATION_S: number;
258
+ /** A valid `expectDurationS`: a finite number of seconds, > 0, at most MAX_EXPECT_DURATION_S. */
259
+ export declare const validExpectDuration: (x: unknown) => x is number;
260
+ /** The job's body, its fields always in this order (the signature is over these bytes). */
261
+ export declare function jobBody(j: JobRequest): string;
262
+ export interface DoneReport {
263
+ id: string;
264
+ attempt: number;
265
+ prefix: string;
266
+ state: "done" | "error";
267
+ /** Rungs in the ladder. */
268
+ rungs?: number;
269
+ error?: string;
270
+ /**
271
+ * Why a failed job failed, when known (the runner's RunnerStatus.code): "unsupported" (nothing decodes the source:
272
+ * store it, flag "no preview", don't ask again), "stale-image" (every container ran an older image: a rollout, ask
273
+ * again later without counting a try), "source" (the source couldn't be read or is damaged). Absent: a lost
274
+ * container, a timeout, or a Worker from before the field.
275
+ */
276
+ code?: RunnerStatus["code"];
277
+ /** The settings version the outputs were made with (the container image's): see {@link stampMatches}. */
278
+ ladder?: string;
279
+ /** Seconds: waited for a container, then the container's phases (download, probe, encode, upload); decode passes. */
280
+ timings?: Record<string, number>;
281
+ /**
282
+ * A job with the `transcript` step: whether its transcript was made. A transcript that can't be made doesn't fail the
283
+ * job (its other outputs are done): state "error" and why. Absent for a job without the step.
284
+ */
285
+ transcript?: {
286
+ state: "done" | "error";
287
+ reason?: string;
288
+ };
289
+ /**
290
+ * A job with the `faststart` step and a ladder: whether the fast-start copy was made. A source that can't be remuxed
291
+ * into an MP4 (VP8, ProRes, a RAW plugin's) or a remux that fails doesn't fail the job (the ladder is done): state
292
+ * "skipped" and why, and no faststart.mp4. Absent for a job without the step. (A fast-start-only job fails instead.)
293
+ */
294
+ faststart?: {
295
+ state: "done" | "skipped";
296
+ reason?: string;
297
+ };
298
+ /**
299
+ * The expected length (JobRequest.expectDurationS) the outputs were checked against: echoed only by a runner that
300
+ * enforces it. A job that asked for the check and gets a done without this echo was run by an older image that
301
+ * ignored the field: the Worker never reports that done (it runs the job again), and a site can check it too.
302
+ */
303
+ expectDurationS?: number;
304
+ }
305
+ /**
306
+ * Were these outputs made with the settings the site expects? During a rollout the Worker (and the site) can be new
307
+ * while some containers still run the old image: their outputs are refused and remade, never served.
308
+ */
309
+ export declare const stampMatches: (r: Pick<DoneReport, "ladder">, version: string) => boolean;
310
+ /** The container's answer to GET /status. */
311
+ export interface RunnerStatus {
312
+ state: "idle" | "running" | "done" | "error";
313
+ phase?: string;
314
+ progress: number;
315
+ error?: string;
316
+ /** Why it failed, when the runner knows: "unsupported" (nothing decodes it: stored, flagged no preview),
317
+ * "stale-image" (the Worker refused this image's outputs), "source" (the source couldn't be read), "disk" (the
318
+ * source and the copies the job keeps of it can't fit the runner's free disk: checked before the download). */
319
+ code?: "unsupported" | "stale-image" | "source" | "disk";
320
+ rungs?: number;
321
+ timings?: Record<string, number>;
322
+ /** The settings version this runner makes. */
323
+ ladder?: string;
324
+ /**
325
+ * A job with the `faststart` step and a ladder: whether the fast-start copy was made. A source that can't be remuxed
326
+ * into an MP4 (VP8, ProRes, a RAW plugin's) or a remux that fails doesn't fail the job (the ladder is done): state
327
+ * "skipped" and why, and no faststart.mp4. Absent for a job without the step. (A fast-start-only job fails instead.)
328
+ */
329
+ faststart?: {
330
+ state: "done" | "skipped";
331
+ reason?: string;
332
+ };
333
+ /**
334
+ * The expected length (JobRequest.expectDurationS) the outputs were checked against: echoed only by a runner that
335
+ * enforces it. A job that asked for the check and gets a done without this echo was run by an older image that
336
+ * ignored the field: the Worker never reports that done (it runs the job again), and a site can check it too.
337
+ */
338
+ expectDurationS?: number;
339
+ }
340
+ /**
341
+ * Header a runner that enforces JobRequest.expectDurationS sends on every output of a job that has one: the length it
342
+ * checks against. The gatekeeper refuses outputs of such a job without it (an older image that ignores the field), so
343
+ * nothing it made is stored, completion file included.
344
+ */
345
+ export declare const EXPECT_HEADER = "x-media-expect-duration";
346
+ /** Header the runner sends its settings version in, on every output it writes (the gatekeeper refuses another). */
347
+ export declare const VERSION_HEADER = "x-media-version";
348
+ /** prep's files, under the job's prefix. */
349
+ export declare const PREP_MEDIA = "edit/media.mp4";
350
+ export declare const PREP_PEAKS = "edit/peaks.bin";
351
+ /** Written last: while it is missing the prep doesn't exist for anyone. */
352
+ export declare const PREP_RESULT = "edit/prep.json";
353
+ export declare const prepSheetName: (i: number) => string;
354
+ /** render's files, under the job's prefix. */
355
+ export declare const RENDER_VIDEO = "render/video.mp4";
356
+ export declare const RENDER_POSTER = "render/poster.jpg";
357
+ /** Written last. */
358
+ export declare const RENDER_RESULT = "render/result.json";
359
+ /** The JSON results' format (PrepResult.format, RenderResult.format). */
360
+ export declare const EDIT_RESULT_FORMAT = 1;
361
+ /** What decides prep's outputs (StepSettings.prep; the step settings' version names them). */
362
+ export interface PrepSettings {
363
+ /** The edit-ready file's short side at most this (a job's own `maxShort`, one of the product's caps, lowers it). */
364
+ maxShort: number;
365
+ /** A longer source is refused. */
366
+ maxSeconds: number;
367
+ /** x264 preset and CRF of a converted source; AAC kbps of its sound (48 kHz stereo). */
368
+ preset: string;
369
+ crf: number;
370
+ audioKbps: number;
371
+ /** Filmstrip sheets (the storyboard layout): columns × rows thumbnails, each `tileLongSide` px on its long side. */
372
+ columns: number;
373
+ rows: number;
374
+ tileLongSide: number;
375
+ /** A thumbnail every this many seconds at least, longer so the filmstrip stays within `maxFrames`. */
376
+ minIntervalS: number;
377
+ maxFrames: number;
378
+ /** JPEG quality (FFmpeg's -q:v, 2 best … 31). */
379
+ jpegQ: number;
380
+ /** Waveform buckets per second (peaks.bin: [min, max] signed 8-bit per bucket, mono). */
381
+ peaksRate: number;
382
+ /** One FFmpeg run's limit (the job's own limit is the Worker's jobTimeoutMs). */
383
+ processTimeoutS: number;
384
+ }
385
+ export declare const DEFAULT_PREP: PrepSettings;
386
+ /** What decides render's outputs (StepSettings.render). */
387
+ export interface RenderSettings {
388
+ /** The output's short side at most this (an edit list's own `output.maxShort` lowers it). */
389
+ maxShort: number;
390
+ /** Limits on an edit list (each within RENDER_LIMITS). */
391
+ maxParts: number;
392
+ maxSources: number;
393
+ maxSeconds: number;
394
+ /** A shorter part is refused. */
395
+ minPartMs: number;
396
+ preset: string;
397
+ crf: number;
398
+ audioKbps: number;
399
+ /** The poster's width at most this. */
400
+ posterWidth: number;
401
+ /** One part's encode limit (and the join's). */
402
+ partTimeoutS: number;
403
+ }
404
+ export declare const DEFAULT_RENDER: RenderSettings;
405
+ /** Hard limits whatever the settings say (an edit list is hostile input until checked). */
406
+ export declare const RENDER_LIMITS: {
407
+ readonly parts: 500;
408
+ readonly sources: 100;
409
+ readonly seconds: number;
410
+ readonly frame: 8192;
411
+ readonly fps: 120;
412
+ };
413
+ /** A render job's body may be this long (any other job's: MAX_BODY). */
414
+ export declare const MAX_RENDER_BODY: number;
415
+ /** prep's settings with every default filled in, each bounded to what the runner can make. */
416
+ export declare function prepSettingsOf(ss: Pick<StepSettings, "prep"> | undefined): PrepSettings;
417
+ /** render's settings with every default filled in, each within RENDER_LIMITS. */
418
+ export declare function renderSettingsOf(ss: Pick<StepSettings, "render"> | undefined): RenderSettings;
419
+ /** The filmstrip's thumbnail interval (seconds) for a source this long: at least minIntervalS, at most maxFrames. */
420
+ export declare const filmstripInterval: (seconds: number, s: Pick<PrepSettings, "minIntervalS" | "maxFrames">) => number;
421
+ /** peaks.bin's size for a source this long: two signed bytes per bucket. */
422
+ export declare const peaksBytes: (seconds: number, rate: number) => number;
423
+ /** edit/prep.json. */
424
+ export interface PrepResult {
425
+ format: typeof EDIT_RESULT_FORMAT;
426
+ /** true: the edit-ready file is edit/media.mp4; false: the source already was one (use it as it is). */
427
+ converted: boolean;
428
+ media: typeof PREP_MEDIA | null;
429
+ durationMs: number;
430
+ /** The edit-ready picture's size (as displayed) and nominal rate. */
431
+ width: number;
432
+ height: number;
433
+ fps: number;
434
+ hasAudio: boolean;
435
+ /** The edit-ready file's size: edit/media.mp4's, or the source's. */
436
+ bytes: number;
437
+ filmstrip: {
438
+ interval: number;
439
+ count: number;
440
+ columns: number;
441
+ rows: number;
442
+ tileWidth: number;
443
+ tileHeight: number;
444
+ sheets: string[];
445
+ };
446
+ /** Waveform: signed 8-bit [min, max] per bucket, `rate` buckets a second, mono. null: no sound. */
447
+ peaks: {
448
+ file: typeof PREP_PEAKS;
449
+ rate: number;
450
+ buckets: number;
451
+ } | null;
452
+ }
453
+ /**
454
+ * Is this a prep.json these settings could have made, for this job (its source's size, its cap)? The reason it isn't,
455
+ * or null. (The gatekeeper's check.)
456
+ */
457
+ export declare function prepResultProblem(r: unknown, s: PrepSettings, job?: {
458
+ bytes: number;
459
+ maxShort?: number;
460
+ }): string | null;
461
+ /** A rectangle in pixels. */
462
+ export interface EditRect {
463
+ x: number;
464
+ y: number;
465
+ width: number;
466
+ height: number;
467
+ }
468
+ /** One part: [inMs, outMs) of a source (its index in RenderJob.sources), as displayed (a phone clip turned upright). */
469
+ export interface EditPart {
470
+ source: number;
471
+ inMs: number;
472
+ outMs: number;
473
+ /** Silence instead of the part's sound. */
474
+ muted?: true;
475
+ /** A crop of the part's picture (in its source's displayed pixels), before it is fitted into the output frame. */
476
+ crop?: EditRect;
477
+ }
478
+ /**
479
+ * An edit list, version 1. Every part is fitted inside the output frame (black bars, never stretched), then the
480
+ * whole-video `crop` (in output-frame pixels) is applied, then the resolution cap (the short side at most
481
+ * `maxShort`, and at most the product's RenderSettings.maxShort). The output runs at `fps`; frame k is at k / fps, so
482
+ * the total is within one frame of the parts' summed length.
483
+ */
484
+ export interface EditList {
485
+ version: 1;
486
+ output: {
487
+ width: number;
488
+ height: number;
489
+ fps: number;
490
+ crop?: EditRect;
491
+ maxShort?: number;
492
+ };
493
+ parts: EditPart[];
494
+ }
495
+ export declare const EDIT_LIST_VERSION = 1;
496
+ /** One source of a render: its key, the ETag it is pinned to (a source replaced meanwhile is refused) and its size. */
497
+ export interface RenderSource {
498
+ src: string;
499
+ etag: string;
500
+ bytes: number;
501
+ }
502
+ export interface RenderJob {
503
+ sources: RenderSource[];
504
+ editList: EditList;
505
+ }
506
+ /** A render job's fields in a fixed order (the signature is over these bytes). */
507
+ export declare function renderBody(r: RenderJob): RenderJob;
508
+ /**
509
+ * Check a render job (hostile until checked): its shape (no unknown fields), the edit list's version and limits, every
510
+ * part's source and times, every crop. The site checks before it signs; the Worker and the container check again.
511
+ */
512
+ export declare function parseRenderJob(x: unknown, s?: RenderSettings): {
513
+ job: RenderJob;
514
+ } | {
515
+ error: string;
516
+ };
517
+ /** The edit list's length (ms): the parts' summed length. */
518
+ export declare const editListMs: (e: Pick<EditList, "parts">) => number;
519
+ /**
520
+ * Frames each part gets on the output clock: frame k is at k / fps, a part owns the frames whose time falls in its
521
+ * span (at least one), so the total is within one frame of the edit list.
522
+ */
523
+ export declare function renderFrames(e: Pick<EditList, "parts" | "output">): number[];
524
+ /** The sound's rate: 48 kHz. */
525
+ export declare const RENDER_SAMPLE_RATE = 48000;
526
+ /** 48 kHz samples each part's sound gets, rounded cumulatively so the total is exact. */
527
+ export declare function renderSamples(e: Pick<EditList, "parts">): number[];
528
+ /** The output's size: the output frame (or its crop) with the short side at most the cap; even sides. */
529
+ export declare function renderFrame(e: Pick<EditList, "output">, s?: Pick<RenderSettings, "maxShort">): {
530
+ width: number;
531
+ height: number;
532
+ };
533
+ /** render/result.json. */
534
+ export interface RenderResult {
535
+ format: typeof EDIT_RESULT_FORMAT;
536
+ /** The picture's length: frames / fps (within one frame of the edit list). */
537
+ durationMs: number;
538
+ frames: number;
539
+ fps: number;
540
+ /** The sound's length in 48 kHz samples (exactly the edit list's). */
541
+ samples: number;
542
+ width: number;
543
+ height: number;
544
+ /** render/video.mp4's size. */
545
+ bytes: number;
546
+ parts: number;
547
+ }
548
+ /** Is this a result.json of this very edit list? The reason it isn't, or null. (The gatekeeper's check.) */
549
+ export declare function renderResultProblem(r: unknown, e: EditList, s: RenderSettings): string | null;
550
+ /** A render's identity: SHA-256 (hex) of its body. Two renders of the same sources and edit list are the same job. */
551
+ export declare function renderHash(r: RenderJob): Promise<string>;
552
+ /**
553
+ * A render's fingerprint, synchronously (FNV-1a, 64 bits, hex, of its body): part of the Worker's job key, so a new
554
+ * edit list for the same prefix is a new job. Not a security boundary (every request is signed); renderHash names things.
555
+ */
556
+ export declare function renderKey(r: RenderJob): string;