Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/voice/src/speak-protocol.ts

Raw
export type Key = string;

export type Capabilities = {
	capture: boolean;
	render: boolean;
	aec: boolean;
	recognition: boolean;
	preview: boolean;
	hotwords: boolean;
	synthesis: boolean;
	sounds: boolean;
	test_io: boolean;
};

export type Profile = {
	id: Key;
	label: string;
	description: string;
	installed: boolean;
	capabilities: Capabilities;
};

export type Asset = {
	id: Key;
	kind: "model" | "runtime" | "sound";
	destination: string;
	source: string;
	sha256: string;
	download_bytes: number;
	installed_bytes: number;
	cached: boolean;
	license: { name: string; url: string; acceptance_required: boolean };
};

export type Plan = {
	id: Key;
	profile: Key;
	ready: boolean;
	writes_required: boolean;
	download_bytes: number;
	installed_bytes: number;
	items: Asset[];
	blockers: string[];
	expires_in_ms: number;
};

export type Sound = {
	id: Key;
	label: string;
	installed: boolean;
	sha256: string;
};

export type Limits = {
	line_bytes: number;
	pending_requests: number;
	active_operations: number;
	resources: number;
	text_chars: number;
	queued_text_chars: number;
	unacked_segments: number;
	hotwords: number;
	hotword_chars: number;
	waveform_bins: number;
	output_queue_bytes: number;
	instance_requests: number;
	instance_operations: number;
};

export type ServiceInfo = {
	instance: Key;
	io_mode: "device" | "fixture" | "fake";
	profiles: Profile[];
	devices: Array<{
		id: Key;
		label: string;
		direction: "capture" | "render";
		available: boolean;
	}>;
	sounds: Sound[];
	capabilities: Capabilities;
	limits: Limits;
};

export type ErrorData = {
	kind:
		| "invalid"
		| "unsupported"
		| "busy"
		| "missing_assets"
		| "consent"
		| "stale"
		| "not_found"
		| "device"
		| "integrity"
		| "io"
		| "timeout"
		| "cancelled"
		| "internal";
	retryable: boolean;
	field: string | null;
	resource: Key | null;
	operation: Key | null;
	detail: string;
};

export type OperationOutcome = {
	outcome: "completed" | "cancelled" | "failed";
	reason: string;
	stop_frame: number | null;
	error: ErrorData | null;
};

export type SpeakEvent = {
	method:
		| "operation.progress"
		| "operation.ended"
		| "resource.ready"
		| "resource.health"
		| "resource.closed"
		| "recognition.activity"
		| "recognition.pending"
		| "recognition.preview"
		| "recognition.preview_cleared"
		| "recognition.final"
		| "recognition.empty"
		| "synthesis.phrase"
		| "playback.progress"
		| "playback.boundary"
		| "audio.level"
		| "service.warning";
	params: {
		instance: Key;
		seq: number;
		resource: Key | null;
		epoch: number | null;
		operation: Key | null;
		data: Record<string, unknown>;
	};
};

const eventNames = new Set<string>([
	"operation.progress",
	"operation.ended",
	"resource.ready",
	"resource.health",
	"resource.closed",
	"recognition.activity",
	"recognition.pending",
	"recognition.preview",
	"recognition.preview_cleared",
	"recognition.final",
	"recognition.empty",
	"synthesis.phrase",
	"playback.progress",
	"playback.boundary",
	"audio.level",
	"service.warning",
]);

type JsonRecord = Record<string, unknown> & {
	kind?: unknown;
	retryable?: unknown;
	field?: unknown;
	resource?: unknown;
	operation?: unknown;
	detail?: unknown;
	done_bytes?: unknown;
	total_bytes?: unknown;
	outcome?: unknown;
	reason?: unknown;
	stop_frame?: unknown;
	error?: unknown;
	capture?: unknown;
	render?: unknown;
	speech?: unknown;
	capture_rate?: unknown;
	render_rate?: unknown;
	status?: unknown;
	capture_frame?: unknown;
	render_frame?: unknown;
	active?: unknown;
	segment?: unknown;
	pending?: unknown;
	revision?: unknown;
	text?: unknown;
	start_frame?: unknown;
	end_frame?: unknown;
	index?: unknown;
	input?: unknown;
	output?: unknown;
	waveform?: unknown;
	playing?: unknown;
	busy?: unknown;
	phase?: unknown;
	through_revision?: unknown;
	through_frame?: unknown;
	consumed_frames?: unknown;
	played_text?: unknown;
	message?: unknown;
	instance?: unknown;
	seq?: unknown;
	epoch?: unknown;
	data?: unknown;
};

export function isRecord(value: unknown): value is JsonRecord {
	return typeof value === "object" && value !== null && !Array.isArray(value);
}

function key(value: unknown): value is Key {
	return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value);
}

function text(value: unknown, limit = 8_000): value is string {
	return typeof value === "string" && [...value].length <= limit;
}

function integer(value: unknown): value is number {
	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
}

function nullableKey(value: unknown): boolean {
	return value === null || key(value);
}

function requireFields(
	value: Record<string, unknown>,
	fields: readonly string[],
): boolean {
	return fields.every((field) => field in value);
}

