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