@vocalstack/mcp 1.0.0 → 1.3.0

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.
@@ -0,0 +1,964 @@
1
+ import { createHash } from "node:crypto";
2
+ import { ToolError, bad } from "./errors.js";
3
+ export const MAX_FILE_BYTES = 10 * 1024 * 1024;
4
+ export const MAX_FILE_BASE64_CHARS = Math.floor(MAX_FILE_BYTES / 3) * 4 + 8 + 1024;
5
+ export const WAIT_MAX_S = 60;
6
+ export const WAITS_PER_KEY = 4;
7
+ const WAIT_POLL_MS = 1000;
8
+ const UPLOAD_TIMEOUT_MS = 15 * 60_000;
9
+ const LANGUAGES_TTL_MS = 60 * 60_000;
10
+ const NO_TRANSCRIPTION = "No transcription with that id for this account.";
11
+ const NO_BROADCAST = "No broadcast with that id for this account.";
12
+ const NO_SPEAKER = "No saved speaker with that id for this account; list_speakers shows them.";
13
+ const OPEN = new Set(["pending", "live", "paused", "processing"]);
14
+ const TERMINAL = new Set(["done", "failed", "stopped"]);
15
+ function put(o, k, v) {
16
+ if (v !== undefined && v !== null)
17
+ o[k] = v;
18
+ }
19
+ function path(...parts) {
20
+ return parts.map((p, i) => (i % 2 ? encodeURIComponent(p) : p)).join("");
21
+ }
22
+ function present(a, k) {
23
+ return a.raw[k] !== undefined && a.raw[k] !== null;
24
+ }
25
+ function notFound(e, message) {
26
+ if (e instanceof ToolError && (e.code === "not_found" || e.code === "forbidden")) {
27
+ throw new ToolError("not_found", message);
28
+ }
29
+ throw e;
30
+ }
31
+ async function transcription(ctx, id) {
32
+ try {
33
+ return await ctx.api.get(path("/v1/transcriptions/", id), undefined, ctx.signal);
34
+ }
35
+ catch (e) {
36
+ notFound(e, NO_TRANSCRIPTION);
37
+ }
38
+ }
39
+ async function broadcast(ctx, id) {
40
+ try {
41
+ return await ctx.api.get(path("/v1/broadcasts/", id), undefined, ctx.signal);
42
+ }
43
+ catch (e) {
44
+ notFound(e, NO_BROADCAST);
45
+ }
46
+ }
47
+ const languages = new Map();
48
+ async function targetLang(a, ctx, k) {
49
+ const l = a.str(k)?.toLowerCase();
50
+ if (l === undefined)
51
+ return undefined;
52
+ let known = languages.get(ctx.api.origin);
53
+ if (!known || Date.now() - known.at > LANGUAGES_TTL_MS) {
54
+ try {
55
+ const r = await ctx.api.get("/v1/languages", undefined, ctx.signal);
56
+ if (Array.isArray(r?.translation) && r.translation.length) {
57
+ known = { at: Date.now(), codes: new Set(r.translation.map((c) => String(c).toLowerCase())) };
58
+ languages.set(ctx.api.origin, known);
59
+ }
60
+ }
61
+ catch {
62
+ known = undefined;
63
+ }
64
+ }
65
+ if (known && !known.codes.has(l))
66
+ throw bad(`\`${k}\` ${JSON.stringify(l)} is not a language this API translates into`);
67
+ return l;
68
+ }
69
+ function jobStatus(job, t) {
70
+ const pr = job.progress ?? {};
71
+ const progress = { pct: pr.pct ?? 0, processedS: pr.processedS ?? 0, segmentsDone: pr.segmentsDone ?? 0 };
72
+ put(progress, "totalS", pr.totalS);
73
+ put(progress, "segmentsTotal", pr.segmentsTotal);
74
+ put(progress, "phase", pr.phase);
75
+ put(progress, "phasePct", pr.phasePct);
76
+ const s = { transcriptionId: t.id, name: t.name, kind: "file", state: job.state, progress, createdAt: job.createdAt };
77
+ put(s, "error", job.error);
78
+ put(s, "queue", job.queue);
79
+ put(s, "finishedAt", job.finishedAt);
80
+ put(s, "spokenLanguage", t.spokenLanguage);
81
+ if (job.source) {
82
+ const o = { kind: job.source.kind, name: job.source.name };
83
+ put(o, "durationS", job.source.durationS);
84
+ put(o, "format", job.source.format);
85
+ s.source = o;
86
+ }
87
+ return s;
88
+ }
89
+ function liveState(state) {
90
+ switch (state) {
91
+ case "processing":
92
+ case "ended":
93
+ return "finishing";
94
+ case "finalized":
95
+ return "done";
96
+ default:
97
+ return state;
98
+ }
99
+ }
100
+ function liveStatus(t) {
101
+ const s = { transcriptionId: t.id, name: t.name, kind: "live", state: liveState(t.state), createdAt: t.createdAt };
102
+ put(s, "startedAt", t.startedAt);
103
+ put(s, "endedAt", t.endedAt);
104
+ put(s, "spokenLanguage", t.spokenLanguage);
105
+ put(s, "durationS", t.durationS);
106
+ return s;
107
+ }
108
+ function statusOf(t) {
109
+ return t.job ? jobStatus(t.job, t) : liveStatus(t);
110
+ }
111
+ function mmss(s) {
112
+ const t = Math.floor(Math.max(0, s));
113
+ const two = (n) => String(n).padStart(2, "0");
114
+ if (t >= 3600)
115
+ return `${Math.floor(t / 3600)}:${two(Math.floor(t / 60) % 60)}:${two(t % 60)}`;
116
+ return `${two(Math.floor(t / 60))}:${two(t % 60)}`;
117
+ }
118
+ function genericName(n) {
119
+ const w = n.trim().split(/\s+/);
120
+ return w.length === 2 && w[0].toLowerCase() === "speaker" && /^\d*$/.test(w[1]);
121
+ }
122
+ function firstOrder(lines) {
123
+ const first = new Map();
124
+ for (const l of lines) {
125
+ if (l.speaker < 0)
126
+ continue;
127
+ const at = first.get(l.speaker);
128
+ if (at === undefined || l.start < at)
129
+ first.set(l.speaker, l.start);
130
+ }
131
+ const order = [...first.entries()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
132
+ return new Map(order.map(([spk], i) => [spk, i + 1]));
133
+ }
134
+ function numbering(lines, snapshot) {
135
+ const server = new Map();
136
+ for (const a of snapshot.speakers ?? []) {
137
+ if (typeof a.number === "number")
138
+ server.set(a.speaker, a.number);
139
+ }
140
+ const order = firstOrder(lines);
141
+ const numbers = new Map(server);
142
+ if (server.size === 0)
143
+ for (const [k, v] of order)
144
+ numbers.set(k, v);
145
+ else {
146
+ let top = Math.max(...server.values());
147
+ const rest = [...order.entries()].filter(([s]) => !server.has(s)).sort((a, b) => a[1] - b[1]);
148
+ for (const [s] of rest)
149
+ numbers.set(s, ++top);
150
+ }
151
+ return numbers;
152
+ }
153
+ function labelled(raw, snapshot, t) {
154
+ const mode = snapshot.speakerLabels ?? t.settings?.speakerLabels ?? "auto";
155
+ const off = mode === "off";
156
+ const lines = raw.map((l) => ({ ...l, speaker: off ? -1 : l.speaker }));
157
+ const heard = new Set(raw.map((l) => l.speaker).filter((s) => s >= 0)).size;
158
+ const shown = mode === "on" || (mode === "auto" && heard > 1);
159
+ const names = new Map();
160
+ for (const a of snapshot.speakers ?? []) {
161
+ if (typeof a.name === "string")
162
+ names.set(a.speaker, a.name);
163
+ }
164
+ const numbers = numbering(lines, snapshot);
165
+ return lines.map((l) => {
166
+ let speakerName = "";
167
+ if (shown) {
168
+ if (l.speaker < 0)
169
+ speakerName = "Unknown speaker";
170
+ else {
171
+ const given = names.get(l.speaker)?.trim();
172
+ speakerName = given && !genericName(given) ? given : `Speaker ${numbers.get(l.speaker) ?? 0}`;
173
+ }
174
+ }
175
+ const speakerNumber = l.speaker >= 0 ? numbers.get(l.speaker) : undefined;
176
+ return { ...l, speakerName, speakerNumber };
177
+ });
178
+ }
179
+ function page(lines, format, words, offset, limit) {
180
+ const total = lines.length;
181
+ const slice = lines.slice(Math.min(offset, total), Math.min(offset + limit, total));
182
+ const out = { segmentCount: total };
183
+ if (offset + slice.length < total)
184
+ out.nextOffset = offset + slice.length;
185
+ const speaker = (l) => {
186
+ if (l.speakerName.trim())
187
+ return l.speakerName;
188
+ if (l.speaker >= 0)
189
+ return `Speaker ${l.speakerNumber ?? l.speaker + 1}`;
190
+ return undefined;
191
+ };
192
+ if (format === "segments") {
193
+ out.segments = slice.map((l) => {
194
+ const s = { start: l.start, end: l.end, text: l.text };
195
+ if (l.speaker >= 0) {
196
+ s.speaker = l.speaker;
197
+ put(s, "speakerNumber", l.speakerNumber);
198
+ }
199
+ put(s, "speakerName", speaker(l));
200
+ put(s, "language", l.language);
201
+ if (words)
202
+ s.words = (l.words ?? []).map((w) => ({ text: w.text, start: w.start, end: w.end }));
203
+ return s;
204
+ });
205
+ }
206
+ else {
207
+ out.text = slice
208
+ .map((l) => {
209
+ const n = speaker(l);
210
+ return n ? `[${mmss(l.start)}] ${n}: ${l.text.trim()}` : `[${mmss(l.start)}] ${l.text.trim()}`;
211
+ })
212
+ .join("\n");
213
+ }
214
+ return out;
215
+ }
216
+ async function snapshot(ctx, id) {
217
+ try {
218
+ return await ctx.api.get(path("/v1/transcriptions/", id, "/transcript"), undefined, ctx.signal);
219
+ }
220
+ catch (e) {
221
+ notFound(e, NO_TRANSCRIPTION);
222
+ }
223
+ }
224
+ function spokenSegments(snap) {
225
+ return (snap.segments ?? [])
226
+ .filter((s) => typeof s.text === "string" && s.text.trim())
227
+ .map((s) => ({ start: s.start, end: s.end, speaker: s.speaker ?? -1, text: s.text, language: s.language, words: s.words ?? [] }));
228
+ }
229
+ function segmentLines(snap, t) {
230
+ return labelled(spokenSegments(snap), snap, t);
231
+ }
232
+ function validKey(k) {
233
+ return k.length >= 1 && k.length <= 255 && /^[\x21-\x7e]+$/.test(k);
234
+ }
235
+ function idempotencyKey(a) {
236
+ const k = a.str("idempotencyKey");
237
+ if (k !== undefined && !validKey(k))
238
+ throw bad("idempotencyKey must be 1 to 255 visible ASCII characters");
239
+ return k;
240
+ }
241
+ function stepKey(key, step) {
242
+ const k = `${key}:${step}`;
243
+ return k.length <= 255 ? k : `${createHash("sha256").update(key).digest("hex")}:${step}`;
244
+ }
245
+ function sourceOf(a) {
246
+ const url = present(a, "url");
247
+ const file = present(a, "fileBase64");
248
+ if (url && file)
249
+ throw bad("give either `url` or `fileBase64`, not both");
250
+ if (!url && !file)
251
+ throw bad(`give \`url\` (a public link) or \`fileBase64\` with \`filename\` (a file up to ${MAX_FILE_BYTES >> 20} MiB)`);
252
+ if (url) {
253
+ const stray = ["filename", "mimeType"].find((k) => present(a, k));
254
+ if (stray)
255
+ throw bad(`\`${stray}\` goes with \`fileBase64\`, not with \`url\``);
256
+ }
257
+ return file;
258
+ }
259
+ function transcribeOptions(a) {
260
+ const settings = {};
261
+ const spoken = a.str("spokenLanguage");
262
+ if (spoken !== undefined)
263
+ settings.spokenLanguage = spoken;
264
+ settings.speakerLabels = a.oneOf("speakerLabels", ["auto", "on", "off"], "auto");
265
+ if (a.bool("summary")) {
266
+ settings.summary = true;
267
+ settings.title = true;
268
+ }
269
+ const options = { settings, shareLink: a.bool("shareLink") };
270
+ put(options, "name", a.str("name"));
271
+ put(options, "startS", a.num("startS"));
272
+ put(options, "endS", a.num("endS"));
273
+ return options;
274
+ }
275
+ function decodeFile(a) {
276
+ const tooBig = () => bad(`fileBase64 is over ${MAX_FILE_BYTES >> 20} MiB decoded; give \`url\` a link to the file instead`);
277
+ const raw = a.rawStr("fileBase64");
278
+ if (raw === undefined)
279
+ throw bad("`fileBase64` must be a string");
280
+ if (raw.length > MAX_FILE_BASE64_CHARS)
281
+ throw tooBig();
282
+ let b64 = raw.trim();
283
+ const at = b64.indexOf(";base64,");
284
+ if (at >= 0)
285
+ b64 = b64.slice(at + 8);
286
+ if (!b64)
287
+ throw bad("`fileBase64` is required");
288
+ if (b64.length > Math.floor(MAX_FILE_BYTES / 3) * 4 + 8)
289
+ throw tooBig();
290
+ const clean = b64.replace(/\s+/g, "");
291
+ const body = clean.replace(/=+$/, "");
292
+ const badAt = body.search(/[^A-Za-z0-9+/]/);
293
+ if (badAt >= 0)
294
+ throw bad(`fileBase64 is not valid base64: Invalid symbol ${body.charCodeAt(badAt)}, offset ${badAt}.`);
295
+ if (body.length % 4 === 1 || clean.length - body.length > 2)
296
+ throw bad("fileBase64 is not valid base64: Invalid input length.");
297
+ const bytes = Buffer.from(body, "base64");
298
+ if (bytes.length > MAX_FILE_BYTES)
299
+ throw bad(`the file is over ${MAX_FILE_BYTES >> 20} MiB; give \`url\` a link to it instead`);
300
+ if (bytes.length === 0)
301
+ throw new ToolError("invalid_audio", "the file is empty");
302
+ return bytes;
303
+ }
304
+ async function transcribe(a, ctx) {
305
+ const key = idempotencyKey(a);
306
+ const file = sourceOf(a);
307
+ const options = transcribeOptions(a);
308
+ let res;
309
+ if (!file) {
310
+ const url = a.reqStr("url");
311
+ if (url.length > 2048)
312
+ throw bad("`url` is longer than 2048 characters");
313
+ res = await ctx.api.request("POST", "/v1/transcriptions", { json: { ...options, url }, idempotencyKey: key, signal: ctx.signal });
314
+ }
315
+ else {
316
+ const filename = a.reqStr("filename");
317
+ const bytes = decodeFile(a);
318
+ const mime = a.str("mimeType");
319
+ const type = mime && mime !== "application/octet-stream" ? mime : "application/octet-stream";
320
+ const form = new FormData();
321
+ form.append("options", JSON.stringify(options));
322
+ form.append("file", new Blob([new Uint8Array(bytes)], { type }), [...filename].slice(0, 255).join(""));
323
+ res = await ctx.api.request("POST", "/v1/transcriptions", { form, idempotencyKey: key, signal: ctx.signal, timeoutMs: UPLOAD_TIMEOUT_MS });
324
+ }
325
+ const t = res.data;
326
+ if (!t.job)
327
+ t.job = await ctx.api.get(path("/v1/transcriptions/", t.id, "/job"), undefined, ctx.signal);
328
+ const v = statusOf(t);
329
+ if (options.shareLink) {
330
+ const links = await ctx.api.get(path("/v1/transcriptions/", t.id, "/share-links"), undefined, ctx.signal);
331
+ const first = links?.links?.[0];
332
+ if (first?.url)
333
+ v.shareUrl = first.url;
334
+ }
335
+ v.next = `Call get_transcription with this transcriptionId and waitS (up to ${WAIT_MAX_S}) to wait for the text.`;
336
+ if (res.headers.get("idempotent-replayed") === "true")
337
+ v.replayed = true;
338
+ return v;
339
+ }
340
+ let waitsOpen = 0;
341
+ function takeWait() {
342
+ if (waitsOpen >= WAITS_PER_KEY) {
343
+ throw new ToolError("rate_limited", `this key already has ${WAITS_PER_KEY} waits open; let one finish first`, {
344
+ retryAfterS: 5,
345
+ limit: WAITS_PER_KEY,
346
+ });
347
+ }
348
+ waitsOpen++;
349
+ let held = true;
350
+ return () => {
351
+ if (held)
352
+ waitsOpen--;
353
+ held = false;
354
+ };
355
+ }
356
+ function phaseText(job) {
357
+ const pr = job.progress ?? {};
358
+ if (job.state === "fetching") {
359
+ const b = pr.fetchedBytes;
360
+ const t = pr.fetchTotalBytes;
361
+ if (pr.phase === "extracting")
362
+ return "extracting the audio";
363
+ if (typeof b === "number" && typeof t === "number")
364
+ return `fetching ${(b / 1e6).toFixed(1)} / ${(t / 1e6).toFixed(1)} MB`;
365
+ if (typeof b === "number")
366
+ return `fetching ${(b / 1e6).toFixed(1)} MB`;
367
+ return "fetching";
368
+ }
369
+ if (job.state === "transcribing") {
370
+ const done = pr.processedS ?? 0;
371
+ return typeof pr.totalS === "number" ? `transcribing ${mmss(done)} of ${mmss(pr.totalS)}` : `transcribing ${mmss(done)}`;
372
+ }
373
+ return String(job.state);
374
+ }
375
+ function sleep(ms, signal) {
376
+ return new Promise((resolve) => {
377
+ if (signal.aborted)
378
+ return resolve();
379
+ const done = () => {
380
+ clearTimeout(timer);
381
+ signal.removeEventListener("abort", done);
382
+ resolve();
383
+ };
384
+ const timer = setTimeout(done, ms);
385
+ signal.addEventListener("abort", done, { once: true });
386
+ });
387
+ }
388
+ async function waitFor(ctx, id, first, timeoutMs) {
389
+ const release = takeWait();
390
+ try {
391
+ const deadline = Date.now() + timeoutMs;
392
+ let job = first;
393
+ let lastSent;
394
+ let lastAt = 0;
395
+ for (;;) {
396
+ if (ctx.progress) {
397
+ const msg = phaseText(job);
398
+ const now = `${job.progress?.pct ?? 0}|${msg}`;
399
+ if (lastSent !== now && Date.now() - lastAt >= 1000) {
400
+ await ctx.progress(job.progress?.pct ?? 0, 100, msg).catch(() => { });
401
+ lastSent = now;
402
+ lastAt = Date.now();
403
+ }
404
+ }
405
+ const left = deadline - Date.now();
406
+ if (left <= 0 || ctx.signal.aborted)
407
+ return true;
408
+ await sleep(Math.min(WAIT_POLL_MS, left), ctx.signal);
409
+ if (ctx.signal.aborted)
410
+ return true;
411
+ try {
412
+ job = await ctx.api.get(path("/v1/transcriptions/", id, "/job"), undefined, ctx.signal);
413
+ }
414
+ catch (e) {
415
+ if (ctx.signal.aborted)
416
+ return true;
417
+ notFound(e, NO_TRANSCRIPTION);
418
+ }
419
+ if (TERMINAL.has(job.state))
420
+ return false;
421
+ }
422
+ }
423
+ finally {
424
+ release();
425
+ }
426
+ }
427
+ function family(l) {
428
+ return l.split(/[_-]/)[0].toLowerCase();
429
+ }
430
+ async function translatedLines(ctx, id, snap, t, lang, offset, limit) {
431
+ const spoken = t.spokenLanguage ?? undefined;
432
+ const sentences = (snap.sentences ?? [])
433
+ .filter((s) => s.status !== "dropped" && typeof s.text === "string" && s.text.trim())
434
+ .sort((x, y) => x.start - y.start || x.sentenceId - y.sentenceId);
435
+ const lines = labelled(sentences.map((s) => ({ start: s.start, end: s.end, speaker: s.speaker ?? -1, text: s.text, language: s.language })), snap, t);
436
+ const shown = sentences.slice(Math.min(offset, sentences.length), Math.min(offset + limit, sentences.length));
437
+ const have = new Map();
438
+ const missing = [];
439
+ for (const s of shown) {
440
+ const done = s.translations?.[lang];
441
+ if (typeof done === "string")
442
+ have.set(s.sentenceId, done);
443
+ else if (!(s.language && family(s.language) === family(lang)))
444
+ missing.push(s.sentenceId);
445
+ }
446
+ for (let i = 0; i < missing.length; i += 40) {
447
+ let r;
448
+ try {
449
+ r = await ctx.api.get(path("/v1/transcriptions/", id, "/translation"), { lang, sentences: missing.slice(i, i + 40).join(",") }, ctx.signal);
450
+ }
451
+ catch (e) {
452
+ if (e instanceof ToolError && e.code === "invalid_options")
453
+ throw bad(`\`lang\` ${JSON.stringify(lang)} is not a language this API translates into`);
454
+ notFound(e, NO_TRANSCRIPTION);
455
+ }
456
+ for (const [k, v] of Object.entries(r.translations ?? {}))
457
+ if (typeof v === "string")
458
+ have.set(Number(k), v);
459
+ }
460
+ sentences.forEach((s, i) => {
461
+ const done = have.get(s.sentenceId);
462
+ if (done !== undefined) {
463
+ lines[i].text = done;
464
+ lines[i].language = lang;
465
+ }
466
+ else if (!(s.language && family(s.language) === family(lang))) {
467
+ lines[i].language = s.language ?? spoken ?? null;
468
+ }
469
+ });
470
+ return lines;
471
+ }
472
+ async function getTranscription(a, ctx) {
473
+ const id = a.id("transcriptionId");
474
+ const waitS = a.int("waitS", 0, 0, WAIT_MAX_S);
475
+ const format = a.oneOf("format", ["text", "segments", "none"], "text");
476
+ const lang = await targetLang(a, ctx, "lang");
477
+ const words = a.bool("includeWords");
478
+ if (words && lang !== undefined)
479
+ throw bad("`includeWords` is for the original language; leave it out with `lang`");
480
+ const offset = a.int("offset", 0, 0, 4294967295);
481
+ const limit = a.int("limit", 500, 1, 2000);
482
+ let t = await transcription(ctx, id);
483
+ let timedOut;
484
+ if (waitS > 0) {
485
+ timedOut = false;
486
+ if (t.job && !TERMINAL.has(t.job.state)) {
487
+ timedOut = await waitFor(ctx, id, t.job, waitS * 1000);
488
+ t = await transcription(ctx, id);
489
+ }
490
+ }
491
+ const out = { status: statusOf(t) };
492
+ if (timedOut !== undefined)
493
+ out.timedOut = timedOut;
494
+ if (format === "none")
495
+ return out;
496
+ if (lang !== undefined) {
497
+ let notYet;
498
+ if (t.job && t.job.state !== "done")
499
+ notYet = `the transcription is ${t.job.state}; wait until it is done (get_transcription with waitS)`;
500
+ else if (!t.job && OPEN.has(t.state)) {
501
+ notYet = "the live transcription is still running; read the text so far without lang, or stop it (stop_broadcast) and translate it then";
502
+ }
503
+ if (notYet !== undefined) {
504
+ if (timedOut === true)
505
+ return out;
506
+ throw new ToolError("invalid_state", notYet);
507
+ }
508
+ const snap = await snapshot(ctx, id);
509
+ const spoken = t.spokenLanguage ?? undefined;
510
+ const same = spoken !== undefined && family(spoken) === family(lang);
511
+ const lines = same ? segmentLines(snap, t) : await translatedLines(ctx, id, snap, t, lang, offset, limit);
512
+ return { ...out, ...page(lines, format, false, offset, limit), lang, translated: !same };
513
+ }
514
+ const snap = await snapshot(ctx, id);
515
+ Object.assign(out, page(segmentLines(snap, t), format, words, offset, limit));
516
+ const partial = t.job ? !TERMINAL.has(t.job.state) : t.state !== "finalized";
517
+ if (partial)
518
+ out.partial = true;
519
+ return out;
520
+ }
521
+ async function listTranscriptions(a, ctx) {
522
+ const lifecycle = a.oneOf("lifecycle", ["active", "archived", "all"], "active");
523
+ const limit = a.int("limit", 20, 1, 100);
524
+ let cursor = a.str("cursor");
525
+ const items = [];
526
+ for (let i = 0; i < 10; i++) {
527
+ let got;
528
+ try {
529
+ got = await ctx.api.get("/v1/transcriptions", { lifecycle, cursor, limit: limit - items.length }, ctx.signal);
530
+ }
531
+ catch (e) {
532
+ if (e instanceof ToolError && e.code === "invalid_options")
533
+ throw bad("`cursor` is not one this tool gave out");
534
+ throw e;
535
+ }
536
+ for (const s of got.transcriptions ?? []) {
537
+ const v = { transcriptionId: s.id, name: s.name, createdAt: s.createdAt };
538
+ if (s.job) {
539
+ v.kind = "file";
540
+ v.state = s.job.state;
541
+ put(v, "durationS", s.job.source?.durationS ?? s.job.progress?.totalS);
542
+ }
543
+ else {
544
+ v.kind = "live";
545
+ v.state = liveState(s.state);
546
+ put(v, "durationS", s.durationS);
547
+ put(v, "broadcastId", s.broadcasts?.[0]?.id);
548
+ }
549
+ put(v, "title", s.title);
550
+ items.push(v);
551
+ }
552
+ cursor = got.nextCursor ?? undefined;
553
+ if (!cursor || items.length >= limit)
554
+ break;
555
+ }
556
+ const out = { transcriptions: items };
557
+ if (cursor)
558
+ out.nextCursor = cursor;
559
+ return out;
560
+ }
561
+ function query(a) {
562
+ const q = a.reqStr("query");
563
+ const n = [...q].length;
564
+ if (n < 2 || n > 200)
565
+ throw bad("`query` must be 2 to 200 characters");
566
+ return q;
567
+ }
568
+ async function only(a, ctx) {
569
+ const id = a.optId("transcriptionId");
570
+ if (id !== undefined)
571
+ await transcription(ctx, id);
572
+ return id;
573
+ }
574
+ async function searchWords(a, ctx) {
575
+ const q = query(a);
576
+ const transcriptionId = await only(a, ctx);
577
+ const lang = a.str("lang");
578
+ const limit = a.int("limit", 20, 1, 50);
579
+ const r = await ctx.api.get("/v1/search", { q, transcription: transcriptionId, lang, limit }, ctx.signal);
580
+ const hits = (r.hits ?? []).map((h) => {
581
+ const v = {
582
+ transcriptionId: h.transcriptionId,
583
+ name: h.linkName,
584
+ mediaStart: h.mediaStart,
585
+ speaker: h.speaker,
586
+ text: h.text,
587
+ score: h.score,
588
+ live: h.live,
589
+ };
590
+ put(v, "rendered", h.rendered);
591
+ put(v, "recordedAt", h.recordedAt);
592
+ return v;
593
+ });
594
+ return { query: r.query, queryEn: r.queryEn, hits };
595
+ }
596
+ async function searchMeaning(a, ctx) {
597
+ const stray = ["lang", "limit"].find((k) => present(a, k));
598
+ if (stray)
599
+ throw bad(`\`${stray}\` applies to mode words only; leave it out with mode meaning`);
600
+ const q = query(a);
601
+ const transcriptionId = await only(a, ctx);
602
+ const r = await ctx.api.get("/v1/search/vector", { q, transcription: transcriptionId }, ctx.signal);
603
+ const passages = (r.hits ?? []).map((h) => ({
604
+ transcriptionId: h.transcriptionId,
605
+ name: h.linkName,
606
+ mediaStart: h.passage?.mediaStart ?? h.mediaStart,
607
+ mediaEnd: h.passage?.mediaEnd ?? h.mediaStart,
608
+ text: h.passage?.text ?? h.text,
609
+ similarity: Math.round(h.similarity * 1000) / 1000,
610
+ live: h.live,
611
+ }));
612
+ const out = { query: r.query, state: r.state, passages };
613
+ put(out, "searchesLeftThisHour", r.allowance?.remaining);
614
+ return out;
615
+ }
616
+ async function search(a, ctx) {
617
+ return a.oneOf("mode", ["words", "meaning"], "words") === "meaning" ? searchMeaning(a, ctx) : searchWords(a, ctx);
618
+ }
619
+ async function summary(a, ctx) {
620
+ const id = a.id("transcriptionId");
621
+ const lang = await targetLang(a, ctx, "lang");
622
+ const t = await transcription(ctx, id);
623
+ const pending = (message) => ({ state: "pending", message });
624
+ const s = await ctx.api.get(path("/v1/transcriptions/", id, "/summary"), { lang }, ctx.signal);
625
+ if (s.state === "ready") {
626
+ const v = { state: "ready", title: s.title ?? t.name, summary: s.summary };
627
+ put(v, "lang", s.lang);
628
+ return v;
629
+ }
630
+ if (t.job?.state === "failed") {
631
+ return { state: "unavailable", message: "The transcription failed, so there is nothing to summarise." };
632
+ }
633
+ if ((t.job && !TERMINAL.has(t.job.state)) || (!t.job && OPEN.has(t.state))) {
634
+ return pending("The transcription is still running; wait for it (get_transcription with waitS), then ask again.");
635
+ }
636
+ if (s.state === "pending")
637
+ return pending("The summary is being written; ask again in a few seconds.");
638
+ let made;
639
+ try {
640
+ made = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/summarize"), { signal: ctx.signal })).data;
641
+ }
642
+ catch (e) {
643
+ if (e instanceof ToolError && e.code === "forbidden") {
644
+ throw new ToolError("forbidden", "This transcription has no summary yet, and starting one needs the write scope; this credential can only read an existing summary.", { requiredScope: ["write"] });
645
+ }
646
+ throw e;
647
+ }
648
+ switch (made.state) {
649
+ case "ready":
650
+ return { state: "ready", title: made.title ?? t.name, summary: made.summary };
651
+ case "unavailable":
652
+ return { state: "unavailable", message: "Summaries are not available on this server." };
653
+ case "not_requested":
654
+ return { state: "not_requested", message: "Transcriptions shorter than a minute are not summarised." };
655
+ default:
656
+ return pending("The summary is being written; ask again in a few seconds.");
657
+ }
658
+ }
659
+ async function all(ctx, route, field, query = {}) {
660
+ const out = [];
661
+ let cursor;
662
+ for (let i = 0; i < 50; i++) {
663
+ const r = await ctx.api.get(route, { ...query, cursor }, ctx.signal);
664
+ out.push(...(r[field] ?? []));
665
+ cursor = r.nextCursor ?? undefined;
666
+ if (!cursor)
667
+ break;
668
+ }
669
+ return out;
670
+ }
671
+ async function speakers(_a, ctx) {
672
+ const list = await all(ctx, "/v1/speakers", "speakers");
673
+ return {
674
+ speakers: list.map((s) => {
675
+ const o = { id: s.id, name: s.name, cloned: s.voice != null };
676
+ if (s.voice)
677
+ o.voiceReady = s.voice.state === "ready" && s.voice.enabled === true && s.consent === "granted";
678
+ put(o, "gender", s.gender);
679
+ return o;
680
+ }),
681
+ };
682
+ }
683
+ function noSpeaker(number) {
684
+ return new ToolError("not_found", `This transcription has no Speaker ${number} who has spoken; get_transcription shows the speaker numbers.`);
685
+ }
686
+ async function saveSpeaker(a, ctx) {
687
+ const id = a.id("transcriptionId");
688
+ const number = a.int("speaker", 1, 1, 1000);
689
+ const name = a.reqStr("name");
690
+ if ([...name].length > 60)
691
+ throw bad("`name` must be 1 to 60 characters");
692
+ const consent = a.bool("consent");
693
+ await transcription(ctx, id);
694
+ const snap = await snapshot(ctx, id);
695
+ const spoken = spokenSegments(snap).filter((l) => l.speaker >= 0);
696
+ const numbers = numbering(spoken, snap);
697
+ const heard = new Set(spoken.map((l) => l.speaker));
698
+ const appearance = [...numbers.entries()]
699
+ .filter(([idx, n]) => n === number && heard.has(idx))
700
+ .map(([idx]) => idx)
701
+ .sort((x, y) => x - y)[0];
702
+ if (appearance === undefined)
703
+ throw noSpeaker(number);
704
+ let s;
705
+ try {
706
+ s = (await ctx.api.request("POST", "/v1/speakers/from-appearance", {
707
+ json: { transcriptionId: id, appearance, name, consent },
708
+ signal: ctx.signal,
709
+ })).data;
710
+ }
711
+ catch (e) {
712
+ if (e instanceof ToolError && e.code === "not_found" && e.message.includes("has not said anything"))
713
+ throw noSpeaker(number);
714
+ throw e;
715
+ }
716
+ const out = { speakerId: s.id, name: s.name, consent: s.consent, cloned: s.voice != null };
717
+ if (s.voice)
718
+ put(out, "voiceState", s.voice.state);
719
+ return out;
720
+ }
721
+ async function deleteSpeaker(a, ctx) {
722
+ const id = a.id("speakerId");
723
+ try {
724
+ await ctx.api.request("DELETE", path("/v1/speakers/", id), { signal: ctx.signal });
725
+ }
726
+ catch (e) {
727
+ if (e instanceof ToolError && (e.code === "not_found" || (e.code === "forbidden" && !e.details.requiredScope))) {
728
+ throw new ToolError("not_found", NO_SPEAKER);
729
+ }
730
+ throw e;
731
+ }
732
+ return { speakerId: id, deleted: true };
733
+ }
734
+ function onAir(b) {
735
+ const c = b.currentTranscription;
736
+ return c && ["live", "paused", "pending"].includes(c.state) ? c : undefined;
737
+ }
738
+ function brief(b) {
739
+ const c = onAir(b);
740
+ const v = {
741
+ broadcastId: b.id,
742
+ name: b.name,
743
+ link: b.shareUrl,
744
+ access: b.access,
745
+ onAir: c !== undefined,
746
+ listenersNow: b.listenersNow ?? 0,
747
+ };
748
+ if (b.lifecycle && b.lifecycle !== "active")
749
+ v.archived = true;
750
+ if (c) {
751
+ v.transcriptionId = c.transcriptionId;
752
+ v.state = liveState(c.state);
753
+ put(v, "onAirSince", c.startedAt);
754
+ }
755
+ put(v, "lastRecordedAt", b.lastRecordedAt);
756
+ return v;
757
+ }
758
+ async function oneBroadcast(a, ctx) {
759
+ const b = await broadcast(ctx, a.id("broadcastId"));
760
+ const v = brief(b);
761
+ v.transcriptions = (b.transcriptions ?? []).slice(0, 20).map((t) => {
762
+ const o = { transcriptionId: t.id, name: t.name, recording: t.recording };
763
+ put(o, "lastRecordedAt", t.lastRecordedAt);
764
+ return o;
765
+ });
766
+ v.streams = (b.audioSources ?? []).map((s) => ({ name: s.name, url: s.url }));
767
+ return { broadcasts: [v] };
768
+ }
769
+ async function listBroadcasts(a, ctx) {
770
+ if (a.str("broadcastId") !== undefined)
771
+ return oneBroadcast(a, ctx);
772
+ const lifecycle = a.oneOf("lifecycle", ["active", "archived", "all"], "active");
773
+ const list = await all(ctx, "/v1/broadcasts", "broadcasts", { lifecycle });
774
+ return { broadcasts: list.map(brief) };
775
+ }
776
+ function streamUrl(a) {
777
+ const u = a.reqStr("streamUrl");
778
+ let parsed;
779
+ try {
780
+ parsed = new URL(u);
781
+ }
782
+ catch {
783
+ throw bad("`streamUrl` must be an http(s) address");
784
+ }
785
+ if (!["http:", "https:"].includes(parsed.protocol) || !parsed.hostname)
786
+ throw bad("`streamUrl` must be an http(s) address");
787
+ return u;
788
+ }
789
+ async function deleteTranscription(a, ctx) {
790
+ const id = a.id("transcriptionId");
791
+ await transcription(ctx, id);
792
+ let t;
793
+ try {
794
+ t = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/archive"), { signal: ctx.signal })).data;
795
+ }
796
+ catch (e) {
797
+ if (e instanceof ToolError && e.code === "invalid_state" && e.message.includes("stop the recording first")) {
798
+ throw new ToolError("invalid_state", "This transcription is still recording live; stop it first (stop_broadcast for a broadcast), then delete it.");
799
+ }
800
+ throw e;
801
+ }
802
+ const out = { transcriptionId: t.id, name: t.name, deleted: true };
803
+ put(out, "deletedAt", t.archivedAt);
804
+ put(out, "restorableUntil", t.purgeAfter);
805
+ return out;
806
+ }
807
+ async function restoreTranscription(a, ctx) {
808
+ const id = a.id("transcriptionId");
809
+ await transcription(ctx, id);
810
+ const t = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/restore"), { signal: ctx.signal })).data;
811
+ return { transcriptionId: t.id, name: t.name, restored: true };
812
+ }
813
+ async function renameSpeaker(a, ctx) {
814
+ const id = a.id("transcriptionId");
815
+ const number = a.int("speaker", 1, 1, 1000);
816
+ const given = a.raw.name;
817
+ if (typeof given !== "string")
818
+ throw bad('`name` must be a string ("" clears the name)');
819
+ const name = [...given.trim()].slice(0, 80).join("");
820
+ await transcription(ctx, id);
821
+ try {
822
+ await ctx.api.request("PUT", path("/v1/transcriptions/", id, "/appearances/", String(number)), {
823
+ json: { name: name || null },
824
+ signal: ctx.signal,
825
+ });
826
+ }
827
+ catch (e) {
828
+ if (e instanceof ToolError && e.code === "not_found") {
829
+ throw new ToolError("not_found", `This transcription has no Speaker ${number}; get_transcription shows the speaker numbers.`);
830
+ }
831
+ throw e;
832
+ }
833
+ return { transcriptionId: id, speaker: number, name: name || null };
834
+ }
835
+ const VOICE_CLONING_NEEDS_CONSENT = "turning voiceCloning on needs voiceCloningConsent: true — confirm you have permission from everyone speaking";
836
+ async function setClonedVoices(a, ctx) {
837
+ const id = a.id("transcriptionId");
838
+ const on = a.raw.on;
839
+ if (typeof on !== "boolean")
840
+ throw bad("`on` must be true or false");
841
+ const consent = a.bool("consent");
842
+ await transcription(ctx, id);
843
+ let t;
844
+ try {
845
+ t = (await ctx.api.request("PATCH", path("/v1/transcriptions/", id), {
846
+ json: { settings: { voiceCloning: on, voiceCloningConsent: consent } },
847
+ signal: ctx.signal,
848
+ })).data;
849
+ }
850
+ catch (e) {
851
+ if (e instanceof ToolError && e.message === VOICE_CLONING_NEEDS_CONSENT) {
852
+ throw bad("Turning cloned voices on needs consent: true, confirming everyone speaking agreed to have their voice cloned.");
853
+ }
854
+ throw e;
855
+ }
856
+ return { transcriptionId: t.id, name: t.name, clonedVoices: t.settings?.voiceCloning === true };
857
+ }
858
+ const ON_AIR = "This broadcast is already on air; stop it first (stop_broadcast) or use another broadcast.";
859
+ async function startBroadcast(a, ctx) {
860
+ const key = idempotencyKey(a);
861
+ const url = streamUrl(a);
862
+ const spoken = a.str("spokenLanguage")?.toLowerCase();
863
+ const speak = a.bool("spokenTranslations");
864
+ let b;
865
+ const given = a.optId("broadcastId");
866
+ if (given !== undefined) {
867
+ b = await broadcast(ctx, given);
868
+ }
869
+ else {
870
+ let name = a.str("name");
871
+ if (name === undefined) {
872
+ try {
873
+ name = new URL(url).hostname.replace(/^www\./, "") || "Live stream";
874
+ }
875
+ catch {
876
+ name = "Live stream";
877
+ }
878
+ }
879
+ const made = await ctx.api.request("POST", "/v1/broadcasts", {
880
+ json: { name },
881
+ idempotencyKey: key && stepKey(key, "broadcast"),
882
+ signal: ctx.signal,
883
+ });
884
+ b = made.data;
885
+ if (made.headers.get("idempotent-replayed") === "true")
886
+ b = await broadcast(ctx, b.id);
887
+ }
888
+ const settings = {};
889
+ if (spoken !== undefined)
890
+ settings.spokenLanguage = spoken;
891
+ if (speak)
892
+ settings.translationTts = true;
893
+ const record = async (source) => ctx.api.request("POST", path("/v1/broadcasts/", b.id, "/record"), {
894
+ json: Object.keys(settings).length ? { audioSource: source, settings } : { audioSource: source },
895
+ idempotencyKey: key && stepKey(key, "record"),
896
+ signal: ctx.signal,
897
+ });
898
+ const refuse = () => new ToolError("invalid_state", ON_AIR, { broadcastId: b.id, link: b.shareUrl });
899
+ let grant;
900
+ if (onAir(b)) {
901
+ const source = (b.audioSources ?? []).find((s) => s.url === url)?.id;
902
+ if (!key || !source)
903
+ throw refuse();
904
+ try {
905
+ grant = await record(source);
906
+ }
907
+ catch {
908
+ throw refuse();
909
+ }
910
+ if (grant.headers.get("idempotent-replayed") !== "true")
911
+ throw refuse();
912
+ }
913
+ else {
914
+ if (!(b.audioSources ?? []).some((s) => s.url === url)) {
915
+ b = (await ctx.api.request("POST", path("/v1/broadcasts/", b.id, "/audio-sources"), { json: { url }, signal: ctx.signal })).data;
916
+ }
917
+ const source = (b.audioSources ?? []).find((s) => s.url === url)?.id;
918
+ if (!source)
919
+ throw new ToolError("internal", "the stream was not added");
920
+ grant = await record(source);
921
+ }
922
+ const v = {
923
+ broadcastId: b.id,
924
+ name: b.name,
925
+ link: b.shareUrl,
926
+ transcriptionId: grant.data.transcription?.id,
927
+ state: liveState(grant.data.transcription?.state),
928
+ message: "Share the link: anyone who opens it picks a language and reads (or hears) the stream in it as it plays. Read the transcript with get_transcription; stop it with stop_broadcast.",
929
+ };
930
+ if (grant.headers.get("idempotent-replayed") === "true")
931
+ v.replayed = true;
932
+ return v;
933
+ }
934
+ async function stopBroadcast(a, ctx) {
935
+ const b = await broadcast(ctx, a.id("broadcastId"));
936
+ const c = onAir(b);
937
+ if (!c)
938
+ throw new ToolError("invalid_state", "This broadcast is not on air.", { broadcastId: b.id });
939
+ const tid = c.transcriptionId;
940
+ const t = await transcription(ctx, tid);
941
+ if (t.state === "live")
942
+ await ctx.api.request("POST", path("/v1/transcriptions/", tid, "/pause"), { signal: ctx.signal });
943
+ if (OPEN.has(t.state))
944
+ await ctx.api.request("POST", path("/v1/transcriptions/", tid, "/stop"), { json: {}, signal: ctx.signal });
945
+ const after = await transcription(ctx, tid);
946
+ return { ...liveStatus(after), broadcastId: b.id, link: b.shareUrl };
947
+ }
948
+ export const handlers = {
949
+ transcribe,
950
+ get_transcription: getTranscription,
951
+ list_transcriptions: listTranscriptions,
952
+ search_transcriptions: search,
953
+ get_summary: summary,
954
+ rename_speaker: renameSpeaker,
955
+ delete_transcription: deleteTranscription,
956
+ restore_transcription: restoreTranscription,
957
+ set_cloned_voices: setClonedVoices,
958
+ list_speakers: speakers,
959
+ save_speaker: saveSpeaker,
960
+ delete_speaker: deleteSpeaker,
961
+ list_broadcasts: listBroadcasts,
962
+ start_broadcast: startBroadcast,
963
+ stop_broadcast: stopBroadcast,
964
+ };