@vocalstack/mcp 1.2.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.
package/README.md CHANGED
@@ -61,24 +61,21 @@ Both offer the same tools.
61
61
  ## Tools
62
62
 
63
63
  <!-- tools -->
64
- - `transcribe_url`: Start transcribing a recorded audio or video at a public link: a media file, a podcast episode, a YouTube video, or a public post on one of the sites listed under url.
65
- - `transcribe_file`: Start transcribing an audio or video file you hold, sent whole as base64 (at most 10 MiB decoded; mp3, m4a, wav, mp4, webm and other common formats).
66
- - `get_transcription`: Read one transcription's text, with timestamps and speakers, and its status.
67
- - `wait_for_transcription`: Wait until a file or link transcription finishes, up to timeoutS seconds (default 50, at most 60), and return its status without the text.
68
- - `list_transcriptions`: List this account's transcriptions (files, links and live ones, including those recorded by broadcasts), newest first, one page at a time.
69
- - `search_transcriptions`: Find the lines where given words or a name were said, across all of this account's transcriptions or in one (transcriptionId).
70
- - `search_by_meaning`: Find the passages closest in meaning to a question or topic, across this account's transcriptions or in one (transcriptionId), in any language and even when they share none of its words.
71
- - `get_summary`: Get the title and summary of a finished transcription.
72
- - `translate_transcription`: Get a whole finished transcription translated into another language, in the same text or segments shape as get_transcription.
64
+ - `transcribe`: Start transcribing a finished recording, from a public link or a file sent inline; returns a transcriptionId at once, before any text.
65
+ - `get_transcription`: Read one transcription's status and text, with timestamps and speakers: as it was spoken or translated, at once or after waiting for it to finish.
66
+ - `list_transcriptions`: List this account's transcriptions, newest first, a page at a time: files, links and live ones, including those broadcasts recorded.
67
+ - `search_transcriptions`: Find what was said across this account's transcriptions, or in one: the lines with given words or a name (mode words), or the passages that answer a question (mode meaning).
68
+ - `get_summary`: Get the title and summary of a finished transcription, writing one the first time if it has none.
73
69
  - `rename_speaker`: Name a speaker in one transcription, so its transcript shows the name instead of "Speaker N".
74
- - `delete_transcription`: Delete a transcription: it moves to the trash with its recordings, transcript, translations and summary, and its share links stop working.
75
- - `list_voices`: List the voices that can read translations aloud in one language: stock voices and this account's own cloned voices.
70
+ - `delete_transcription`: Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.
71
+ - `restore_transcription`: Bring a deleted transcription back from the trash, with its recordings, transcript, translations, summary and working share links.
76
72
  - `set_cloned_voices`: Turn cloned voices on or off for one transcription's spoken translations.
77
- - `list_speakers`: List the speakers this account has saved: people named once so they are recognised by name in later transcriptions.
78
- - `list_broadcasts`: List this account's broadcasts, most recently updated first (up to 500, no paging).
79
- - `get_broadcast`: Get one broadcast in detail: whether it is on air, its public link, the transcriptions it recorded and the stream addresses it uses.
80
- - `start_broadcast`: Start live transcription and translation of a live stream (YouTube live, internet radio, HLS .m3u8 or Icecast).
81
- - `stop_broadcast`: Stop the live transcription a broadcast is running (started with start_broadcast), which also stops its billing.
73
+ - `list_speakers`: List the speakers this account has saved: people recognised by name in every new transcription.
74
+ - `save_speaker`: Save one speaker of a transcription to the account's saved speakers, so later transcriptions recognise and name them; their own speech in this transcription is the sample.
75
+ - `delete_speaker`: Delete a saved speaker for good: their name, fingerprint, stored sample and any cloned voice are erased at once and cannot be restored.
76
+ - `list_broadcasts`: List this account's broadcasts, or get one in detail.
77
+ - `start_broadcast`: Start live transcription and translation of a stream playing now, on a public link listeners open in their own language.
78
+ - `stop_broadcast`: Stop the live transcription a broadcast is running, which also stops its billing.
82
79
  <!-- /tools -->
83
80
 
