@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,68 @@
1
+ /**
2
+ * Detecting the profile in Node (the Mac app's main process, a server, a container, a self-hosted media runner).
3
+ *
4
+ * Every OS touch point is an injected dependency (`NodeHostDeps`), so each environment is tested with fakes. The real
5
+ * ones live in ./node (`nodeHostDeps`, `createNodeHostProbe`), the only file that imports node:*: this module and
6
+ * everything reachable from ./index stay bundleable for a browser or a Worker.
7
+ *
8
+ * Static facts (CPU model and cores, total memory, encoders) are read once; `refresh()` re-reads only what changes
9
+ * (power, thermal, load, memory pressure, disk, network interface), cheaply enough to call every few seconds.
10
+ */
11
+ import { type HostGlobals } from "./environment";
12
+ import { type Run } from "./encoders";
13
+ import type { HostProfile } from "./types";
14
+ /** Electron's powerMonitor, or anything shaped like it (only the methods used here). */
15
+ export interface PowerMonitorLike {
16
+ isOnBatteryPower?(): boolean;
17
+ /** macOS: "unknown" | "nominal" | "fair" | "serious" | "critical". */
18
+ getCurrentThermalState?(): string;
19
+ }
20
+ export interface NodeHostDeps {
21
+ platform: string;
22
+ arch?: string;
23
+ /** os.availableParallelism() (falls back to os.cpus().length). */
24
+ parallelism(): number;
25
+ cpuModel?(): string | undefined;
26
+ /** os.loadavg() */
27
+ loadavg(): number[];
28
+ totalmem(): number;
29
+ freemem(): number;
30
+ run: Run;
31
+ /** Contents, or undefined when unreadable/missing. */
32
+ readFile(path: string): Promise<string | undefined>;
33
+ exists(path: string): Promise<boolean>;
34
+ readdir(path: string): Promise<string[]>;
35
+ /** Link target, or undefined. */
36
+ readlink(path: string): Promise<string | undefined>;
37
+ statfs(path: string): Promise<{
38
+ bavail: number;
39
+ bsize: number;
40
+ blocks: number;
41
+ } | undefined>;
42
+ env: Record<string, string | undefined>;
43
+ now(): number;
44
+ }
45
+ export interface HostProbeOptions {
46
+ /** Required in Node (pass `nodeHostDeps()` from ./node, or use `createNodeHostProbe`); not used in a browser or a
47
+ * Worker. */
48
+ deps?: NodeHostDeps | Promise<NodeHostDeps>;
49
+ /** Defaults to globalThis (environment detection: Electron? a Worker?). */
50
+ globals?: HostGlobals;
51
+ /** Electron's powerMonitor (the Mac app): its battery and thermal answers beat pmset's. */
52
+ powerMonitor?: PowerMonitorLike;
53
+ /** The volume whose free space matters (the app's data or render folder). Default: the working directory. */
54
+ diskPath?: string;
55
+ /** ffmpeg to probe; false = skip the encoder probe (an upload-only product). Default "ffmpeg". */
56
+ ffmpeg?: string | false;
57
+ /** Command and filesystem deadline (default 3 s; the encoder probe uses its own 15 s). */
58
+ timeoutMs?: number;
59
+ }
60
+ export interface HostProbe {
61
+ /** The full profile (static facts are read on the first call and cached). */
62
+ detect(): Promise<HostProfile>;
63
+ /** Re-read the dynamic facts onto the cached static ones (calls detect() the first time). */
64
+ refresh(): Promise<HostProfile>;
65
+ }
66
+ export declare function createHostProbe(o?: HostProbeOptions): HostProbe;
67
+ /** One call: the profile of the machine this runs on (in Node pass `deps`, or use ./node's detectNodeHostProfile). */
68
+ export declare const detectHostProfile: (o?: HostProbeOptions) => Promise<HostProfile>;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Hardware video encoders, via ffmpeg. `ffmpeg -encoders` lists what the build was compiled with, not what the machine
3
+ * can do (NVENC, QSV and VAAPI are in most Linux builds whether or not there is a GPU), so every hardware candidate is
4
+ * proven with a real 5-frame encode of a generated test pattern before it is marked `verified`. libx264 is the
5
+ * fallback everywhere.
6
+ */
7
+ import type { EncoderInfo, MediaProfile } from "./types";
8
+ /** Runs a program; never rejects. ok = exited 0 before the deadline. */
9
+ export type Run = (cmd: string, args: string[], timeoutMs: number) => Promise<{
10
+ ok: boolean;
11
+ out: string;
12
+ }>;
13
+ /** `ffmpeg -hide_banner -hwaccels` → ["videotoolbox"]. */
14
+ export declare function parseHwaccels(out: string): string[];
15
+ /** Video encoders we know how to use (h264/hevc/av1/prores, hardware or the libx264/libx265/SVT-AV1 software ones). */
16
+ export declare function parseEncoders(out: string): Omit<EncoderInfo, "verified">[];
17
+ /** The ffmpeg arguments that prove an encoder works: 5 frames of testsrc2 at 320x240 into the null muxer. */
18
+ export declare function testEncodeArgs(e: Pick<EncoderInfo, "name" | "api">, renderDevice?: string): string[] | null;
19
+ export interface ProbeMediaOptions {
20
+ run: Run;
21
+ /** ffmpeg to probe (default "ffmpeg" on PATH). */
22
+ ffmpeg?: string;
23
+ /** Linux render node for VAAPI/QSV, when one exists. */
24
+ renderDevice?: string;
25
+ /** Per command (default 15 s: a first VideoToolbox or CUDA init can take a few seconds). */
26
+ timeoutMs?: number;
27
+ /** Prove only these codecs (default h264 and hevc: what proxies and ladders use). */
28
+ codecs?: EncoderInfo["codec"][];
29
+ }
30
+ /** Probe ffmpeg: decode accelerations, encoders, and which of them really encode here. */
31
+ export declare function probeMedia(o: ProbeMediaOptions): Promise<MediaProfile>;
32
+ /** The encoder to use for `codec`: the first verified hardware one (unless `prefer` is "software"), else the
33
+ * verified software one; undefined when neither works (no ffmpeg, or a build without libx264). */
34
+ export declare function pickEncoder(m: MediaProfile, codec?: EncoderInfo["codec"], prefer?: "hardware" | "software"): EncoderInfo | undefined;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Where the code runs, and what the runtimes without a shell (browser, Cloudflare Worker) can say about the machine.
3
+ * Pure over an injected `globals` object, so every environment is testable from Node.
4
+ */
5
+ import type { HostEnvironment, HostProfile, InterfaceKind } from "./types";
6
+ /** The slice of globalThis this module reads. */
7
+ export interface HostGlobals {
8
+ process?: {
9
+ versions?: Record<string, string | undefined>;
10
+ platform?: string;
11
+ arch?: string;
12
+ /** Electron: "browser" (main), "renderer", "worker", "utility". */
13
+ type?: string;
14
+ env?: Record<string, string | undefined>;
15
+ };
16
+ navigator?: {
17
+ userAgent?: string;
18
+ hardwareConcurrency?: number;
19
+ /** GB, rounded down to a power of two and capped at 8 by browsers. */
20
+ deviceMemory?: number;
21
+ connection?: {
22
+ type?: string;
23
+ effectiveType?: string;
24
+ downlink?: number;
25
+ rtt?: number;
26
+ saveData?: boolean;
27
+ };
28
+ getBattery?: () => Promise<{
29
+ charging: boolean;
30
+ level: number;
31
+ }>;
32
+ storage?: {
33
+ estimate?: () => Promise<{
34
+ quota?: number;
35
+ usage?: number;
36
+ }>;
37
+ };
38
+ };
39
+ window?: unknown;
40
+ document?: unknown;
41
+ /** Present in web workers. */
42
+ importScripts?: unknown;
43
+ /** workerd's own global. */
44
+ WebSocketPair?: unknown;
45
+ }
46
+ /** Which runtime this is. `inContainer` is the Node-side container check (linux.ts looksLikeContainer). */
47
+ export declare function detectEnvironment(g: HostGlobals, inContainer?: boolean): HostEnvironment;
48
+ /** Network Information API → our kind. Chrome/Android only; Safari and Firefox don't expose it. */
49
+ export declare function browserKind(type: string | undefined): InterfaceKind | undefined;
50
+ /** A browser's profile: cores, a coarse memory figure, battery, the Network Information API's estimates. */
51
+ export declare function detectBrowser(g: HostGlobals, now?: () => number): Promise<HostProfile>;
52
+ /** A Cloudflare Worker: one isolate, no shell, no ffmpeg. The facts that matter are the platform's own limits. */
53
+ export declare function detectWorker(g: HostGlobals, now?: () => number): HostProfile;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Host profile: what machine this is (CPU, memory, disk, power, thermal, network, environment, hardware encoders) and
3
+ * how hard to drive it (upload connections, part size, hashing threads, encoder and renders), re-evaluated live.
4
+ * docs/platform/HOST-PROFILE.md.
5
+ *
6
+ * Nothing reachable from here imports node:* (a browser or Worker bundle stays clean); Node code imports ./node, which
7
+ * re-exports all of this plus the real OS dependencies (nodeHostDeps, createNodeHostProbe, detectNodeHostProfile).
8
+ */
9
+ /** Which entry point this is (`@uploadfilm/sdk/host`). */
10
+ export declare const SDK_ENTRY: "host";
11
+ export type * from "./types";
12
+ export { createHostProbe, detectHostProfile, type HostProbe, type HostProbeOptions, type NodeHostDeps, type PowerMonitorLike, } from "./detect";
13
+ export { detectEnvironment, detectBrowser, detectWorker, browserKind, type HostGlobals } from "./environment";
14
+ export { probeMedia, pickEncoder, parseEncoders, parseHwaccels, testEncodeArgs, type Run, type ProbeMediaOptions, } from "./encoders";
15
+ export { measureNetwork, ThroughputSampler, type MeasureOptions } from "./network";
16
+ export { decide, defaultPolicy, enforce, environmentCap, fastCores, memoryBudget, modeOf, tighter, MODE_RANK, MIN_PART, MAX_PART, ORIGINALS_MIN_SHARE, ABSOLUTE_MAX_CONNECTIONS, type Policy, type TuneDecision, type TuneMode, type TuneOverrides, } from "./policy";
17
+ export { createTuner, FALLBACK_DECISION, type Tuner, type TunerOptions, type TuneListener } from "./tuner";
18
+ export { bindEngine, connectionsForPart, engineConnections, partSizeFor, runnerSettings, videoEncodeArgs, watchPowerMonitor, withOriginalsShare, type LaneLike, type PowerMonitorEvents, type RunnerSettings, type TunableEngine, type VideoEncodeArgs, } from "./adapters";
19
+ export * as macReaders from "./mac";
20
+ export * as linuxReaders from "./linux";
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Linux readers (pure parsers over /proc and /sys contents). Containers read their own cgroup limits: a pod with
3
+ * `cpu.max = 200000 100000` has 2 CPUs however many the node has, and `memory.max` is what the OOM killer counts.
4
+ */
5
+ import type { InterfaceKind, MemoryPressure, ThermalState } from "./types";
6
+ /** cgroup v2 `cpu.max` ("200000 100000" → 2; "max 100000" → undefined) or v1 cfs quota/period. Rounded up. */
7
+ export declare function cgroupCpus(cpuMax: string | undefined, v1?: {
8
+ quota?: string;
9
+ period?: string;
10
+ }): number | undefined;
11
+ /** cgroup `memory.max` / v1 `memory.limit_in_bytes` → bytes; "max" or v1's "unlimited" (≈ 2^63) → undefined. */
12
+ export declare function cgroupMemory(v: string | undefined): number | undefined;
13
+ /** /proc/meminfo → total and available bytes. */
14
+ export declare function parseMeminfo(out: string): {
15
+ total?: number;
16
+ free?: number;
17
+ };
18
+ /**
19
+ * Pressure stall information (/proc/pressure/memory or a cgroup's memory.pressure): "some avg10=…", "full avg10=…".
20
+ * full avg10 ≥ 10 % (every task stalled on memory a tenth of the time) = critical; some avg10 ≥ 10 % = warn.
21
+ */
22
+ export declare function parsePsi(out: string | undefined): MemoryPressure | undefined;
23
+ /** Memory pressure when PSI isn't there: under 5 % of total available = critical, under 10 % = warn. */
24
+ export declare function pressureFromFree(free: number | undefined, total: number | undefined): MemoryPressure | undefined;
25
+ export interface PowerSupply {
26
+ /** /sys/class/power_supply/<n>/type: "Mains", "Battery", "USB", … */
27
+ type?: string;
28
+ /** "online" for Mains/USB ("1"). */
29
+ online?: string;
30
+ /** "capacity" for Battery (0..100). */
31
+ capacity?: string;
32
+ /** "status" for Battery: "Charging", "Discharging", "Full", "Not charging". */
33
+ status?: string;
34
+ /** "scope": "Device" for a mouse's or headset's battery (not the machine's). */
35
+ scope?: string;
36
+ }
37
+ /** The machine's power from /sys/class/power_supply. No supply at all (most servers) = AC. */
38
+ export declare function linuxPower(supplies: PowerSupply[]): {
39
+ source?: "ac" | "battery";
40
+ batteryPercent?: number;
41
+ };
42
+ export interface ThermalZone {
43
+ /** millidegrees C */
44
+ temp?: string;
45
+ /** trip points: type ("passive", "hot", "critical") → millidegrees */
46
+ trips: {
47
+ type: string;
48
+ temp: string;
49
+ }[];
50
+ }
51
+ /** Hottest zone against its own trip points: ≥ critical trip = critical, ≥ hot = serious, ≥ passive = fair. */
52
+ export declare function linuxThermal(zones: ThermalZone[]): ThermalState | undefined;
53
+ /** /proc/net/route → the interface of the default route (destination 00000000, lowest metric). */
54
+ export declare function defaultIface(route: string): string | undefined;
55
+ export interface LinuxIface {
56
+ name: string;
57
+ /** /sys/class/net/<n>/wireless exists. */
58
+ wireless?: boolean;
59
+ /** /sys/class/net/<n>/type (1 = Ethernet framing, 772 = loopback, 65534 = tun). */
60
+ type?: string;
61
+ /** Basename of the /sys/class/net/<n>/device/driver link ("ipheth" = USB iPhone, "rndis_host"/"cdc_ether"/"cdc_ncm"
62
+ * = USB phone tethering or an adapter, "r8152" …). */
63
+ driver?: string;
64
+ }
65
+ /** Interface kind. USB tethering drivers (ipheth, rndis_host) mean a phone; cdc_ether is also used by USB Ethernet
66
+ * dongles, so it stays "ethernet". A wwan/wwp interface is a cellular modem. */
67
+ export declare function linuxKind(i: LinuxIface): InterfaceKind;
68
+ /** `nmcli -t -f GENERAL.METERED dev show <iface>` → "GENERAL.METERED:yes" / "yes (guessed)" / "no" / "unknown". */
69
+ export declare function parseNmMetered(out: string): boolean | undefined;
70
+ /** `powerprofilesctl get` → "power-saver" | "balanced" | "performance". */
71
+ export declare const parsePowerProfile: (out: string) => boolean | undefined;
72
+ /** Signs of a container: /.dockerenv, /run/.containerenv (Podman), a container runtime in /proc/1/cgroup, the
73
+ * `container` env var systemd-nspawn/Podman set, or Kubernetes' service env. */
74
+ export declare function looksLikeContainer(o: {
75
+ dockerenv: boolean;
76
+ containerenv: boolean;
77
+ cgroup1?: string;
78
+ env: Record<string, string | undefined>;
79
+ }): boolean;
80
+ /**
81
+ * /proc/self/cgroup → where this process sits: the unified (v2) path from the "0::<path>" line, and v1 controllers'
82
+ * paths ("4:memory:/docker/abc", "3:cpu,cpuacct:/…" → memory, cpu and cpuacct each).
83
+ */
84
+ export declare function parseProcCgroup(out: string | undefined): {
85
+ v2?: string;
86
+ v1: Record<string, string>;
87
+ };
88
+ /**
89
+ * The cgroup directories whose limits apply to a process at `path` under the mount `root`: its own and every ancestor
90
+ * up to the root ("/system.slice/x.service" → root/system.slice/x.service, root/system.slice, root). A limit anywhere
91
+ * on the way up binds. Inside a container with its own cgroup namespace the path is "/" (just the root); a Docker v1
92
+ * container without one shows the host's path, which doesn't exist inside, so the root (the container's own) is read.
93
+ */
94
+ export declare function cgroupDirs(root: string, path: string | undefined): string[];
@@ -0,0 +1,47 @@
1
+ /**
2
+ * macOS readers (pure parsers over command output). Every command used here runs without a permission prompt:
3
+ * sysctl, pmset, route, networksetup, ipconfig. A missing tool or odd output only leaves that field unknown.
4
+ */
5
+ import type { CoreLevel, InterfaceKind, MemoryPressure, ThermalState } from "./types";
6
+ /** `sysctl hw.ncpu hw.physicalcpu hw.nperflevels hw.perflevelN.* hw.memsize machdep.cpu.brand_string
7
+ * kern.memorystatus_vm_pressure_level` in "name: value" form (sysctl without -n) → a map. */
8
+ export declare function parseSysctl(out: string): Map<string, string>;
9
+ /** Core levels from sysctl, fastest first. undefined when the machine has one kind of core (Intel). */
10
+ export declare function coreLevels(s: Map<string, string>): CoreLevel[] | undefined;
11
+ /** kern.memorystatus_vm_pressure_level: 1 normal, 2 warn, 4 critical (xnu's kVMPressure* levels). */
12
+ export declare function macPressure(v: string | undefined): MemoryPressure | undefined;
13
+ /** `pmset -g batt` → power source and charge. "Now drawing from 'AC Power'" / "'Battery Power'". A desktop Mac
14
+ * prints AC with no battery line. */
15
+ export declare function parsePmsetBatt(out: string): {
16
+ source?: "ac" | "battery";
17
+ batteryPercent?: number;
18
+ };
19
+ /**
20
+ * `pmset -g` (the "Currently in use" settings) → Low Power Mode. macOS 14+ prints `powermode N` (0 automatic,
21
+ * 1 low power, 2 high power); older releases print `lowpowermode 0|1`.
22
+ */
23
+ export declare function parseLowPower(out: string): boolean | undefined;
24
+ /**
25
+ * `pmset -g therm`. Apple silicon usually prints only "No thermal warning level has been recorded"; a hot Mac prints
26
+ * `Thermal Warning Level = N` (IOPM.h: 0 normal, 5 danger, 10 critical; higher values are warning/trap states) and an
27
+ * Intel Mac `CPU_Speed_Limit = NN` (percent of full speed). Levels: 1–4 = fair, 5–9 = serious, ≥ 10 = critical; a speed
28
+ * limit under 100 % = fair, under 80 % = serious, at or under 50 % = critical. The worse of the two wins.
29
+ */
30
+ export declare function parseTherm(out: string): ThermalState | undefined;
31
+ export declare const THERMAL_RANK: Record<ThermalState, number>;
32
+ /** `networksetup -listallhardwareports` → device ("en0") → hardware port ("Wi-Fi"). */
33
+ export declare function parsePorts(out: string): Map<string, string>;
34
+ /** `route -n get default` → gateway and interface. */
35
+ export declare function parseRoute(out: string): {
36
+ gateway?: string;
37
+ iface?: string;
38
+ };
39
+ export declare const isTunnel: (iface: string) => boolean;
40
+ /** The hardware port's name → interface kind (same reading as UploadFilm's app/src/main/netinfo.ts kindOf). */
41
+ export declare function portKind(port: string | undefined, iface?: string): InterfaceKind;
42
+ /**
43
+ * iPhone Personal Hotspot hands out 172.20.10.0/28 with the router at .1 (Wi-Fi, USB and Bluetooth alike). An office
44
+ * LAN can use the same router address, so all three must agree: router .1, our address in .2–.14, a /28 mask. (The
45
+ * rule UploadFilm's netinfo.ts looksLikeHotspot uses.)
46
+ */
47
+ export declare function looksLikeHotspot(gateway?: string, localIp?: string, mask?: string): boolean;
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Measured network: RTT and throughput. Nothing here knows a host name: the product passes the URLs (its own storage
3
+ * endpoint or a presigned test object), so a measurement goes where its real uploads go. Two sources:
4
+ *
5
+ * - `measureNetwork`: an active test (a few tiny requests for RTT, one timed download and/or upload).
6
+ * - `ThroughputSampler`: passive, from what the transfer engine actually moved (no extra traffic; preferred once
7
+ * uploads run, since a test object is not the real path under load).
8
+ */
9
+ import type { NetworkProfile } from "./types";
10
+ type FetchLike = (url: string, init?: {
11
+ method?: string;
12
+ body?: Uint8Array;
13
+ signal?: AbortSignal;
14
+ headers?: Record<string, string>;
15
+ }) => Promise<{
16
+ ok: boolean;
17
+ status: number;
18
+ arrayBuffer(): Promise<ArrayBuffer>;
19
+ }>;
20
+ export interface MeasureOptions {
21
+ fetch: FetchLike;
22
+ /** A small object (or any cheap endpoint) for RTT: HEAD requests, the median is reported. */
23
+ rttUrl?: string;
24
+ /** Number of RTT samples (default 5; the first warms the connection and is dropped). */
25
+ rttSamples?: number;
26
+ /** A GET whose body is timed for download throughput (a few MB is enough). */
27
+ downloadUrl?: string;
28
+ /** A PUT target (presigned) timed with `uploadBytes` of zeros for upload throughput. */
29
+ uploadUrl?: string;
30
+ /** Bytes to PUT (default 4 MiB). */
31
+ uploadBytes?: number;
32
+ /** Overall deadline (default 20 s). */
33
+ timeoutMs?: number;
34
+ now?: () => number;
35
+ }
36
+ /** One active measurement. Fields it couldn't measure (no URL given, a request failed, the deadline hit) are left out. */
37
+ export declare function measureNetwork(o: MeasureOptions): Promise<Pick<NetworkProfile, "rttMs" | "upBps" | "downBps" | "measuredAt">>;
38
+ /**
39
+ * Passive throughput: feed it the transfer engine's measured rate (engine.rate, bytes/s) and how many connections were
40
+ * busy. It keeps the best sustained rate of a sliding window, so a lull between files doesn't read as a slow line, and
41
+ * forgets it when the network changes (`reset()` on an interface change).
42
+ */
43
+ export declare class ThroughputSampler {
44
+ private readonly windowMs;
45
+ private readonly now;
46
+ private samples;
47
+ constructor(windowMs?: number, now?: () => number);
48
+ /** A rate reading. Readings with nothing in flight say nothing about the line and are ignored. */
49
+ add(bps: number, busyConnections: number): void;
50
+ reset(): void;
51
+ /** The 80th percentile of the window's readings (a sustained rate, not a burst), or undefined with < 3 readings. */
52
+ get upBps(): number | undefined;
53
+ }
54
+ export {};
@@ -0,0 +1,13 @@
1
+ import { type HostProbeOptions, type NodeHostDeps, type Run } from "@uploadfilm/sdk/host";
2
+ export * from "@uploadfilm/sdk/host";
3
+ /** Which entry point this is (`@uploadfilm/sdk/host/node`). */
4
+ export declare const SDK_ENTRY: "host/node";
5
+ /** execFile that always settles: ok = exit 0 before the deadline; stdout is kept on a non-zero exit (sysctl exits 1
6
+ * on one unknown name but prints the rest). The child is SIGKILLed at the deadline. */
7
+ export declare const nodeRun: Run;
8
+ /** The real Node dependencies. */
9
+ export declare function nodeHostDeps(): NodeHostDeps;
10
+ /** createHostProbe with the real Node dependencies. */
11
+ export declare const createNodeHostProbe: (o?: HostProbeOptions) => import("@uploadfilm/sdk/host").HostProbe;
12
+ /** The profile of the machine this runs on. */
13
+ export declare const detectNodeHostProfile: (o?: HostProbeOptions) => Promise<import("@uploadfilm/sdk/host").HostProfile>;
@@ -0,0 +1,101 @@
1
+ import type { EncoderInfo, HostProfile, HwApi } from "./types";
2
+ export type TuneMode = "open" | "normal" | "eco" | "minimal";
3
+ export declare const MODE_RANK: Record<TuneMode, number>;
4
+ /** The transfer engine's smallest part (integrity.ts MIN_PART). */
5
+ export declare const MIN_PART: number;
6
+ /** Largest part the policy picks (buffered in memory per connection). */
7
+ export declare const MAX_PART: number;
8
+ /** The rule: originals keep at least ⌈⅔ × connections⌉. */
9
+ export declare const ORIGINALS_MIN_SHARE: number;
10
+ /** No policy or override goes above this many connections. */
11
+ export declare const ABSOLUTE_MAX_CONNECTIONS = 256;
12
+ export interface TuneDecision {
13
+ mode: TuneMode;
14
+ /** Bounds for the transfer engine's hill-climbing tuner (EngineCoreOptions.connections). */
15
+ connections: {
16
+ min: number;
17
+ start: number;
18
+ max: number;
19
+ };
20
+ /** The originals lane's share (≥ ⅔) and what it guarantees at `connections.max`. */
21
+ originals: {
22
+ minShare: number;
23
+ minConnections: number;
24
+ };
25
+ /** Part size floor for multiparts created now, bytes (a whole MiB, ≥ 16 MiB). Saved multiparts keep theirs. */
26
+ partSize: number;
27
+ /**
28
+ * Most bytes of parts that may be in flight at once (null = no memory figure). The engine buffers each in-flight part
29
+ * once, and an object bigger than 9,500 × partSize (or a resumed multipart) has bigger parts than `partSize`: cap its
30
+ * connections with `connectionsForPart(d, actualPartSize)` so the total stays under this.
31
+ */
32
+ inflightBytes: number | null;
33
+ /** Threads for whole-file hashing (sha256 for dedupe). */
34
+ hashThreads: number;
35
+ /** Local encoding (proxies, a self-hosted media runner). renders = 0: don't start new renders now. */
36
+ encode: {
37
+ /** ffmpeg encoder name, or null when nothing verified encodes here. */
38
+ encoder: string | null;
39
+ api: HwApi | null;
40
+ hardware: boolean;
41
+ renders: number;
42
+ /** ffmpeg -threads per render. */
43
+ threads: number;
44
+ /** setpriority niceness for ffmpeg children (0..19). */
45
+ nice: number;
46
+ };
47
+ /** The link is metered (hotspot, cellular, saveData): products may hold big lanes (UploadFilm holds originals). */
48
+ metered: boolean;
49
+ /** Why, in words, for logs and support ("on battery", "hotspot: max 8"). */
50
+ reasons: string[];
51
+ }
52
+ export interface TuneOverrides {
53
+ /** Ceiling on connections (always respected, every mode). */
54
+ maxConnections?: number;
55
+ /** Floor on connections (clamped to the max). */
56
+ minConnections?: number;
57
+ /** Replaces the environment's cap (Worker 6, browser 6, else 64); at most 256. */
58
+ hardCap?: number;
59
+ /** Fixed part size floor, bytes (clamped to 16 MiB..256 MiB, whole MiB). */
60
+ partSize?: number;
61
+ /** Ceilings. */
62
+ hashThreads?: number;
63
+ renders?: number;
64
+ /** Encoder preference: "hardware" (default), "software", or an exact ffmpeg encoder name (used if verified). */
65
+ encoder?: "hardware" | "software" | (string & {});
66
+ codec?: EncoderInfo["codec"];
67
+ /** The originals' share; raised to ⅔ if lower. */
68
+ originalsShare?: number;
69
+ /** Force a mode (a product's "max speed" or "be gentle" setting). */
70
+ mode?: TuneMode;
71
+ }
72
+ export type Policy = (p: HostProfile, o: TuneOverrides) => TuneDecision;
73
+ /** Cap on connections from where the code runs. */
74
+ export declare function environmentCap(p: HostProfile): {
75
+ cap: number;
76
+ why?: string;
77
+ };
78
+ /** The stress mode of a profile, with the reasons. */
79
+ export declare function modeOf(p: HostProfile): {
80
+ mode: TuneMode;
81
+ reasons: string[];
82
+ };
83
+ /** Cores that aren't efficiency cores (all of them on Intel/x86 or an M5 Max). */
84
+ export declare function fastCores(p: HostProfile): number;
85
+ /** What memory allows to be buffered by in-flight parts: a quarter of what's free (or of total / 2 when free is
86
+ * unknown); unlimited when nothing is known. */
87
+ export declare function memoryBudget(p: HostProfile): number;
88
+ /** The default policy. */
89
+ export declare const defaultPolicy: Policy;
90
+ /**
91
+ * The invariants, applied to any decision (the default policy's or a product's): overrides as ceilings and floors, the
92
+ * environment cap, ordering, the originals' ⅔, CPU oversubscription. Idempotent.
93
+ */
94
+ export declare function enforce(d: TuneDecision, p: HostProfile, o?: TuneOverrides): TuneDecision;
95
+ /** Decide: run `policy` (default the built-in one) and enforce the invariants on what it returns. */
96
+ export declare function decide(p: HostProfile, o?: TuneOverrides, policy?: Policy): TuneDecision;
97
+ /**
98
+ * Field-wise tighter of two decisions (smaller limits, smaller part size, higher niceness); used while a relaxation
99
+ * waits, so tightening never waits. Encoder and metadata come from `next`.
100
+ */
101
+ export declare function tighter(cur: TuneDecision, next: TuneDecision): TuneDecision;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The live tuner: re-reads the profile every `intervalMs` (and whenever poked: Electron's on-battery, a thermal change,
3
+ * a network change), decides, and tells subscribers (the transfer engine, the media runner) when the decision changed.
4
+ *
5
+ * Backing off is immediate. Moving to a calmer mode (eco → normal → open) waits until the calmer readings have held for
6
+ * `relaxAfterMs`, so plugging in for ten seconds or a load spike that ends doesn't flap the engine; meanwhile the
7
+ * field-wise tighter of the two decisions applies (a tightening in one field never waits for a relaxation in another).
8
+ * Within one mode the limits follow memory and the network at once.
9
+ */
10
+ import type { HostProbe } from "./detect";
11
+ import { type Policy, type TuneDecision, type TuneOverrides } from "./policy";
12
+ import type { HostProfile } from "./types";
13
+ /** Anything that consumes decisions (the transfer engine, a media runner, a UI). */
14
+ export type TuneListener = (d: TuneDecision, profile: HostProfile) => void;
15
+ /** The pluggable tuner the transfer engine and the media runner take. */
16
+ export interface Tuner {
17
+ /** The decision in force (a safe default until the first evaluation). */
18
+ readonly decision: TuneDecision;
19
+ readonly profile: HostProfile | undefined;
20
+ /** Re-read the profile and decide now. */
21
+ evaluate(): Promise<TuneDecision>;
22
+ subscribe(fn: TuneListener): () => void;
23
+ setOverrides(o: TuneOverrides): void;
24
+ /** Passive throughput from the transfer engine (engine.rate, busy connections). */
25
+ observeThroughput(bps: number, busyConnections: number): void;
26
+ start(): void;
27
+ stop(): void;
28
+ }
29
+ export interface TunerOptions {
30
+ /** Where profiles come from: a HostProbe, or any async function (tests, a browser, a fixed profile). */
31
+ probe: HostProbe | (() => Promise<HostProfile>);
32
+ policy?: Policy;
33
+ overrides?: TuneOverrides;
34
+ /** Re-read every (default 15 s). */
35
+ intervalMs?: number;
36
+ /** A more permissive decision must hold this long before it applies (default 60 s). */
37
+ relaxAfterMs?: number;
38
+ now?: () => number;
39
+ setInterval?: (fn: () => void, ms: number) => unknown;
40
+ clearInterval?: (h: unknown) => void;
41
+ /** An evaluation failed (the probe threw or timed out) or a subscriber threw: the last decision stays. */
42
+ onError?: (e: unknown) => void;
43
+ /** A read that takes longer than this fails the evaluation (default 10 s): a hung probe never freezes back-off. */
44
+ probeTimeoutMs?: number;
45
+ }
46
+ /** What applies before anything is known: the transfer engine's own defaults. */
47
+ export declare const FALLBACK_DECISION: TuneDecision;
48
+ export declare function createTuner(o: TunerOptions): Tuner;