@parcha/pi-browser 0.1.0-beta.32 → 0.1.0-beta.34

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 (49) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/NOTICE +30 -0
  3. package/README.md +28 -178
  4. package/dist/core/contract.js +14 -5
  5. package/dist/core/custody.d.ts +6 -0
  6. package/dist/core/custody.js +6 -0
  7. package/dist/core/driving-guard.js +17 -2
  8. package/dist/core/host.d.ts +2 -2
  9. package/dist/core/tools.d.ts +9 -0
  10. package/dist/driver/cdp.d.ts +6 -0
  11. package/dist/driver/cdp.js +245 -0
  12. package/dist/driver/page-driver.js +29 -3
  13. package/dist/durable/store.js +13 -4
  14. package/dist/durable.d.ts +1 -0
  15. package/dist/durable.js +1 -0
  16. package/dist/live-view/provider.d.ts +2 -2
  17. package/dist/live-view/provider.js +2 -2
  18. package/dist/live-view/server.d.ts +1 -1
  19. package/dist/providers/chrome-args.d.ts +3 -0
  20. package/dist/providers/chrome-args.js +13 -2
  21. package/dist/vendor/browser-use-pi/ax.d.ts +106 -0
  22. package/dist/vendor/browser-use-pi/ax.js +642 -0
  23. package/dist/vendor/browser-use-pi/cdp.d.ts +19 -0
  24. package/dist/vendor/browser-use-pi/cdp.js +106 -0
  25. package/dist/vendor/browser-use-pi/page.d.ts +38 -0
  26. package/dist/vendor/browser-use-pi/page.js +112 -0
  27. package/package.json +6 -24
  28. package/src/vendor/browser-use-pi/UPSTREAM.json +25 -0
  29. package/src/vendor/stagehand-facade/UPSTREAM.json +0 -4
  30. package/dist/coding-agent-local.d.ts +0 -12
  31. package/dist/coding-agent-local.js +0 -72
  32. package/dist/coding-agent.d.ts +0 -135
  33. package/dist/coding-agent.js +0 -641
  34. package/dist/providers/assigned.d.ts +0 -18
  35. package/dist/providers/assigned.js +0 -75
  36. package/dist/recorder/credential.d.ts +0 -9
  37. package/dist/recorder/credential.js +0 -49
  38. package/dist/recorder/follow.d.ts +0 -36
  39. package/dist/recorder/follow.js +0 -163
  40. package/dist/recorder/frames.d.ts +0 -87
  41. package/dist/recorder/frames.js +0 -377
  42. package/dist/recorder/index.d.ts +0 -4
  43. package/dist/recorder/index.js +0 -7
  44. package/dist/recorder/jpeg.d.ts +0 -8
  45. package/dist/recorder/jpeg.js +0 -70
  46. package/dist/recorder/track.d.ts +0 -107
  47. package/dist/recorder/track.js +0 -280
  48. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +0 -15
  49. package/dist/vendor/stagehand-facade/screenshot-transport.js +0 -51
