@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.14
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/CHANGELOG.md +7 -0
- package/README.md +27 -8
- package/dist/coding-agent.d.ts +1 -0
- package/dist/coding-agent.js +5 -3
- package/dist/core/contract.js +1 -1
- package/dist/core/custody.d.ts +9 -3
- package/dist/core/custody.js +13 -9
- package/dist/core/failures.d.ts +8 -0
- package/dist/core/failures.js +18 -9
- package/dist/core/guard.d.ts +1 -1
- package/dist/core/guard.js +2 -1
- package/dist/core/host.d.ts +51 -2
- package/dist/core/tools.d.ts +37 -2
- package/dist/core/tools.js +84 -54
- package/dist/core/usage.d.ts +1 -20
- package/dist/driver/extension-worker.d.ts +6 -0
- package/dist/driver/extension-worker.js +121 -0
- package/dist/driver/stagehand.js +1 -51
- package/dist/durable.d.ts +7 -3
- package/dist/durable.js +467 -369
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/providers/browserbase.js +1 -1
- package/dist/providers/cdp.d.ts +7 -0
- package/dist/providers/cdp.js +90 -20
- package/dist/providers/kernel.js +1 -1
- package/dist/recorder/index.d.ts +1 -0
- package/dist/recorder/index.js +1 -0
- package/dist/recorder/jpeg.d.ts +3 -0
- package/dist/recorder/jpeg.js +36 -0
- package/dist/recorder/track.d.ts +107 -0
- package/dist/recorder/track.js +259 -0
- package/package.json +3 -3
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export * from "./core/contract.js";
|
|
2
|
+
export { BrowserFailureError, type AttachedSession, type BrowserDriver, type CustodyPort, type DriverFactory, type DriverOptions, type Overrides, type ToolOutput } from "./core/custody.js";
|
|
2
3
|
export * from "./core/decisions.js";
|
|
3
4
|
export * from "./core/downloads.js";
|
|
4
5
|
export * from "./core/effects.js";
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// The host-neutral core: it imports no pi package and no host, only Node's builtins and the package's own dependencies.
|
|
2
2
|
export * from "./core/contract.js";
|
|
3
|
+
export { BrowserFailureError } from "./core/custody.js";
|
|
3
4
|
export * from "./core/decisions.js";
|
|
4
5
|
export * from "./core/downloads.js";
|
|
5
6
|
export * from "./core/effects.js";
|
|
@@ -11,7 +11,7 @@ export const SEARCH_QUERY_MAX = 200;
|
|
|
11
11
|
export const SEARCH_RESULTS_MAX = 25;
|
|
12
12
|
/** Into `downloadPath` (default `downloads`, Browserbase's synced-downloads rule); the socket stays open. */
|
|
13
13
|
export const setDownloadBehavior = (url, options = {}) => cdpCall(url, "Browser.setDownloadBehavior", { behavior: "allow", downloadPath: options.downloadPath ?? "downloads", eventsEnabled: true }, options.timeoutMs);
|
|
14
|
-
const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch" };
|
|
14
|
+
const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 21_600, survivesDisconnect: true, releaseIsAsync: true, extension: "uploaded-per-launch", settings: { proxies: true, verified: true, geolocation: true, region: true, context: true } };
|
|
15
15
|
const notFound = (e) => e?.status === 404;
|
|
16
16
|
/** ISO alpha-2 country, US state abbreviation, upper-case city; no two-letter country, no geolocation. */
|
|
17
17
|
export function browserbaseGeolocation(raw) {
|
package/dist/providers/cdp.d.ts
CHANGED
|
@@ -41,6 +41,13 @@ export declare class ProfileOwnershipUnclearError extends Error {
|
|
|
41
41
|
readonly code = "profile_ownership_unclear";
|
|
42
42
|
constructor(dir: string, port: number);
|
|
43
43
|
}
|
|
44
|
+
/** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
|
|
45
|
+
* `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
|
|
46
|
+
* only for a process that leads one. */
|
|
47
|
+
export declare function killTree(pid: number, io?: {
|
|
48
|
+
kill?: (pid: number, signal: "SIGKILL") => void;
|
|
49
|
+
leadsGroup?: (pid: number) => boolean | null;
|
|
50
|
+
}): Promise<void>;
|
|
44
51
|
/** `internals` is for tests: the removal a release uses. */
|
|
45
52
|
export declare function cdpProvider(options: CdpOptions, internals?: {
|
|
46
53
|
remove?: RemoveDir;
|
package/dist/providers/cdp.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { execFile, spawn } from "node:child_process";
|
|
2
|
-
import {
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
import { mkdir, mkdtemp, open, readdir, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
|
|
4
|
+
import os from "node:os";
|
|
3
5
|
import path from "node:path";
|
|
4
6
|
import { BrowserFailureError } from "../core/custody.js";
|
|
5
7
|
import { cdpCall } from "./cdp-call.js";
|
|
@@ -32,7 +34,7 @@ const CHROME_FLAGS = [
|
|
|
32
34
|
"--remote-allow-origins=*",
|
|
33
35
|
"--enable-features=WebMCPTesting,DevToolsWebMCPSupport",
|
|
34
36
|
];
|
|
35
|
-
const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally" };
|
|
37
|
+
const CAPS = { timeoutModel: "wall-clock", maxLifetimeS: 86_400, survivesDisconnect: true, releaseIsAsync: false, extension: "loaded-locally", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
|
|
36
38
|
const downloadsDir = (profileRoot, tag) => path.join(profileDir(profileRoot, tag) + ".downloads");
|
|
37
39
|
const READY_MS = 20_000;
|
|
38
40
|
/** The browser is gone and directories it used are not: a profile left behind holds the session's cookies, so a release that cannot remove
|
|
@@ -127,6 +129,42 @@ const profileDir = (root, tag) => {
|
|
|
127
129
|
throw new Error("a cdp lease tag is one path segment of [A-Za-z0-9_.-]");
|
|
128
130
|
return path.join(root, tag);
|
|
129
131
|
};
|
|
132
|
+
/** Chrome writes temp entries under its TMPDIR (its singleton socket directory, its url_fetcher entries) and a Chrome that is killed removes none of
|
|
133
|
+
* them, so each lease's Chrome gets a TMPDIR of its own, made under the host's, named in the profile (`.pib-tmpdir`) and removed with the lease: what
|
|
134
|
+
* Chrome writes there never lands in the host's TMPDIR. The directory carries an owner file naming the lease's tag, and only a directory that names the
|
|
135
|
+
* tag asked for is ever removed, so a profile that names another path (a copied or hand-written one) removes nothing. Chrome aborts when its socket path
|
|
136
|
+
* passes 107 bytes, so a host TMPDIR too long to leave room for the private directory's name and the socket's is left as it is (Chrome inherits it). Not
|
|
137
|
+
* made on Windows, where Chrome's temp directory is not TMPDIR. */
|
|
138
|
+
const TMP_MARKER = ".pib-tmpdir";
|
|
139
|
+
const TMP_OWNER = ".pib-owner";
|
|
140
|
+
const TMP_NAME = /^pib-[A-Za-z0-9]{6}$/;
|
|
141
|
+
const SOCKET_PATH_MAX = 107;
|
|
142
|
+
const SOCKET_PATH_TAIL = "/.org.chromium.Chromium.XXXXXX/SingletonSocket".length;
|
|
143
|
+
async function makePrivateTmp(tag, profile, remove) {
|
|
144
|
+
if (process.platform === "win32")
|
|
145
|
+
return null;
|
|
146
|
+
const base = os.tmpdir();
|
|
147
|
+
if (Buffer.byteLength(path.join(base, "pib-XXXXXX")) + SOCKET_PATH_TAIL > SOCKET_PATH_MAX)
|
|
148
|
+
return null;
|
|
149
|
+
const dir = await mkdtemp(path.join(base, "pib-"));
|
|
150
|
+
try {
|
|
151
|
+
await writeFile(path.join(dir, TMP_OWNER), tag);
|
|
152
|
+
await writeFile(path.join(profile, TMP_MARKER), dir);
|
|
153
|
+
}
|
|
154
|
+
catch (error) {
|
|
155
|
+
// The directory is not recorded anywhere yet, so a setup that fails here removes it, and names it if it cannot.
|
|
156
|
+
const left = await removeTree(dir, remove);
|
|
157
|
+
throw left ? new ProfileNotRemovedError([dir], left.error, error) : error;
|
|
158
|
+
}
|
|
159
|
+
return dir;
|
|
160
|
+
}
|
|
161
|
+
/** The private directory the profile names, when it is one this provider made for this tag. */
|
|
162
|
+
async function ownedTmp(profile, tag) {
|
|
163
|
+
const named = (await readFile(path.join(profile, TMP_MARKER), "utf8").catch(() => "")).trim();
|
|
164
|
+
if (!named || !path.isAbsolute(named) || !TMP_NAME.test(path.basename(named)))
|
|
165
|
+
return null;
|
|
166
|
+
return (await readFile(path.join(named, TMP_OWNER), "utf8").catch(() => null)) === tag ? named : null;
|
|
167
|
+
}
|
|
130
168
|
/** Signal 0 only asks; EPERM means the process exists under another user. */
|
|
131
169
|
const alive = (pid) => { try {
|
|
132
170
|
process.kill(pid, 0);
|
|
@@ -155,18 +193,38 @@ async function singletonDir(profile) {
|
|
|
155
193
|
const dir = socket && path.basename(socket) === "SingletonSocket" ? path.dirname(socket) : null;
|
|
156
194
|
return dir && /^\.?(org\.chromium\.Chromium|com\.google\.Chrome)\.[A-Za-z0-9]{6}$/.test(path.basename(dir)) ? dir : null;
|
|
157
195
|
}
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
196
|
+
/** Whether `pid` leads its own process group (Chrome is started detached, so it does); null where there is no /proc to ask. */
|
|
197
|
+
function leadsOwnGroup(pid) {
|
|
198
|
+
if (process.platform !== "linux")
|
|
199
|
+
return null;
|
|
161
200
|
try {
|
|
162
|
-
|
|
201
|
+
const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
|
|
202
|
+
// pid (comm) state ppid pgrp ...: the name may hold spaces and brackets, so the fields are counted from its last ")".
|
|
203
|
+
return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2]) === pid;
|
|
163
204
|
}
|
|
164
205
|
catch {
|
|
206
|
+
return false;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
/** A pid reaches here from a ref's id, which a restart reads back from a record: `kill(-1)` signals every process the user can,
|
|
210
|
+
* `kill(0)` this process's own group, so neither a pid below 2 nor our own is ever signalled, and a negative pid (a whole group)
|
|
211
|
+
* only for a process that leads one. */
|
|
212
|
+
export async function killTree(pid, io = {}) {
|
|
213
|
+
if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid)
|
|
214
|
+
return;
|
|
215
|
+
if (process.platform === "win32")
|
|
216
|
+
return void (await new Promise((resolve) => execFile("taskkill", ["/pid", String(pid), "/T", "/F"], () => resolve())));
|
|
217
|
+
const kill = io.kill ?? ((target, signal) => process.kill(target, signal));
|
|
218
|
+
if ((io.leadsGroup ?? leadsOwnGroup)(pid) !== false) {
|
|
165
219
|
try {
|
|
166
|
-
|
|
220
|
+
return kill(-pid, "SIGKILL");
|
|
167
221
|
}
|
|
168
|
-
catch { }
|
|
222
|
+
catch { /* no such group: the process alone */ }
|
|
223
|
+
}
|
|
224
|
+
try {
|
|
225
|
+
kill(pid, "SIGKILL");
|
|
169
226
|
}
|
|
227
|
+
catch { /* already gone */ }
|
|
170
228
|
}
|
|
171
229
|
/** `internals` is for tests: the removal a release uses. */
|
|
172
230
|
export function cdpProvider(options, internals = {}) {
|
|
@@ -174,9 +232,12 @@ export function cdpProvider(options, internals = {}) {
|
|
|
174
232
|
const downloads = "chrome" in options ? localDownloads(options.chrome.profileRoot) : undefined;
|
|
175
233
|
// So a release can wait for the exit it caused: an unreaped child still answers `kill 0`.
|
|
176
234
|
const children = new Map();
|
|
177
|
-
/**
|
|
178
|
-
* lease in this process is told
|
|
179
|
-
const
|
|
235
|
+
/** Directories besides the profile (Chrome's socket directory, the lease's private TMPDIR) that a release could not remove: the profile that named
|
|
236
|
+
* them may go first, so the next release of the lease in this process is told them here. (A restarted process has the report's text.) */
|
|
237
|
+
const extrasLeft = new Map();
|
|
238
|
+
/** The private TMPDIR of each lease this provider started, by tag: the profile's marker is the only record a restarted process has, and a profile
|
|
239
|
+
* that something else removed first takes it along. */
|
|
240
|
+
const privateTmps = new Map();
|
|
180
241
|
/** A spawned Chrome whose handle we hold is ours (a handle cannot name a recycled pid); after a restart, only while
|
|
181
242
|
* the browser on the recorded port reports that pid. */
|
|
182
243
|
const isOurs = async ({ pid, port }) => {
|
|
@@ -200,10 +261,13 @@ export function cdpProvider(options, internals = {}) {
|
|
|
200
261
|
await writeFile(path.join(dir, "Default", "Preferences"), JSON.stringify({ download: { default_directory: downloadsDir(profileRoot, spec.tag), prompt_for_download: false }, savefile: { default_directory: downloadsDir(profileRoot, spec.tag) } }));
|
|
201
262
|
// A file left by an earlier Chrome on this profile names a browser that is not this one.
|
|
202
263
|
await rm(path.join(dir, "DevToolsActivePort"), { force: true });
|
|
264
|
+
const tmp = await makePrivateTmp(spec.tag, dir, remove);
|
|
265
|
+
if (tmp)
|
|
266
|
+
privateTmps.set(spec.tag, tmp);
|
|
203
267
|
const child = spawn(executablePath, [
|
|
204
268
|
...CHROME_FLAGS, ...(sandbox ? [] : ["--no-sandbox"]), ...(headless ? ["--headless=new"] : []), "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${dir}`,
|
|
205
269
|
`--window-size=${spec.viewport.width},${spec.viewport.height}`, ...args, "about:blank",
|
|
206
|
-
], { stdio: "ignore", detached: true });
|
|
270
|
+
], { stdio: "ignore", detached: true, ...(tmp ? { env: { ...process.env, TMPDIR: tmp } } : {}) });
|
|
207
271
|
// A Chrome that cannot start emits `error`, which unhandled would end the host: it rejects create instead.
|
|
208
272
|
let failed = null;
|
|
209
273
|
child.once("error", (error) => { failed = error; });
|
|
@@ -216,7 +280,8 @@ export function cdpProvider(options, internals = {}) {
|
|
|
216
280
|
});
|
|
217
281
|
if (child.pid === undefined) {
|
|
218
282
|
await sleep(0);
|
|
219
|
-
const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag)], remove);
|
|
283
|
+
const left = await removeAll([dir, downloadsDir(profileRoot, spec.tag), ...(tmp ? [tmp] : [])], remove);
|
|
284
|
+
privateTmps.delete(spec.tag);
|
|
220
285
|
const why = failed ?? new Error("Chrome could not be started");
|
|
221
286
|
throw left ? new ProfileNotRemovedError(left.dirs, left.error, why) : why;
|
|
222
287
|
}
|
|
@@ -301,14 +366,19 @@ export function cdpProvider(options, internals = {}) {
|
|
|
301
366
|
// nothing is removed.
|
|
302
367
|
if (!("endpoint" in options) && SAFE_TAG.test(local.tag)) {
|
|
303
368
|
const dir = profileDir(options.chrome.profileRoot, local.tag);
|
|
304
|
-
const socketDir =
|
|
305
|
-
|
|
306
|
-
//
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
369
|
+
const socketDir = await singletonDir(dir);
|
|
370
|
+
const tmp = privateTmps.get(local.tag) ?? await ownedTmp(dir, local.tag);
|
|
371
|
+
// All are always tried, the profile first named: the profile's link and marker are the only places the other directories' names are read, so
|
|
372
|
+
// they are reported here with the profile's, not left for a later release to miss.
|
|
373
|
+
const extras = [...new Set([...(socketDir ? [socketDir] : []), ...(tmp ? [tmp] : []), ...(extrasLeft.get(local.tag) ?? [])])];
|
|
374
|
+
const left = await removeAll([dir, ...extras], remove);
|
|
375
|
+
const stuck = extras.filter((extra) => left?.dirs.includes(extra));
|
|
376
|
+
if (stuck.length > 0)
|
|
377
|
+
extrasLeft.set(local.tag, stuck);
|
|
310
378
|
else
|
|
311
|
-
|
|
379
|
+
extrasLeft.delete(local.tag);
|
|
380
|
+
if (!tmp || !stuck.includes(tmp))
|
|
381
|
+
privateTmps.delete(local.tag);
|
|
312
382
|
if (left)
|
|
313
383
|
throw new ProfileNotRemovedError(left.dirs, left.error);
|
|
314
384
|
}
|
package/dist/providers/kernel.js
CHANGED
|
@@ -9,7 +9,7 @@ export const KERNEL_IDLE_MIN_S = 10;
|
|
|
9
9
|
export const KERNEL_IDLE_MAX_S = 259_200;
|
|
10
10
|
// Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
|
|
11
11
|
// the lifetime cap is its largest idle timeout.
|
|
12
|
-
const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, extension: "uploaded-per-launch" };
|
|
12
|
+
const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
|
|
13
13
|
/** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
|
|
14
14
|
* copied: an echo of the request could carry the key or a URL. */
|
|
15
15
|
export class KernelError extends Error {
|
package/dist/recorder/index.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export { frameRecorder, type FrameData, type FrameGapData, type FrameLine, type FrameRecorder, type FrameRecorderOptions, type FrameSink } from "./frames.js";
|
|
2
2
|
export { CREDENTIAL_PROBE } from "./credential.js";
|
|
3
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";
|
package/dist/recorder/index.js
CHANGED
package/dist/recorder/jpeg.d.ts
CHANGED
|
@@ -3,3 +3,6 @@ export declare function jpegSize(bytes: Uint8Array): {
|
|
|
3
3
|
w: number;
|
|
4
4
|
h: number;
|
|
5
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;
|
package/dist/recorder/jpeg.js
CHANGED
|
@@ -32,3 +32,39 @@ export function jpegSize(bytes) {
|
|
|
32
32
|
}
|
|
33
33
|
return null;
|
|
34
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
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
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[]>;
|