84
81
  Errors come back as tool results with `isError` set and a body with `error` (a code such as `not_found`, `invalid_options`, `invalid_state`, `insufficient_credit` or `rate_limited`), `message`, `retryable`, `retryAfterS` and `topUpUrl` when credit is needed. Retry a start with the same `idempotencyKey` so nothing is made or billed twice.
package/dist/handlers.js CHANGED
@@ -2,12 +2,14 @@ import { createHash } from "node:crypto";
2
2
  import { ToolError, bad } from "./errors.js";
3
3
  export const MAX_FILE_BYTES = 10 * 1024 * 1024;
4
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;
5
+ export const WAIT_MAX_S = 60;
6
+ export const WAITS_PER_KEY = 4;
7
7
  const WAIT_POLL_MS = 1000;
8
8
  const UPLOAD_TIMEOUT_MS = 15 * 60_000;
9
+ const LANGUAGES_TTL_MS = 60 * 60_000;
9
10
  const NO_TRANSCRIPTION = "No transcription with that id for this account.";
10
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.";
11
13
  const OPEN = new Set(["pending", "live", "paused", "processing"]);
12
14
  const TERMINAL = new Set(["done", "failed", "stopped"]);
13
15
  function put(o, k, v) {
@@ -17,6 +19,9 @@ function put(o, k, v) {
17
19
  function path(...parts) {
18
20
  return parts.map((p, i) => (i % 2 ? encodeURIComponent(p) : p)).join("");
19
21
  }
22
+ function present(a, k) {
23
+ return a.raw[k] !== undefined && a.raw[k] !== null;
24
+ }
20
25
  function notFound(e, message) {
21
26
  if (e instanceof ToolError && (e.code === "not_found" || e.code === "forbidden")) {
22
27
  throw new ToolError("not_found", message);
@@ -39,6 +44,28 @@ async function broadcast(ctx, id) {
39
44
  notFound(e, NO_BROADCAST);
40
45
  }
41
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
+ }
42
69
  function jobStatus(job, t) {
43
70
  const pr = job.progress ?? {};
44
71
  const progress = { pct: pr.pct ?? 0, processedS: pr.processedS ?? 0, segmentsDone: pr.segmentsDone ?? 0 };
@@ -104,17 +131,9 @@ function firstOrder(lines) {
104
131
  const order = [...first.entries()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
105
132
  return new Map(order.map(([spk], i) => [spk, i + 1]));
106
133
  }
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();
134
+ function numbering(lines, snapshot) {
114
135
  const server = new Map();
115
136
  for (const a of snapshot.speakers ?? []) {
116
- if (typeof a.name === "string")
117
- names.set(a.speaker, a.name);
118
137
  if (typeof a.number === "number")
119
138
  server.set(a.speaker, a.number);
120
139
  }
@@ -129,6 +148,20 @@ function labelled(raw, snapshot, t) {
129
148
  for (const [s] of rest)
130
149
  numbers.set(s, ++top);
131
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);
132
165
  return lines.map((l) => {
133
166
  let speakerName = "";
134
167
  if (shown) {
@@ -188,11 +221,13 @@ async function snapshot(ctx, id) {
188
221
  notFound(e, NO_TRANSCRIPTION);
189
222
  }
190
223
  }
191
- function segmentLines(snap, t) {
192
- const raw = (snap.segments ?? [])
224
+ function spokenSegments(snap) {
225
+ return (snap.segments ?? [])
193
226
  .filter((s) => typeof s.text === "string" && s.text.trim())
194
227
  .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);
228
+ }
229
+ function segmentLines(snap, t) {
230
+ return labelled(spokenSegments(snap), snap, t);
196
231
  }
197
232
  function validKey(k) {
198
233
  return k.length >= 1 && k.length <= 255 && /^[\x21-\x7e]+$/.test(k);
@@ -207,6 +242,20 @@ function stepKey(key, step) {
207
242
  const k = `${key}:${step}`;
208
243
  return k.length <= 255 ? k : `${createHash("sha256").update(key).digest("hex")}:${step}`;
209
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
+ }
210
259
  function transcribeOptions(a) {
211
260
  const settings = {};
212
261
  const spoken = a.str("spokenLanguage");
@@ -224,7 +273,7 @@ function transcribeOptions(a) {
224
273
  return options;
225
274
  }
226
275
  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`);
276
+ const tooBig = () => bad(`fileBase64 is over ${MAX_FILE_BYTES >> 20} MiB decoded; give \`url\` a link to the file instead`);
228
277
  const raw = a.rawStr("fileBase64");
229
278
  if (raw === undefined)
230
279
  throw bad("`fileBase64` must be a string");
@@ -247,13 +296,14 @@ function decodeFile(a) {
247
296
  throw bad("fileBase64 is not valid base64: Invalid input length.");
248
297
  const bytes = Buffer.from(body, "base64");
249
298
  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`);
299
+ throw bad(`the file is over ${MAX_FILE_BYTES >> 20} MiB; give \`url\` a link to it instead`);
251
300
  if (bytes.length === 0)
252
301
  throw new ToolError("invalid_audio", "the file is empty");
253
302
  return bytes;
254
303
  }
255
- async function transcribe(a, ctx, file) {
304
+ async function transcribe(a, ctx) {
256
305
  const key = idempotencyKey(a);
306
+ const file = sourceOf(a);
257
307
  const options = transcribeOptions(a);
258
308
  let res;
259
309
  if (!file) {
@@ -282,27 +332,26 @@ async function transcribe(a, ctx, file) {
282
332
  if (first?.url)
283
333
  v.shareUrl = first.url;
284
334
  }
285
- v.next = "Call wait_for_transcription with this transcriptionId.";
335
+ v.next = `Call get_transcription with this transcriptionId and waitS (up to ${WAIT_MAX_S}) to wait for the text.`;
286
336
  if (res.headers.get("idempotent-replayed") === "true")
287
337
  v.replayed = true;
288
338
  return v;
289
339
  }
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;
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
+ };
306
355
  }
307
356
  function phaseText(job) {
308
357
  const pr = job.progress ?? {};
@@ -336,45 +385,138 @@ function sleep(ms, signal) {
336
385
  signal.addEventListener("abort", done, { once: true });
337
386
  });
338
387
  }
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();
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);
358
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;
359
421
  }
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 };
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;
366
448
  try {
367
- job = await ctx.api.get(path("/v1/transcriptions/", id, "/job"), undefined, ctx.signal);
449
+ r = await ctx.api.get(path("/v1/transcriptions/", id, "/translation"), { lang, sentences: missing.slice(i, i + 40).join(",") }, ctx.signal);
368
450
  }
369
451
  catch (e) {
370
- if (ctx.signal.aborted)
371
- return { ...st, timedOut: true };
452
+ if (e instanceof ToolError && e.code === "invalid_options")
453
+ throw bad(`\`lang\` ${JSON.stringify(lang)} is not a language this API translates into`);
372
454
  notFound(e, NO_TRANSCRIPTION);
373
455
  }
374
- st = jobStatus(job, t);
375
- if (TERMINAL.has(job.state))
376
- return { ...st, timedOut: false };
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 };
377
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;
378
520
  }
379
521
  async function listTranscriptions(a, ctx) {
380
522
  const lifecycle = a.oneOf("lifecycle", ["active", "archived", "all"], "active");
@@ -429,7 +571,7 @@ async function only(a, ctx) {
429
571
  await transcription(ctx, id);
430
572
  return id;
431
573
  }
432
- async function search(a, ctx) {
574
+ async function searchWords(a, ctx) {
433
575
  const q = query(a);
434
576
  const transcriptionId = await only(a, ctx);
435
577
  const lang = a.str("lang");
@@ -451,7 +593,10 @@ async function search(a, ctx) {
451
593
  });
452
594
  return { query: r.query, queryEn: r.queryEn, hits };
453
595
  }
454
- async function searchByMeaning(a, ctx) {
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`);
455
600
  const q = query(a);
456
601
  const transcriptionId = await only(a, ctx);
457
602
  const r = await ctx.api.get("/v1/search/vector", { q, transcription: transcriptionId }, ctx.signal);
@@ -468,12 +613,12 @@ async function searchByMeaning(a, ctx) {
468
613
  put(out, "searchesLeftThisHour", r.allowance?.remaining);
469
614
  return out;
470
615
  }
471
- function family(l) {
472
- return l.split(/[_-]/)[0].toLowerCase();
616
+ async function search(a, ctx) {
617
+ return a.oneOf("mode", ["words", "meaning"], "words") === "meaning" ? searchMeaning(a, ctx) : searchWords(a, ctx);
473
618
  }
474
619
  async function summary(a, ctx) {
475
620
  const id = a.id("transcriptionId");
476
- const lang = a.str("lang")?.toLowerCase();
621
+ const lang = await targetLang(a, ctx, "lang");
477
622
  const t = await transcription(ctx, id);
478
623
  const pending = (message) => ({ state: "pending", message });
479
624
  const s = await ctx.api.get(path("/v1/transcriptions/", id, "/summary"), { lang }, ctx.signal);
@@ -486,7 +631,7 @@ async function summary(a, ctx) {
486
631
  return { state: "unavailable", message: "The transcription failed, so there is nothing to summarise." };
487
632
  }
488
633
  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.");
634
+ return pending("The transcription is still running; wait for it (get_transcription with waitS), then ask again.");
490
635
  }
491
636
  if (s.state === "pending")
492
637
  return pending("The summary is being written; ask again in a few seconds.");
@@ -511,78 +656,6 @@ async function summary(a, ctx) {
511
656
  return pending("The summary is being written; ask again in a few seconds.");
512
657
  }
513
658
  }
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
659
  async function all(ctx, route, field, query = {}) {
587
660
  const out = [];
588
661
  let cursor;
@@ -607,6 +680,57 @@ async function speakers(_a, ctx) {
607
680
  }),
608
681
  };
609
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
+ }
610
734
  function onAir(b) {
611
735
  const c = b.currentTranscription;
612
736
  return c && ["live", "paused", "pending"].includes(c.state) ? c : undefined;
@@ -631,12 +755,7 @@ function brief(b) {
631
755
  put(v, "lastRecordedAt", b.lastRecordedAt);
632
756
  return v;
633
757
  }
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) {
758
+ async function oneBroadcast(a, ctx) {
640
759
  const b = await broadcast(ctx, a.id("broadcastId"));
641
760
  const v = brief(b);
642
761
  v.transcriptions = (b.transcriptions ?? []).slice(0, 20).map((t) => {
@@ -645,7 +764,14 @@ async function getBroadcast(a, ctx) {
645
764
  return o;
646
765
  });
647
766
  v.streams = (b.audioSources ?? []).map((s) => ({ name: s.name, url: s.url }));
648
- return v;
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) };
649
775
  }
650
776
  function streamUrl(a) {
651
777
  const u = a.reqStr("streamUrl");
@@ -678,6 +804,12 @@ async function deleteTranscription(a, ctx) {
678
804
  put(out, "restorableUntil", t.purgeAfter);
679
805
  return out;
680
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
+ }
681
813
  async function renameSpeaker(a, ctx) {
682
814
  const id = a.id("transcriptionId");
683
815
  const number = a.int("speaker", 1, 1, 1000);
@@ -814,22 +946,19 @@ async function stopBroadcast(a, ctx) {
814
946
  return { ...liveStatus(after), broadcastId: b.id, link: b.shareUrl };
815
947
  }
816
948
  export const handlers = {
817
- transcribe_url: (a, ctx) => transcribe(a, ctx, false),
818
- transcribe_file: (a, ctx) => transcribe(a, ctx, true),
949
+ transcribe,
819
950
  get_transcription: getTranscription,
820
- wait_for_transcription: wait,
821
951
  list_transcriptions: listTranscriptions,
822
952
  search_transcriptions: search,
823
- search_by_meaning: searchByMeaning,
824
953
  get_summary: summary,
825
- translate_transcription: translate,
826
954
  rename_speaker: renameSpeaker,
827
955
  delete_transcription: deleteTranscription,
828
- list_voices: voices,
956
+ restore_transcription: restoreTranscription,
829
957
  set_cloned_voices: setClonedVoices,
830
958
  list_speakers: speakers,
959
+ save_speaker: saveSpeaker,
960
+ delete_speaker: deleteSpeaker,
831
961
  list_broadcasts: listBroadcasts,
832
- get_broadcast: getBroadcast,
833
962
  start_broadcast: startBroadcast,
834
963
  stop_broadcast: stopBroadcast,
835
964
  };