@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,195 @@
1
+ /**
2
+ * Embed code and guides: the player options an embed's URL asks for (autoplay, loop, controls, start…), the presets offered beside
3
+ * the code, what chrome the player shows, the embed URLs and the copy-paste snippets (the responsive <iframe> and a plain
4
+ * <video> tag). Pure, so the embed page, the code generators and the tests share one copy. Each product serves its own
5
+ * embed routes on its own host (`base`); the path layout defaults to /e/<id>, /e/<id>/video.mp4 and /e/<id>/poster.jpg
6
+ * and can be changed with `paths`. Moved from UploadFilm's shared/embedCode.ts, output unchanged.
7
+ *
8
+ * One self-contained module (no imports): UploadFilm's shared/embedCode.ts re-exports it by file path, and plain Node
9
+ * test loaders load it without a bundler.
10
+ */
11
+ export interface EmbedOptions {
12
+ /** Start playing on load. Browsers only allow that muted, so autoplay implies muted (unless `autoplaySound`). */
13
+ autoplay: boolean;
14
+ muted: boolean;
15
+ /**
16
+ * Opt-in (`autoplay=1&muted=0`): try to autoplay WITH sound. That only works where the host page had a user
17
+ * click that the iframe's allow="autoplay" carries into it (Chrome; e.g. a drawer the visitor just opened).
18
+ * Otherwise (Safari almost always) the player falls back to muted autoplay. Needs autoplay and the full
19
+ * player (not controls=0 / background); `muted` is false when it's on.
20
+ */
21
+ autoplaySound: boolean;
22
+ loop: boolean;
23
+ /** Show the browser's controls. Off for background/hero videos. */
24
+ controls: boolean;
25
+ /** Start at this many seconds. */
26
+ start: number;
27
+ /** Show the file name over the poster before playing. */
28
+ title: boolean;
29
+ /**
30
+ * The big round play button over the poster until the first play (`bigplay=0|1`). On by default;
31
+ * it only shows when the video isn't autoplaying (or reduced motion stopped it).
32
+ */
33
+ bigPlay: boolean;
34
+ /**
35
+ * The control bar of the full player (`bar=0|1`; ignored with controls=0). null (no `bar` param) is
36
+ * automatic: hidden until the first play while the big play button is up, then as the skin shows it.
37
+ * true keeps it visible from the start, false never shows it (keyboard and click still work).
38
+ */
39
+ bar: boolean | null;
40
+ }
41
+ export declare const DEFAULT_EMBED_OPTIONS: EmbedOptions;
42
+ /** The player styles offered beside the code. */
43
+ export declare const EMBED_PRESETS: {
44
+ key: string;
45
+ label: string;
46
+ opts: EmbedOptions;
47
+ }[];
48
+ /**
49
+ * What the player shows right now. The big play button: wanted, nothing played yet, and not autoplaying (unless
50
+ * reduced motion stopped it). The control bar of the full player is hidden by bar=0, or while it waits for the
51
+ * first play behind the big button (bar unset); bar=1 keeps it.
52
+ */
53
+ export declare function playerChrome(o: Pick<EmbedOptions, "autoplay" | "controls" | "bigPlay" | "bar">, s: {
54
+ started: boolean;
55
+ reducedMotion: boolean;
56
+ }): {
57
+ bigPlay: boolean;
58
+ hideBar: boolean;
59
+ };
60
+ /**
61
+ * Query → options. `background=1` is the hero-video preset (autoplay, muted, loop, no controls, no
62
+ * title). `t` accepts seconds ("90") or "1m30s".
63
+ */
64
+ export declare function parseEmbedOptions(q: URLSearchParams): EmbedOptions;
65
+ /** Seconds ("90", "12.5") or "1h2m3s" → seconds, capped at a week; anything else is 0. */
66
+ export declare function parseStart(v: string | null | undefined): number;
67
+ /** Options → the shortest query that means them (defaults left out), "" when everything is default. */
68
+ export declare function embedOptionsQuery(o: EmbedOptions): string;
69
+ /** Top-left of a menu opened at (x, y), kept fully on screen with `margin` to spare (an embed can be tiny). */
70
+ export declare function menuPosition(at: {
71
+ x: number;
72
+ y: number;
73
+ }, menu: {
74
+ w: number;
75
+ h: number;
76
+ }, view: {
77
+ w: number;
78
+ h: number;
79
+ }, margin?: number): {
80
+ x: number;
81
+ y: number;
82
+ };
83
+ /** Where an embed's player page, video file and poster live under a product's host. */
84
+ export interface EmbedPaths {
85
+ player: (embedId: string) => string;
86
+ video: (embedId: string) => string;
87
+ poster: (embedId: string) => string;
88
+ }
89
+ export declare const DEFAULT_EMBED_PATHS: EmbedPaths;
90
+ export declare const playerUrl: (base: string, embedId: string, o?: EmbedOptions, paths?: EmbedPaths) => string;
91
+ export declare const videoUrl: (base: string, embedId: string, paths?: EmbedPaths) => string;
92
+ export declare const posterUrl: (base: string, embedId: string, paths?: EmbedPaths) => string;
93
+ /**
94
+ * The embed id in a player link's path (/e/<id>, a trailing slash allowed), or null when the path is anything else or
95
+ * the id fails `isId` (each product decides its ids' shape).
96
+ */
97
+ export declare function embedIdOfPath(pathname: string, isId: RegExp | ((id: string) => boolean), prefix?: string): string | null;
98
+ /** HTML attribute escaping (&, ", <, >). */
99
+ export declare const escapeAttr: (s: string) => string;
100
+ /** Width ÷ height of what plays, from the proxy (or the original's displayed size). 16:9 when unknown. */
101
+ export declare function aspectOf(w: number | undefined, h: number | undefined): {
102
+ w: number;
103
+ h: number;
104
+ };
105
+ /** What the iframe may do: autoplay, fullscreen, picture-in-picture, protected media. */
106
+ export declare const IFRAME_ALLOW = "autoplay; fullscreen; picture-in-picture; encrypted-media";
107
+ /**
108
+ * The responsive iframe: fills its container's width at the video's own aspect ratio (vertical phone
109
+ * clips stay vertical), with fullscreen and picture-in-picture allowed.
110
+ */
111
+ export declare function iframeSnippet(base: string, embedId: string, o: EmbedOptions, size: {
112
+ w: number;
113
+ h: number;
114
+ }, title: string, paths?: EmbedPaths): string;
115
+ /** A plain <video> tag on the file URL, for site builders that want their own player (or none). */
116
+ export declare function videoSnippet(base: string, embedId: string, o: EmbedOptions, size: {
117
+ w: number;
118
+ h: number;
119
+ }, paths?: EmbedPaths): string;
120
+ /** Above this an original is too heavy for someone's website by default: embeds wait for a lighter rendition. */
121
+ export declare const EMBED_ORIGINAL_MAX_BPS = 20000000;
122
+ export type PlayableFile = {
123
+ kind: string;
124
+ name: string;
125
+ mime: string;
126
+ media?: {
127
+ videoCodec?: string;
128
+ pixFmt?: string;
129
+ bitrate?: number;
130
+ };
131
+ };
132
+ /** An original every browser plays as it is: H.264 8-bit 4:2:0 in an mp4/mov. */
133
+ export declare function originalPlayable(f: PlayableFile): boolean;
134
+ /** An original an embed may play before a lighter rendition is up: every browser plays it, and it's light enough to stream. */
135
+ export declare const embedPlaysOriginal: (f: PlayableFile, opts?: {
136
+ maxBps?: number;
137
+ }) => boolean;
138
+ /** The product hosting the video, as the guides name it. */
139
+ export interface EmbedProvider {
140
+ /** "It's hosted on <name>". */
141
+ name: string;
142
+ /** What the video file is, in "the video file (<fileLabel>) is: …". Default "MP4". */
143
+ fileLabel?: string;
144
+ /**
145
+ * Where the video file redirects (signed storage URLs), so a <video> tag under a Content-Security-Policy needs it in
146
+ * media-src too. `label` names the storage ("Cloudflare R2"), `hosts` is the CSP source list.
147
+ */
148
+ fileStorage?: {
149
+ label: string;
150
+ hosts: string;
151
+ };
152
+ /** The embed path layout, when it isn't /e/<id>. */
153
+ paths?: EmbedPaths;
154
+ }
155
+ export interface EmbedContext {
156
+ base: string;
157
+ embedId: string;
158
+ opts: EmbedOptions;
159
+ size: {
160
+ w: number;
161
+ h: number;
162
+ };
163
+ title: string;
164
+ provider: EmbedProvider;
165
+ }
166
+ export interface GuideStep {
167
+ title: string;
168
+ description?: string;
169
+ /** Something to paste: the AI prompt, the embed code or a link. */
170
+ code?: string;
171
+ /** What `code` is, for its copy button and label. */
172
+ kind?: "prompt" | "code" | "link";
173
+ }
174
+ export type GuideGroup = "ai" | "builder";
175
+ export interface Platform {
176
+ id: string;
177
+ name: string;
178
+ group: GuideGroup;
179
+ }
180
+ export declare const PLATFORMS: Platform[];
181
+ /**
182
+ * Self-contained instructions for a coding assistant or AI site builder: what the video is, the exact
183
+ * snippet, how to keep it responsive, and how to translate it to JSX without breaking the player.
184
+ */
185
+ export declare function aiPrompt(c: EmbedContext): string;
186
+ /** The steps for one platform. Unknown ids fall back to plain HTML. */
187
+ export declare function guideFor(platform: string, c: EmbedContext): GuideStep[];
188
+ /** For "Open in ChatGPT / Claude": a link that starts a chat with the prompt typed in. */
189
+ export declare const chatUrl: (to: "chatgpt" | "claude", prompt: string) => string;
190
+ /** What a menu pick copies (the step with something to paste) and the line shown after it. */
191
+ export declare function pickFor(platform: string, c: EmbedContext): {
192
+ text: string;
193
+ kind: NonNullable<GuideStep["kind"]>;
194
+ hint: string;
195
+ };
@@ -0,0 +1,4 @@
1
+ /** Every message of the embed control API carries this `source` (./protocol.ts). */
2
+ export declare const EMBED_API_SOURCE = "uploadfilm";
3
+ /** Bumped only when a message changes meaning; added fields and actions don't. */
4
+ export declare const EMBED_API_VERSION = 1;
@@ -0,0 +1,62 @@
1
+ /** What the host knows of the player, as last reported. */
2
+ export interface EmbedControllerState {
3
+ currentTime: number;
4
+ duration: number;
5
+ paused: boolean;
6
+ muted: boolean;
7
+ }
8
+ export type EmbedControllerEvent = "ready" | "play" | "pause" | "ended" | "timeupdate" | "volumechange";
9
+ type Handler = (this: EmbedController, state: EmbedControllerState) => void;
10
+ interface MessageLike {
11
+ source: unknown;
12
+ data: unknown;
13
+ }
14
+ interface WindowLike {
15
+ addEventListener(type: "message", fn: (e: MessageLike) => void): void;
16
+ removeEventListener(type: "message", fn: (e: MessageLike) => void): void;
17
+ }
18
+ /** The embed's <iframe> (anything with a contentWindow and load events). */
19
+ export interface EmbedFrame {
20
+ readonly contentWindow: {
21
+ postMessage(message: unknown, targetOrigin: string): void;
22
+ } | null;
23
+ addEventListener(type: "load", fn: () => void): void;
24
+ removeEventListener(type: "load", fn: () => void): void;
25
+ }
26
+ type Msg = {
27
+ [k: string]: unknown;
28
+ };
29
+ export declare class EmbedController {
30
+ iframe: EmbedFrame;
31
+ /** The player answered and has a video to command: commands go straight to it. */
32
+ ready: boolean;
33
+ state: EmbedControllerState;
34
+ _queue: Msg[];
35
+ _handlers: {
36
+ [event: string]: Handler[];
37
+ };
38
+ _doc: unknown;
39
+ _stale: unknown;
40
+ _readyDoc: unknown;
41
+ _root: WindowLike;
42
+ _onMessage: (e: MessageLike) => void;
43
+ _onLoad: () => void;
44
+ _observer?: {
45
+ disconnect(): void;
46
+ };
47
+ constructor(iframe: EmbedFrame);
48
+ /** The constructor's work, callable on an object made by the <script> build's `UploadFilm.Player` (with or without new). */
49
+ _init(iframe: EmbedFrame, root: WindowLike): void;
50
+ _send(msg: Msg): void;
51
+ _command(msg: Msg): this;
52
+ _emit(event: string): void;
53
+ play(): this;
54
+ pause(): this;
55
+ mute(): this;
56
+ unmute(): this;
57
+ seek(seconds: number): this;
58
+ on(event: EmbedControllerEvent, fn: Handler): this;
59
+ off(event: EmbedControllerEvent, fn: Handler): this;
60
+ destroy(): void;
61
+ }
62
+ export {};
@@ -0,0 +1,32 @@
1
+ /**
2
+ * <uploadfilm-player>: an embed as one element. It renders the responsive iframe (the same frame as iframeSnippet:
3
+ * full width at the video's aspect ratio, autoplay/fullscreen/picture-in-picture allowed) and drives it with the control
4
+ * API (./controller.ts), so a page can call play(), pause(), seek() on the element and listen for its events.
5
+ *
6
+ * import { defineEmbedElement } from "@uploadfilm/sdk/player";
7
+ * defineEmbedElement(); // once, in the browser
8
+ *
9
+ * <uploadfilm-player src="https://<host>/e/<id>?title=0" width="1920" height="1080" title="Reel"></uploadfilm-player>
10
+ * el.play(); el.seek(12.5); el.addEventListener("ended", (e) => e.detail.currentTime);
11
+ *
12
+ * Events (CustomEvent, detail = the state): ready, play, pause, ended, timeupdate, volumechange. Commands given before
13
+ * the element is in the page wait for it (and then for the player, like the controller's). Nothing is registered at
14
+ * import (the package is side-effect free): call defineEmbedElement().
15
+ */
16
+ import { type EmbedControllerState } from "./controller";
17
+ export declare const EMBED_ELEMENT_TAG = "uploadfilm-player";
18
+ /** What <uploadfilm-player> offers besides HTMLElement's own members. */
19
+ export interface EmbedElement extends HTMLElement {
20
+ readonly ready: boolean;
21
+ readonly state: EmbedControllerState;
22
+ readonly iframe: HTMLIFrameElement;
23
+ play(): this;
24
+ pause(): this;
25
+ mute(): this;
26
+ unmute(): this;
27
+ seek(seconds: number): this;
28
+ }
29
+ /** An http(s) URL for the iframe (resolved against the page), or null for anything else: javascript:, data:, blob:… */
30
+ export declare function embedSrc(value: string | null): string | null;
31
+ /** Registers <uploadfilm-player> (or `tag`) once; a no-op outside a browser or when it's already defined. */
32
+ export declare function defineEmbedElement(tag?: string): void;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The frame side of the embed control API: the embed page (inside the iframe) answers the page around it. The host side
3
+ * is ./controller.ts (`new UploadFilm.Player(iframe)`, <uploadfilm-player>); the messages are ./protocol.ts. Without
4
+ * this, every product wrote the command handler and the event posting itself (ClipMe adoption, gap 9).
5
+ *
6
+ * const control = serveEmbedControl(player, { embedId: "abc123" }); // player: createPlayer(…) / usePlayer().player
7
+ * control.ready(); // when a video becomes commandable later (a processing page that finished)
8
+ * control.stop(); // on unmount
9
+ *
10
+ * The behaviour is UploadFilm's embed page's (web/app/e/[eid]/EmbedPlayer.tsx controlApi): it listens to its parent
11
+ * only; it says "ready" once per load of the page (`doc`), and again when `ready()` finds a video to command; a command
12
+ * that arrives while there's nothing to command (no element yet, or `playable()` false) is answered with "state", so
13
+ * the host keeps it until "ready" says playable; "state" is always answered; play, pause, ended, volumechange are
14
+ * forwarded, timeupdate at most every EMBED_TIMEUPDATE_MS. The engine's commands keep the viewer's intent (a pause
15
+ * during a recovery holds, a play aborted by a source load is retried).
16
+ */
17
+ import { type EmbedCommand, type EmbedEventName } from "./protocol";
18
+ /** The engine calls the frame side makes (a `Player` from createPlayer fits). */
19
+ export interface EmbedResponderPlayer {
20
+ readonly element: HTMLVideoElement | null;
21
+ play(): Promise<unknown>;
22
+ pause(): void;
23
+ seek(t: number): void;
24
+ setMuted(m: boolean): void;
25
+ on(event: "play" | "pause" | "ended" | "volumechange" | "timeupdate" | "sourcechange", cb: () => void): () => void;
26
+ }
27
+ /** The embed page's window, as the frame side uses it. */
28
+ export interface EmbedFrameWindow {
29
+ parent: {
30
+ postMessage(message: unknown, targetOrigin: string): void;
31
+ };
32
+ addEventListener(type: "message", f: (e: MessageEvent) => void): void;
33
+ removeEventListener(type: "message", f: (e: MessageEvent) => void): void;
34
+ }
35
+ export type EmbedAction = Exclude<EmbedCommand, {
36
+ action: "state";
37
+ }>;
38
+ export interface EmbedResponderOptions {
39
+ /** The embed's id, reported in every message (`embed`): the host matches its iframe by it. */
40
+ embedId: string;
41
+ /** This load of the page. Default: a random id. */
42
+ doc?: string;
43
+ /** Default: `window` (inside the iframe). */
44
+ win?: EmbedFrameWindow;
45
+ /**
46
+ * There is a video to command (false while processing, gone). Default: the player has an element. A page whose video
47
+ * mounts later (a poster first) says true here as soon as it has one to play: commands then run on the engine, which
48
+ * keeps them until its element attaches (a play starts it, a seek and a mute apply to it), or go to `onCommand`.
49
+ */
50
+ playable?: () => boolean;
51
+ /**
52
+ * Run a command yourself: return true when handled (e.g. a play that presses the page's own big button, which mounts
53
+ * the player). Anything else runs on the engine.
54
+ */
55
+ onCommand?: (c: EmbedAction) => boolean | void;
56
+ now?: () => number;
57
+ }
58
+ /** The element events forwarded to the host. */
59
+ export declare const EMBED_FORWARDED: readonly EmbedEventName[];
60
+ /** Run one command on the engine (what serveEmbedControl does after `onCommand` declines it). */
61
+ export declare function runEmbedCommand(player: EmbedResponderPlayer, c: EmbedAction): void;
62
+ export declare function serveEmbedControl(player: EmbedResponderPlayer, o: EmbedResponderOptions): {
63
+ ready(): void;
64
+ stop(): void;
65
+ };
@@ -0,0 +1,14 @@
1
+ /** The script's own global (./loader.ts). */
2
+ export declare const DEFAULT_EMBED_GLOBAL = "UploadFilm";
3
+ export declare function assertGlobalName(name: string): void;
4
+ /**
5
+ * The embed script (PLAYER_SCRIPT, or dist/embed/player.js) defining `<name>.Player` instead of `UploadFilm.Player`.
6
+ * The built script runs unchanged inside; whatever a page already had on `UploadFilm` (and on `<name>`) is kept, and no
7
+ * `UploadFilm` global is left behind by this script. `name` "UploadFilm": the script as it is.
8
+ */
9
+ export declare function renameEmbedGlobal(script: string, name: string): string;
10
+ /**
11
+ * Define `<name>.Player(iframe)` (with or without `new`) on `root` (default: window): the same constructor the script
12
+ * defines, for an app that bundles the player from npm. Keeps whatever else is on `<name>`.
13
+ */
14
+ export declare function definePlayerGlobal(name?: string, root?: object): void;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Embeds: player options from the embed URL, the copy-paste snippets and "add it to your site" guides, oEmbed, the
3
+ * postMessage control API (protocol + host-side controller), and <uploadfilm-player>. The <script> build of the
4
+ * controller is ./loader.ts (served by `@uploadfilm/sdk/server`'s servePlayerScript()). The embed page's own half of the
5
+ * control API is ./frame.ts (serveEmbedControl); ./global.ts names the script's global after a product.
6
+ */
7
+ export { DEFAULT_EMBED_OPTIONS, EMBED_PRESETS, embedOptionsQuery, menuPosition, parseEmbedOptions, parseStart, playerChrome, type EmbedOptions, } from "./code";
8
+ export { DEFAULT_EMBED_PATHS, EMBED_ORIGINAL_MAX_BPS, IFRAME_ALLOW, aspectOf, embedIdOfPath, embedPlaysOriginal, escapeAttr, iframeSnippet, originalPlayable, playerUrl, posterUrl, videoSnippet, videoUrl, type EmbedPaths, type PlayableFile, } from "./code";
9
+ export { PLATFORMS, aiPrompt, chatUrl, guideFor, pickFor, type EmbedContext, type EmbedProvider, type GuideGroup, type GuideStep, type Platform, } from "./code";
10
+ export { buildOEmbed, oembedDiscoveryUrl, oembedSize, parseOEmbedRequest, type OEmbedRequest, type OEmbedResponse, type OEmbedVideo, } from "./oembed";
11
+ export { EMBED_API_SOURCE, EMBED_API_VERSION, EMBED_TIMEUPDATE_MS, embedMessage, parseEmbedCommand, type EmbedCommand, type EmbedEventName, type EmbedMessage, type EmbedPlayerState, } from "./protocol";
12
+ export { EmbedController, type EmbedControllerEvent, type EmbedControllerState, type EmbedFrame } from "./controller";
13
+ export { EMBED_FORWARDED, runEmbedCommand, serveEmbedControl, type EmbedAction, type EmbedFrameWindow, type EmbedResponderOptions, type EmbedResponderPlayer, } from "./frame";
14
+ export { DEFAULT_EMBED_GLOBAL, assertGlobalName, definePlayerGlobal, renameEmbedGlobal } from "./global";
15
+ export { EMBED_ELEMENT_TAG, defineEmbedElement, embedSrc, type EmbedElement } from "./element";
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,74 @@
1
+ /**
2
+ * oEmbed (https://oembed.com) for embed player links: GET <oembed endpoint>?url=<player link>[&maxwidth&maxheight]
3
+ * → { type: "video", html: <the responsive iframe>, … }. JSON only; the player link's options (autoplay, loop…) carry
4
+ * into the iframe. Pure: a product's route parses the request with parseOEmbedRequest, looks the embed up its own way,
5
+ * and answers with buildOEmbed. Moved from UploadFilm's web/app/api/oembed/route.ts, JSON unchanged.
6
+ */
7
+ import { type EmbedOptions } from "./code";
8
+ import { type EmbedPaths } from "./code";
9
+ /** What the route answers before any lookup: an error (status + JSON body), or the embed asked about. */
10
+ export type OEmbedRequest = {
11
+ ok: false;
12
+ status: 400 | 404 | 501;
13
+ body: {
14
+ error: string;
15
+ } | string;
16
+ } | {
17
+ ok: true;
18
+ embedId: string;
19
+ opts: EmbedOptions;
20
+ maxwidth: number;
21
+ maxheight: number;
22
+ };
23
+ /**
24
+ * Reads an oEmbed request's query. `isId` is the product's embed id shape; `prefix` the player path's (default "/e/").
25
+ * 501 "Only JSON." for another format, 400 without a parsable url, 404 when it isn't a player link.
26
+ */
27
+ export declare function parseOEmbedRequest(q: URLSearchParams, isId: RegExp | ((id: string) => boolean), opts?: {
28
+ prefix?: string;
29
+ providerName?: string;
30
+ }): OEmbedRequest;
31
+ /** The size an oEmbed answer reports: 640 wide by default (YouTube's), capped by maxwidth/maxheight, aspect kept. */
32
+ export declare function oembedSize(aspect: {
33
+ w: number;
34
+ h: number;
35
+ }, maxwidth?: number, maxheight?: number): {
36
+ width: number;
37
+ height: number;
38
+ };
39
+ export interface OEmbedVideo {
40
+ /** The product (`provider_name`) and its site (`provider_url`, also the base of every URL). */
41
+ providerName: string;
42
+ base: string;
43
+ embedId: string;
44
+ title: string;
45
+ /** The video's size (any units; only its aspect counts). */
46
+ size: {
47
+ w: number;
48
+ h: number;
49
+ };
50
+ /** The player options from the link (parseOEmbedRequest). */
51
+ opts: EmbedOptions;
52
+ /** It has a poster: thumbnail_url is the embed's poster. */
53
+ thumbnail: boolean;
54
+ maxwidth?: number;
55
+ maxheight?: number;
56
+ paths?: EmbedPaths;
57
+ }
58
+ export interface OEmbedResponse {
59
+ version: "1.0";
60
+ type: "video";
61
+ provider_name: string;
62
+ provider_url: string;
63
+ title: string;
64
+ width: number;
65
+ height: number;
66
+ html: string;
67
+ thumbnail_url?: string;
68
+ thumbnail_width?: number;
69
+ thumbnail_height?: number;
70
+ }
71
+ /** The oEmbed JSON for one embed. */
72
+ export declare function buildOEmbed(v: OEmbedVideo): OEmbedResponse;
73
+ /** The oEmbed discovery link a player page puts in its <head> (application/json+oembed). */
74
+ export declare const oembedDiscoveryUrl: (endpoint: string, playerLink: string) => string;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The embed control API's messages: the page around an embed (window.parent) drives the player with postMessage, and
3
+ * the player reports what it does, so a site can play, pause or seek a player without reloading its iframe.
4
+ *
5
+ * Messages to the player: { source: "uploadfilm", action: "play" | "pause" | "mute" | "unmute" | "seek" | "state", time? }
6
+ * Messages from the player: { source: "uploadfilm", version: 1, event: "ready" | "play" | "pause" | "ended" | "timeupdate" |
7
+ * "state" | "volumechange", embed, doc, playable, currentTime, duration, paused, muted }
8
+ * `doc` names one load of the embed page (a reload, or a new src, is a new doc): the page emits "ready" once per doc.
9
+ * `playable`: there is a video to command (false while it's still processing or gone): the host keeps its commands
10
+ * until it is.
11
+ *
12
+ * Any page may control an embed it holds (as with YouTube's and Vimeo's embeds); what the player reports is its own
13
+ * playback state, nothing private. The host side is ./controller.ts (also the <script> build, ./loader.ts). Moved from
14
+ * UploadFilm's web/lib/embedApi.ts, messages unchanged (API version 1).
15
+ */
16
+ import { EMBED_API_SOURCE, EMBED_API_VERSION } from "./constants";
17
+ export { EMBED_API_SOURCE, EMBED_API_VERSION };
18
+ export type EmbedCommand = {
19
+ action: "play";
20
+ } | {
21
+ action: "pause";
22
+ } | {
23
+ action: "mute";
24
+ } | {
25
+ action: "unmute";
26
+ } | {
27
+ action: "seek";
28
+ time: number;
29
+ } | {
30
+ action: "state";
31
+ };
32
+ /**
33
+ * A command from the host page, or null for anything else (other scripts' messages, malformed ones). Never throws on
34
+ * structured-clone data (what postMessage delivers): fuzzed in test/embed-api.
35
+ */
36
+ export declare function parseEmbedCommand(data: unknown): EmbedCommand | null;
37
+ export type EmbedEventName = "ready" | "play" | "pause" | "ended" | "timeupdate" | "state" | "volumechange";
38
+ /** The player's state, as the embed page reads it off its <video>. */
39
+ export interface EmbedPlayerState {
40
+ /** This load of the embed page. */
41
+ doc: string;
42
+ /** A video is there to command. */
43
+ playable: boolean;
44
+ currentTime: number;
45
+ duration: number;
46
+ paused: boolean;
47
+ muted: boolean;
48
+ }
49
+ /** What the embed page posts to its parent. */
50
+ export interface EmbedMessage {
51
+ source: typeof EMBED_API_SOURCE;
52
+ version: typeof EMBED_API_VERSION;
53
+ event: EmbedEventName;
54
+ embed: string;
55
+ doc: string;
56
+ playable: boolean;
57
+ currentTime: number;
58
+ duration: number;
59
+ paused: boolean;
60
+ muted: boolean;
61
+ }
62
+ export declare function embedMessage(event: EmbedEventName, embed: string, s: EmbedPlayerState): EmbedMessage;
63
+ /** timeupdate is sent at most this often (the media element fires it ~4 times a second). */
64
+ export declare const EMBED_TIMEUPDATE_MS = 1000;