agent-screenplay 0.0.0-stage → 0.1.0

package/dist/scenario/schema.js

@@ -0,0 +1,262 @@
+import { z } from "zod";
+/**
+ * A target names one element on screen, never coordinates (except `at` for
+ * desktop apps that expose no accessible elements). Playwright-style strings:
+ *   "text=Save"                      visible text (exact match first, then contains)
+ *   "role=button[name='Save']"       ARIA role and accessible name
+ *   "label=Email"                    form field by its label
+ *   "placeholder=Search"             input by placeholder
+ *   "testid=save-button"             data-testid
+ *   "css=.toolbar > button"          CSS selector (web only)
+ * A bare string without a prefix is treated as text.
+ */
+export const Target = z
+    .string()
+    .min(1)
+    .describe("The element to act on: text=…, role=button[name='…'], label=…, placeholder=…, testid=…, css=… (web only). A bare string means text=.");
+export const SURFACES = ["window", "menubar", "menu", "sheet", "popover", "alert"];
+const Common = {
+    say: z
+        .string()
+        .optional()
+        .describe("Narration for this step: shown as a caption, and spoken when voice is enabled. The step lasts at least as long as the sentence."),
+    zoom: z
+        .union([z.boolean(), z.number().min(1).max(4)])
+        .optional()
+        .describe("false: keep the camera wide for this step. A number: force this zoom level (1 = no zoom)."),
+    hold: z
+        .number()
+        .min(0)
+        .max(30)
+        .optional()
+        .describe("Extra seconds to stay on the result of this step before the next one."),
+    app: z
+        .string()
+        .optional()
+        .describe('Desktop: the app this step acts in (default: the scenario\'s app, or the last one opened). Another app than the scenario\'s needs "screen": true; there it also becomes the app the next steps act in.'),
+    surface: z
+        .enum(SURFACES)
+        .optional()
+        .describe("Desktop: where to look for the element: window (default, the app's front window), menubar (the app's menus in the menu bar), menu (an open menu), sheet, popover or alert."),
+};
+const Open = z
+    .object({
+    open: z.string().describe('Desktop, with "screen": true: launch this app or bring it to the front. The next steps act in it.'),
+    ...Common,
+})
+    .strict();
+const Goto = z.object({ goto: z.string().describe("URL or path to open (relative to the scenario url)."), ...Common }).strict();
+const Click = z
+    .object({
+    click: Target,
+    button: z.enum(["left", "right"]).optional(),
+    double: z.boolean().optional(),
+    ...Common,
+})
+    .strict();
+const Type = z
+    .object({
+    type: z.string().describe("Text to type, letter by letter. ${ENV_VAR} is replaced from the environment."),
+    into: Target.optional().describe("Field to click first. Omit to type where the focus already is."),
+    clear: z.boolean().optional().describe("Clear the field before typing."),
+    secret: z.boolean().optional().describe("Mask the text in captions, logs and the storyboard."),
+    submit: z.boolean().optional().describe("Press Enter after typing."),
+    ...Common,
+})
+    .strict();
+const Press = z.object({ press: z.string().describe("Key or chord, e.g. Enter, Escape, Meta+K."), ...Common }).strict();
+const Hover = z.object({ hover: Target, ...Common }).strict();
+const Scroll = z
+    .object({
+    scroll: z
+        .union([Target, z.enum(["down", "up", "top", "bottom"])])
+        .describe("An element to bring into view, or a direction (down/up scroll one screen)."),
+    ...Common,
+})
+    .strict();
+const Select = z.object({ select: Target, option: z.string(), ...Common }).strict();
+const Wait = z
+    .object({
+    wait: z
+        .union([Target, z.number().min(0).max(120)])
+        .describe("An element/text to wait for, or a number of seconds. Long waits are sped up in the video."),
+    timeout: z.number().min(1).max(300).optional().describe("Seconds before giving up (default 30)."),
+    ...Common,
+})
+    .strict();
+const Pause = z.object({ pause: z.number().min(0).max(30).describe("Seconds to stay still."), ...Common }).strict();
+const Title = z
+    .object({
+    title: z.string().describe("Opening card shown full screen."),
+    subtitle: z.string().optional(),
+    duration: z.number().min(0.5).max(15).optional(),
+    say: Common.say,
+})
+    .strict();
+const End = z
+    .object({
+    end: z.string().describe("Closing card shown full screen (result, call to action)."),
+    subtitle: z.string().optional(),
+    duration: z.number().min(0.5).max(15).optional(),
+    say: Common.say,
+})
+    .strict();
+const Callout = z
+    .object({
+    callout: Target,
+    text: z.string().describe("Text of the bubble pointing at the element."),
+    duration: z.number().min(0.5).max(15).optional(),
+    ...Common,
+})
+    .strict();
+const Highlight = z
+    .object({
+    highlight: Target,
+    text: z.string().optional(),
+    duration: z.number().min(0.5).max(15).optional(),
+    ...Common,
+})
+    .strict();
+const ZoomTo = z
+    .object({
+    zoomTo: Target.describe("Frame the camera on this element without acting on it."),
+    duration: z.number().min(0.5).max(15).optional(),
+    ...Common,
+})
+    .strict();
+export const Step = z.union([
+    Goto,
+    Open,
+    Click,
+    Type,
+    Press,
+    Hover,
+    Scroll,
+    Select,
+    Wait,
+    Pause,
+    Title,
+    End,
+    Callout,
+    Highlight,
+    ZoomTo,
+]);
+export const BACKGROUNDS = ["sunset", "ocean", "lavender", "forest", "midnight", "mono", "paper"];
+const Color = z.string().regex(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i, "a hex color like #0ea5e9");
+export const Gradient = z
+    .object({
+    gradient: z.array(Color).min(2).max(4).describe("2 to 4 hex colors, from the start of the gradient to its end."),
+    angle: z.number().min(0).max(360).optional().describe("Direction in degrees, as in CSS: 90 goes left to right, 180 top to bottom (default 135)."),
+})
+    .strict();
+export const Style = z
+    .object({
+    background: z
+        .union([z.string(), Gradient])
+        .optional()
+        .describe(`A preset (${BACKGROUNDS.join(", ")}), a color like #0f172a, an image path (relative to the file that sets it), or a gradient { "gradient": ["#0ea5e9", "#6366f1"], "angle": 135 }.`),
+    padding: z.number().min(0).max(400).optional().describe("Space around the recording, in output pixels (default 72)."),
+    radius: z.number().min(0).max(80).optional().describe("Corner radius of the recording (default 14)."),
+    shadow: z.boolean().optional().describe("Drop shadow under the recording (default true)."),
+    cursor: z.enum(["macos", "dot", "none"]).optional().describe("Cursor drawn in the video (default macos)."),
+    cursorSize: z.number().min(0.5).max(3).optional().describe("Cursor scale (default 1)."),
+    maxZoom: z.number().min(1).max(4).optional().describe("Highest automatic zoom (default 1.9). Automatic zooms also stop where the capture runs out of pixels, so a small app window that already fills the video is not zoomed; a number in a step's `zoom` still forces it."),
+    autoZoom: z.boolean().optional().describe("Zoom automatically on clicks and typing (default true)."),
+    captions: z.boolean().optional().describe("Show the `say` text as captions (default true)."),
+    accent: z.string().optional().describe("Accent color for clicks, callouts and highlights (default #3b82f6)."),
+    frame: z.enum(["none", "browser"]).optional().describe("Draw a minimal browser window bar above web recordings (default none)."),
+})
+    .strict();
+export const Voice = z
+    .object({
+    enabled: z.boolean().optional().describe("Speak each step's `say` text (default false). Needs CARTESIA_API_KEY."),
+    language: z.string().optional().describe("Language code, e.g. en, fr, de (default en)."),
+    id: z.string().optional().describe("Cartesia voice id (default: a narration voice for the language)."),
+    speed: z.number().min(0.6).max(1.5).optional(),
+    model: z.string().optional().describe("Cartesia model (default sonic-3.6)."),
+})
+    .strict();
+export const Output = z
+    .object({
+    width: z.number().int().min(320).max(3840).optional().describe("Video width (default 1920)."),
+    height: z.number().int().min(240).max(2160).optional().describe("Video height (default 1080)."),
+    fps: z.union([z.literal(24), z.literal(25), z.literal(30), z.literal(50), z.literal(60)]).optional().describe("Frames per second (default 30)."),
+    gif: z.boolean().optional().describe("Also write a GIF (default false)."),
+    path: z.string().optional().describe("Where to write the MP4 (default: next to the scenario, same name)."),
+})
+    .strict();
+export const Scenario = z
+    .object({
+    $schema: z.string().optional(),
+    name: z.string().optional().describe("Name of the video (default: the file name)."),
+    url: z.string().optional().describe("Web: the page to start on."),
+    app: z
+        .string()
+        .optional()
+        .describe('Desktop: the application to film, as the OS names it. With "screen": true, the app brought to the front first (optional).'),
+    screen: z
+        .boolean()
+        .optional()
+        .describe("Desktop: film the whole main screen instead of one app's window, to show several apps or the menu bar. Everything on screen is filmed (notifications, other windows, the menu bar icons): close or hide what should not be seen."),
+    hideOthers: z
+        .boolean()
+        .optional()
+        .describe("Desktop, macOS, with \"screen\": true: hide the other apps before filming (Hide Others, ⌥⌘H, in `app`). Default false."),
+    viewport: z
+        .object({ width: z.number().int().min(320).max(3840), height: z.number().int().min(240).max(2160) })
+        .optional()
+        .describe("Web: browser size in CSS pixels (default 1440x900)."),
+    scale: z.number().min(1).max(3).optional().describe("Web: device pixel ratio of the capture (default 2, Retina)."),
+    colorScheme: z.enum(["light", "dark"]).optional(),
+    locale: z.string().optional().describe("Web: browser locale, e.g. fr-FR."),
+    auth: z
+        .object({ storageState: z.string().describe("Path to a session saved by `screenplay login`.") })
+        .optional(),
+    hideScrollbars: z.boolean().optional().describe("Web: hide scrollbars (default true)."),
+    typingSpeed: z.number().min(0.2).max(5).optional().describe("Typing speed multiplier (default 1, about 14 characters/second)."),
+    style: Style.optional(),
+    voice: Voice.optional(),
+    output: Output.optional(),
+    steps: z.array(Step).min(1),
+})
+    .strict()
+    .refine((s) => Boolean(s.url) !== Boolean(s.app || s.screen), {
+    message: "Give either `url` (a website), or `app` (a desktop application's window) and/or `\"screen\": true` (the whole screen).",
+})
+    .refine((s) => !s.url || s.steps.every((st) => !("open" in st) && !("app" in st) && !("surface" in st)), {
+    message: "`open`, `app` and `surface` in steps are for desktop recordings, not websites.",
+});
+const KINDS = [
+    "goto",
+    "open",
+    "click",
+    "type",
+    "press",
+    "hover",
+    "scroll",
+    "select",
+    "wait",
+    "pause",
+    "title",
+    "end",
+    "callout",
+    "highlight",
+    "zoomTo",
+];
+export function stepKind(step) {
+    for (const k of KINDS)
+        if (k in step)
+            return k;
+    throw new Error(`Unknown step: ${JSON.stringify(step)}`);
+}
+export function describeStep(step) {
+    const kind = stepKind(step);
+    const value = step[kind];
+    if (kind === "type") {
+        const t = step;
+        const text = t.secret ? "••••••" : t.type;
+        return t.into ? `type "${text}" into ${t.into}` : `type "${text}"`;
+    }
+    return `${kind} ${typeof value === "string" ? value : JSON.stringify(value)}`;
+}
+//# sourceMappingURL=schema.js.map

