@vocalstack/mcp 1.5.2 → 1.5.3

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
@@ -62,7 +62,7 @@ Both offer the same tools.
62
62
 
63
63
  <!-- tools -->
64
64
  - `create_transcription`: 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, or its title and summary: as spoken or translated, at once or after waiting for it to finish.
65
+ - `get_transcription`: Read or export one transcription: its status and text with timestamps and speakers, its title and summary, or the whole transcript as an SRT, WebVTT or Markdown file; as spoken or translated, at once or after waiting for it to finish.
66
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
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
68
  - `update_transcription`: Change a transcription: its name, its public share link, its summary, whether spoken translations use the speakers' own cloned voices, or bring it back from the trash.
@@ -71,8 +71,8 @@ Both offer the same tools.
71
71
  - `update_speaker`: Name or save a speaker: name one person in one transcription (instead of "Speaker N") and optionally save them so later transcriptions recognise them, or rename a saved speaker and switch their cloned voice on or off, everywhere they are recognised.
72
72
  - `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.
73
73
  - `list_broadcasts`: List this account's broadcasts, or get one in detail.
74
- - `start_broadcast`: Start live transcription and translation of a stream playing now, on a public link listeners open in their own language.
75
- - `update_broadcast`: Change a broadcast's settings: its name, who can listen (public, or private with a password), the language spoken, and whether translations are read aloud, in stock or the speakers' own cloned voices; or bring it back from the trash.
74
+ - `start_broadcast`: Start live transcription and translation of a stream playing now, on a public link listeners open in their own language; or set up a broadcast and its link ahead of the event.
75
+ - `update_broadcast`: Change a broadcast's settings: its name, who can listen (public, or private behind a listener code VocalStack makes), the language spoken, and whether translations are read aloud, in stock or the speakers' own cloned voices; or bring it back from the trash.
76
76
  - `stop_broadcast`: Stop the live transcription a broadcast is running, which also stops its billing.
77
77
  - `delete_broadcast`: Move a broadcast to the trash: its public link and stream addresses stop working for listeners.
78
78
  - `get_account`: Check the account's credit and usage: the balance left, the plan, whether a new file or live transcription would start now (and what would refuse it), and this period's limits.
package/dist/api.js CHANGED
@@ -104,7 +104,7 @@ export class Api {
104
104
  const retryable = typeof parsed?.data?.retryable === "boolean" ? parsed.data.retryable : undefined;
105
105
  throw new ToolError(code, message, details, res.status, retryable);
106
106
  }
107
- return { data: parsed, headers: res.headers };
107
+ return { data: (opts.raw ? text : parsed), headers: res.headers };
108
108
  }
109
109
  get(path, query, signal) {
110
110
  return this.request("GET", path, { query, signal }).then((r) => r.data);
package/dist/handlers.js CHANGED
@@ -1,4 +1,4 @@
1
- import { createHash } from "node:crypto";
1
+ import { createHash, randomUUID } 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;
@@ -469,12 +469,23 @@ async function translatedLines(ctx, id, snap, t, lang, offset, limit) {
469
469
  });
470
470
  return lines;
471
471
  }
472
+ async function exportFile(ctx, id, format, lang) {
473
+ const r = await ctx.api.request("GET", path("/v1/transcriptions/", id, "/export"), { query: { format, lang }, raw: true, signal: ctx.signal });
474
+ const disposition = r.headers.get("content-disposition") ?? "";
475
+ const star = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
476
+ const plain = /filename="([^"]*)"/i.exec(disposition);
477
+ const fileName = star ? decodeURIComponent(star[1]) : plain ? plain[1] : `transcript.${format}`;
478
+ return { fileName, contentType: (r.headers.get("content-type") ?? "text/plain").split(";")[0].trim(), content: r.data };
479
+ }
472
480
  async function getTranscription(a, ctx) {
473
481
  const id = a.id("transcriptionId");
474
482
  const waitS = a.int("waitS", 0, 0, WAIT_MAX_S);
475
- const format = a.oneOf("format", ["text", "segments", "summary", "none"], "text");
483
+ const format = a.oneOf("format", ["text", "segments", "summary", "srt", "vtt", "markdown", "none"], "text");
476
484
  const lang = await targetLang(a, ctx, "lang");
477
485
  const words = a.bool("includeWords");
486
+ const fileFormat = { srt: "srt", vtt: "vtt", markdown: "md" }[format];
487
+ if (fileFormat && words)
488
+ throw bad("`includeWords` goes with format segments");
478
489
  if (words && lang !== undefined)
479
490
  throw bad("`includeWords` is for the original language; leave it out with `lang`");
480
491
  const offset = a.int("offset", 0, 0, 4294967295);
@@ -519,15 +530,23 @@ async function getTranscription(a, ctx) {
519
530
  return out;
520
531
  throw new ToolError("invalid_state", notYet);
521
532
  }
522
- const snap = await snapshot(ctx, id);
523
533
  const spoken = t.spokenLanguage ?? undefined;
524
534
  const same = spoken !== undefined && family(spoken) === family(lang);
535
+ if (fileFormat)
536
+ return { ...out, file: await exportFile(ctx, id, fileFormat, same ? undefined : lang), lang, translated: !same };
537
+ const snap = await snapshot(ctx, id);
525
538
  const lines = same ? segmentLines(snap, t) : await translatedLines(ctx, id, snap, t, lang, offset, limit);
526
539
  return { ...out, ...page(lines, format, false, offset, limit), lang, translated: !same };
527
540
  }
541
+ const partial = t.job ? !TERMINAL.has(t.job.state) : t.state !== "finalized";
542
+ if (fileFormat) {
543
+ out.file = await exportFile(ctx, id, fileFormat, undefined);
544
+ if (partial)
545
+ out.partial = true;
546
+ return out;
547
+ }
528
548
  const snap = await snapshot(ctx, id);
529
549
  Object.assign(out, page(segmentLines(snap, t), format, words, offset, limit));
530
- const partial = t.job ? !TERMINAL.has(t.job.state) : t.state !== "finalized";
531
550
  if (partial)
532
551
  out.partial = true;
533
552
  return out;
@@ -1072,7 +1091,9 @@ async function updateBroadcast(a, ctx) {
1072
1091
  const id = a.id("broadcastId");
1073
1092
  const name = a.str("name");
1074
1093
  const access = a.raw.access === undefined || a.raw.access === null ? undefined : a.oneOf("access", ["public", "private"], "public");
1075
- const password = a.str("password");
1094
+ const newCode = optBool(a, "newListenerCode");
1095
+ if (newCode === false)
1096
+ throw bad("`newListenerCode` takes only true (make a new code); leave it out to keep the current one");
1076
1097
  const spokenRaw = a.str("spokenLanguage");
1077
1098
  const speak = optBool(a, "spokenTranslations");
1078
1099
  const cloned = optBool(a, "clonedVoices");
@@ -1080,9 +1101,9 @@ async function updateBroadcast(a, ctx) {
1080
1101
  const restore = optBool(a, "restore");
1081
1102
  if (restore === false)
1082
1103
  throw bad("`restore` takes only true (bring it back from the trash); delete_broadcast moves it there");
1083
- const changes = [name, access, password, spokenRaw, speak, cloned].some((v) => v !== undefined);
1104
+ const changes = [name, access, newCode, spokenRaw, speak, cloned].some((v) => v !== undefined);
1084
1105
  if (!changes && restore === undefined) {
1085
- throw bad("give at least one of `name`, `access`, `password`, `spokenLanguage`, `spokenTranslations`, `clonedVoices` or `restore` to change");
1106
+ throw bad("give at least one of `name`, `access`, `newListenerCode`, `spokenLanguage`, `spokenTranslations`, `clonedVoices` or `restore` to change");
1086
1107
  }
1087
1108
  if (cloned === true && !consent)
1088
1109
  throw bad(NEEDS_CONSENT);
@@ -1095,8 +1116,16 @@ async function updateBroadcast(a, ctx) {
1095
1116
  body.name = name;
1096
1117
  if (access !== undefined)
1097
1118
  body.access = access;
1098
- if (password !== undefined && access !== "public")
1099
- body.password = password;
1119
+ const privateAfter = access === undefined ? b.access === "private" : access === "private";
1120
+ if (newCode === true && !privateAfter)
1121
+ throw bad('`newListenerCode` is for a private broadcast; make it private with access: "private" (that makes a code too)');
1122
+ const fresh = () => {
1123
+ const u = randomUUID().replace(/-/g, "");
1124
+ return `${u.slice(0, 4)}-${u.slice(4, 8)}`;
1125
+ };
1126
+ let made = newCode === true ? fresh() : undefined;
1127
+ if (made !== undefined)
1128
+ body.password = made;
1100
1129
  const settings = {};
1101
1130
  if (spokenRaw !== undefined) {
1102
1131
  const l = spokenRaw.trim().toLowerCase();
@@ -1112,19 +1141,26 @@ async function updateBroadcast(a, ctx) {
1112
1141
  body.settings = settings;
1113
1142
  if (changes)
1114
1143
  try {
1115
- b = (await ctx.api.request("PATCH", path("/v1/broadcasts/", id), { json: body, signal: ctx.signal })).data;
1144
+ try {
1145
+ b = (await ctx.api.request("PATCH", path("/v1/broadcasts/", id), { json: body, signal: ctx.signal })).data;
1146
+ }
1147
+ catch (e) {
1148
+ if (!(e instanceof ToolError && /needs? a password/.test(e.message)))
1149
+ throw e;
1150
+ made = fresh();
1151
+ body.password = made;
1152
+ b = (await ctx.api.request("PATCH", path("/v1/broadcasts/", id), { json: body, signal: ctx.signal })).data;
1153
+ }
1116
1154
  }
1117
1155
  catch (e) {
1118
1156
  if (e instanceof ToolError && e.code === "invalid_state") {
1119
1157
  throw new ToolError("invalid_state", "This broadcast is in the trash; pass restore: true to bring it back.");
1120
1158
  }
1121
- if (e instanceof ToolError && e.message === "private broadcasts need a password") {
1122
- throw bad("A private broadcast needs a `password` (at least 4 characters) the first time.");
1123
- }
1124
1159
  consentError(e);
1125
1160
  }
1126
1161
  return {
1127
1162
  ...brief(b),
1163
+ ...(made !== undefined ? { listenerCode: made } : {}),
1128
1164
  spokenLanguage: b.settings?.spokenLanguage ?? "auto",
1129
1165
  spokenTranslations: b.settings?.translationTts === true,
1130
1166
  clonedVoices: b.settings?.voiceCloning === true,
@@ -1134,6 +1170,24 @@ async function updateBroadcast(a, ctx) {
1134
1170
  const ON_AIR = "This broadcast is already on air; stop it first (stop_broadcast) or use another broadcast.";
1135
1171
  async function startBroadcast(a, ctx) {
1136
1172
  const key = idempotencyKey(a);
1173
+ if (a.raw.streamUrl === undefined || a.raw.streamUrl === null) {
1174
+ if (a.raw.broadcastId !== undefined && a.raw.broadcastId !== null) {
1175
+ throw bad("`streamUrl` is required with `broadcastId`: it is what goes on air (update_broadcast changes the broadcast's settings)");
1176
+ }
1177
+ if (present(a, "spokenLanguage") || present(a, "spokenTranslations")) {
1178
+ throw bad("`spokenLanguage` and `spokenTranslations` go with `streamUrl`; to set them ahead, use update_broadcast on the new broadcast");
1179
+ }
1180
+ const name = a.str("name")?.trim() || "Live stream";
1181
+ const made = await ctx.api.request("POST", "/v1/broadcasts", { json: { name }, idempotencyKey: key && stepKey(key, "broadcast"), signal: ctx.signal });
1182
+ const b = made.data;
1183
+ return {
1184
+ broadcastId: b.id,
1185
+ name: b.name,
1186
+ link: b.shareUrl,
1187
+ onAir: false,
1188
+ message: "Set up, off air and not billed. Share the link now; set access (private returns a listener code), the language or spoken translations with update_broadcast; go on air with start_broadcast with this broadcastId and the streamUrl.",
1189
+ };
1190
+ }
1137
1191
  const url = streamUrl(a);
1138
1192
  const spoken = a.str("spokenLanguage")?.toLowerCase();
1139
1193
  const speak = a.bool("spokenTranslations");
package/dist/tools.json CHANGED
@@ -111,17 +111,20 @@
111
111
  {
112
112
  "name": "get_transcription",
113
113
  "title": "Read a transcription",
114
- "description": "Read one transcription's status and text, with timestamps and speakers, or its title and summary: as spoken or translated, at once or after waiting for it to finish.\nUse: after create_transcription (waitS saves polling), or any time during a live transcription for the text so far. An overview: format summary. Finding a passage in many transcriptions: search_transcriptions.\nBehaviour: free. A wait ends as soon as the work does, and sends progress notifications when the client gives a progress token. lang needs a finished transcription; the first call in a new language can take up to a minute on a long one, later pages are quick. Page with offset = nextOffset.\nReturns: status (state, progress, error when failed, shareUrl when it has a public link: made with shareLink in create_transcription or update_transcription), timedOut when waitS was set, then segmentCount, partial while text is still coming, text or segments, nextOffset when more remain, and lang and translated with lang. format summary returns summary instead: state ready with title and summary (and lang when translated), pending while it is written or the transcription runs, none when none was asked for (update_transcription with summary true writes one), not_requested under a minute, unavailable when it failed. A wait that runs out with lang set returns the status only.\nErrors: not_found; invalid_state for lang before it is finished; invalid_options for an unsupported lang or includeWords with lang; rate_limited (with retryAfterS) when waitS is set and 4 waits are already open for this key (8 for the account), or past 600 calls a minute per API key.",
114
+ "description": "Read or export one transcription: its status and text with timestamps and speakers, its title and summary, or the whole transcript as an SRT, WebVTT or Markdown file; as spoken or translated, at once or after waiting for it to finish.\nUse: after create_transcription (waitS saves polling), or any time during a live transcription for the text so far. An overview: format summary. Subtitles or a document to save: format srt, vtt or markdown. Finding a passage in many transcriptions: search_transcriptions.\nBehaviour: free. A wait ends as soon as the work does, and sends progress notifications when the client gives a progress token. lang needs a finished transcription; the first call in a new language can take up to a minute on a long one, later pages are quick. Page with offset = nextOffset.\nReturns: status (state, progress, error when failed, shareUrl when it has a public link: made with shareLink in create_transcription or update_transcription), timedOut when waitS was set, then segmentCount, partial while text is still coming, text or segments, nextOffset when more remain, and lang and translated with lang. format summary returns summary instead: state ready with title and summary (and lang when translated), pending while it is written or the transcription runs, none when none was asked for (update_transcription with summary true writes one), not_requested under a minute, unavailable when it failed. format srt, vtt or markdown returns file (fileName, contentType, content: the whole file as text, partial while it runs) instead of text. A wait that runs out with lang set returns the status only.\nErrors: not_found; invalid_state for lang before it is finished; invalid_options for an unsupported lang or includeWords with lang; rate_limited (with retryAfterS) when waitS is set and 4 waits are already open for this key (8 for the account), or past 600 calls a minute per API key.",
115
115
  "inputSchema": {
116
116
  "additionalProperties": false,
117
117
  "properties": {
118
118
  "format": {
119
119
  "default": "text",
120
- "description": "text: one string, a line per segment as \"[mm:ss] Speaker 1: words\", for reading and quoting; segments: timed lines (start, end, text, speakerNumber, speakerName), for subtitles and exact times; summary: the title and summary only, for an overview; none: status only (with waitS: wait without reading).",
120
+ "description": "text: one string, a line per segment as \"[mm:ss] Speaker 1: words\", for reading and quoting; segments: timed lines (start, end, text, speakerNumber, speakerName), for exact times; summary: the title and summary only, for an overview; srt, vtt or markdown: the whole transcript as a ready file (SubRip or WebVTT subtitles, or a Markdown document), returned as file with fileName, contentType and content, not paged; none: status only (with waitS: wait without reading).",
121
121
  "enum": [
122
122
  "text",
123
123
  "segments",
124
124
  "summary",
125
+ "srt",
126
+ "vtt",
127
+ "markdown",
125
128
  "none"
126
129
  ]
127
130
  },
@@ -298,7 +301,7 @@
298
301
  {
299
302
  "name": "update_transcription",
300
303
  "title": "Update a transcription",
301
- "description": "Change a transcription: its name, its public share link, its summary, whether spoken translations use the speakers' own cloned voices, or bring it back from the trash.\nUse: renaming, sharing or unsharing, asking for a summary later, switching cloned voices, or restoring one deleted by mistake. Only the fields given change; give at least one. Speaker names: update_speaker. Removing it: delete_transcription.\nArguments: transcriptionId (required). name 1 to 200 characters. shareLink true makes a public read-only link (or keeps the one it has), false turns every public link off. summary true writes a title and summary if it has none (a finished transcription of at least a minute). clonedVoices true needs consent true, recording that everyone speaking agreed to be cloned; false needs no consent. restore true brings a deleted one back first, then applies the rest.\nBehaviour: free; calling again with the same fields changes nothing. A link turned off cannot be turned back on: shareLink true afterwards makes a new address. With cloned voices on, each speaker's translated words are read in that speaker's own voice, never anyone else's; speakers who refused, or without a usable clone, keep a stock voice; lines read after the change use it.\nReturns: transcriptionId, name, shareUrl (null with no public link), summary (state ready, pending, not_requested or unavailable) when asked for, clonedVoices, restored with restore.\nErrors: invalid_options for no field to change, a bad name, summary or restore false, or clonedVoices true without consent; invalid_state for a deleted transcription without restore true, or summary before it is finished; not_found once erased after the restore window; not_found; forbidden for a read-only key.",
304
+ "description": "Change a transcription: its name, its public share link, its summary, whether spoken translations use the speakers' own cloned voices, or bring it back from the trash.\nUse: renaming, sharing or unsharing, asking for a summary later, switching cloned voices, or restoring one deleted by mistake. Only the fields given change; give at least one. Speaker names: update_speaker. Removing it: delete_transcription.\nArguments: transcriptionId (required). name 1 to 200 characters. shareLink true makes a public read-only link (or keeps the one it has), false turns every public link off. summary true writes a title and summary if it has none (a finished transcription of at least a minute). clonedVoices true needs consent true, recording that everyone speaking agreed to be cloned; false needs no consent. restore true brings a deleted transcription back first, then applies the rest (a deleted broadcast: update_broadcast with restore).\nBehaviour: free; calling again with the same fields changes nothing. A link turned off cannot be turned back on: shareLink true afterwards makes a new address. With cloned voices on, each speaker's translated words are read in that speaker's own voice, never anyone else's; speakers who refused, or without a usable clone, keep a stock voice; lines read after the change use it.\nReturns: transcriptionId, name, shareUrl (null with no public link), summary (state ready, pending, not_requested or unavailable) when asked for, clonedVoices, restored with restore.\nErrors: invalid_options for no field to change, a bad name, summary or restore false, or clonedVoices true without consent; invalid_state for a deleted transcription without restore true, or summary before it is finished; not_found once erased after the restore window; not_found; forbidden for a read-only key.",
302
305
  "inputSchema": {
303
306
  "additionalProperties": false,
304
307
  "properties": {
@@ -360,7 +363,7 @@
360
363
  {
361
364
  "name": "delete_transcription",
362
365
  "title": "Delete a transcription",
363
- "description": "Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.\nUse: to remove one. For 30 days update_transcription with restore true brings it back unchanged (list_transcriptions with lifecycle archived lists the trash); after that it is erased for good. Saved speakers stay (delete_speaker). A broadcast itself: delete_broadcast.\nArguments: transcriptionId, a 36-character UUID (8-4-4-4-12 hex digits, as 0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a) from create_transcription, list_transcriptions or search_transcriptions; a broadcastId, speakerId or the code in a share link is not_found. One already in the trash is left as it is, so a retry is safe.\nBehaviour: free, and a soft delete: nothing is erased for 30 days. At once its share links answer not found, voices reading its translations stop, and it drops out of list_transcriptions and search_transcriptions. Restoring brings back the same share links. A file or link still being transcribed is stopped first and keeps its text so far, billed only for what was transcribed; restoring does not resume it. A live one must be stopped first (stop_broadcast).\nReturns: transcriptionId, name, deleted, deletedAt, restorableUntil.\nErrors: invalid_state while recording live or when locked; not_found; forbidden for a read-only key.",
366
+ "description": "Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.\nUse: to remove one; undo with update_transcription restore true (list_transcriptions with lifecycle archived lists the trash). Saved speakers stay (delete_speaker). A broadcast itself: delete_broadcast.\nArguments: transcriptionId only: the transcriptionId field returned by create_transcription, list_transcriptions, search_transcriptions or start_broadcast, a 36-character UUID such as 0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a, upper or lower case. Not a name (look it up with search_transcriptions), not a broadcastId, speakerId or the code in a share link: those are not_found. Example: {transcriptionId: \"0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a\"}.\nBehaviour: free; a soft delete kept 30 days, then erased for good. At once its share links answer not found, voices reading its translations stop, and it leaves list_transcriptions and search_transcriptions; restoring brings back the same links. A file still being transcribed is stopped and keeps its text so far, billed only for that; restoring does not resume it. A live one must be stopped first (stop_broadcast). One already in the trash is left as it is, so a retry is safe.\nReturns: transcriptionId, name, deleted, deletedAt, restorableUntil.\nErrors: invalid_state while recording live or when locked; not_found; forbidden for a read-only key.",
364
367
  "inputSchema": {
365
368
  "additionalProperties": false,
366
369
  "properties": {
@@ -471,7 +474,7 @@
471
474
  {
472
475
  "name": "delete_speaker",
473
476
  "title": "Delete a saved speaker",
474
- "description": "Delete a saved speaker for good: their name, fingerprint, stored sample and any cloned voice are erased at once and cannot be restored.\nUse: the person should no longer be recognised, or asked for their voice to be removed. A name inside one transcription: update_speaker.\nArguments: speakerId is a saved speaker's id, the id field of list_speakers or the speakerId update_speaker with save returned; not a speaker number (\"Speaker 2\") and not a transcriptionId. To unname someone in one transcription instead: update_speaker with an empty name.\nBehaviour: free. Transcripts keep every line they spoke; lines labelled with their saved name go back to \"Speaker N\".\nReturns: speakerId, deleted true.\nErrors: not_found for an unknown or already deleted id; forbidden for a read-only key.",
477
+ "description": "Delete a saved speaker for good: their name, fingerprint, stored sample and any cloned voice are erased at once and cannot be restored.\nUse: the person should no longer be recognised, or asked for their voice to be removed. A name inside one transcription: update_speaker.\nArguments: speakerId is a saved speaker's id, the id field of list_speakers or the speakerId update_speaker with save returned; not a speaker number (\"Speaker 2\") and not a transcriptionId. To unname someone in one transcription instead: update_speaker with an empty name.\nBehaviour: free; the erasure is complete before the call returns, with no trash and no undo. Transcripts keep every line they spoke, with their speaker numbers; lines labelled with their saved name go back to \"Speaker N\" (update_speaker names them again there). From then on new and running transcriptions no longer recognise them, and translations of their words read aloud use a stock voice instead of their clone. The id is never reused: saving the same person again (update_speaker with save) gives a new speakerId and needs their consent again to clone. A repeat call answers not_found and changes nothing. Gives rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: speakerId, deleted true.\nErrors: not_found for an unknown or already deleted id, or one of another account; forbidden for a read-only key.",
475
478
  "inputSchema": {
476
479
  "additionalProperties": false,
477
480
  "properties": {
@@ -535,7 +538,7 @@
535
538
  {
536
539
  "name": "start_broadcast",
537
540
  "title": "Start a broadcast",
538
- "description": "Start live transcription and translation of a stream playing now, on a public link listeners open in their own language.\nUse: a stream playing now. A recording that has ended: create_transcription. Reading it while it runs: get_transcription.\nArguments: streamUrl must be live when called; the same streamUrl on the same broadcast reuses its stream. broadcastId (from list_broadcasts) reruns an existing broadcast on its old link, and then name is ignored; without it a new broadcast is made, named name or the stream's host. spokenLanguage is a code like en (omit to detect). spokenTranslations true adds audio of each translation.\nList price: $0.60 an hour while it runs, billed per second; Pay as you go bills at least 5 minutes per transcription. Listeners and translations are free.\nTranscriptions running at once per account: 5 on Pay as you go, 50 on Premium; past that a start is refused with quota_exceeded.\nBehaviour: not idempotent (idempotentHint false): every call starts a new billed run, and without broadcastId a new broadcast with a new link. The one exception is a retry: repeating the same arguments with the same idempotencyKey within 24 h returns the first run (replayed true) instead of starting another. A run lasts until stop_broadcast or the stream ends, and billing stops at that moment.\nReturns: broadcastId, name, link (anyone who opens it reads, or with spokenTranslations also hears, the stream in their language), transcriptionId, state.\nErrors: invalid_state (with link) when already on air, invalid_options for a non-http(s) address, insufficient_credit (with topUpUrl), quota_exceeded, not_found for an unknown broadcastId, forbidden for a key without the write and recordings:publish scopes.",
541
+ "description": "Start live transcription and translation of a stream playing now, on a public link listeners open in their own language; or set up a broadcast and its link ahead of the event.\nUse: a stream playing now, with listeners following live, or a broadcast to set up and share before the event. A recording that has ended, even a past live stream's file: create_transcription. Reading it while it runs: get_transcription.\nArguments: streamUrl must be live when called; the same streamUrl on the same broadcast reuses its stream. Without streamUrl (and without broadcastId) it only sets up a new broadcast, off air and free: its link can be shared and configured with update_broadcast before the event. broadcastId (from list_broadcasts) reruns an existing broadcast on its old link, and then name is ignored; without it a new broadcast is made, named name or the stream's host. spokenLanguage is a code like en (omit to detect). spokenTranslations true adds audio of each translation.\nList price: $0.60 an hour while it runs, billed per second; Pay as you go bills at least 5 minutes per transcription. Listeners and translations are free.\nTranscriptions running at once per account: 5 on Pay as you go, 50 on Premium; past that a start is refused with quota_exceeded.\nBehaviour: every call with streamUrl starts a new billed run (set up only: free, nothing runs), and without broadcastId a new broadcast with a new link; a retry with the same idempotencyKey within 24 h returns the first run (replayed true) instead. VocalStack's servers pull the stream as a visitor who is not signed in; nothing is posted to or changed at the source. Listeners on the link see each line within seconds of it being said, translated into the language they pick, with no account; the text is kept as a transcription. A run lasts until stop_broadcast or the stream ends, and billing stops at that moment.\nReturns: broadcastId, name, link (anyone who opens it reads, or with spokenTranslations also hears, the stream in their language), transcriptionId, state; set up only: broadcastId, name, link, onAir false.\nErrors: invalid_state (with link) when already on air, invalid_options for a non-http(s) address or broadcastId without streamUrl, insufficient_credit (with topUpUrl), quota_exceeded, not_found for an unknown broadcastId, forbidden for a key without the write and recordings:publish scopes.",
539
542
  "inputSchema": {
540
543
  "additionalProperties": false,
541
544
  "properties": {
@@ -576,7 +579,7 @@
576
579
  "type": "boolean"
577
580
  },
578
581
  "streamUrl": {
579
- "description": "http(s) address of a stream playing now: a YouTube live, an internet radio station, an HLS (.m3u8) or Icecast stream. A recording that has ended goes to create_transcription instead.",
582
+ "description": "http(s) address of a stream playing now: a YouTube live, an internet radio station, an HLS (.m3u8) or Icecast stream. Omit it (and broadcastId) to only set up a new broadcast and its link ahead of the event, off air and unbilled. A recording that has ended goes to create_transcription instead.",
580
583
  "examples": [
581
584
  "https://www.youtube.com/watch?v=jfKfPfyJRdk",
582
585
  "https://stream.example.org/radio.m3u8"
@@ -586,9 +589,6 @@
586
589
  "type": "string"
587
590
  }
588
591
  },
589
- "required": [
590
- "streamUrl"
591
- ],
592
592
  "type": "object"
593
593
  },
594
594
  "annotations": {
@@ -602,12 +602,12 @@
602
602
  {
603
603
  "name": "update_broadcast",
604
604
  "title": "Update a broadcast",
605
- "description": "Change a broadcast's settings: its name, who can listen (public, or private with a password), the language spoken, and whether translations are read aloud, in stock or the speakers' own cloned voices; or bring it back from the trash.\nUse: before or between runs; settings apply from the next start_broadcast, the name and access at once. Only the fields given change; give at least one. Starting it: start_broadcast; ending it: stop_broadcast; removing it: delete_broadcast.\nArguments: broadcastId (required); the rest are independent and optional, except that password counts only with access private (required the first time it goes private) and clonedVoices only with spokenTranslations on, needing consent true. restore true brings a deleted broadcast back first, then applies the rest. Examples: {broadcastId, access: \"private\", password: \"choir2026\"}; {broadcastId, spokenTranslations: true, clonedVoices: true, consent: true}; {broadcastId, restore: true}.\nBehaviour: free; the link and the broadcastId stay the same. Changing access or the password signs out every current listener at once, even on air: their page asks for the link again (and the new password when private), and they miss the lines spoken until they are back; the transcript itself is kept. Language and voice settings never touch a run in progress. Two calls at once: the later one wins, field by field. Works with a key or token of this account with the write scope; a read-only key is refused before anything changes. restore works for 30 days after delete_broadcast; after that the broadcast is not_found. Calling again with the same fields changes nothing else, and rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: the broadcast (broadcastId, name, link, access, onAir, listenersNow) with spokenLanguage, spokenTranslations and clonedVoices, and restored with restore.\nErrors: invalid_options for nothing to change, a bad name, a short password, private without a password, an unknown language, restore false, or clonedVoices true without consent; invalid_state for a broadcast in the trash without restore true; not_found for an unknown broadcastId; forbidden for a read-only key.",
605
+ "description": "Change a broadcast's settings: its name, who can listen (public, or private behind a listener code VocalStack makes), the language spoken, and whether translations are read aloud, in stock or the speakers' own cloned voices; or bring it back from the trash.\nUse: before or between runs; settings apply from the next start_broadcast, the name and access at once. Only the fields given change; give at least one. Starting it: start_broadcast; ending it: stop_broadcast; removing it: delete_broadcast.\nArguments: broadcastId (required); the rest are independent and optional, except that newListenerCode goes only with a private broadcast and clonedVoices only with spokenTranslations on, needing consent true. No code is ever passed in: VocalStack makes it, so it never sits in the model's arguments. restore true brings a deleted broadcast back first, then applies the rest. Examples: {broadcastId, access: \"private\"} (returns listenerCode); {broadcastId, newListenerCode: true}; {broadcastId, spokenTranslations: true, clonedVoices: true, consent: true}; {broadcastId, restore: true}.\nBehaviour: the link and broadcastId never change; no call here makes a new address (for one: delete_broadcast, then start_broadcast without broadcastId). Changing access or the listener code signs out every current listener at once, even on air: their page asks for the link again (and the code when private), and they miss the lines spoken until they are back; the transcript is kept. Making it public again lets anyone with the link in, with no sign-in. The name shows to listeners at once; language and voice settings never touch a run in progress. Two calls at once: the later one wins, field by field. A read-only key is refused before anything changes. restore works for 30 days after delete_broadcast; after that it is not_found. Gives rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: the broadcast (broadcastId, name, link, access, onAir, listenersNow) with spokenLanguage, spokenTranslations and clonedVoices, and restored with restore; listenerCode only on the call that made it (going private the first time, or newListenerCode), never again, so pass it on to the listeners then.\nErrors: invalid_options for nothing to change, a bad name, newListenerCode on a public broadcast, an unknown language, restore false, or clonedVoices true without consent; invalid_state for a broadcast in the trash without restore true; not_found for an unknown broadcastId; forbidden for a read-only key.",
606
606
  "inputSchema": {
607
607
  "additionalProperties": false,
608
608
  "properties": {
609
609
  "access": {
610
- "description": "public: anyone with the link can follow it; private: listeners must enter password. Changing it signs out every current listener.",
610
+ "description": "public: anyone with the link can follow it; private: listeners must enter the broadcast's listener code, which VocalStack makes the first time it goes private and returns once as listenerCode. Changing it signs out every current listener.",
611
611
  "enum": [
612
612
  "public",
613
613
  "private"
@@ -639,14 +639,9 @@
639
639
  "minLength": 1,
640
640
  "type": "string"
641
641
  },
642
- "password": {
643
- "description": "The listeners' password, at least 4 characters: required to make a broadcast private the first time, and setting a new one signs out every current listener. Ignored with access public.",
644
- "examples": [
645
- "choir2026"
646
- ],
647
- "maxLength": 200,
648
- "minLength": 4,
649
- "type": "string"
642
+ "newListenerCode": {
643
+ "description": "true: VocalStack makes a new listener code for a private broadcast and returns it once as listenerCode, signing out every current listener (share the new one with them). The old code stops working at once. Not accepted with access public.",
644
+ "type": "boolean"
650
645
  },
651
646
  "restore": {
652
647
  "description": "true: bring it back from the trash (after delete_broadcast, within the restore window) with its link, settings and recorded transcriptions; other fields given apply after. false is not accepted.",
@@ -742,7 +737,7 @@
742
737
  {
743
738
  "name": "get_account",
744
739
  "title": "Check credit and usage",
745
- "description": "Check the account's credit and usage: the balance left, the plan, whether a new file or live transcription would start now (and what would refuse it), and this period's limits.\nUse: before a long or live transcription, after an insufficient_credit or quota_exceeded error, or to tell the user what they have left. Prices per minute are in create_transcription and start_broadcast; adding credit happens at topUpUrl, in a browser.\nArguments: none.\nBehaviour: free and read-only; reflects charges as they land, including a live run still being billed. Gives rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: billingEnabled; plan (id, name, kind) or null; balance in US dollars (negative while a plan lets a running transcription continue below zero); canStart and startBlock (no_credit or hourly_limit, null when it starts) for a file; canStartLive and startBlockLive (also concurrency) for a live one; running, concurrentLimit, createdLastHour and createLimit (null means unlimited); period (start, end); monthlyCredit when a plan grants one; usageCap (amount, period, used, resetsAt) when this API key has a spending cap; topUpUrl.\nErrors: rate_limited (with retryAfterS); forbidden for a token without the read scope.",
740
+ "description": "Check the account's credit and usage: the balance left, the plan, whether a new file or live transcription would start now (and what would refuse it), and this period's limits.\nUse: before a long or live transcription, after an insufficient_credit or quota_exceeded error, or to tell the user what they have left. Prices per minute are in create_transcription and start_broadcast; adding credit happens at topUpUrl, in a browser.\nArguments: none.\nBehaviour: free and read-only; nothing is cached, each call reads the account as it is at that moment, including a live run still being billed. Calling it changes nothing and spends nothing. Gives rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: billingEnabled; plan (id, name, kind) or null; balance in US dollars (negative while a plan lets a running transcription continue below zero); canStart and startBlock (no_credit or hourly_limit, null when it starts) for a file; canStartLive and startBlockLive (also concurrency) for a live one; running, concurrentLimit, createdLastHour and createLimit (null means unlimited); period (start, end); monthlyCredit when a plan grants one; usageCap (amount, period, used, resetsAt) when this API key has a spending cap; topUpUrl.\nErrors: rate_limited (with retryAfterS); forbidden for a token without the read scope.",
746
741
  "inputSchema": {
747
742
  "additionalProperties": false,
748
743
  "properties": {},
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vocalstack/mcp",
3
- "version": "1.5.2",
3
+ "version": "1.5.3",
4
4
  "description": "VocalStack's MCP server: transcribe, translate, search and summarize audio and video, and run live broadcasts, from any MCP client, on VocalStack's public API.",
5
5
  "license": "MIT",
6
6
  "type": "module",