ultrafastmov 0.1.1 → 0.1.2

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.
package/README.md CHANGED
@@ -1,45 +1,46 @@
1
1
  # ultrafastmov
2
2
 
3
3
  TypeScript client for ultrafast, the GPU video engine. A video is a JSON
4
- document; the render service turns it into an MP4. This package talks to
5
- ultrafast Cloud or your own `ultrafast serve`.
4
+ document; your own `ultrafast serve` turns it into a video (MP4, ProRes,
5
+ WebM, a GIF, an image sequence) at any size, and this package talks to it.
6
6
 
7
7
  ```bash
8
+ ultrafast serve # on the machine with the GPU; prints its API key when it starts
8
9
  npm i ultrafastmov
9
10
  ```
10
11
 
11
12
  ```typescript
12
13
  import { Ultrafast } from "ultrafastmov";
13
14
 
14
- const uf = new Ultrafast(); // ULTRAFAST_API_KEY
15
+ const uf = new Ultrafast(); // the server on this machine; ULTRAFAST_API_KEY
15
16
 
16
17
  const doc = await uf.load("film.json");
17
- const sheet = await uf.sheet(doc, { count: 9 });
18
- const job = await uf.render(doc, {
19
- webhook: "https://example.com/rendered",
20
- });
21
- console.log(job.id, job.status);
18
+ await (await uf.sheet(doc, { count: 9 })).save("sheet.png");
19
+ const render = await uf.render(doc);
20
+ await render.save("film.mp4");
22
21
  ```
23
22
 
24
23
  Node 18 or later, no dependencies. ESM and CommonJS.
25
24
 
26
- ## Your own server
25
+ ## The server
27
26
 
28
27
  `ultrafast serve` is the open-source render service for one machine with a
