repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/voice/src/speak-protocol.ts
Rawexport 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"],
};
}