function validError(value: unknown): boolean {
	return (
		isRecord(value) &&
		requireFields(value, [
			"kind",
			"retryable",
			"field",
			"resource",
			"operation",
			"detail",
		]) &&
		[
			"invalid",
			"unsupported",
			"busy",
			"missing_assets",
			"consent",
			"stale",
			"not_found",
			"device",
			"integrity",
			"io",
			"timeout",
			"cancelled",
			"internal",
		].includes(value.kind as string) &&
		typeof value.retryable === "boolean" &&
		(value.field === null || text(value.field, 256)) &&
		nullableKey(value.resource) &&
		nullableKey(value.operation) &&
		text(value.detail, 512)
	);
}

function validData(method: string, value: unknown): boolean {
	if (!isRecord(value)) return false;
	const numbers = (...names: string[]) =>
		names.every((name) => integer(value[name]));
	switch (method) {
		case "operation.progress":
			return (
				["validating", "downloading", "installing", "loading"].includes(
					value.phase as string,
				) &&
				numbers("done_bytes", "total_bytes") &&
				(value.done_bytes as number) <= (value.total_bytes as number)
			);
		case "operation.ended":
			return (
				(value.outcome === "completed" ||
					value.outcome === "cancelled" ||
					value.outcome === "failed") &&
				text(value.reason, 64) &&
				(value.stop_frame === null || integer(value.stop_frame)) &&
				(value.outcome === "failed") === (value.error !== null) &&
				(value.error === null || validError(value.error))
			);
		case "resource.ready":
			return (
				typeof value.capture === "boolean" &&
				typeof value.render === "boolean" &&
				typeof value.speech === "boolean" &&
				(value.capture_rate === null ||
					(integer(value.capture_rate) &&
						value.capture_rate >= 1 &&
						value.capture_rate <= 384_000)) &&
				(value.render_rate === null ||
					(integer(value.render_rate) &&
						value.render_rate >= 1 &&
						value.render_rate <= 384_000))
			);
		case "resource.health":
			return (
				value.status === "unavailable" &&
				numbers("capture_frame", "render_frame") &&
				validError(value.error)
			);
		case "resource.closed":
			return numbers("capture_frame", "render_frame");
		case "recognition.activity":
			return typeof value.active === "boolean" && nullableKey(value.segment);
		case "recognition.pending":
			return typeof value.pending === "boolean";
		case "recognition.preview":
			return (
				key(value.segment) &&
				numbers("revision") &&
				(value.revision as number) >= 1 &&
				text(value.text)
			);
		case "recognition.preview_cleared":
			return key(value.segment) && numbers("through_revision");
		case "recognition.final":
			return (
				key(value.segment) &&
				text(value.text) &&
				numbers("start_frame", "end_frame") &&
				(value.start_frame as number) <= (value.end_frame as number)
			);
		case "recognition.empty":
			return (
				key(value.segment) &&
				numbers("start_frame", "end_frame") &&
				(value.start_frame as number) <= (value.end_frame as number)
			);
		case "synthesis.phrase":
			return numbers("index") && text(value.text) && /\S/u.test(value.text);
		case "playback.progress":
			return (
				numbers("through_frame", "consumed_frames") && text(value.played_text)
			);
		case "playback.boundary":
			return numbers("through_frame");
		case "audio.level":
			return (
				typeof value.input === "number" &&
				Number.isFinite(value.input) &&
				value.input >= 0 &&
				typeof value.output === "number" &&
				Number.isFinite(value.output) &&
				value.output >= 0 &&
				Array.isArray(value.waveform) &&
				value.waveform.length <= 32 &&
				value.waveform.every(
					(item) =>
						typeof item === "number" && Number.isFinite(item) && item >= 0,
				) &&
				typeof value.playing === "boolean" &&
				typeof value.busy === "boolean"
			);
		case "service.warning":
			return (
				[
					"invalid",
					"unsupported",
					"busy",
					"missing_assets",
					"consent",
					"stale",
					"not_found",
					"device",
					"integrity",
					"io",
					"timeout",
					"cancelled",
					"internal",
				].includes(value.kind as string) && text(value.message, 512)
			);
		default:
			return false;
	}
}

/** Validates known event shapes; unknown events retain the common sequence fence. */
export function parseEvent(
	method: unknown,
	params: unknown,
): SpeakEvent | undefined {
	if (typeof method !== "string" || !isRecord(params))
		throw new Error("invalid notification");
	if (
		!requireFields(params, [
			"instance",
			"seq",
			"resource",
			"epoch",
			"operation",
			"data",
		]) ||
		!key(params.instance) ||
		!integer(params.seq) ||
		params.seq < 1 ||
		!nullableKey(params.resource) ||
		(params.epoch !== null && (!integer(params.epoch) || params.epoch < 1)) ||
		!nullableKey(params.operation) ||
		!isRecord(params.data)
	)
		throw new Error("invalid event fence");
	if (!eventNames.has(method)) return undefined;
	if (!validData(method, params.data))
		throw new Error(`invalid ${method} event`);
	return {
		method: method as SpeakEvent["method"],
		params: params as SpeakEvent["params"],
	};
}