29
- GPU.
28
+ GPU: install `ultrafast` with `cargo install ultrafast`,
29
+ `brew install ultrafastmov/tap/ultrafast` or the
30
+ `ghcr.io/ultrafastmov/ultrafast` image
31
+ ([self-hosting](https://github.com/ultrafastmov/ultrafast/blob/main/docs/service/SELF_HOST.md)).
32
+ The client talks to `http://127.0.0.1:8080` unless told otherwise:
30
33
 
31
34
  ```bash
32
- export ULTRAFAST_BASE_URL=http://localhost:8080
33
- export ULTRAFAST_API_KEY=... # the server's key (it prints one at first start)
35
+ export ULTRAFAST_BASE_URL=http://gpu-box:8080 # a server on another machine
36
+ export ULTRAFAST_API_KEY=... # the server's key
34
37
  ```
35
38
 
36
- or `new Ultrafast({ baseUrl: "http://localhost:8080", apiKey })`. Without
37
- `ULTRAFAST_BASE_URL` the client uses ultrafast Cloud,
38
- `https://api.ultrafast.mov`.
39
+ or `new Ultrafast({ baseUrl: "http://gpu-box:8080", apiKey })`.
39
40
 
40
- Everything here works against it except what only ultrafast Cloud has:
41
- jobs and webhooks (`{ job }`, `{ webhook }`, `uf.jobs`), `{ uri }` output
42
- to your own bucket, and `gs://`, `s3://` or `r2://` inputs. Those throw
41
+ Jobs and webhooks (`{ job }`, `{ webhook }`, `uf.jobs`), `{ uri }` output
42
+ to your own bucket, and `gs://`, `s3://` or `r2://` inputs are for
43
+ ultrafast Cloud, which isn't open yet. The server answers them with
43
44
  `CloudOnlyError` (`e.feature` says which).
44
45
 
45
46
  ## Methods
@@ -54,15 +55,20 @@ const { ok, issues } = await uf.check(doc);
54
55
  for (const issue of await uf.review(doc, { safe: "social" })) {
55
56
  console.log(issue.kind, issue.node, issue.from, issue.to, issue.message);
56
57
  }
57
- console.log(`${await uf.estimate(doc)}`); // $0.004, 8 s of 1080p
58
+ console.log(`${await uf.estimate(doc)}`); // 8 s of 1080p, 2.1 GPU seconds
58
59
 
59
60
  const render = await uf.render(doc); // stored; render.url is signed
60
61
  await render.save("film.mp4"); // streamed, sha256 checked
61
62
  const short = await uf.render(doc, { inline: true, range: [0, 3] });
62
63
 
63
- const job = await uf.render(doc, { job: true }); // or { webhook } (Cloud)
64
- const done = await job.wait(); // polls; throws the job's error if it failed
65
- await uf.jobs.get(job.id);
64
+ // One document, every deliverable: the settings are `ultrafast export`'s.
65
+ await uf.render(doc, { quality: "draft", size: "720p", inline: true }); // a quick preview
66
+ await uf.render(doc, { size: "4k", quality: "high" }); // rendered at 4K, not scaled up
67
+ await uf.render(doc, { codec: "prores", alpha: true, name: "overlay.mov" }); // ProRes 4444 with alpha
68
+ await uf.render(doc, { format: "webm", alpha: true }); // VP9 with alpha
69
+ await uf.render(doc, { format: "gif", fps: 15, size: "480p", loops: 0 }); // a GIF that plays once
70
+ await uf.render(doc, { format: "png", alpha: true }); // a zip of PNG frames
71
+ console.log(`${await uf.estimate(doc, { size: "4k", quality: "master" })}`); // counted at the output size
66
72
 
67
73
  const asset = await uf.upload("interview.mp4"); // or a Blob, File or bytes
68
74
  // "src": asset.uri
@@ -78,13 +84,18 @@ client, while its size and mtime stay the same) and sends a copy with
78
84
  `asset://` references in their place; your object is not changed. Paths
79
85
  resolve against the document's directory when it came from `uf.load`
80
86
  (spread copies keep it), else the working directory. Font family names (`"Inter"`), inline face tracks
81
- and `asset://`, `https://`, `data:` and (on Cloud) `gs://`, `s3://`, `r2://` values are
82
- sent as they are. `uf.prepare(doc)` returns the copy without rendering.
87
+ and `asset://`, `https://` and `data:` values are sent as they are. `uf.prepare(doc)` returns the copy without rendering.
83
88
 
84
89
  Reading files needs Node. In edge runtimes, pass documents as objects whose
85
90
  media are already references.
86
91
 
87
- ## Webhooks (Cloud)
92
+ ## Jobs and webhooks (ultrafast Cloud, not open yet)
93
+
94
+ ```typescript
95
+ const job = await uf.render(doc, { job: true }); // or { webhook }
96
+ const done = await job.wait(); // polls; throws the job's error if it failed
97
+ await uf.jobs.get(job.id);
98
+ ```
88
99
 
89
100
  ```typescript
90
101
  import { verifyWebhook } from "ultrafastmov";
@@ -113,8 +124,9 @@ writes to an `output.uri`, where the request's `attempt` ids make the
113
124
  retry a replay.
114
125
 
115
126
  A synchronous render holds the request open until the video is written,
116
- and Node's fetch stops waiting for response headers after 5 minutes: on
117
- Cloud, use a job for long renders.
127
+ and Node's fetch stops waiting for response headers after 5 minutes. For
128
+ longer renders, pass a `fetch` with a longer `headersTimeout` (undici's
129
+ `Agent`), or render in parts with `range`.
118
130
 
119
131
  ## Types
120
132
 
@@ -2,11 +2,12 @@ import { type FetchLike, Transport } from "./http.js";
2
2
  import { Estimate, Image, Job, Render, Review } from "./results.js";
3
3
  import type { Document } from "./schema.js";
4
4
  import type { Asset, Attempt, CheckResult, Health, Me } from "./types.js";
5
- export declare const DEFAULT_BASE_URL = "https://api.ultrafast.mov";
5
+ /** A local `ultrafast serve` on its default port. */
6
+ export declare const DEFAULT_BASE_URL = "http://127.0.0.1:8080";
6
7
  export interface UltrafastOptions {
7
- /** Default: `ULTRAFAST_API_KEY`. */
8
+ /** Default: `ULTRAFAST_API_KEY` (the key the server prints at first start). */
8
9
  apiKey?: string;
9
- /** Default: `ULTRAFAST_BASE_URL`, else ultrafast Cloud. A self-hosted server: `http://localhost:8080`. */
10
+ /** Default: `ULTRAFAST_BASE_URL`, else `http://127.0.0.1:8080`, a server on this machine. */
10
11
  baseUrl?: string;
11
12
  /** A fetch implementation (default: the global one). */
12
13
  fetch?: FetchLike;
@@ -17,18 +18,49 @@ export interface UltrafastOptions {
17
18
  }
18
19
  /** A document, or the path of a document file (Node). */
19
20
  export type DocumentInput = Document | string;
20
- export interface RenderOptions {
21
- /** The mp4 in the response (at most 32 MiB) instead of stored with a signed URL. */
21
+ /** An output size: `"720p"`, `"1080p"`, `"1440p"`, `"4k"` (the short side), `"WxH"`, or `[w, h]`. */
22
+ export type Size = "720p" | "1080p" | "1440p" | "4k" | `${number}p` | `${number}x${number}` | [number, number];
23
+ /**
24
+ * Export settings, as `ultrafast export` and the MCP export tools spell them.
25
+ * Settings that don't go together are refused before anything renders.
26
+ */
27
+ export interface ExportSettings {
28
+ /** The container (default: from `name`'s extension, else mp4). `png` and `exr` are image sequences (a zip); `wav` to `opus` are sound alone. */
29
+ format?: "mp4" | "mov" | "mkv" | "webm" | "gif" | "png" | "exr" | "wav" | "mp3" | "m4a" | "flac" | "opus";
30
+ /** Default h264 (vp9 for webm). */
31
+ codec?: "h264" | "hevc" | "h265" | "av1" | "vp9" | "prores";
32
+ /** draft: a fast preview without motion blur; standard (default); high; master: twice the motion-blur samples, the best encode. */
33
+ quality?: "draft" | "standard" | "high" | "master";
34
+ /** Rendered at this size, not scaled up. */
35
+ size?: Size;
36
+ /** A multiple of the document's size, instead of `size`. */
37
+ scale?: number;
38
+ /** Output frame rate (default the document's; a GIF's at most 30). */
39
+ fps?: number;
40
+ /** Constant quality on the codec's scale, lower is better (H.264/HEVC 0-51, AV1/VP9 0-63). */
41
+ crf?: number;
42
+ /** Bits per second, or text such as `"8M"`, instead of `crf`; null for the quality level's. */
43
+ bitrate?: number | string | null;
44
+ /** Default hq; 4444 with `alpha`. */
45
+ prores_profile?: "proxy" | "light" | "standard" | "hq" | "4444" | "4444-xq";
46
+ /** Keep transparency: ProRes 4444, VP9, GIF, PNG, EXR. */
47
+ alpha?: boolean;
48
+ /** Mix the document's sound (default true). */
49
+ audio?: boolean;
50
+ /** Default aac (opus for webm, pcm with ProRes). */
51
+ audio_codec?: "aac" | "opus" | "mp3" | "flac" | "pcm" | "pcm-24";
52
+ /** Bits per second, or text such as `"192k"`. */
53
+ audio_bitrate?: number | string;
54
+ /** GIF: times it plays again after the first (0: once; default forever). */
55
+ loops?: number;
56
+ }
57
+ export interface RenderOptions extends ExportSettings {
58
+ /** The file in the response (at most 32 MiB) instead of stored with a signed URL. */
22
59
  inline?: boolean;
23
60
  /** Create the video at this object in your own bucket (`s3://`, `r2://`, `gs://`); create-only. */
24
61
  uri?: string;
25
- /** The stored file's name (default `film.mp4`). */
62
+ /** The stored file's name (default `film.<format>`, `frames.zip` for a sequence); its extension picks the format. */
26
63
  name?: string;
27
- codec?: "h264" | "hevc";
28
- /** Bits per second; null for the format's default. */
29
- bitrate?: number | null;
30
- /** Mix the document's sound (default true). */
31
- audio?: boolean;
32
64
  /** `[from, to]` seconds of the document (default all of it). */
33
65
  range?: [number, number] | null;
34
66
  /** Ids that make retries safe; one is made up per call when missing. */
@@ -92,8 +124,7 @@ export declare class Jobs {
92
124
  cancel(id: string): Promise<Job>;
93
125
  }
94
126
  /**
95
- * A client of the ultrafast render service: ultrafast Cloud, or your own
96
- * `ultrafast serve`.
127
+ * A client of an ultrafast render service: your own `ultrafast serve`.
97
128
  *
98
129
  * ```ts
99
130
  * const uf = new Ultrafast(); // ULTRAFAST_API_KEY
@@ -151,8 +182,12 @@ export declare class Ultrafast {
151
182
  }): Promise<CheckResult>;
152
183
  /** Renders the film and reports what a viewer would trip on. */
153
184
  review(doc: DocumentInput, opts?: ReviewOptions): Promise<Review>;
154
- /** What rendering will cost (free). */
155
- estimate(doc: DocumentInput, opts?: {
185
+ /**
186
+ * What rendering will cost (free). Pass the export settings you will render
187
+ * with (`size`, `quality`, `fps`, ...): minutes count the output size and
188
+ * frames are timed at that quality and frame rate.
189
+ */
190
+ estimate(doc: DocumentInput, opts?: ExportSettings & {
156
191
  range?: [number, number] | null;
157
192
  signal?: AbortSignal;
158
193
  }): Promise<Estimate>;
@@ -6,7 +6,32 @@ const files_js_1 = require("./files.js");
6
6
  const http_js_1 = require("./http.js");
7
7
  const results_js_1 = require("./results.js");
8
8
  const runtime_js_1 = require("./runtime.js");
9
- exports.DEFAULT_BASE_URL = "https://api.ultrafast.mov";
9
+ /** A local `ultrafast serve` on its default port. */
10
+ exports.DEFAULT_BASE_URL = "http://127.0.0.1:8080";
11
+ const SETTINGS = [
12
+ "format",
13
+ "codec",
14
+ "quality",
15
+ "size",
16
+ "scale",
17
+ "fps",
18
+ "crf",
19
+ "bitrate",
20
+ "prores_profile",
21
+ "alpha",
22
+ "audio",
23
+ "audio_codec",
24
+ "audio_bitrate",
25
+ "loops",
26
+ ];
27
+ /** The export settings among `opts`. */
28
+ function settingsOf(opts) {
29
+ const out = {};
30
+ for (const k of SETTINGS)
31
+ if (opts[k] !== undefined)
32
+ out[k] = opts[k];
33
+ return out;
34
+ }
10
35
  function compact(o) {
11
36
  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
12
37
  }
@@ -54,8 +79,7 @@ class Jobs {
54
79
  }
55
80
  exports.Jobs = Jobs;
56
81
  /**
57
- * A client of the ultrafast render service: ultrafast Cloud, or your own
58
- * `ultrafast serve`.
82
+ * A client of an ultrafast render service: your own `ultrafast serve`.
59
83
  *
60
84
  * ```ts
61
85
  * const uf = new Ultrafast(); // ULTRAFAST_API_KEY
@@ -125,9 +149,7 @@ class Ultrafast {
125
149
  inline: opts.inline,
126
150
  uri: opts.uri,
127
151
  name: opts.name,
128
- codec: opts.codec,
129
- bitrate: opts.bitrate,
130
- audio: opts.audio,
152
+ ...settingsOf(opts),
131
153
  range: opts.range,
132
154
  });
133
155
  const body = compact({
@@ -145,7 +167,7 @@ class Ultrafast {
145
167
  const res = await this.#transport.request({
146
168
  path: "/v1/render",
147
169
  json: body,
148
- accept: opts.inline ? "video/mp4, application/json" : "application/json",
170
+ accept: opts.inline ? "video/mp4, video/*, image/gif, audio/*, application/zip, application/json" : "application/json",
149
171
  // With `uri` a retry is a replay (409 with the stored receipt); without
150
172
  // it a resent render could render twice, so only what the server refused.
151
173
  retry: opts.uri ? "safe" : "unsent",
@@ -160,7 +182,8 @@ class Ultrafast {
160
182
  throw (0, errors_js_1.errorFromResponse)(409, text);
161
183
  }
162
184
  const type = res.headers.get("content-type") ?? "";
163
- if (type.startsWith("video/") || type === "application/octet-stream") {
185
+ // Inline: the file itself (an mp4, a webm, a gif, a zip of frames, sound).
186
+ if (type !== "" && !type.startsWith("application/json")) {
164
187
  const bytes = new Uint8Array(await res.arrayBuffer());
165
188
  const receipt = (parseJson(res.headers.get("x-ultrafast-receipt")) ?? { receipt_version: 1, status: "rendered" });
166
189
  receipt.sha256 ??= res.headers.get("x-ultrafast-sha256") ?? undefined;
@@ -204,12 +227,17 @@ class Ultrafast {
204
227
  });
205
228
  return new results_js_1.Review(data);
206
229
  }
207
- /** What rendering will cost (free). */
230
+ /**
231
+ * What rendering will cost (free). Pass the export settings you will render
232
+ * with (`size`, `quality`, `fps`, ...): minutes count the output size and
233
+ * frames are timed at that quality and frame rate.
234
+ */
208
235
  async estimate(doc, opts = {}) {
209
236
  const document = await this.prepare(doc);
237
+ const output = settingsOf(opts);
210
238
  const data = await this.#transport.json({
211
239
  path: "/v1/estimate",
212
- json: { document, range: opts.range ?? null },
240
+ json: compact({ document, range: opts.range ?? null, output: Object.keys(output).length ? output : undefined }),
213
241
  signal: opts.signal,
214
242
  });
215
243
  return new results_js_1.Estimate(data);
@@ -1,5 +1,5 @@
1
1
  export { Ultrafast, Jobs, DEFAULT_BASE_URL } from "./client.js";
2
- export type { UltrafastOptions, DocumentInput, RenderOptions, JobOptions, FrameOptions, SheetOptions, ReviewOptions, UploadOptions, UploadInput, } from "./client.js";
2
+ export type { UltrafastOptions, DocumentInput, RenderOptions, ExportSettings, Size, JobOptions, FrameOptions, SheetOptions, ReviewOptions, UploadOptions, UploadInput, } from "./client.js";
3
3
  export { Render, Job, Image, Review, Estimate } from "./results.js";
4
4
  export type { WaitOptions } from "./results.js";
5
5
  export { verifyWebhook, WebhookVerificationError } from "./webhooks.js";
@@ -12,17 +12,19 @@ export declare class Render {
12
12
  /** Signed download URL (null for an inline render, or a bucket the server cannot sign for). */
13
13
  get url(): string | null;
14
14
  get sha256(): string | undefined;
15
- /** Size of the mp4 in bytes. */
15
+ /** Size of the file in bytes. */
16
16
  get bytes(): number | undefined;
17
17
  /** Seconds of video. */
18
18
  get duration(): number | undefined;
19
19
  get frames(): number | undefined;
20
20
  get minutes(): number | undefined;
21
- /** The mp4 bytes. */
21
+ /** The file's name: the stored object's, else `film.<format>` (`frames.zip` for an image sequence). */
22
+ get filename(): string;
23
+ /** The file's bytes (an mp4, a webm, a gif, a zip of frames: `receipt.video.format` says which). */
22
24
  arrayBuffer(opts?: {
23
25
  signal?: AbortSignal;
24
26
  }): Promise<ArrayBuffer>;
25
- /** Writes the mp4 to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
27
+ /** Writes the file to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
26
28
  save(path: string, opts?: {
27
29
  signal?: AbortSignal;
28
30
  }): Promise<string>;
@@ -92,7 +94,11 @@ export declare class Review implements ReviewData {
92
94
  get ok(): boolean;
93
95
  [Symbol.iterator](): Iterator<ReviewIssue>;
94
96
  }
95
- /** What a document will cost. `String(estimate)` reads like "$0.004, 8 s of 1080p". */
97
+ /**
98
+ * What a document will cost. `String(estimate)` reads like
99
+ * "8 s of 1080p, 2.1 GPU seconds", or "$0.004, 8 s of 1080p" from a server
100
+ * that sets a price.
101
+ */
96
102
  export declare class Estimate implements EstimateData {
97
103
  readonly minutes: number;
98
104
  readonly usd: number | null;
@@ -59,7 +59,7 @@ class Render {
59
59
  get sha256() {
60
60
  return this.receipt.sha256 ?? this.receipt.object?.sha256 ?? undefined;
61
61
  }
62
- /** Size of the mp4 in bytes. */
62
+ /** Size of the file in bytes. */
63
63
  get bytes() {
64
64
  return this.receipt.bytes ?? this.receipt.object?.size ?? this.#inline?.byteLength;
65
65
  }
@@ -73,20 +73,30 @@ class Render {
73
73
  get minutes() {
74
74
  return this.receipt.minutes;
75
75
  }
76
+ /** The file's name: the stored object's, else `film.<format>` (`frames.zip` for an image sequence). */
77
+ get filename() {
78
+ if (this.url) {
79
+ const name = decodeURIComponent(new URL(this.url).pathname.split("/").pop() ?? "");
80
+ if (name.includes("."))
81
+ return name;
82
+ }
83
+ const format = this.receipt.video?.format ?? "mp4";
84
+ return format === "png" || format === "exr" ? "frames.zip" : `film.${format}`;
85
+ }
76
86
  #source() {
77
87
  if (this.url)
78
88
  return this.url;
79
89
  const where = this.receipt.object?.uri;
80
90
  throw new errors_js_1.UltrafastError(where ? `the video went to ${where}, which the server cannot sign a URL for` : "this receipt has no download URL", { code: "not_found" });
81
91
  }
82
- /** The mp4 bytes. */
92
+ /** The file's bytes (an mp4, a webm, a gif, a zip of frames: `receipt.video.format` says which). */
83
93
  async arrayBuffer(opts = {}) {
84
94
  if (this.#inline)
85
95
  return this.#inline.slice().buffer;
86
96
  const res = await this.#transport.download(this.#source(), opts.signal);
87
97
  return res.arrayBuffer();
88
98
  }
89
- /** Writes the mp4 to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
99
+ /** Writes the file to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
90
100
  async save(path, opts = {}) {
91
101
  if (this.#inline)
92
102
  return writeBytes(this.#inline, path);
@@ -235,7 +245,11 @@ class Review {
235
245
  }
236
246
  }
237
247
  exports.Review = Review;
238
- /** What a document will cost. `String(estimate)` reads like "$0.004, 8 s of 1080p". */
248
+ /**
249
+ * What a document will cost. `String(estimate)` reads like
250
+ * "8 s of 1080p, 2.1 GPU seconds", or "$0.004, 8 s of 1080p" from a server
251
+ * that sets a price.
252
+ */
239
253
  class Estimate {
240
254
  minutes;
241
255
  usd;
@@ -260,6 +274,10 @@ class Estimate {
260
274
  if (this.width && this.height)
261
275
  what += ` of ${Math.min(this.width, this.height)}p`;
262
276
  parts.push(what);
277
+ if (typeof this.usd !== "number" && typeof this.gpu_seconds === "number") {
278
+ const n = Number(this.gpu_seconds.toFixed(this.gpu_seconds >= 1 ? 1 : 2));
279
+ parts.push(`${n} GPU second${n === 1 ? "" : "s"}`);
280
+ }
263
281
  return parts.join(", ");
264
282
  }
265
283
  }
@@ -36,9 +36,15 @@ export interface VideoInfo {
36
36
  width: number;
37
37
  height: number;
38
38
  duration: number;
39
- codec: "h264" | "hevc" | (string & {});
39
+ /** `h264`, `hevc`, `av1`, `vp9`, `prores-<profile>`, `gif`, `png`, `exr`, or the sound's codec for sound alone. */
40
+ codec: "h264" | "hevc" | "av1" | "vp9" | "gif" | "png" | "exr" | (string & {});
40
41
  audio: boolean;
41
42
  range: [number, number];
43
+ /** The container: `mp4`, `mov`, `mkv`, `webm`, `gif`, `png`/`exr` (a zipped sequence), or sound alone. */
44
+ format?: string;
45
+ quality?: "draft" | "standard" | "high" | "master";
46
+ /** Set when transparency was kept. */
47
+ alpha?: boolean;
42
48
  }
43
49
  export interface InputRecord {
44
50
  uri: string;
@@ -1,2 +1,2 @@
1
1
  /** This package's version (also in package.json). */
2
- export declare const VERSION = "0.1.1";
2
+ export declare const VERSION = "0.1.2";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** This package's version (also in package.json). */
5
- exports.VERSION = "0.1.1";
5
+ exports.VERSION = "0.1.2";
@@ -2,11 +2,12 @@ import { type FetchLike, Transport } from "./http.js";
2
2
  import { Estimate, Image, Job, Render, Review } from "./results.js";
3
3
  import type { Document } from "./schema.js";
4
4
  import type { Asset, Attempt, CheckResult, Health, Me } from "./types.js";
5
- export declare const DEFAULT_BASE_URL = "https://api.ultrafast.mov";
5
+ /** A local `ultrafast serve` on its default port. */
6
+ export declare const DEFAULT_BASE_URL = "http://127.0.0.1:8080";
6
7
  export interface UltrafastOptions {
7
- /** Default: `ULTRAFAST_API_KEY`. */
8
+ /** Default: `ULTRAFAST_API_KEY` (the key the server prints at first start). */
8
9
  apiKey?: string;
9
- /** Default: `ULTRAFAST_BASE_URL`, else ultrafast Cloud. A self-hosted server: `http://localhost:8080`. */
10
+ /** Default: `ULTRAFAST_BASE_URL`, else `http://127.0.0.1:8080`, a server on this machine. */
10
11
  baseUrl?: string;
11
12
  /** A fetch implementation (default: the global one). */
12
13
  fetch?: FetchLike;
@@ -17,18 +18,49 @@ export interface UltrafastOptions {
17
18
  }
18
19
  /** A document, or the path of a document file (Node). */
19
20
  export type DocumentInput = Document | string;
20
- export interface RenderOptions {
21
- /** The mp4 in the response (at most 32 MiB) instead of stored with a signed URL. */
21
+ /** An output size: `"720p"`, `"1080p"`, `"1440p"`, `"4k"` (the short side), `"WxH"`, or `[w, h]`. */
22
+ export type Size = "720p" | "1080p" | "1440p" | "4k" | `${number}p` | `${number}x${number}` | [number, number];
23
+ /**
24
+ * Export settings, as `ultrafast export` and the MCP export tools spell them.
25
+ * Settings that don't go together are refused before anything renders.
26
+ */
27
+ export interface ExportSettings {
28
+ /** The container (default: from `name`'s extension, else mp4). `png` and `exr` are image sequences (a zip); `wav` to `opus` are sound alone. */
29
+ format?: "mp4" | "mov" | "mkv" | "webm" | "gif" | "png" | "exr" | "wav" | "mp3" | "m4a" | "flac" | "opus";
30
+ /** Default h264 (vp9 for webm). */
31
+ codec?: "h264" | "hevc" | "h265" | "av1" | "vp9" | "prores";
32
+ /** draft: a fast preview without motion blur; standard (default); high; master: twice the motion-blur samples, the best encode. */
33
+ quality?: "draft" | "standard" | "high" | "master";
34
+ /** Rendered at this size, not scaled up. */
35
+ size?: Size;
36
+ /** A multiple of the document's size, instead of `size`. */
37
+ scale?: number;
38
+ /** Output frame rate (default the document's; a GIF's at most 30). */
39
+ fps?: number;
40
+ /** Constant quality on the codec's scale, lower is better (H.264/HEVC 0-51, AV1/VP9 0-63). */
41
+ crf?: number;
42
+ /** Bits per second, or text such as `"8M"`, instead of `crf`; null for the quality level's. */
43
+ bitrate?: number | string | null;
44
+ /** Default hq; 4444 with `alpha`. */
45
+ prores_profile?: "proxy" | "light" | "standard" | "hq" | "4444" | "4444-xq";
46
+ /** Keep transparency: ProRes 4444, VP9, GIF, PNG, EXR. */
47
+ alpha?: boolean;
48
+ /** Mix the document's sound (default true). */
49
+ audio?: boolean;
50
+ /** Default aac (opus for webm, pcm with ProRes). */
51
+ audio_codec?: "aac" | "opus" | "mp3" | "flac" | "pcm" | "pcm-24";
52
+ /** Bits per second, or text such as `"192k"`. */
53
+ audio_bitrate?: number | string;
54
+ /** GIF: times it plays again after the first (0: once; default forever). */
55
+ loops?: number;
56
+ }
57
+ export interface RenderOptions extends ExportSettings {
58
+ /** The file in the response (at most 32 MiB) instead of stored with a signed URL. */
22
59
  inline?: boolean;
23
60
  /** Create the video at this object in your own bucket (`s3://`, `r2://`, `gs://`); create-only. */
24
61
  uri?: string;
25
- /** The stored file's name (default `film.mp4`). */
62
+ /** The stored file's name (default `film.<format>`, `frames.zip` for a sequence); its extension picks the format. */
26
63
  name?: string;
27
- codec?: "h264" | "hevc";
28
- /** Bits per second; null for the format's default. */
29
- bitrate?: number | null;
30
- /** Mix the document's sound (default true). */
31
- audio?: boolean;
32
64
  /** `[from, to]` seconds of the document (default all of it). */
33
65
  range?: [number, number] | null;
34
66
  /** Ids that make retries safe; one is made up per call when missing. */
@@ -92,8 +124,7 @@ export declare class Jobs {
92
124
  cancel(id: string): Promise<Job>;
93
125
  }
94
126
  /**
95
- * A client of the ultrafast render service: ultrafast Cloud, or your own
96
- * `ultrafast serve`.
127
+ * A client of an ultrafast render service: your own `ultrafast serve`.
97
128
  *
98
129
  * ```ts
99
130
  * const uf = new Ultrafast(); // ULTRAFAST_API_KEY
@@ -151,8 +182,12 @@ export declare class Ultrafast {
151
182
  }): Promise<CheckResult>;
152
183
  /** Renders the film and reports what a viewer would trip on. */
153
184
  review(doc: DocumentInput, opts?: ReviewOptions): Promise<Review>;
154
- /** What rendering will cost (free). */
155
- estimate(doc: DocumentInput, opts?: {
185
+ /**
186
+ * What rendering will cost (free). Pass the export settings you will render
187
+ * with (`size`, `quality`, `fps`, ...): minutes count the output size and
188
+ * frames are timed at that quality and frame rate.
189
+ */
190
+ estimate(doc: DocumentInput, opts?: ExportSettings & {
156
191
  range?: [number, number] | null;
157
192
  signal?: AbortSignal;
158
193
  }): Promise<Estimate>;
@@ -3,7 +3,32 @@ import { BASE_DIR, rewriteLocalFiles } from "./files.js";
3
3
  import { Transport } from "./http.js";
4
4
  import { Estimate, Image, Job, Render, Review } from "./results.js";
5
5
  import { contentTypeFor, env, node, randomId } from "./runtime.js";
6
- export const DEFAULT_BASE_URL = "https://api.ultrafast.mov";
6
+ /** A local `ultrafast serve` on its default port. */
7
+ export const DEFAULT_BASE_URL = "http://127.0.0.1:8080";
8
+ const SETTINGS = [
9
+ "format",
10
+ "codec",
11
+ "quality",
12
+ "size",
13
+ "scale",
14
+ "fps",
15
+ "crf",
16
+ "bitrate",
17
+ "prores_profile",
18
+ "alpha",
19
+ "audio",
20
+ "audio_codec",
21
+ "audio_bitrate",
22
+ "loops",
23
+ ];
24
+ /** The export settings among `opts`. */
25
+ function settingsOf(opts) {
26
+ const out = {};
27
+ for (const k of SETTINGS)
28
+ if (opts[k] !== undefined)
29
+ out[k] = opts[k];
30
+ return out;
31
+ }
7
32
  function compact(o) {
8
33
  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
9
34
  }
@@ -50,8 +75,7 @@ export class Jobs {
50
75
  }
51
76
  }
52
77
  /**
53
- * A client of the ultrafast render service: ultrafast Cloud, or your own
54
- * `ultrafast serve`.
78
+ * A client of an ultrafast render service: your own `ultrafast serve`.
55
79
  *
56
80
  * ```ts
57
81
  * const uf = new Ultrafast(); // ULTRAFAST_API_KEY
@@ -121,9 +145,7 @@ export class Ultrafast {
121
145
  inline: opts.inline,
122
146
  uri: opts.uri,
123
147
  name: opts.name,
124
- codec: opts.codec,
125
- bitrate: opts.bitrate,
126
- audio: opts.audio,
148
+ ...settingsOf(opts),
127
149
  range: opts.range,
128
150
  });
129
151
  const body = compact({
@@ -141,7 +163,7 @@ export class Ultrafast {
141
163
  const res = await this.#transport.request({
142
164
  path: "/v1/render",
143
165
  json: body,
144
- accept: opts.inline ? "video/mp4, application/json" : "application/json",
166
+ accept: opts.inline ? "video/mp4, video/*, image/gif, audio/*, application/zip, application/json" : "application/json",
145
167
  // With `uri` a retry is a replay (409 with the stored receipt); without
146
168
  // it a resent render could render twice, so only what the server refused.
147
169
  retry: opts.uri ? "safe" : "unsent",
@@ -156,7 +178,8 @@ export class Ultrafast {
156
178
  throw errorFromResponse(409, text);
157
179
  }
158
180
  const type = res.headers.get("content-type") ?? "";
159
- if (type.startsWith("video/") || type === "application/octet-stream") {
181
+ // Inline: the file itself (an mp4, a webm, a gif, a zip of frames, sound).
182
+ if (type !== "" && !type.startsWith("application/json")) {
160
183
  const bytes = new Uint8Array(await res.arrayBuffer());
161
184
  const receipt = (parseJson(res.headers.get("x-ultrafast-receipt")) ?? { receipt_version: 1, status: "rendered" });
162
185
  receipt.sha256 ??= res.headers.get("x-ultrafast-sha256") ?? undefined;
@@ -200,12 +223,17 @@ export class Ultrafast {
200
223
  });
201
224
  return new Review(data);
202
225
  }
203
- /** What rendering will cost (free). */
226
+ /**
227
+ * What rendering will cost (free). Pass the export settings you will render
228
+ * with (`size`, `quality`, `fps`, ...): minutes count the output size and
229
+ * frames are timed at that quality and frame rate.
230
+ */
204
231
  async estimate(doc, opts = {}) {
205
232
  const document = await this.prepare(doc);
233
+ const output = settingsOf(opts);
206
234
  const data = await this.#transport.json({
207
235
  path: "/v1/estimate",
208
- json: { document, range: opts.range ?? null },
236
+ json: compact({ document, range: opts.range ?? null, output: Object.keys(output).length ? output : undefined }),
209
237
  signal: opts.signal,
210
238
  });
211
239
  return new Estimate(data);
@@ -1,5 +1,5 @@
1
1
  export { Ultrafast, Jobs, DEFAULT_BASE_URL } from "./client.js";
2
- export type { UltrafastOptions, DocumentInput, RenderOptions, JobOptions, FrameOptions, SheetOptions, ReviewOptions, UploadOptions, UploadInput, } from "./client.js";
2
+ export type { UltrafastOptions, DocumentInput, RenderOptions, ExportSettings, Size, JobOptions, FrameOptions, SheetOptions, ReviewOptions, UploadOptions, UploadInput, } from "./client.js";
3
3
  export { Render, Job, Image, Review, Estimate } from "./results.js";
4
4
  export type { WaitOptions } from "./results.js";
5
5
  export { verifyWebhook, WebhookVerificationError } from "./webhooks.js";
@@ -12,17 +12,19 @@ export declare class Render {
12
12
  /** Signed download URL (null for an inline render, or a bucket the server cannot sign for). */
13
13
  get url(): string | null;
14
14
  get sha256(): string | undefined;
15
- /** Size of the mp4 in bytes. */
15
+ /** Size of the file in bytes. */
16
16
  get bytes(): number | undefined;
17
17
  /** Seconds of video. */
18
18
  get duration(): number | undefined;
19
19
  get frames(): number | undefined;
20
20
  get minutes(): number | undefined;
21
- /** The mp4 bytes. */
21
+ /** The file's name: the stored object's, else `film.<format>` (`frames.zip` for an image sequence). */
22
+ get filename(): string;
23
+ /** The file's bytes (an mp4, a webm, a gif, a zip of frames: `receipt.video.format` says which). */
22
24
  arrayBuffer(opts?: {
23
25
  signal?: AbortSignal;
24
26
  }): Promise<ArrayBuffer>;
25
- /** Writes the mp4 to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
27
+ /** Writes the file to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
26
28
  save(path: string, opts?: {
27
29
  signal?: AbortSignal;
28
30
  }): Promise<string>;
@@ -92,7 +94,11 @@ export declare class Review implements ReviewData {
92
94
  get ok(): boolean;
93
95
  [Symbol.iterator](): Iterator<ReviewIssue>;
94
96
  }
95
- /** What a document will cost. `String(estimate)` reads like "$0.004, 8 s of 1080p". */
97
+ /**
98
+ * What a document will cost. `String(estimate)` reads like
99
+ * "8 s of 1080p, 2.1 GPU seconds", or "$0.004, 8 s of 1080p" from a server
100
+ * that sets a price.
101
+ */
96
102
  export declare class Estimate implements EstimateData {
97
103
  readonly minutes: number;
98
104
  readonly usd: number | null;
@@ -54,7 +54,7 @@ export class Render {
54
54
  get sha256() {
55
55
  return this.receipt.sha256 ?? this.receipt.object?.sha256 ?? undefined;
56
56
  }
57
- /** Size of the mp4 in bytes. */
57
+ /** Size of the file in bytes. */
58
58
  get bytes() {
59
59
  return this.receipt.bytes ?? this.receipt.object?.size ?? this.#inline?.byteLength;
60
60
  }
@@ -68,20 +68,30 @@ export class Render {
68
68
  get minutes() {
69
69
  return this.receipt.minutes;
70
70
  }
71
+ /** The file's name: the stored object's, else `film.<format>` (`frames.zip` for an image sequence). */
72
+ get filename() {
73
+ if (this.url) {
74
+ const name = decodeURIComponent(new URL(this.url).pathname.split("/").pop() ?? "");
75
+ if (name.includes("."))
76
+ return name;
77
+ }
78
+ const format = this.receipt.video?.format ?? "mp4";
79
+ return format === "png" || format === "exr" ? "frames.zip" : `film.${format}`;
80
+ }
71
81
  #source() {
72
82
  if (this.url)
73
83
  return this.url;
74
84
  const where = this.receipt.object?.uri;
75
85
  throw new UltrafastError(where ? `the video went to ${where}, which the server cannot sign a URL for` : "this receipt has no download URL", { code: "not_found" });
76
86
  }
77
- /** The mp4 bytes. */
87
+ /** The file's bytes (an mp4, a webm, a gif, a zip of frames: `receipt.video.format` says which). */
78
88
  async arrayBuffer(opts = {}) {
79
89
  if (this.#inline)
80
90
  return this.#inline.slice().buffer;
81
91
  const res = await this.#transport.download(this.#source(), opts.signal);
82
92
  return res.arrayBuffer();
83
93
  }
84
- /** Writes the mp4 to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
94
+ /** Writes the file to `path` (Node), streaming the download and checking its sha256. Resolves with `path`. */
85
95
  async save(path, opts = {}) {
86
96
  if (this.#inline)
87
97
  return writeBytes(this.#inline, path);
@@ -226,7 +236,11 @@ export class Review {
226
236
  return this.issues[Symbol.iterator]();
227
237
  }
228
238
  }
229
- /** What a document will cost. `String(estimate)` reads like "$0.004, 8 s of 1080p". */
239
+ /**
240
+ * What a document will cost. `String(estimate)` reads like
241
+ * "8 s of 1080p, 2.1 GPU seconds", or "$0.004, 8 s of 1080p" from a server
242
+ * that sets a price.
243
+ */
230
244
  export class Estimate {
231
245
  minutes;
232
246
  usd;
@@ -251,6 +265,10 @@ export class Estimate {
251
265
  if (this.width && this.height)
252
266
  what += ` of ${Math.min(this.width, this.height)}p`;
253
267
  parts.push(what);
268
+ if (typeof this.usd !== "number" && typeof this.gpu_seconds === "number") {
269
+ const n = Number(this.gpu_seconds.toFixed(this.gpu_seconds >= 1 ? 1 : 2));
270
+ parts.push(`${n} GPU second${n === 1 ? "" : "s"}`);
271
+ }
254
272
  return parts.join(", ");
255
273
  }
256
274
  }
@@ -36,9 +36,15 @@ export interface VideoInfo {
36
36
  width: number;
37
37
  height: number;
38
38
  duration: number;
39
- codec: "h264" | "hevc" | (string & {});
39
+ /** `h264`, `hevc`, `av1`, `vp9`, `prores-<profile>`, `gif`, `png`, `exr`, or the sound's codec for sound alone. */
40
+ codec: "h264" | "hevc" | "av1" | "vp9" | "gif" | "png" | "exr" | (string & {});
40
41
  audio: boolean;
41
42
  range: [number, number];
43
+ /** The container: `mp4`, `mov`, `mkv`, `webm`, `gif`, `png`/`exr` (a zipped sequence), or sound alone. */
44
+ format?: string;
45
+ quality?: "draft" | "standard" | "high" | "master";
46
+ /** Set when transparency was kept. */
47
+ alpha?: boolean;
42
48
  }
43
49
  export interface InputRecord {
44
50
  uri: string;
@@ -1,2 +1,2 @@
1
1
  /** This package's version (also in package.json). */
2
- export declare const VERSION = "0.1.1";
2
+ export declare const VERSION = "0.1.2";
@@ -1,2 +1,2 @@
1
1
  /** This package's version (also in package.json). */
2
- export const VERSION = "0.1.1";
2
+ export const VERSION = "0.1.2";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ultrafastmov",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "TypeScript client for ultrafast, the GPU video engine: render, frame, sheet, check, review, estimate and upload",
5
5
  "license": "(Apache-2.0 OR MIT)",
6
6
  "homepage": "https://ultrafast.mov",