package/dist/scenario/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/scenario/schema.ts"],"names":[],"mappings":"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"}

package/dist/scenario/target.d.ts

@@ -0,0 +1,26 @@
+export type ParsedTarget = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "role";
+    role: string;
+    name?: string;
+} | {
+    kind: "label";
+    text: string;
+} | {
+    kind: "placeholder";
+    text: string;
+} | {
+    kind: "testid";
+    id: string;
+} | {
+    kind: "css";
+    selector: string;
+} | {
+    kind: "at";
+    x: number;
+    y: number;
+};
+/** Parse "text=…", "role=button[name='…']", "label=…", "placeholder=…", "testid=…", "css=…", "at=x,y". */
+export declare function parseTarget(input: string): ParsedTarget;

package/dist/scenario/target.js

@@ -0,0 +1,40 @@
+const ROLE_RE = /^([a-z]+)(?:\[name=(['"])(.*)\2\])?$/i;
+/** Parse "text=…", "role=button[name='…']", "label=…", "placeholder=…", "testid=…", "css=…", "at=x,y". */
+export function parseTarget(input) {
+    const s = input.trim();
+    const eq = s.indexOf("=");
+    const prefix = eq > 0 ? s.slice(0, eq).toLowerCase() : "";
+    const rest = eq > 0 ? s.slice(eq + 1).trim() : s;
+    switch (prefix) {
+        case "text":
+            return { kind: "text", text: unquote(rest) };
+        case "role": {
+            const m = ROLE_RE.exec(rest);
+            if (!m)
+                throw new Error(`Invalid role target "${input}". Use role=button or role=button[name='Save'].`);
+            return { kind: "role", role: m[1].toLowerCase(), name: m[3] };
+        }
+        case "label":
+            return { kind: "label", text: unquote(rest) };
+        case "placeholder":
+            return { kind: "placeholder", text: unquote(rest) };
+        case "testid":
+            return { kind: "testid", id: unquote(rest) };
+        case "css":
+            return { kind: "css", selector: rest };
+        case "at": {
+            const [x, y] = rest.split(",").map((v) => Number(v.trim()));
+            if (!Number.isFinite(x) || !Number.isFinite(y))
+                throw new Error(`Invalid target "${input}". Use at=x,y.`);
+            return { kind: "at", x, y };
+        }
+        default:
+            return { kind: "text", text: unquote(s) };
+    }
+}
+function unquote(s) {
+    if (s.length >= 2 && (s[0] === "'" || s[0] === '"') && s[s.length - 1] === s[0])
+        return s.slice(1, -1);
+    return s;
+}
+//# sourceMappingURL=target.js.map

package/dist/scenario/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/scenario/target.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,GAAG,uCAAuC,CAAC;AAExD,0GAA0G;AAC1G,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,KAAK,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,KAAK,iDAAiD,CAAC,CAAC;YACxG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,CAAC;QACD,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,KAAK,aAAa;YAChB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACzC,KAAK,IAAI,EAAE,CAAC;YACV,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,gBAAgB,CAAC,CAAC;YAC1G,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9B,CAAC;QACD;YACE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,CAAS;IACxB,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvG,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/take.d.ts

@@ -0,0 +1,100 @@
+import type { StepKind } from "./scenario/schema.js";
+/** A rectangle in source coordinates (CSS pixels of the filmed viewport, or points of the filmed window or screen). */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * What happened during one step of a take. Times are seconds since the start
+ * of the take, on the same clock as the captured frames.
+ */
+export interface TakeStep {
+    index: number;
+    kind: StepKind;
+    label: string;
+    start: number;
+    end: number;
+    /** The cursor starts travelling towards `point`. */
+    travelStart?: number;
+    /** The click happens / typing starts. */
+    actionAt?: number;
+    /** Typing ends. */
+    actionEnd?: number;
+    /** Where the cursor goes. */
+    point?: Point;
+    /** The element's box at action time. */
+    box?: Box;
+    /** Spans spent waiting (page loads, slow elements): sped up in the video. */
+    waits: Array<[number, number]>;
+    /** Smooth scroll spans. */
+    scrolls?: Array<[number, number]>;
+    /** The page navigated during this step. */
+    navigated?: boolean;
+    /** A title or end card, inserted at `start` (it takes no recording time). */
+    card?: {
+        kind: "title" | "end";
+        title: string;
+        subtitle?: string;
+        duration: number;
+    };
+    /** Typed characters (masked when secret). */
+    typed?: string;
+}
+export interface FramesSource {
+    kind: "frames";
+    /** Directory of the frame images, relative to the take directory. */
+    dir: string;
+    /** [time, file name] sorted by time. */
+    frames: Array<[number, string]>;
+}
+export interface VideoSource {
+    kind: "video";
+    /** Video file, relative to the take directory. */
+    file: string;
+    fps: number;
+    /** Seconds between the take clock and the video's first frame (video time = take time - offset). */
+    offset: number;
+    /** Region of the video that holds the filmed window, in video pixels. */
+    crop: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface Take {
+    version: 1;
+    name: string;
+    recordedAt: string;
+    platform: NodeJS.Platform;
+    target: {
+        kind: "web";
+        url: string;
+    } | {
+        kind: "desktop";
+        app: string;
+        screen?: boolean;
+    };
+    /** Size of the filmed area in source coordinates (CSS pixels / logical points). */
+    width: number;
+    height: number;
+    /** Pixels per source unit in the captured images. */
+    scale: number;
+    duration: number;
+    cursorStart: Point;
+    source: FramesSource | VideoSource;
+    steps: TakeStep[];
+    /** What the recording depends on (see scenario/fingerprint.ts), to refuse re-rendering a changed scenario. */
+    inputs?: {
+        setup: string;
+        steps: string[];
+    };
+}
+export declare function writeTake(dir: string, take: Take): string;
+export declare function readTake(dir: string): Take;

package/dist/take.js

@@ -0,0 +1,15 @@
+import fs from "node:fs";
+import path from "node:path";
+export function writeTake(dir, take) {
+    const file = path.join(dir, "take.json");
+    fs.writeFileSync(file, JSON.stringify(take, null, 2));
+    return file;
+}
+export function readTake(dir) {
+    const file = path.join(dir, "take.json");
+    if (!fs.existsSync(file)) {
+        throw new Error(`No recording found in ${dir}. Run \`screenplay record\` first.`);
+    }
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+//# sourceMappingURL=take.js.map

package/dist/take.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"take.js","sourceRoot":"","sources":["../src/take.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAsF7B,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAU;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACzC,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACzC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,oCAAoC,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAS,CAAC;AAC3D,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/voice/cartesia.d.ts

@@ -0,0 +1,12 @@
+import type { Voice } from "../scenario/schema.js";
+export declare class VoiceError extends Error {
+}
+export interface Clip {
+    file: string;
+    duration: number;
+}
+export declare function voiceKey(): string | undefined;
+/** Synthesize each text (cached on disk by content), and return the clip files with their durations. */
+export declare function synthesizeAll(texts: Map<number, string>, voice: Voice, cacheDir: string): Promise<Map<number, Clip>>;
+/** Duration of a PCM WAV file, from its header. */
+export declare function wavDuration(buf: Buffer): number;

package/dist/voice/cartesia.js

@@ -0,0 +1,103 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const API = "https://api.cartesia.ai";
+const VERSION = "2026-08-14";
+const DEFAULT_MODEL = "sonic-3.6";
+/** Narration voices picked for clear product walkthroughs. Other languages use Cartesia's first voice for the language. */
+const DEFAULT_VOICES = {
+    en: "a33f7a4c-100f-41cf-a1fd-5822e8fc253f", // Lauren: expressive narration
+    fr: "7c58f4a4-a72c-42fa-a503-41b9408820f3", // Inès: corporate narration
+};
+export class VoiceError extends Error {
+}
+export function voiceKey() {
+    return process.env.CARTESIA_API_KEY || undefined;
+}
+/** Synthesize each text (cached on disk by content), and return the clip files with their durations. */
+export async function synthesizeAll(texts, voice, cacheDir) {
+    // The key is only needed for sentences not generated before (they are cached by content).
+    const requireKey = () => {
+        const key = voiceKey();
+        if (!key) {
+            throw new VoiceError("Voice-over is enabled but CARTESIA_API_KEY is not set. Set it (https://play.cartesia.ai/keys), or remove `voice.enabled`, or pass --no-voice.");
+        }
+        return key;
+    };
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const language = voice.language ?? "en";
+    const base = language.split("-")[0].toLowerCase();
+    const voiceId = voice.id ?? DEFAULT_VOICES[base] ?? (await defaultVoice(language, requireKey()));
+    const model = voice.model ?? DEFAULT_MODEL;
+    const out = new Map();
+    for (const [index, text] of texts) {
+        const hash = crypto
+            .createHash("sha1")
+            .update(JSON.stringify([model, voiceId, language, voice.speed ?? 1, text]))
+            .digest("hex")
+            .slice(0, 16);
+        const file = path.join(cacheDir, `${hash}.wav`);
+        if (!fs.existsSync(file)) {
+            const key = requireKey();
+            const body = {
+                model_id: model,
+                transcript: text,
+                voice: { id: voiceId },
+                language,
+                output_format: { container: "wav", encoding: "pcm_s16le", sample_rate: 44100 },
+                ...(voice.speed ? { generation_config: { speed: voice.speed } } : {}),
+            };
+            const res = await fetch(`${API}/tts/bytes`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${key}`, "Cartesia-Version": VERSION, "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const detail = (await res.text()).slice(0, 400);
+                throw new VoiceError(`Cartesia refused the narration of step ${index + 1} (${res.status}): ${detail}`);
+            }
+            const buf = Buffer.from(await res.arrayBuffer());
+            // Write then rename, so an interrupted download never leaves a broken cached clip.
+            fs.writeFileSync(`${file}.part`, buf);
+            fs.renameSync(`${file}.part`, file);
+        }
+        out.set(index, { file, duration: wavDuration(fs.readFileSync(file)) });
+    }
+    return out;
+}
+async function defaultVoice(language, key) {
+    const base = language.split("-")[0].toLowerCase();
+    if (DEFAULT_VOICES[base])
+        return DEFAULT_VOICES[base];
+    const res = await fetch(`${API}/voices?language=${encodeURIComponent(base)}&limit=1`, {
+        headers: { Authorization: `Bearer ${key}`, "Cartesia-Version": VERSION },
+    });
+    if (res.ok) {
+        const data = (await res.json());
+        const id = data.data?.[0]?.id;
+        if (id)
+            return id;
+    }
+    throw new VoiceError(`No Cartesia voice found for language "${language}". Set voice.id in the scenario.`);
+}
+/** Duration of a PCM WAV file, from its header. */
+export function wavDuration(buf) {
+    if (buf.toString("ascii", 0, 4) !== "RIFF")
+        throw new VoiceError("Narration audio is not a WAV file.");
+    let off = 12;
+    let byteRate = 0;
+    while (off + 8 <= buf.length) {
+        const id = buf.toString("ascii", off, off + 4);
+        const size = buf.readUInt32LE(off + 4);
+        if (id === "fmt ")
+            byteRate = buf.readUInt32LE(off + 16);
+        if (id === "data") {
+            // Streaming WAVs may carry a placeholder size: fall back to the bytes present.
+            const real = Math.min(size, buf.length - off - 8);
+            return byteRate ? real / byteRate : 0;
+        }
+        off += 8 + size + (size % 2);
+    }
+    return 0;
+}
+//# sourceMappingURL=cartesia.js.map

package/dist/voice/cartesia.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartesia.js","sourceRoot":"","sources":["../../src/voice/cartesia.ts"],"names":[],"mappings":"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"}