@@ -1,377 +0,0 @@
1
- import { createHash } from "node:crypto";
2
- import { CREDENTIAL_PROBE } from "./credential.js";
3
- import { followPage } from "./follow.js";
4
- import { jpegSize } from "./jpeg.js";
5
- const MAX_QUEUED_LINES = 32;
6
- /** The conversation id in a lease tag: `ar-<run>-<conversation>-<n>`. */
7
- const tagConversation = (tag) => { const m = /-(\d+)-\d+$/.exec(tag); return m ? Number(m[1]) : null; };
8
- /** One session asks its page at most 1000 / PROBE_GAP_MS = 20 times a second: arrival checks and delivery checks share one pace, each sent at least this far after the last. */
9
- const PROBE_GAP_MS = 50;
10
- /** While the host holds a session, the hold is asked again this often (nothing else asks when the page does not repaint), so its lifting is seen. */
11
- const HOLD_POLL_MS = 500;
12
- export function frameRecorder(options) {
13
- const maxFps = Math.max(1, Math.min(10, options.maxFps ?? 10));
14
- const maxWidth = Math.min(800, options.maxWidth ?? 800);
15
- const quality = options.quality ?? 60;
16
- const spacingMs = Math.ceil(1000 / maxFps);
17
- const captures = new Map();
18
- const made = new Set();
19
- const counts = { frames: 0, gaps: 0, dropped: 0 };
20
- const sinkTimeoutMs = options.sinkTimeoutMs ?? 5_000;
21
- const pclock = options.probeClock ?? { now: () => performance.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) };
22
- let closed = false;
23
- // Lines reach the sink one at a time, in the order they were made, and a write is never left behind: the next one starts only when the
24
- // one before has ended. A line the sink has not stored within sinkTimeoutMs of being made counts as dropped (its write, if it had started,
25
- // may still land, but nothing is written after it until it does); one whose turn comes after that is not written at all. A sink that never
26
- // answers leaves one unfinished write and at most MAX_QUEUED_LINES lines waiting; the rest are dropped at once.
27
- let queue = Promise.resolve();
28
- let queued = 0;
29
- /** The timers of lines waiting or being written: unreferenced while the process lives on its own, referenced once `close` waits on them. */
30
- const sinkTimers = new Set();
31
- /** `make` builds the line when its turn comes (a gap reads the last frame that was saved by then). */
32
- const emit = (make, withhold) => {
33
- if (queued >= MAX_QUEUED_LINES) {
34
- counts.dropped += 1;
35
- return Promise.resolve(false);
36
- }
37
- queued += 1;
38
- let abandoned = false;
39
- let answered = false;
40
- let answer = () => { };
41
- const result = new Promise((resolve) => { answer = (ok, counted = true) => { if (answered)
42
- return; answered = true; if (!ok && counted)
43
- counts.dropped += 1; resolve(ok); }; });
44
- const timer = setTimeout(() => { abandoned = true; answer(false); }, sinkTimeoutMs);
45
- sinkTimers.add(timer);
46
- if (closed)
47
- timer.ref?.();
48
- else
49
- timer.unref?.();
50
- queue = queue.then(async () => {
51
- try {
52
- if (abandoned)
53
- return;
54
- // The last step before the write: a frame that waited behind another session's slow write is judged by the hold as it is now, not as it was when it was queued.
55
- if (withhold?.()) {
56
- answer(false, false);
57
- return;
58
- }
59
- const [line, blobs] = make();
60
- await options.sink(line, blobs);
61
- answer(true); // too late to count when the timeout already answered
62
- }
63
- catch {
64
- answer(false);
65
- }
66
- finally {
67
- clearTimeout(timer);
68
- sinkTimers.delete(timer);
69
- queued -= 1;
70
- }
71
- });
72
- return result;
73
- };
74
- const base = (c, t) => ({ channel: "live", source: "browser", t, ...(options.gen ? { gen: options.gen() } : {}), conv: c.conv });
75
- const gap = (c, reason, from, detail) => {
76
- const t = options.clock();
77
- return emit(() => [{ ...base(c, t), kind: "frame.gap", data: { session: c.ref.id, from: from ?? c.lastFrameT ?? t, reason, ...(detail ? { detail } : {}) } }]).then((ok) => { if (ok)
78
- counts.gaps += 1; });
79
- };
80
- /** A credential may be on the page: the capture pauses, once, until the page navigates and the check is clean. */
81
- const hold = (c, why) => {
82
- c.ready = null;
83
- c.waiting = null;
84
- if (c.paused)
85
- return;
86
- c.paused = true;
87
- c.navigated = false;
88
- void gap(c, "credential_on_page", undefined, why ?? "field");
89
- };
90
- /** The host's hold, read now. A hold that throws is a hold (a host that cannot say is not asked twice); anything but `true` is none. The first read of a span writes its one gap;
91
- * the read that finds it over ends it. */
92
- const held = (c) => {
93
- if (!options.hold)
94
- return false;
95
- let on;
96
- try {
97
- on = options.hold(c.ref) === true;
98
- }
99
- catch {
100
- on = true;
101
- }
102
- if (!on) {
103
- if (c.hostHeld) {
104
- c.hostHeld = false;
105
- lifted(c);
106
- }
107
- return false;
108
- }
109
- if (!c.hostHeld) {
110
- c.hostHeld = true;
111
- if (!c.stopped) {
112
- void gap(c, "credential_on_page", undefined, "host");
113
- watchHold(c);
114
- }
115
- }
116
- return true;
117
- };
118
- const watchHold = (c) => {
119
- if (c.holdTimer)
120
- return;
121
- c.holdTimer = setInterval(() => { if (c.stopped || closed)
122
- stopWatching(c);
123
- else
124
- held(c); }, HOLD_POLL_MS);
125
- c.holdTimer.unref?.();
126
- };
127
- const stopWatching = (c) => { if (c.holdTimer)
128
- clearInterval(c.holdTimer); c.holdTimer = null; };
129
- /** The hold was true and is not: the screencast sends a frame only when the page repaints, and a person's login has often already left the page, so the replay would end at the hold. One frame of the page as it is
130
- * now is asked for and judged like any other (a field still holding a value makes it the credential gap, not a frame). A failed capture costs this frame: the next screencast frame covers it. */
131
- const lifted = (c) => { stopWatching(c); void captureNow(c); };
132
- const captureNow = async (c) => {
133
- const follower = c.follower;
134
- if (!follower || c.stopped)
135
- return;
136
- try {
137
- const seen = c.frameSeq;
138
- const frame = await follower.capture();
139
- // A screencast frame that came while the capture was in flight is a newer picture of the page: the late capture is dropped, so the replay never jumps back.
140
- if (c.stopped || c.follower !== follower || c.frameSeq !== seen)
141
- return;
142
- c.waiting = frame;
143
- judge(c);
144
- }
145
- catch { /* no capture this time */ }
146
- };
147
- const check = async (c) => {
148
- try {
149
- options.onProbe?.(pclock.now());
150
- const answer = (await c.follower?.evaluate(CREDENTIAL_PROBE));
151
- return answer && typeof answer.hold === "boolean" ? { hold: answer.hold, why: typeof answer.why === "string" ? answer.why : null } : "unchecked";
152
- }
153
- catch {
154
- return "unchecked";
155
- } // a page that cannot be checked is not recorded
156
- };
157
- /** Every check of the page goes through here, one at a time: it is sent no earlier than PROBE_GAP_MS after the last one was sent, measured at the
158
- * send, so a wait that ended late cannot be followed by one that ends on time and lands closer. Any half-open second then holds at most 20. */
159
- const paced = (c, send) => {
160
- let result;
161
- c.pacing = c.pacing.then(async () => {
162
- for (;;) {
163
- const wait = c.lastProbeAt + PROBE_GAP_MS - pclock.now();
164
- if (wait <= 0)
165
- break;
166
- await pclock.sleep(wait);
167
- }
168
- c.lastProbeAt = pclock.now();
169
- result = send();
170
- }).catch(() => { result ??= Promise.reject(new Error("the check was not sent")); });
171
- return c.pacing.then(() => result);
172
- };
173
- const arm = (c) => {
174
- if (c.timer || c.busy || c.stopped || !c.ready)
175
- return;
176
- c.timer = setTimeout(() => { c.timer = null; void deliver(c); }, Math.max(0, spacingMs - (Date.now() - c.lastEmitMs)));
177
- c.timer.unref?.();
178
- };
179
- /** A frame is judged against the page the moment it arrives: the check that follows it stands for the page at its capture. A frame that
180
- * arrives while a check runs waits for the next one; the one judged last is the one kept. */
181
- function judge(c) {
182
- if (c.probing || c.stopped || !c.waiting || !c.follower)
183
- return;
184
- c.probing = true;
185
- let frame = null;
186
- // The frame is the newest one when the check is sent: one that came while it waited for its turn replaces the older.
187
- void paced(c, async () => { frame = c.waiting; c.waiting = null; return c.stopped || !frame ? null : check(c); })
188
- .then((verdict) => { if (verdict === null || !frame)
189
- c.probing = false;
190
- else
191
- settle(c, frame, verdict); }, () => { c.probing = false; });
192
- }
193
- function settle(c, frame, verdict) {
194
- c.probing = false;
195
- if (c.stopped)
196
- return;
197
- if (c.follower?.epoch() === frame.page.epoch) {
198
- if (verdict !== "unchecked" && verdict.hold)
199
- hold(c, verdict.why);
200
- else if (verdict !== "unchecked") {
201
- frame.verdict = verdict;
202
- c.ready = frame;
203
- }
204
- }
205
- judge(c);
206
- arm(c);
207
- }
208
- /** The judged frame whose turn has come: checked again now (a credential seen between its capture and now drops it), then kept. */
209
- async function deliver(c) {
210
- if (c.busy || c.stopped || !c.ready || !c.follower)
211
- return;
212
- c.busy = true;
213
- // The slot is taken when the check starts, so the next frame is a full spacing after this one whatever the check costs.
214
- c.lastEmitMs = Date.now();
215
- const frame = c.ready;
216
- c.ready = null;
217
- try {
218
- const verdict = await paced(c, async () => (c.stopped ? "unchecked" : check(c)));
219
- if (c.stopped)
220
- return;
221
- // A frame belongs to the page it showed: one held across a navigation or a move to another page is not kept.
222
- if (c.follower?.epoch() !== frame.page.epoch)
223
- return;
224
- if (verdict === "unchecked")
225
- return;
226
- if (verdict.hold) {
227
- hold(c, verdict.why);
228
- return;
229
- }
230
- // A pause lifts at a navigation, once the page holds no credential.
231
- if (c.paused) {
232
- if (!c.navigated)
233
- return;
234
- c.paused = false;
235
- }
236
- const size = jpegSize(frame.bytes) ?? (frame.page.deviceWidth > 0 ? { w: Math.min(frame.page.deviceWidth, maxWidth), h: Math.round(Math.min(frame.page.deviceWidth, maxWidth) * (frame.page.deviceHeight / frame.page.deviceWidth)) } : null);
237
- if (!size)
238
- return;
239
- const hash = createHash("sha256").update(frame.bytes).digest("hex");
240
- const t = options.clock();
241
- const saved = await emit(() => [{ ...base(c, t), kind: "frame", data: { session: c.ref.id, provider: c.provider, w: size.w, h: size.h, mime: "image/jpeg" }, blobs: [hash] }, { [hash]: new Uint8Array(frame.bytes) }], () => held(c));
242
- if (saved) {
243
- counts.frames += 1;
244
- c.lastFrameT = t;
245
- }
246
- c.lastEmitMs = Date.now();
247
- }
248
- finally {
249
- c.busy = false;
250
- arm(c);
251
- }
252
- }
253
- function connect(c, url) {
254
- c.follower = followPage(url, {
255
- frame(bytes, page) {
256
- if (c.stopped)
257
- return;
258
- c.frameSeq += 1;
259
- // The newest frame wins: an older one still held is not worth keeping.
260
- if (held(c))
261
- return;
262
- c.waiting = { bytes, page };
263
- judge(c);
264
- },
265
- navigated() { c.navigated = true; },
266
- closed() {
267
- c.follower = null;
268
- if (c.stopped || closed)
269
- return;
270
- c.reconnect = setTimeout(() => { c.reconnect = null; if (!c.stopped && !closed)
271
- connect(c, url); }, 1_000);
272
- c.reconnect.unref?.();
273
- },
274
- }, { maxWidth, maxHeight: 2_000, quality });
275
- }
276
- function start(ref, url, provider, conv) {
277
- if (closed)
278
- return;
279
- const owner = conv ?? tagConversation(ref.tag);
280
- if (owner === null || owner === undefined)
281
- return;
282
- if (captures.get(ref.id))
283
- return;
284
- const c = { ref, conv: owner, provider: provider.name, follower: null, lastFrameT: null, paused: false, navigated: false, hostHeld: false, holdTimer: null, frameSeq: 0, ready: null, waiting: null, probing: false, lastProbeAt: -Infinity, pacing: Promise.resolve(), busy: false, timer: null, lastEmitMs: 0, stopped: false, reconnect: null };
285
- captures.set(ref.id, c);
286
- // A session first seen in this process that an earlier process already framed: the frames stopped when that process was killed.
287
- if (!made.has(ref.id)) {
288
- const from = options.lastFrameAt?.(ref.id) ?? null;
289
- if (from !== null) {
290
- c.lastFrameT = from;
291
- void gap(c, "process_killed", from);
292
- }
293
- }
294
- connect(c, url);
295
- }
296
- function stop(c) {
297
- c.stopped = true;
298
- if (c.timer)
299
- clearTimeout(c.timer);
300
- if (c.reconnect)
301
- clearTimeout(c.reconnect);
302
- stopWatching(c);
303
- c.timer = null;
304
- c.reconnect = null;
305
- c.ready = null;
306
- c.waiting = null;
307
- c.follower?.close();
308
- c.follower = null;
309
- captures.delete(c.ref.id);
310
- }
311
- return {
312
- watch(provider, conv) {
313
- const watched = Object.create(provider);
314
- watched.create = async (spec, signal) => {
315
- const ref = await provider.create(spec, signal);
316
- made.add(ref.id);
317
- return ref;
318
- };
319
- watched.attach = async (ref, signal) => {
320
- const target = await provider.attach(ref, signal);
321
- start(ref, target.sdkCdpUrl, provider, conv);
322
- return target;
323
- };
324
- watched.release = async (ref, signal) => {
325
- // The capture ends when the provider says the session is released: one it refuses to release is still running, and still recorded.
326
- await provider.release(ref, signal);
327
- const c = captures.get(ref.id);
328
- if (c) {
329
- stop(c);
330
- void gap(c, "session_released");
331
- } // storage is not the browser call's to wait for: close() flushes
332
- else if (!closed) {
333
- // A release made by a process that never captured the session (a later one finishing an earlier one's release): the tile
334
- // ended where an earlier process's frames stopped.
335
- const from = options.lastFrameAt?.(ref.id) ?? null;
336
- const owner = conv ?? tagConversation(ref.tag);
337
- if (from !== null && owner !== null)
338
- void gap({ ref, conv: owner, lastFrameT: from }, "session_released");
339
- }
340
- };
341
- return watched;
342
- },
343
- pause(session) {
344
- const c = captures.get(session);
345
- if (!c || c.paused)
346
- return;
347
- c.paused = true;
348
- c.navigated = false;
349
- void gap(c, "credential_on_page", undefined, "host");
350
- },
351
- resume(session) {
352
- const c = captures.get(session);
353
- if (c) {
354
- c.paused = false;
355
- judge(c);
356
- arm(c);
357
- }
358
- },
359
- stats: () => ({ ...counts, sessions: captures.size }),
360
- async close() {
361
- closed = true;
362
- for (const t of sinkTimers)
363
- t.ref?.();
364
- for (const c of [...captures.values()])
365
- stop(c);
366
- // What was already handed over is delivered first, for as long as the sink answers: every line has its own timeout, and a sink that
367
- // never answers is not waited on past one.
368
- let giveUp;
369
- try {
370
- await Promise.race([queue, new Promise((resolve) => { giveUp = setTimeout(resolve, sinkTimeoutMs + 50); })]);
371
- }
372
- finally {
373
- clearTimeout(giveUp);
374
- }
375
- },
376
- };
377
- }
@@ -1,4 +0,0 @@
1
- export { frameRecorder, type FrameData, type FrameGapData, type FrameLine, type FrameRecorder, type FrameRecorderOptions, type FrameSink } from "./frames.js";
2
- export { CREDENTIAL_PROBE } from "./credential.js";
3
- export { jpegSize } from "./jpeg.js";
4
- export { exportFrameTracks, planTrack, TrackExportError, type FrameTrackData, type FrameTrackLine, type Track, type TrackFrame, type TrackGap, type TrackIndex, type TrackOptions, type TrackPlan, type TrackSegment } from "./track.js";
@@ -1,7 +0,0 @@
1
- // The host-side frame recorder: it screencasts each browser session over DevTools and hands agentrun.recording/1's `frame` and
2
- // `frame.gap` lines, with the JPEG blobs, to a sink the host passes. It is read-only beside the session's own connections and writes
3
- // nothing of its own.
4
- export { frameRecorder } from "./frames.js";
5
- export { CREDENTIAL_PROBE } from "./credential.js";
6
- export { jpegSize } from "./jpeg.js";
7
- export { exportFrameTracks, planTrack, TrackExportError } from "./track.js";
@@ -1,8 +0,0 @@
1
- /** The pixel size a JPEG states in its first start-of-frame segment, or null when it states none. */
2
- export declare function jpegSize(bytes: Uint8Array): {
3
- w: number;
4
- h: number;
5
- } | null;
6
- /** The sampling factors the first start-of-frame segment states for each component, as hex pairs joined by commas ("22,11,11" is 4:2:0, the layout
7
- * a browser's JPEG has; "11" is grayscale), or null when it states none. */
8
- export declare function jpegSampling(bytes: Uint8Array): string | null;
@@ -1,70 +0,0 @@
1
- /** The pixel size a JPEG states in its first start-of-frame segment, or null when it states none. */
2
- export function jpegSize(bytes) {
3
- if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
4
- return null;
5
- let at = 2;
6
- while (at + 4 <= bytes.length) {
7
- if (bytes[at] !== 0xff) {
8
- at += 1;
9
- continue;
10
- }
11
- const marker = bytes[at + 1];
12
- if (marker === 0xff) {
13
- at += 1;
14
- continue;
15
- }
16
- if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
17
- at += 2;
18
- continue;
19
- }
20
- if (marker === 0xd9 || marker === 0xda)
21
- return null;
22
- const length = (bytes[at + 2] << 8) | bytes[at + 3];
23
- // C0..CF are start-of-frame markers, except C4 (tables), C8 (reserved) and CC (arithmetic conditioning).
24
- if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
25
- if (at + 9 > bytes.length)
26
- return null;
27
- const h = (bytes[at + 5] << 8) | bytes[at + 6];
28
- const w = (bytes[at + 7] << 8) | bytes[at + 8];
29
- return w > 0 && h > 0 ? { w, h } : null;
30
- }
31
- at += 2 + length;
32
- }
33
- return null;
34
- }
35
- /** The sampling factors the first start-of-frame segment states for each component, as hex pairs joined by commas ("22,11,11" is 4:2:0, the layout
36
- * a browser's JPEG has; "11" is grayscale), or null when it states none. */
37
- export function jpegSampling(bytes) {
38
- if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
39
- return null;
40
- let at = 2;
41
- while (at + 4 <= bytes.length) {
42
- if (bytes[at] !== 0xff) {
43
- at += 1;
44
- continue;
45
- }
46
- const marker = bytes[at + 1];
47
- if (marker === 0xff) {
48
- at += 1;
49
- continue;
50
- }
51
- if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
52
- at += 2;
53
- continue;
54
- }
55
- if (marker === 0xd9 || marker === 0xda)
56
- return null;
57
- const length = (bytes[at + 2] << 8) | bytes[at + 3];
58
- if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
59
- const count = bytes[at + 9];
60
- if (count === undefined || count < 1 || at + 10 + count * 3 > bytes.length)
61
- return null;
62
- const factors = [];
63
- for (let i = 0; i < count; i += 1)
64
- factors.push(bytes[at + 10 + i * 3 + 1].toString(16).padStart(2, "0"));
65
- return factors.join(",");
66
- }
67
- at += 2 + length;
68
- }
69
- return null;
70
- }
@@ -1,107 +0,0 @@
1
- /** `frame.track`: written at export, one per session. The blobs are the WebM and its index, in that order. */
2
- export type FrameTrackData = {
3
- session: string;
4
- fps: number;
5
- from: number;
6
- to: number;
7
- };
8
- export type FrameTrackLine = {
9
- channel: "live";
10
- source: "browser";
11
- kind: "frame.track";
12
- t: number;
13
- conv: number;
14
- data: FrameTrackData;
15
- blobs: [string, string];
16
- };
17
- /** One stretch of the track: a frame shown, or the slate (`sha256` null) while the session had no frame to show. Times are the recording's. */
18
- export type TrackSegment = {
19
- start: number;
20
- end: number;
21
- sha256: string | null;
22
- reason?: string;
23
- };
24
- export type TrackFrame = {
25
- t: number;
26
- ms: number;
27
- sha256: string;
28
- w: number;
29
- h: number;
30
- };
31
- export type TrackGap = {
32
- from: number;
33
- to: number;
34
- reason: string;
35
- detail?: string;
36
- };
37
- export type TrackPlan = {
38
- session: string;
39
- conv: number;
40
- fps: number;
41
- from: number;
42
- to: number;
43
- width: number;
44
- height: number;
45
- segments: TrackSegment[];
46
- frames: TrackFrame[];
47
- gaps: TrackGap[];
48
- };
49
- /** The index blob: where each frame and each gap is, so a viewer maps a time in the recording (`t`) to a time in the video (`t - from`). */
50
- export type TrackIndex = {
51
- version: 1;
52
- session: string;
53
- fps: number;
54
- from: number;
55
- to: number;
56
- width: number;
57
- height: number;
58
- codec: "vp9";
59
- frames: TrackFrame[];
60
- gaps: TrackGap[];
61
- };
62
- export declare class TrackExportError extends Error {
63
- readonly code: "ffmpeg_missing" | "ffmpeg_failed" | "ffmpeg_timeout" | "aborted";
64
- constructor(code: TrackExportError["code"], message: string);
65
- }
66
- /** The timeline of one session's lines. Each frame is shown until the next one; a gap puts the slate up (from the moment it was written, except
67
- * `process_killed`, which starts at the last frame the earlier process saved: nothing is known after it) until the next frame or the end.
68
- * Null when the session has no frame. `skip` names frames whose picture could not be read: they show the slate and are not listed. */
69
- export declare function planTrack(lines: Iterable<unknown>, options?: {
70
- fps?: number;
71
- endAt?: number;
72
- skip?: ReadonlySet<string>;
73
- }): TrackPlan | null;
74
- export type TrackOptions = {
75
- /** The recording's lines; `frame` and `frame.gap` of every session are read, anything else is ignored. */
76
- lines: Iterable<unknown>;
77
- /** The bytes of a blob by its sha256 (the JPEG a `frame` line names); null or a throw: not there. */
78
- readBlob: (sha256: string) => Uint8Array | null | undefined | Promise<Uint8Array | null | undefined>;
79
- fps?: number;
80
- /** When the recording ended, in its own ms: the last frame or slate is shown until then. */
81
- endAt?: number;
82
- /** The program to start; default `ffmpeg` on the PATH. */
83
- ffmpeg?: string;
84
- /** For each session's encoding; default 120 s. */
85
- timeoutMs?: number;
86
- signal?: AbortSignal;
87
- };
88
- export type Track = {
89
- line: FrameTrackLine;
90
- /** The video and the index, by sha256: the host keeps the first as `blobs/<sha256>.webm` and the second as `blobs/<sha256>.json`. */
91
- blobs: Record<string, Uint8Array>;
92
- files: {
93
- webm: string;
94
- index: string;
95
- };
96
- index: TrackIndex;
97
- /** Frames the track could not use, shown as the slate: `missing` (no such blob), `hash_mismatch`, `not_a_jpeg`. */
98
- skipped: Array<{
99
- sha256: string;
100
- reason: "missing" | "hash_mismatch" | "not_a_jpeg";
101
- }>;
102
- };
103
- /** One WebM (VP9) and one index per session that has a frame. A session's pictures are read one at a time and written straight to a private temporary
104
- * directory made for the session and removed after, so memory holds one picture at a time (not every picture of the recording), and ffmpeg reads
105
- * only files there: it is started with a short environment, not given a URL, and nothing it writes reaches the recording but the video. `readBlob`
106
- * may be asked for the same blob again by another session. */
107
- export declare function exportFrameTracks(options: TrackOptions): Promise<Track[]>;