@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.15
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 +12 -0
- package/README.md +29 -8
- package/dist/coding-agent.d.ts +7 -0
- package/dist/coding-agent.js +33 -16
- package/dist/core/contract.js +1 -1
- package/dist/core/custody.d.ts +16 -3
- package/dist/core/custody.js +28 -11
- package/dist/core/downloads.d.ts +1 -0
- package/dist/core/downloads.js +2 -2
- 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 +60 -2
- package/dist/core/sites.js +2 -1
- 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 +7 -0
- package/dist/driver/extension-worker.js +148 -0
- package/dist/driver/new-document.d.ts +26 -0
- package/dist/driver/new-document.js +40 -0
- package/dist/driver/stagehand.js +9 -61
- package/dist/durable.d.ts +14 -3
- package/dist/durable.js +507 -369
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/providers/browserbase.d.ts +17 -0
- package/dist/providers/browserbase.js +49 -8
- package/dist/providers/cdp.d.ts +14 -0
- package/dist/providers/cdp.js +270 -66
- package/dist/providers/kernel.js +40 -6
- package/dist/providers/profiles.d.ts +19 -0
- package/dist/providers/profiles.js +124 -0
- package/dist/providers/shared.d.ts +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 +280 -0
- package/dist/testing/backend.js +2 -2
- package/package.json +3 -3
package/dist/providers/kernel.js
CHANGED
|
@@ -3,13 +3,14 @@
|
|
|
3
3
|
import { createHash, randomUUID } from "node:crypto";
|
|
4
4
|
import { readFile } from "node:fs/promises";
|
|
5
5
|
import { directFetch } from "./http.js";
|
|
6
|
+
import { claimWriter, freeWriter, isWriter, noteWriter } from "./profiles.js";
|
|
6
7
|
import { accountKey, assertTag, defaultSleep, DEFAULT_CONFIRM, extensionArchive, kernelHoldings, nonEmpty, releaseAndConfirm, tagValue, untilAborted, uploadOnce } from "./shared.js";
|
|
7
8
|
export const KERNEL_BASE_URL = "https://api.onkernel.com";
|
|
8
9
|
export const KERNEL_IDLE_MIN_S = 10;
|
|
9
10
|
export const KERNEL_IDLE_MAX_S = 259_200;
|
|
10
11
|
// Kernel ends a session after `timeout_seconds` with no CDP or live-view connection and sets no wall-clock limit, so
|
|
11
12
|
// 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" };
|
|
13
|
+
const CAPS = { timeoutModel: "inactivity", maxLifetimeS: KERNEL_IDLE_MAX_S, survivesDisconnect: true, releaseIsAsync: false, profiles: true, extension: "uploaded-per-launch", settings: { proxies: false, verified: false, geolocation: false, region: false, context: false } };
|
|
13
14
|
/** The call and the HTTP status, plus Kernel's error code when it is a plain identifier. Kernel's message is never
|
|
14
15
|
* copied: an echo of the request could carry the key or a URL. */
|
|
15
16
|
export class KernelError extends Error {
|
|
@@ -31,6 +32,7 @@ export function kernelCreateBody(spec, options = {}) {
|
|
|
31
32
|
timeout_seconds: Math.min(KERNEL_IDLE_MAX_S, Math.max(KERNEL_IDLE_MIN_S, Math.round(spec.idleTimeoutS) || KERNEL_IDLE_MIN_S)),
|
|
32
33
|
viewport: { width: spec.viewport.width, height: spec.viewport.height },
|
|
33
34
|
tags: { ...tags, agentrun_tag: spec.tag },
|
|
35
|
+
...(spec.profile ? { profile: { name: spec.profile.name, save_changes: spec.profile.save } } : {}),
|
|
34
36
|
...(options.extension ? { extensions: [options.extension] } : {}),
|
|
35
37
|
};
|
|
36
38
|
}
|
|
@@ -50,7 +52,7 @@ export function kernelProvider(options = {}) {
|
|
|
50
52
|
async function call(method, route, init = {}) {
|
|
51
53
|
if (!apiKey)
|
|
52
54
|
throw new Error("the kernel provider needs KERNEL_API_KEY in the env it is given; none is set");
|
|
53
|
-
const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}")}`;
|
|
55
|
+
const name = `${method} ${route.replace(/\/browsers\/[^/?]+/, "/browsers/{id}").replace(/\/extensions\/[^/?]+/, "/extensions/{name}").replace(/\/profiles\/[^/?]+/, "/profiles/{name}")}`;
|
|
54
56
|
const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
|
|
55
57
|
let body;
|
|
56
58
|
if (init.raw) {
|
|
@@ -152,6 +154,19 @@ export function kernelProvider(options = {}) {
|
|
|
152
154
|
forget(ref.id);
|
|
153
155
|
return state;
|
|
154
156
|
};
|
|
157
|
+
const running = (ref) => async (signal) => { const now = await status(ref, signal); return now === "running" || now === "pending"; };
|
|
158
|
+
/** A browser can only name a profile Kernel knows. Creating it first is safe to race: a 409 means another process just did. */
|
|
159
|
+
const ensureProfile = async (name, signal) => {
|
|
160
|
+
if ((await call("GET", `/profiles/${encodeURIComponent(name)}`, { signal })).status !== 404)
|
|
161
|
+
return;
|
|
162
|
+
try {
|
|
163
|
+
await call("POST", "/profiles", { body: { name }, signal });
|
|
164
|
+
}
|
|
165
|
+
catch (error) {
|
|
166
|
+
if (error.status !== 409)
|
|
167
|
+
throw error;
|
|
168
|
+
}
|
|
169
|
+
};
|
|
155
170
|
return {
|
|
156
171
|
name: "kernel",
|
|
157
172
|
caps: CAPS,
|
|
@@ -159,14 +174,27 @@ export function kernelProvider(options = {}) {
|
|
|
159
174
|
// The upload is shared by every create on the account: a cancelled caller stops waiting, the upload goes on for
|
|
160
175
|
// the rest.
|
|
161
176
|
signal?.throwIfAborted();
|
|
162
|
-
|
|
163
|
-
|
|
177
|
+
if (spec.profile?.save)
|
|
178
|
+
await claimWriter(`${account}|profile:${spec.profile.name}`, spec.profile.name, spec.tag, `${spec.metadata.run}|${spec.metadata.label}`, signal);
|
|
179
|
+
let body;
|
|
180
|
+
try {
|
|
181
|
+
if (spec.profile)
|
|
182
|
+
await ensureProfile(spec.profile.name, signal);
|
|
183
|
+
body = kernelCreateBody(spec, { stealth: options.stealth, headless: options.headless, extension: await untilAborted(extension(), signal) });
|
|
184
|
+
}
|
|
185
|
+
catch (error) {
|
|
186
|
+
freeWriter(spec.tag);
|
|
187
|
+
throw error;
|
|
188
|
+
}
|
|
189
|
+
// At most once: a lost answer is found again by its tag (findByTag), never by a second create. A failed send keeps the
|
|
190
|
+
// profile's claim until findByTag has looked: the browser may exist.
|
|
164
191
|
const created = await call("POST", "/browsers", { body, signal });
|
|
165
192
|
const id = nonEmpty(created.json?.session_id);
|
|
166
193
|
const url = nonEmpty(created.json?.cdp_ws_url);
|
|
167
194
|
if (created.status === 404 || !id || !url)
|
|
168
195
|
throw new KernelError("POST /browsers", created.status, "no_session");
|
|
169
196
|
cdpUrls.set(held(id), url);
|
|
197
|
+
noteWriter(spec.tag, running({ id, tag: spec.tag }));
|
|
170
198
|
const live = nonEmpty(created.json?.browser_live_view_url);
|
|
171
199
|
if (live)
|
|
172
200
|
liveUrls.set(held(id), live);
|
|
@@ -196,8 +224,14 @@ export function kernelProvider(options = {}) {
|
|
|
196
224
|
}
|
|
197
225
|
}
|
|
198
226
|
// Kernel pages by headers: X-Has-More, and X-Next-Offset as the next page's absolute start.
|
|
199
|
-
if (page.headers.get("x-has-more") !== "true")
|
|
227
|
+
if (page.headers.get("x-has-more") !== "true") {
|
|
228
|
+
if (!out.length)
|
|
229
|
+
freeWriter(tag);
|
|
230
|
+
for (const ref of out)
|
|
231
|
+
if (isWriter(ref.tag))
|
|
232
|
+
noteWriter(ref.tag, running(ref));
|
|
200
233
|
return out;
|
|
234
|
+
}
|
|
201
235
|
// More pages with no usable next offset would truncate the set custody releases: a failure, never a partial
|
|
202
236
|
// answer.
|
|
203
237
|
const next = Number(page.headers.get("x-next-offset"));
|
|
@@ -236,7 +270,7 @@ export function kernelProvider(options = {}) {
|
|
|
236
270
|
await releaseAndConfirm({
|
|
237
271
|
request: async () => ((await call("DELETE", `/browsers/${encodeURIComponent(ref.id)}`, { signal })).status === 404 ? "gone" : undefined),
|
|
238
272
|
status: () => status(ref, signal),
|
|
239
|
-
forget: () => forget(ref.id),
|
|
273
|
+
forget: () => { forget(ref.id); freeWriter(ref.tag); },
|
|
240
274
|
confirm,
|
|
241
275
|
sleep,
|
|
242
276
|
stillRunning: `Kernel session ${ref.id} still running after its delete`,
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
|
|
2
|
+
* profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
|
|
3
|
+
* while the old session is still being released) waits for the release; anyone else is refused. */
|
|
4
|
+
export declare function claimWriter(key: string, name: string, tag: string, owner: string, signal?: AbortSignal): Promise<void>;
|
|
5
|
+
/** `running` says whether the session still runs (a probe that cannot answer in time counts as running); `settle` is what a new
|
|
6
|
+
* saver must wait out after finding it stopped, when the provider is still writing its state back. */
|
|
7
|
+
export declare function noteWriter(tag: string, running: (signal: AbortSignal) => Promise<boolean>, settle?: () => Promise<void>): void;
|
|
8
|
+
export declare function freeWriter(tag: string): void;
|
|
9
|
+
export declare function isWriter(tag: string): boolean;
|
|
10
|
+
/** Context ids are not secrets, and Browserbase has no way to look a context up by name, so the name to id map is the host's.
|
|
11
|
+
* `resolve` returns the name's context, calling `make` only when there is none, and no two callers may both make one. */
|
|
12
|
+
export type ProfileStore = {
|
|
13
|
+
resolve(key: string, make: (signal: AbortSignal) => Promise<string>): Promise<string>;
|
|
14
|
+
};
|
|
15
|
+
/** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
|
|
16
|
+
* not this format, or cannot be read, is never overwritten. */
|
|
17
|
+
export declare function fileProfileStore(file?: string, options?: {
|
|
18
|
+
makeLimitMs?: number;
|
|
19
|
+
}): ProfileStore;
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { randomBytes } from "node:crypto";
|
|
2
|
+
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
|
3
|
+
import os from "node:os";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { BrowserFailureError } from "../core/custody.js";
|
|
6
|
+
import { withLock } from "../core/downloads.js";
|
|
7
|
+
const writers = new Map();
|
|
8
|
+
const WAIT_MS = 20_000;
|
|
9
|
+
const PROBE_MS = 2_000;
|
|
10
|
+
const refusal = (message) => new BrowserFailureError({ ok: false, code: "refused", retryable: false, effect: "none", message });
|
|
11
|
+
/** True when `work` finishes within `ms`; false at the deadline; rejects when `signal` aborts, leaving `work` to finish alone. */
|
|
12
|
+
async function waitFor(work, signal, ms) {
|
|
13
|
+
let timer;
|
|
14
|
+
let abort;
|
|
15
|
+
try {
|
|
16
|
+
return await Promise.race([
|
|
17
|
+
work.then(() => true),
|
|
18
|
+
new Promise((resolve) => { timer = setTimeout(() => resolve(false), Math.max(0, ms)); }),
|
|
19
|
+
new Promise((_, reject) => { if (signal) {
|
|
20
|
+
abort = () => reject(signal.reason);
|
|
21
|
+
if (signal.aborted)
|
|
22
|
+
abort();
|
|
23
|
+
else
|
|
24
|
+
signal.addEventListener("abort", abort, { once: true });
|
|
25
|
+
} }),
|
|
26
|
+
]);
|
|
27
|
+
}
|
|
28
|
+
finally {
|
|
29
|
+
clearTimeout(timer);
|
|
30
|
+
if (abort)
|
|
31
|
+
signal?.removeEventListener("abort", abort);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Both vendors keep the last writer's state and neither locks, so within this process one session at a time may save to a
|
|
35
|
+
* profile. A holder that is no longer running is replaced; the same owner's successor (a relaunch asks for its replacement
|
|
36
|
+
* while the old session is still being released) waits for the release; anyone else is refused. */
|
|
37
|
+
export async function claimWriter(key, name, tag, owner, signal) {
|
|
38
|
+
for (const end = Date.now() + WAIT_MS;;) {
|
|
39
|
+
const held = writers.get(key);
|
|
40
|
+
if (!held || held.tag === tag) {
|
|
41
|
+
writers.set(key, { tag, owner });
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
if (held.running && !(await held.running(AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(PROBE_MS)])).catch(() => true))) {
|
|
45
|
+
if (held.settle && !(await waitFor(held.settle(), signal, end - Date.now())))
|
|
46
|
+
throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
|
|
47
|
+
if (writers.get(key) === held)
|
|
48
|
+
writers.delete(key);
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
if (held.owner !== owner)
|
|
52
|
+
throw refusal(`browser profile "${name}": one session at a time may save to a profile, and another session is saving to it now. Wait for it to end, or start without saving. No session was started.`);
|
|
53
|
+
if (Date.now() > end)
|
|
54
|
+
throw refusal(`browser profile "${name}": the session that was saving to it is still ending. Try again in a moment. No session was started.`);
|
|
55
|
+
signal?.throwIfAborted();
|
|
56
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
/** `running` says whether the session still runs (a probe that cannot answer in time counts as running); `settle` is what a new
|
|
60
|
+
* saver must wait out after finding it stopped, when the provider is still writing its state back. */
|
|
61
|
+
export function noteWriter(tag, running, settle) {
|
|
62
|
+
for (const held of writers.values())
|
|
63
|
+
if (held.tag === tag)
|
|
64
|
+
Object.assign(held, { running, ...(settle ? { settle } : {}) });
|
|
65
|
+
}
|
|
66
|
+
export function freeWriter(tag) {
|
|
67
|
+
for (const [key, held] of writers)
|
|
68
|
+
if (held.tag === tag)
|
|
69
|
+
writers.delete(key);
|
|
70
|
+
}
|
|
71
|
+
export function isWriter(tag) {
|
|
72
|
+
for (const held of writers.values())
|
|
73
|
+
if (held.tag === tag)
|
|
74
|
+
return true;
|
|
75
|
+
return false;
|
|
76
|
+
}
|
|
77
|
+
const SCHEMA = "pi-browser.profiles.v1";
|
|
78
|
+
const defaultProfilesFile = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "pi-browser", "profiles.json");
|
|
79
|
+
const notOurs = (file) => new Error(`the profiles file ${path.basename(file)} is not a pi-browser profiles file, so it was left as it is`);
|
|
80
|
+
async function readProfiles(file) {
|
|
81
|
+
let text;
|
|
82
|
+
try {
|
|
83
|
+
text = await readFile(file, "utf8");
|
|
84
|
+
}
|
|
85
|
+
catch (error) {
|
|
86
|
+
if (error.code === "ENOENT")
|
|
87
|
+
return { schema: SCHEMA, contexts: {} };
|
|
88
|
+
throw error;
|
|
89
|
+
}
|
|
90
|
+
try {
|
|
91
|
+
const parsed = JSON.parse(text);
|
|
92
|
+
const contexts = parsed?.contexts;
|
|
93
|
+
if (parsed?.schema === SCHEMA && contexts && typeof contexts === "object" && !Array.isArray(contexts) && Object.values(contexts).every((id) => typeof id === "string" && id !== ""))
|
|
94
|
+
return parsed;
|
|
95
|
+
}
|
|
96
|
+
catch { /* not JSON */ }
|
|
97
|
+
throw notOurs(file);
|
|
98
|
+
}
|
|
99
|
+
/** A JSON file, read, extended and written under one lock, so two processes' first uses of a name make one context; a file that is
|
|
100
|
+
* not this format, or cannot be read, is never overwritten. */
|
|
101
|
+
export function fileProfileStore(file = defaultProfilesFile(), options = {}) {
|
|
102
|
+
// The lock is taken over once it is 30 s old (core/downloads.ts's rule), so `make` must end well before: a slower one is cut here, never left
|
|
103
|
+
// to run past the lock that protects it.
|
|
104
|
+
const makeLimitMs = options.makeLimitMs ?? 20_000;
|
|
105
|
+
return {
|
|
106
|
+
async resolve(key, make) {
|
|
107
|
+
await mkdir(path.dirname(file), { recursive: true });
|
|
108
|
+
return withLock(`${file}.lock`, async () => {
|
|
109
|
+
const current = await readProfiles(file);
|
|
110
|
+
const known = current.contexts[key];
|
|
111
|
+
if (known)
|
|
112
|
+
return known;
|
|
113
|
+
const limit = AbortSignal.timeout(makeLimitMs);
|
|
114
|
+
// Listening before `make` does, so the cut's own words are what the caller hears.
|
|
115
|
+
const cut = new Promise((_, reject) => limit.addEventListener("abort", () => reject(new Error(`making the profile's context took longer than ${makeLimitMs} ms, so it was cut before the profiles file's lock could be taken over`)), { once: true }));
|
|
116
|
+
const id = await Promise.race([make(limit), cut]);
|
|
117
|
+
const next = `${file}.${randomBytes(4).toString("hex")}.tmp`;
|
|
118
|
+
await writeFile(next, `${JSON.stringify({ schema: SCHEMA, contexts: { ...current.contexts, [key]: id } }, null, 2)}\n`);
|
|
119
|
+
await rename(next, file);
|
|
120
|
+
return id;
|
|
121
|
+
}, "the profiles file");
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
}
|
|
@@ -20,7 +20,7 @@ export declare function uploadOnce<T>(uploads: Map<string, Promise<T>>, account:
|
|
|
20
20
|
export declare function releaseAndConfirm(o: {
|
|
21
21
|
request: () => Promise<"gone" | void>;
|
|
22
22
|
status: () => Promise<ResourceStatus>;
|
|
23
|
-
forget: () => void
|
|
23
|
+
forget: () => void | Promise<void>;
|
|
24
24
|
confirm: {
|
|
25
25
|
polls: number;
|
|
26
26
|
intervalMs: number;
|
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[]>;
|