π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
import { i18n, localStorage } from '@/core/env';
import type { Branding } from '@/core/export/branding';
import { dataUrlToBytes, fitLogo, loadBranding } from '@/core/export/branding';
import type { ExportOptions } from '@/core/export/options';
import { loadExportOptions } from '@/core/export/options';
import { extractDomain, formatDate } from '@/core/export/utils';
import {
availableContainers,
COVER_SECONDS,
FPS,
FRAME_FILL,
FRAME_HEIGHT,
FRAME_WIDTH,
RESOLUTION_SPECS,
STEP_SECONDS,
STEP_ZOOM_TRANSITION_SEC,
STEP_ZOOMED_OUT_SEC,
TRANSITION_SECONDS,
uniformTimeline,
type VideoContainer,
type VideoTimeline,
VOICE_LEAD_SEC,
voiceTimeline,
} from '@/core/export/video-support';
import { COVER_SEGMENT, stepNarration } from '@/core/export/voiceover/script';
import { actionSteps, calloutAccent, isBlock } from '@/core/guides/blocks';
import type { BlockType, Guide, Screenshot, Step } from '@/core/guides/types';
import { logger } from '@/core/logger';
import type { Rect } from '@/core/rect';
import type { Ctx } from '@/core/screenshot/draw';
import { drawRoundedRect, TARGET_RADIUS, TARGET_STROKE } from '@/core/screenshot/draw';
import { clamp, resolveFrameViewport, resolveTarget } from '@/core/screenshot/geometry';
import { renderScreenshot } from '@/core/screenshot/render';
const KEY_FRAME_INTERVAL_SEC = 2;
const ZOOM_MIN = 1;
const ZOOM_MAX = 3.5;
const ZOOM_PAD_RATIO = 0.15;
const MAX_UPSCALE = 1.5;
const RESERVE_PASSES = 3;
const BACKDROP = '#1E1B4B';
const MUTED = '#9CA3AF';
const ON_DARK = '#FFFFFF';
const TOOLTIP_BG = 'rgba(17, 15, 43, 0.92)';
const TOOLTIP_FONT_SIZE = 20;
const TOOLTIP_LINE_HEIGHT = 27;
const TOOLTIP_PADDING_X = 16;
const TOOLTIP_PADDING_Y = 12;
const TOOLTIP_RADIUS = 10;
const TOOLTIP_GAP = 14;
const TOOLTIP_MAX_LINES = 3;
const TOOLTIP_MAX_WIDTH_RATIO = 0.45;
const FRAME_PADDING = 20;
const RING_DELAY_SEC = 0.12;
const RING_POP_SEC = 0.22;
const RING_OVERSHOOT = 0.16;
const RING_PAD = 7;
const TOOLTIP_DELAY_SEC = 0.37;
const TOOLTIP_FADE_SEC = 0.28;
const TOOLTIP_RISE = 8;
const CURSOR_START_SEC = 0.35;
const CURSOR_HEIGHT = 23;
const CURSOR_PAGE_RATIO = 0.026;
const CURSOR_MIN_SCALE = 0.9;
const CURSOR_MAX_SCALE = 2.6;
const CURSOR_PRESS_SEC = 0.16;
const CURSOR_PRESS_SCALE = 0.86;
const COVER_MARGIN = 96;
const COVER_CELL_WIDTH = 300;
const RENDER_OPTIONS = { format: 'image/webp', quality: 0.9 } as const;
const BLOCK_BLUR = 'blur(24px)';
const BLOCK_OVERSCAN = 1.12;
const BLOCK_WASH = 'rgba(30, 27, 75, 0.7)';
const BLOCK_WASH_FLAT = 'rgba(30, 27, 75, 0.86)';
const BLOCK_MAX_WIDTH_RATIO = 0.72;
const HEADING_FONT_SIZE = 58;
const HEADING_LINE_HEIGHT = 74;
const HEADING_MAX_LINES = 3;
const CALLOUT_FONT_SIZE = 36;
const CALLOUT_LINE_HEIGHT = 50;
const CALLOUT_MAX_LINES = 4;
const CALLOUT_BAR_WIDTH = 6;
const CALLOUT_BAR_GAP = 26;
export { FPS, STEP_SECONDS };
export function toFrames(seconds: number, fps = FPS): number {
return Math.round(seconds * fps);
}
export function stepFrames(fps = FPS): number {
return toFrames(STEP_SECONDS, fps);
}
export function overlapFrames(fps = FPS): number {
return toFrames(TRANSITION_SECONDS, fps);
}
export function totalStepFrames(stepCount: number, fps = FPS): number {
if (stepCount <= 0) return 0;
return stepCount * stepFrames(fps) - (stepCount - 1) * overlapFrames(fps);
}
export function stepSpans(timeline: VideoTimeline, count: number, fps = FPS): number[] {
return Array.from({ length: count }, (_, index) =>
Math.max(stepFrames(fps), toFrames(timeline.stepSeconds[index] ?? STEP_SECONDS, fps)),
);
}
export function stepStarts(spans: number[], fps = FPS): number[] {
const overlap = overlapFrames(fps);
const starts: number[] = [];
let at = 0;
for (const span of spans) {
starts.push(at);
at += span - overlap;
}
return starts;
}
export function spannedFrames(spans: number[], fps = FPS): number {
if (spans.length === 0) return 0;
const starts = stepStarts(spans, fps);
return starts[spans.length - 1]! + spans[spans.length - 1]!;
}
export function zoomProgress(frame: number, fps = FPS): number {
const held = toFrames(STEP_ZOOMED_OUT_SEC, fps);
const moving = toFrames(STEP_ZOOM_TRANSITION_SEC, fps);
if (frame <= held) return 0;
if (frame >= held + moving) return 1;
return (frame - held) / moving;
}
export function landingFrame(fps = FPS): number {
return toFrames(STEP_ZOOMED_OUT_SEC + STEP_ZOOM_TRANSITION_SEC, fps);
}
function fadeAt(frame: number, startSec: number, spanSec: number, fps: number): number {
const start = landingFrame(fps) + toFrames(startSec, fps);
const span = toFrames(spanSec, fps);
if (frame < start) return 0;
if (span <= 0 || frame >= start + span) return 1;
return (frame - start) / span;
}
export function ringProgress(frame: number, fps = FPS): number {
return fadeAt(frame, RING_DELAY_SEC, RING_POP_SEC, fps);
}
export function tooltipProgress(frame: number, fps = FPS): number {
return fadeAt(frame, TOOLTIP_DELAY_SEC, TOOLTIP_FADE_SEC, fps);
}
export function cursorProgress(frame: number, fps = FPS): number {
const start = toFrames(CURSOR_START_SEC, fps);
const land = landingFrame(fps);
if (frame <= start) return 0;
if (frame >= land) return 1;
return (frame - start) / (land - start);
}
export function easeInOut(t: number): number {
const x = clamp(t, 0, 1);
return x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2;
}
interface Size {
width: number;
height: number;
}
export function findIdealZoomLevel(
target: Rect,
imgWidth: number,
imgHeight: number,
viewWidth: number,
viewHeight: number,
): number {
const nx = target.x / imgWidth;
const ny = target.y / imgHeight;
const needWidth = Math.min(target.width / imgWidth + 2 * ZOOM_PAD_RATIO, 1 - nx) * viewWidth;
const needHeight = Math.min(target.height / imgHeight + 2 * ZOOM_PAD_RATIO, 1 - ny) * viewHeight;
const zoom = Math.min(viewWidth / needWidth, viewHeight / needHeight);
return Number.isFinite(zoom) ? clamp(zoom, ZOOM_MIN, sharpZoomCeiling(imgWidth, viewWidth)) : ZOOM_MIN;
}
export function sharpZoomCeiling(imgWidth: number, viewWidth = FRAME_WIDTH): number {
if (!(imgWidth > 0) || !(viewWidth > 0)) return ZOOM_MAX;
return clamp((imgWidth * MAX_UPSCALE) / viewWidth, ZOOM_MIN, ZOOM_MAX);
}
export function zoomCrop(
image: Size,
target: Rect | null,
eased: number,
viewWidth = FRAME_WIDTH,
viewHeight = FRAME_HEIGHT,
): Rect {
const full = { x: 0, y: 0, width: image.width, height: image.height };
if (!target) return full;
const zoom = findIdealZoomLevel(target, image.width, image.height, viewWidth, viewHeight);
if (zoom <= ZOOM_MIN) return full;
const width = image.width / zoom;
const height = image.height / zoom;
const x = clamp(target.x + target.width / 2 - width / 2, 0, image.width - width);
const y = clamp(target.y + target.height / 2 - height / 2, 0, image.height - height);
const t = clamp(eased, 0, 1);
return {
x: x * t,
y: y * t,
width: image.width + (width - image.width) * t,
height: image.height + (height - image.height) * t,
};
}
export function letterbox(srcWidth: number, srcHeight: number, dstWidth: number, dstHeight: number) {
const scale = Math.min(dstWidth / srcWidth, dstHeight / srcHeight);
const width = srcWidth * scale;
const height = srcHeight * scale;
return { scale, width, height, x: (dstWidth - width) / 2, y: (dstHeight - height) / 2 };
}
function coverFit(source: Size, overscan: number): Rect {
const scale = Math.max(FRAME_WIDTH / source.width, FRAME_HEIGHT / source.height) * overscan;
const width = source.width * scale;
const height = source.height * scale;
return { x: (FRAME_WIDTH - width) / 2, y: (FRAME_HEIGHT - height) / 2, width, height };
}
export function wrapLines(
text: string,
maxWidth: number,
measure: (line: string) => number,
maxLines = TOOLTIP_MAX_LINES,
): string[] {
const words = text.trim().split(/\s+/).filter(Boolean);
if (words.length === 0) return [];
const lines: string[] = [];
let current = '';
for (const word of words) {
const candidate = current ? `${current} ${word}` : word;
if (current && measure(candidate) > maxWidth) {
lines.push(current);
current = word;
if (lines.length === maxLines) {
lines[maxLines - 1] = `${lines[maxLines - 1]}β¦`;
return lines;
}
} else {
current = candidate;
}
}
if (current) lines.push(current);
return lines;
}
export function tooltipBand(box: { height: number }): number {
return box.height + TOOLTIP_GAP + FRAME_PADDING;
}
export function reserveTooltip(
target: Rect,
band: number,
image: Size,
fitHeight: number,
viewWidth = FRAME_WIDTH,
viewHeight = FRAME_HEIGHT,
): Rect {
if (band <= 0 || fitHeight <= 0) return target;
const below = target.y + target.height / 2 < image.height / 2;
let rect = target;
for (let pass = 0; pass < RESERVE_PASSES; pass++) {
const zoom = findIdealZoomLevel(rect, image.width, image.height, viewWidth, viewHeight);
const reserve = (band * image.height) / (zoom * fitHeight);
const top = clamp(below ? target.y : target.y - reserve, 0, image.height);
const bottom = clamp((below ? target.y + reserve : target.y) + target.height, top, image.height);
rect = { x: target.x, y: top, width: target.width, height: bottom - top };
}
return rect;
}
export function tooltipPlacement(
target: Rect,
tooltip: { width: number; height: number },
frameWidth = FRAME_WIDTH,
frameHeight = FRAME_HEIGHT,
) {
const below = target.y + target.height + TOOLTIP_GAP;
const fitsBelow = below + tooltip.height <= frameHeight - FRAME_PADDING;
const rawY = fitsBelow ? below : target.y - TOOLTIP_GAP - tooltip.height;
const rawX = target.x + target.width / 2 - tooltip.width / 2;
return {
x: clamp(rawX, FRAME_PADDING, Math.max(FRAME_PADDING, frameWidth - tooltip.width - FRAME_PADDING)),
y: clamp(rawY, FRAME_PADDING, Math.max(FRAME_PADDING, frameHeight - tooltip.height - FRAME_PADDING)),
below: fitsBelow,
};
}
function logoBitmap(logo: NonNullable<Branding['logo']>): Promise<ImageBitmap> {
const bytes = dataUrlToBytes(logo.dataUrl);
return createImageBitmap(new Blob([bytes as BlobPart]));
}
interface TooltipBox {
lines: string[];
width: number;
height: number;
}
function measureTooltip(ctx: Ctx, text: string): TooltipBox | null {
ctx.font = `500 ${TOOLTIP_FONT_SIZE}px Poppins, sans-serif`;
const lines = wrapLines(text, FRAME_WIDTH * TOOLTIP_MAX_WIDTH_RATIO, (line) => ctx.measureText(line).width);
if (lines.length === 0) return null;
const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
return {
lines,
width: textWidth + TOOLTIP_PADDING_X * 2,
height: lines.length * TOOLTIP_LINE_HEIGHT + TOOLTIP_PADDING_Y * 2,
};
}
function drawTooltip(ctx: Ctx, box: TooltipBox, target: Rect) {
const at = tooltipPlacement(target, box);
ctx.fillStyle = TOOLTIP_BG;
drawRoundedRect(ctx, at.x, at.y, box.width, box.height, TOOLTIP_RADIUS);
ctx.fill();
ctx.fillStyle = ON_DARK;
ctx.textBaseline = 'top';
box.lines.forEach((line, i) => {
ctx.fillText(line, at.x + TOOLTIP_PADDING_X, at.y + TOOLTIP_PADDING_Y + i * TOOLTIP_LINE_HEIGHT);
});
}
interface Point {
x: number;
y: number;
}
export const CURSOR_ENTRY_ORIGIN: Point = { x: 0.5, y: 1.08 };
export function cursorOriginFor(index: number, targetAt: (i: number) => Point | null): Point {
for (let i = index - 1; i >= 0; i--) {
const behind = targetAt(i);
if (behind) return behind;
}
return CURSOR_ENTRY_ORIGIN;
}
interface ScreenshotLayer {
kind: 'screenshot';
bitmap: ImageBitmap;
fit: ReturnType<typeof letterbox>;
target: Rect | null;
ring: { color: string; dashed: boolean } | null;
from: Point;
description: string;
}
interface BlockLayer {
kind: 'block';
blockType: BlockType;
accent: string;
description: string;
backdrop: ImageBitmap | null;
blurred: boolean;
}
type StepLayer = ScreenshotLayer | BlockLayer;
function detectCanvasFilter(): boolean {
try {
const ctx = new OffscreenCanvas(1, 1).getContext('2d');
if (!ctx || !('filter' in ctx)) return false;
ctx.filter = BLOCK_BLUR;
const applied = ctx.filter !== 'none';
ctx.filter = 'none';
return applied;
} catch {
return false;
}
}
let filterSupport: boolean | undefined;
function supportsCanvasFilter(): boolean {
filterSupport ??= detectCanvasFilter();
return filterSupport;
}
async function blurBackdrop(screenshot: Screenshot): Promise<Pick<BlockLayer, 'backdrop' | 'blurred'>> {
const canvas = new OffscreenCanvas(FRAME_WIDTH, FRAME_HEIGHT);
const ctx = canvas.getContext('2d');
if (!ctx) throw new Error('Canvas 2D context unavailable');
const rendered = await renderScreenshot(screenshot, {
...RENDER_OPTIONS,
viewport: resolveFrameViewport(screenshot),
});
const source = await createImageBitmap(rendered);
const blurred = supportsCanvasFilter();
const at = coverFit(source, blurred ? BLOCK_OVERSCAN : 1);
if (blurred) ctx.filter = BLOCK_BLUR;
ctx.drawImage(source, at.x, at.y, at.width, at.height);
ctx.filter = 'none';
source.close();
return { backdrop: await createImageBitmap(canvas), blurred };
}
async function loadBlockLayer(step: Step, behind: Screenshot | undefined): Promise<BlockLayer> {
return {
kind: 'block',
blockType: step.blockType ?? 'callout',
accent: calloutAccent(step),
description: step.description,
...(behind ? await blurBackdrop(behind) : { backdrop: null, blurred: false }),
};
}
export function normalizedTargetCenter(screenshot: Screenshot): Point | null {
const target = resolveTarget(screenshot);
if (!target) return null;
const viewport = resolveFrameViewport(screenshot);
if (!(viewport.width > 0) || !(viewport.height > 0)) return null;
return {
x: clamp((target.x + target.width / 2 - viewport.x) / viewport.width, 0, 1),
y: clamp((target.y + target.height / 2 - viewport.y) / viewport.height, 0, 1),
};
}
async function loadScreenshotLayer(step: Step, screenshot: Screenshot, from: Point): Promise<ScreenshotLayer> {
const viewport = resolveFrameViewport(screenshot);
const rendered = await renderScreenshot(screenshot, { ...RENDER_OPTIONS, viewport, target: false });
const bitmap = await createImageBitmap(rendered);
const target = resolveTarget(screenshot);
const sx = bitmap.width / viewport.width;
const sy = bitmap.height / viewport.height;
return {
kind: 'screenshot',
bitmap,
fit: letterbox(bitmap.width, bitmap.height, FRAME_WIDTH, FRAME_HEIGHT),
target: target
? {
x: (target.x - viewport.x) * sx,
y: (target.y - viewport.y) * sy,
width: target.width * sx,
height: target.height * sy,
}
: null,
ring: target ? { color: target.color, dashed: target.border === 'dashed' } : null,
from: { x: from.x * bitmap.width, y: from.y * bitmap.height },
description: step.description,
};
}
function releaseLayer(layer: StepLayer) {
if (layer.kind === 'screenshot') layer.bitmap.close();
else layer.backdrop?.close();
}
function drawBlockText(ctx: Ctx, layer: BlockLayer) {
const heading = layer.blockType === 'heading';
const fontSize = heading ? HEADING_FONT_SIZE : CALLOUT_FONT_SIZE;
const lineHeight = heading ? HEADING_LINE_HEIGHT : CALLOUT_LINE_HEIGHT;
ctx.font = `700 ${fontSize}px Poppins, sans-serif`;
const lines = wrapLines(
layer.description,
FRAME_WIDTH * BLOCK_MAX_WIDTH_RATIO,
(line) => ctx.measureText(line).width,
heading ? HEADING_MAX_LINES : CALLOUT_MAX_LINES,
);
if (lines.length === 0) return;
const middle = FRAME_HEIGHT / 2;
const height = lines.length * lineHeight;
const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
const centerX = FRAME_WIDTH / 2 + (heading ? 0 : (CALLOUT_BAR_WIDTH + CALLOUT_BAR_GAP) / 2);
if (!heading) {
ctx.fillStyle = layer.accent;
const barX = centerX - textWidth / 2 - CALLOUT_BAR_GAP - CALLOUT_BAR_WIDTH;
drawRoundedRect(ctx, barX, middle - height / 2, CALLOUT_BAR_WIDTH, height, CALLOUT_BAR_WIDTH / 2);
ctx.fill();
}
ctx.fillStyle = ON_DARK;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
lines.forEach((line, i) => {
ctx.fillText(line, centerX, middle + (i - (lines.length - 1) / 2) * lineHeight);
});
}
function drawBlockFrame(ctx: Ctx, layer: BlockLayer) {
ctx.save();
if (layer.backdrop) {
ctx.drawImage(layer.backdrop, 0, 0, FRAME_WIDTH, FRAME_HEIGHT);
ctx.fillStyle = layer.blurred ? BLOCK_WASH : BLOCK_WASH_FLAT;
} else {
ctx.fillStyle = BACKDROP;
}
ctx.fillRect(0, 0, FRAME_WIDTH, FRAME_HEIGHT);
drawBlockText(ctx, layer);
ctx.restore();
}
function drawRing(ctx: Ctx, at: Rect, ring: NonNullable<ScreenshotLayer['ring']>, progress: number) {
const pad = RING_PAD * (1 + RING_OVERSHOOT * (1 - progress) ** 2);
ctx.save();
ctx.globalAlpha *= progress;
ctx.strokeStyle = ring.color;
ctx.lineWidth = TARGET_STROKE;
if (ring.dashed) ctx.setLineDash([8, 5]);
drawRoundedRect(ctx, at.x - pad, at.y - pad, at.width + pad * 2, at.height + pad * 2, TARGET_RADIUS);
ctx.stroke();
ctx.restore();
}
export function cursorScale(imageHeight: number, cameraScale: number): number {
if (!(imageHeight > 0) || !(cameraScale > 0)) return CURSOR_MIN_SCALE;
const onPage = (imageHeight * CURSOR_PAGE_RATIO) / CURSOR_HEIGHT;
return clamp(onPage * cameraScale, CURSOR_MIN_SCALE, CURSOR_MAX_SCALE);
}
function drawCursor(ctx: Ctx, x: number, y: number, scale: number) {
ctx.save();
ctx.translate(x, y);
ctx.scale(scale, scale);
ctx.beginPath();
ctx.moveTo(0, 0);
ctx.lineTo(0, 20);
ctx.lineTo(5.2, 15.2);
ctx.lineTo(8.6, 23);
ctx.lineTo(12.2, 21.4);
ctx.lineTo(8.8, 13.8);
ctx.lineTo(15.6, 13.2);
ctx.closePath();
ctx.fillStyle = ON_DARK;
ctx.strokeStyle = BACKDROP;
ctx.lineWidth = 1.6;
ctx.lineJoin = 'round';
ctx.fill();
ctx.stroke();
ctx.restore();
}
function drawStepFrame(ctx: Ctx, layer: StepLayer, frame: number, device: Size, fps = FPS) {
if (layer.kind === 'block') {
drawBlockFrame(ctx, layer);
return;
}
const { fit } = layer;
const box = layer.description ? measureTooltip(ctx, layer.description) : null;
const framed =
box && layer.target
? reserveTooltip(layer.target, tooltipBand(box), layer.bitmap, fit.height, device.width, device.height)
: layer.target;
const crop = zoomCrop(layer.bitmap, framed, easeInOut(zoomProgress(frame, fps)), device.width, device.height);
ctx.drawImage(layer.bitmap, crop.x, crop.y, crop.width, crop.height, fit.x, fit.y, fit.width, fit.height);
const scale = fit.width / crop.width;
const project = (x: number, y: number) => ({ x: fit.x + (x - crop.x) * scale, y: fit.y + (y - crop.y) * scale });
const anchor: Rect = layer.target
? {
...project(layer.target.x, layer.target.y),
width: layer.target.width * scale,
height: layer.target.height * scale,
}
: { x: FRAME_WIDTH / 2, y: FRAME_HEIGHT, width: 0, height: 0 };
const ringIn = ringProgress(frame, fps);
if (layer.target && layer.ring && ringIn > 0) drawRing(ctx, anchor, layer.ring, ringIn);
const tipIn = tooltipProgress(frame, fps);
if (box && tipIn > 0) {
ctx.save();
ctx.globalAlpha *= tipIn;
ctx.translate(0, (1 - tipIn) * -TOOLTIP_RISE);
drawTooltip(ctx, box, anchor);
ctx.restore();
}
if (layer.target) {
const travel = easeInOut(cursorProgress(frame, fps));
const tip = project(
layer.from.x + (layer.target.x + layer.target.width * 0.42 - layer.from.x) * travel,
layer.from.y + (layer.target.y + layer.target.height * 0.55 - layer.from.y) * travel,
);
const pressed = ringIn > 0 && frame < landingFrame() + toFrames(RING_DELAY_SEC + CURSOR_PRESS_SEC);
const size = cursorScale(layer.bitmap.height, scale) * (pressed ? CURSOR_PRESS_SCALE : 1);
drawCursor(ctx, tip.x, tip.y, size);
}
}
async function drawCardFrame(ctx: Ctx, guide: Guide, steps: Step[], brand: Branding, label: string) {
ctx.fillStyle = BACKDROP;
ctx.fillRect(0, 0, FRAME_WIDTH, FRAME_HEIGHT);
ctx.textBaseline = 'top';
let y = 150;
ctx.fillStyle = MUTED;
ctx.font = '700 14px Poppins, sans-serif';
ctx.fillText(label.toUpperCase(), COVER_MARGIN, y);
y += 34;
ctx.fillStyle = ON_DARK;
ctx.font = '700 52px Poppins, sans-serif';
const titleWidth = FRAME_WIDTH - COVER_MARGIN * 2 - (brand.logo ? 240 : 0);
for (const line of wrapLines(guide.title, titleWidth, (l) => ctx.measureText(l).width, 2)) {
ctx.fillText(line, COVER_MARGIN, y);
y += 64;
}
y += 26;
ctx.strokeStyle = brand.accent;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(COVER_MARGIN, y);
ctx.lineTo(FRAME_WIDTH - COVER_MARGIN, y);
ctx.stroke();
y += 26;
const domain = extractDomain(steps);
const cells: Array<[string, string]> = [
[i18n.t('export.steps').toUpperCase(), String(steps.length).padStart(2, '0')],
[i18n.t('export.created').toUpperCase(), formatDate(guide.createdAt)],
];
if (domain) cells.push([i18n.t('export.source').toUpperCase(), domain]);
cells.forEach(([label, value], index) => {
const x = COVER_MARGIN + index * COVER_CELL_WIDTH;
ctx.fillStyle = MUTED;
ctx.font = '700 12px Poppins, sans-serif';
ctx.fillText(label, x, y);
ctx.fillStyle = index === 0 ? brand.accent : ON_DARK;
ctx.font = '700 30px Poppins, sans-serif';
ctx.fillText(value, x, y + 20);
});
if (brand.logo) {
const size = fitLogo(brand.logo, 200, 64);
const bitmap = await logoBitmap(brand.logo);
ctx.drawImage(bitmap, FRAME_WIDTH - COVER_MARGIN - size.width, 132, size.width, size.height);
bitmap.close();
}
const footer = [brand.footer, brand.attribution ? i18n.t('export.madeWith') : ''].filter(Boolean).join(' Β· ');
if (footer) {
ctx.fillStyle = MUTED;
ctx.font = '500 15px Poppins, sans-serif';
ctx.fillText(footer, COVER_MARGIN, FRAME_HEIGHT - 96);
}
}
export type VideoOptions = Pick<ExportOptions, 'cover' | 'stepDescriptions' | 'resolution' | 'voiceover'>;
export type FrameOptions = Pick<ExportOptions, 'cover' | 'stepDescriptions'> & { timeline?: VideoTimeline };
export interface VideoExportControls {
onProgress?: (done: number, total: number) => void;
onVoiceProgress?: (done: number, total: number, next?: string) => void;
onMuxProgress?: (done: number, total: number) => void;
signal?: AbortSignal;
}
export type StepKind = 'click' | 'type' | 'key' | 'navigate' | 'note';
export interface VideoChapter {
stepId: string;
title: string;
kind: StepKind;
start: number;
end: number;
spoken: boolean;
}
export function stepKind(step: Step): StepKind {
if (isBlock(step)) return 'note';
const action = step.action ?? '';
if (action.startsWith('keydown:')) return 'key';
if (action === 'input') return 'type';
if (action === 'navigate') return 'navigate';
return 'click';
}
type VoiceoverSkipReason = 'failed' | 'noAudioCodec' | 'noKey' | 'nothingToSay';
export interface VoiceoverSkip {
reason: VoiceoverSkipReason;
detail?: string;
}
export interface VideoExportResult {
blob: Blob;
extension: string;
chapters: VideoChapter[];
voiceoverError?: VoiceoverSkip;
}
export function videoChapters(frames: Step[], cover: boolean, fps = FPS, timeline?: VideoTimeline): VideoChapter[] {
if (frames.length === 0) return [];
const plan = timeline ?? uniformTimeline(frames.length);
const offset = cover ? plan.coverSeconds : 0;
const spans = stepSpans(plan, frames.length, fps);
const starts = stepStarts(spans, fps);
const last = offset + spannedFrames(spans, fps) / fps;
return frames.map((step, index) => ({
stepId: step.id,
title: step.description?.trim() || i18n.t('export.stepLabel', [String(index + 1)]),
kind: stepKind(step),
start: offset + starts[index]! / fps,
end: index === frames.length - 1 ? last : offset + starts[index + 1]! / fps,
spoken: stepNarration(step).length > 0,
}));
}
export type FrameSink = (timeSec: number, durationSec: number) => Promise<void>;
export async function composeGuideFrames(
guide: Guide,
frames: Step[],
screenshots: Map<string, Screenshot>,
options: FrameOptions,
brand: Branding,
ctx: Ctx,
device: Size,
sink: FrameSink,
controls: { onProgress?: (done: number, total: number) => void; signal?: AbortSignal } = {},
fps = FPS,
): Promise<void> {
const overlap = overlapFrames(fps);
const timeline = options.timeline ?? uniformTimeline(frames.length);
const spans = stepSpans(timeline, frames.length, fps);
const starts = stepStarts(spans, fps);
const stepTotal = spannedFrames(spans, fps);
const total = stepTotal + (options.cover ? 2 : 0);
const loaded = new Map<number, StepLayer>();
const { onProgress, signal } = controls;
let done = 0;
const backdropFor = (index: number) => {
for (let i = index - 1; i >= 0; i--) {
const behind = screenshots.get(frames[i]!.id);
if (behind) return behind;
}
return undefined;
};
const targetAt = (index: number) => {
const behind = screenshots.get(frames[index]!.id);
return behind ? normalizedTargetCenter(behind) : null;
};
const layerAt = async (index: number) => {
const cached = loaded.get(index);
if (cached) return cached;
const step = frames[index]!;
const layer = isBlock(step)
? await loadBlockLayer(step, backdropFor(index))
: await loadScreenshotLayer(step, screenshots.get(step.id) as Screenshot, cursorOriginFor(index, targetAt));
if (layer.kind === 'screenshot' && !options.stepDescriptions) layer.description = '';
loaded.set(index, layer);
return layer;
};
const releaseBefore = (index: number) => {
for (const [key, layer] of loaded) {
if (key < index) {
releaseLayer(layer);
loaded.delete(key);
}
}
};
const abortIfRequested = () => {
if (signal?.aborted) throw new DOMException('Video export was aborted', 'AbortError');
};
try {
const offset = options.cover ? timeline.coverSeconds : 0;
const cards = actionSteps(frames);
if (options.cover) {
abortIfRequested();
await drawCardFrame(ctx, guide, cards, brand, i18n.t('export.guideLabel'));
await sink(0, timeline.coverSeconds);
done += 1;
onProgress?.(done, total);
}
let index = 0;
for (let frame = 0; frame < stepTotal; frame++) {
abortIfRequested();
while (index + 1 < starts.length && frame >= starts[index + 1]!) index += 1;
const local = frame - starts[index]!;
const outgoing = index > 0 && local < overlap ? index - 1 : -1;
const current = await layerAt(index);
const previous = outgoing >= 0 ? await layerAt(outgoing) : null;
releaseBefore(outgoing >= 0 ? outgoing : index);
ctx.globalAlpha = 1;
ctx.fillStyle = FRAME_FILL;
ctx.fillRect(0, 0, FRAME_WIDTH, FRAME_HEIGHT);
if (previous) {
drawStepFrame(ctx, previous, frame - starts[outgoing]!, device, fps);
ctx.globalAlpha = (local + 1) / overlap;
drawStepFrame(ctx, current, local, device, fps);
ctx.globalAlpha = 1;
} else {
drawStepFrame(ctx, current, local, device, fps);
}
await sink(offset + frame / fps, 1 / fps);
done += 1;
onProgress?.(done, total);
}
if (options.cover) {
abortIfRequested();
await drawCardFrame(ctx, guide, cards, brand, i18n.t('export.endLabel'));
await sink(offset + stepTotal / fps, COVER_SECONDS);
done += 1;
onProgress?.(done, total);
}
} finally {
for (const layer of loaded.values()) releaseLayer(layer);
loaded.clear();
}
}
interface PreparedVoiceover {
container: VideoContainer;
codec: 'aac' | 'opus';
clips: Map<number, AudioBuffer>;
timeline: VideoTimeline;
}
type NarrationOutcome = { voice: PreparedVoiceover; error?: undefined } | { voice: null; error: VoiceoverSkip };
async function narrateOrSkip(
guide: Guide,
frames: Step[],
cover: boolean,
containers: VideoContainer[],
controls: VideoExportControls,
): Promise<NarrationOutcome> {
try {
return await prepareVoiceover(guide, frames, cover, containers, controls);
} catch (error) {
if (error instanceof DOMException && error.name === 'AbortError') throw error;
logger.error('[voiceover] narration failed, exporting a silent video', error);
return { voice: null, error: { reason: 'failed', detail: error instanceof Error ? error.message : String(error) } };
}
}
async function prepareVoiceover(
guide: Guide,
frames: Step[],
cover: boolean,
containers: VideoContainer[],
controls: VideoExportControls,
): Promise<NarrationOutcome> {
const [
{ pickVoiceContainer },
{ resolveVoiceoverConfig, VOICEOVER_SETTINGS },
{ voiceoverProvider },
{ voiceoverScript },
{ renderVoiceover },
] = await Promise.all([
import('./voiceover/audio'),
import('./voiceover/config'),
import('./voiceover/providers'),
import('./voiceover/script'),
import('./voiceover/render'),
]);
const config = resolveVoiceoverConfig(await localStorage.get([...VOICEOVER_SETTINGS]));
if (!config.apiKey) {
logger.error('[voiceover] skipped: no', voiceoverProvider(config.provider).label, 'API key');
return { voice: null, error: { reason: 'noKey' } };
}
const segments = voiceoverScript(guide, frames, cover);
if (segments.length === 0) {
logger.error('[voiceover] skipped: this guide has no text to read aloud');
return { voice: null, error: { reason: 'nothingToSay' } };
}
const picked = await pickVoiceContainer(containers);
if (!picked) {
logger.error('[voiceover] skipped: this browser cannot encode audio for', containers.join('/') || 'any container');
return { voice: null, error: { reason: 'noAudioCodec' } };
}
const clips = await renderVoiceover(segments, config, {
signal: controls.signal,
onProgress: controls.onVoiceProgress,
});
const seconds = new Map(Array.from(clips, ([index, clip]) => [index, clip.duration]));
return {
voice: {
container: picked.container,
codec: picked.codec,
clips,
timeline: voiceTimeline(frames.length, seconds),
},
};
}
function voiceoverPlacement(
clips: Map<number, AudioBuffer>,
starts: number[],
offsetSec: number,
fps = FPS,
): { startSec: number; buffer: AudioBuffer }[] {
return Array.from(clips, ([index, buffer]) => ({
startSec: (index === COVER_SEGMENT ? 0 : offsetSec + starts[index]! / fps) + VOICE_LEAD_SEC,
buffer,
}));
}
export async function exportGuideAsVideo(
guide: Guide,
steps: Step[],
screenshots: Map<string, Screenshot>,
exportOptions?: VideoOptions,
controls: VideoExportControls = {},
): Promise<VideoExportResult> {
const frames = steps.filter((step) => isBlock(step) || screenshots.has(step.id));
if (frames.length === 0) throw new Error('This guide has no screenshots to turn into a video');
const {
AudioBufferSource,
BufferTarget,
CanvasSource,
Mp4OutputFormat,
Output,
QUALITY_HIGH,
QUALITY_MEDIUM,
WebMOutputFormat,
} = await import('mediabunny');
const [brand, options] = await Promise.all([
loadBranding(),
exportOptions ? Promise.resolve(exportOptions) : loadExportOptions(),
]);
const requested = RESOLUTION_SPECS[options.resolution] ? options.resolution : '720p';
const preferred = await availableContainers(requested);
const resolution = preferred.length > 0 ? requested : '720p';
const containers = preferred.length > 0 ? preferred : await availableContainers('720p');
if (containers.length === 0) throw new Error('This browser cannot encode video');
const spec = RESOLUTION_SPECS[resolution];
const narration: NarrationOutcome | { voice: null; error?: undefined } = options.voiceover
? await narrateOrSkip(guide, frames, Boolean(options.cover), containers, controls)
: { voice: null };
const voice = narration.voice;
const container = voice?.container ?? containers[0];
const mp4 = container === 'mp4';
const timeline = voice?.timeline ?? uniformTimeline(frames.length);
const canvas = document.createElement('canvas');
canvas.width = spec.width;
canvas.height = spec.height;
const ctx = canvas.getContext('2d');
if (!ctx) throw new Error('Canvas 2D context unavailable');
ctx.scale(spec.width / FRAME_WIDTH, spec.height / FRAME_HEIGHT);
const device = { width: spec.width, height: spec.height };
const output = new Output({
format: mp4 ? new Mp4OutputFormat() : new WebMOutputFormat(),
target: new BufferTarget(),
});
const source = new CanvasSource(canvas, {
codec: mp4 ? 'avc' : 'vp9',
quality: QUALITY_HIGH,
keyFrameInterval: KEY_FRAME_INTERVAL_SEC,
});
output.addVideoTrack(source);
const audio = voice ? new AudioBufferSource({ codec: voice.codec, quality: QUALITY_MEDIUM }) : null;
if (audio) output.addAudioTrack(audio);
await output.start();
try {
await composeGuideFrames(
guide,
frames,
screenshots,
{ ...options, timeline },
brand,
ctx,
device,
(at, dur) => source.add(at, dur),
controls,
);
if (voice && audio) {
const { writeVoiceTrack } = await import('./voiceover/audio');
const spans = stepSpans(timeline, frames.length);
const offset = options.cover ? timeline.coverSeconds : 0;
const total = offset + spannedFrames(spans) / FPS + (options.cover ? COVER_SECONDS : 0);
await writeVoiceTrack(
voiceoverPlacement(voice.clips, stepStarts(spans), offset),
total,
(buffer) => audio.add(buffer),
undefined,
controls.onMuxProgress,
controls.signal,
);
}
if (controls.signal?.aborted) throw new DOMException('Video export was aborted', 'AbortError');
await output.finalize();
} catch (error) {
await output.cancel();
throw error;
}
const buffer = output.target.buffer;
if (!buffer) throw new Error('Video encoding produced no output');
return {
blob: new Blob([buffer], { type: mp4 ? 'video/mp4' : 'video/webm' }),
extension: mp4 ? 'mp4' : 'webm',
chapters: videoChapters(frames, Boolean(options.cover), FPS, timeline),
...(narration.error ? { voiceoverError: narration.error } : {}),
};
}