@vocalstack/mcp 1.4.0 → 1.5.2

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,20 +62,20 @@ 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: as it was spoken or translated, at once or after waiting for it to finish.
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.
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
- - `get_summary`: Get the title and summary of a finished transcription, writing one the first time if it has none.
69
- - `rename_speaker`: Name or rename a speaker: one person in one transcription, so its transcript shows the name instead of "Speaker N", or a saved speaker, everywhere they are recognised.
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.
70
69
  - `delete_transcription`: Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.
71
- - `set_cloned_voices`: Turn cloned voices on or off for spoken translations: for one transcription, or for one saved speaker everywhere they are recognised.
72
70
  - `list_speakers`: List the speakers this account has saved: people recognised by name in every new transcription.
73
- - `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.
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.
74
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.
75
73
  - `list_broadcasts`: List this account's broadcasts, or get one in detail.
76
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.
77
76
  - `stop_broadcast`: Stop the live transcription a broadcast is running, which also stops its billing.
78
77
  - `delete_broadcast`: Move a broadcast to the trash: its public link and stream addresses stop working for listeners.
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.
79
79
  <!-- /tools -->
80
80
 
81
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
@@ -472,7 +472,7 @@ async function translatedLines(ctx, id, snap, t, lang, offset, limit) {
472
472
  async function getTranscription(a, ctx) {
473
473
  const id = a.id("transcriptionId");
474
474
  const waitS = a.int("waitS", 0, 0, WAIT_MAX_S);
475
- const format = a.oneOf("format", ["text", "segments", "none"], "text");
475
+ const format = a.oneOf("format", ["text", "segments", "summary", "none"], "text");
476
476
  const lang = await targetLang(a, ctx, "lang");
477
477
  const words = a.bool("includeWords");
478
478
  if (words && lang !== undefined)
@@ -501,6 +501,12 @@ async function getTranscription(a, ctx) {
501
501
  out.timedOut = timedOut;
502
502
  if (format === "none")
503
503
  return out;
504
+ if (format === "summary") {
505
+ if (words)
506
+ throw bad("`includeWords` goes with format segments");
507
+ out.summary = await summaryOf(ctx, id, t, lang);
508
+ return out;
509
+ }
504
510
  if (lang !== undefined) {
505
511
  let notYet;
506
512
  if (t.job && t.job.state !== "done")
@@ -624,11 +630,7 @@ async function searchMeaning(a, ctx) {
624
630
  async function search(a, ctx) {
625
631
  return a.oneOf("mode", ["words", "meaning"], "words") === "meaning" ? searchMeaning(a, ctx) : searchWords(a, ctx);
626
632
  }
627
- async function summary(a, ctx) {
628
- const id = a.id("transcriptionId");
629
- const lang = await targetLang(a, ctx, "lang");
630
- const t = await transcription(ctx, id);
631
- const pending = (message) => ({ state: "pending", message });
633
+ async function summaryOf(ctx, id, t, lang) {
632
634
  const s = await ctx.api.get(path("/v1/transcriptions/", id, "/summary"), { lang }, ctx.signal);
633
635
  if (s.state === "ready") {
634
636
  const v = { state: "ready", title: s.title ?? t.name, summary: s.summary };
@@ -639,20 +641,28 @@ async function summary(a, ctx) {
639
641
  return { state: "unavailable", message: "The transcription failed, so there is nothing to summarise." };
640
642
  }
641
643
  if ((t.job && !TERMINAL.has(t.job.state)) || (!t.job && OPEN.has(t.state))) {
642
- return pending("The transcription is still running; wait for it (get_transcription with waitS), then ask again.");
644
+ return { state: "pending", message: "The transcription is still running; wait for it (get_transcription with waitS), then ask again." };
643
645
  }
644
646
  if (s.state === "pending")
645
- return pending("The summary is being written; ask again in a few seconds.");
646
- let made;
647
- try {
648
- made = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/summarize"), { signal: ctx.signal })).data;
649
- }
650
- catch (e) {
651
- if (e instanceof ToolError && e.code === "forbidden") {
652
- 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"] });
653
- }
654
- throw e;
647
+ return { state: "pending", message: "The summary is being written; ask again in a few seconds." };
648
+ if (s.state === "unavailable")
649
+ return { state: "unavailable", message: "Summaries are not available on this server." };
650
+ const length = t.durationS ?? t.job?.source?.durationS;
651
+ if (typeof length === "number" && length < 60) {
652
+ return { state: "not_requested", message: "Transcriptions shorter than a minute are not summarised." };
653
+ }
654
+ return { state: "none", message: "No summary was asked for; update_transcription with summary true writes one." };
655
+ }
656
+ async function writeSummary(ctx, id, t) {
657
+ const current = await summaryOf(ctx, id, t);
658
+ if (current.state === "ready" || current.state === "unavailable" || current.state === "not_requested")
659
+ return current;
660
+ if ((t.job && !TERMINAL.has(t.job.state)) || (!t.job && OPEN.has(t.state))) {
661
+ throw new ToolError("invalid_state", "The transcription is still running; wait for it (get_transcription with waitS), then ask for the summary.");
655
662
  }
663
+ if (current.state === "pending")
664
+ return current;
665
+ const made = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/summarize"), { signal: ctx.signal })).data;
656
666
  switch (made.state) {
657
667
  case "ready":
658
668
  return { state: "ready", title: made.title ?? t.name, summary: made.summary };
@@ -661,7 +671,7 @@ async function summary(a, ctx) {
661
671
  case "not_requested":
662
672
  return { state: "not_requested", message: "Transcriptions shorter than a minute are not summarised." };
663
673
  default:
664
- return pending("The summary is being written; ask again in a few seconds.");
674
+ return { state: "pending", message: "The summary is being written; ask again in a few seconds." };
665
675
  }
666
676
  }
667
677
  async function all(ctx, route, field, query = {}) {
@@ -691,14 +701,10 @@ async function speakers(_a, ctx) {
691
701
  function noSpeaker(number) {
692
702
  return new ToolError("not_found", `This transcription has no Speaker ${number} who has spoken; get_transcription shows the speaker numbers.`);
693
703
  }
694
- async function saveSpeaker(a, ctx) {
695
- const id = a.id("transcriptionId");
696
- const number = a.int("speaker", 1, 1, 1000);
697
- const name = a.reqStr("name");
698
- if ([...name].length > 60)
699
- throw bad("`name` must be 1 to 60 characters");
700
- const consent = a.bool("consent");
701
- await transcription(ctx, id);
704
+ async function saveSpeaker(ctx, id, number, name, consent) {
705
+ const n = [...name].length;
706
+ if (n === 0 || n > 60)
707
+ throw bad("with `save`, `name` must be 1 to 60 characters");
702
708
  const snap = await snapshot(ctx, id);
703
709
  const spoken = spokenSegments(snap).filter((l) => l.speaker >= 0);
704
710
  const numbers = numbering(spoken, snap);
@@ -709,6 +715,17 @@ async function saveSpeaker(a, ctx) {
709
715
  .sort((x, y) => x - y)[0];
710
716
  if (appearance === undefined)
711
717
  throw noSpeaker(number);
718
+ const known = (await all(ctx, "/v1/speakers", "speakers")).find((s) => s.transcriptionId === id && s.consent !== "refused" && !s.draft && s.library !== false && typeof s.name === "string" && s.name.toLowerCase() === name.toLowerCase());
719
+ if (known) {
720
+ let s = known;
721
+ if (consent && s.consent !== "granted") {
722
+ s = (await ctx.api.request("POST", path("/v1/speakers/", s.id, "/consent"), { json: { consent: "granted" }, signal: ctx.signal })).data;
723
+ }
724
+ const out = { speakerId: s.id, saved: false, consent: s.consent, cloned: s.voice != null };
725
+ if (s.voice)
726
+ put(out, "voiceState", s.voice.state);
727
+ return out;
728
+ }
712
729
  let s;
713
730
  try {
714
731
  s = (await ctx.api.request("POST", "/v1/speakers/from-appearance", {
@@ -721,11 +738,32 @@ async function saveSpeaker(a, ctx) {
721
738
  throw noSpeaker(number);
722
739
  throw e;
723
740
  }
724
- const out = { speakerId: s.id, name: s.name, consent: s.consent, cloned: s.voice != null };
741
+ const out = { speakerId: s.id, saved: true, consent: s.consent, cloned: s.voice != null };
725
742
  if (s.voice)
726
743
  put(out, "voiceState", s.voice.state);
727
744
  return out;
728
745
  }
746
+ async function getAccount(_a, ctx) {
747
+ const b = await ctx.api.get("/v1/billing", {}, ctx.signal);
748
+ const l = b.limitsUsage ?? {};
749
+ const out = {
750
+ billingEnabled: b.enabled ?? null,
751
+ plan: b.plan ?? null,
752
+ balance: b.balance ?? null,
753
+ canStart: b.canStart ?? null,
754
+ startBlock: b.startBlock ?? null,
755
+ canStartLive: b.canStartLive ?? null,
756
+ startBlockLive: b.startBlockLive ?? null,
757
+ running: l.running ?? null,
758
+ concurrentLimit: l.concurrentLimit ?? null,
759
+ createdLastHour: l.createdLastHour ?? null,
760
+ createLimit: l.createLimit ?? null,
761
+ period: b.period ?? null,
762
+ topUpUrl: b.topUpUrl ?? null,
763
+ };
764
+ put(out, "monthlyCredit", b.monthlyCredit);
765
+ return out;
766
+ }
729
767
  async function deleteSpeaker(a, ctx) {
730
768
  const id = a.id("speakerId");
731
769
  try {
@@ -812,7 +850,15 @@ async function deleteTranscription(a, ctx) {
812
850
  put(out, "restorableUntil", t.purgeAfter);
813
851
  return out;
814
852
  }
815
- function renameTarget(a) {
853
+ function optBool(a, k) {
854
+ const v = a.raw[k];
855
+ if (v === undefined || v === null)
856
+ return undefined;
857
+ if (typeof v !== "boolean")
858
+ throw bad(`\`${k}\` must be true or false`);
859
+ return v;
860
+ }
861
+ function speakerTarget(a) {
816
862
  const sid = present(a, "speakerId");
817
863
  const tid = present(a, "transcriptionId");
818
864
  const spk = present(a, "speaker");
@@ -834,66 +880,6 @@ function noSavedSpeaker(e) {
834
880
  }
835
881
  throw e;
836
882
  }
837
- async function renameSavedSpeaker(a, ctx) {
838
- const id = a.id("speakerId");
839
- const given = a.raw.name;
840
- if (typeof given !== "string")
841
- throw bad("`name` must be a string");
842
- const name = given.trim();
843
- const n = [...name].length;
844
- if (n === 0 || n > 60)
845
- throw bad("a saved speaker's `name` must be 1 to 60 characters");
846
- let s;
847
- try {
848
- s = (await ctx.api.request("PATCH", path("/v1/speakers/", id), { json: { name }, signal: ctx.signal })).data;
849
- }
850
- catch (e) {
851
- noSavedSpeaker(e);
852
- }
853
- return { speakerId: s.id, name: s.name };
854
- }
855
- async function renameSpeaker(a, ctx) {
856
- if (renameTarget(a))
857
- return renameSavedSpeaker(a, ctx);
858
- const id = a.id("transcriptionId");
859
- const number = a.int("speaker", 1, 1, 1000);
860
- const given = a.raw.name;
861
- if (typeof given !== "string")
862
- throw bad('`name` must be a string ("" clears the name)');
863
- const name = [...given.trim()].slice(0, 80).join("");
864
- await transcription(ctx, id);
865
- try {
866
- await ctx.api.request("PUT", path("/v1/transcriptions/", id, "/appearances/", String(number)), {
867
- json: { name: name || null },
868
- signal: ctx.signal,
869
- });
870
- }
871
- catch (e) {
872
- if (e instanceof ToolError && e.code === "not_found") {
873
- throw new ToolError("not_found", `This transcription has no Speaker ${number}; get_transcription shows the speaker numbers.`);
874
- }
875
- throw e;
876
- }
877
- return { transcriptionId: id, speaker: number, name: name || null };
878
- }
879
- const VOICE_CLONING_NEEDS_CONSENT = "turning voiceCloning on needs voiceCloningConsent: true — confirm you have permission from everyone speaking";
880
- function clonedVoicesTarget(a) {
881
- const sid = present(a, "speakerId");
882
- const tid = present(a, "transcriptionId");
883
- if (sid && !tid)
884
- return true;
885
- if (tid && !sid)
886
- return false;
887
- if (sid)
888
- throw bad("give either `transcriptionId` (one transcription) or `speakerId` (a saved speaker), not both");
889
- throw bad("give `transcriptionId` (one transcription) or `speakerId` (a saved speaker)");
890
- }
891
- function onArg(a) {
892
- const on = a.raw.on;
893
- if (typeof on !== "boolean")
894
- throw bad("`on` must be true or false");
895
- return on;
896
- }
897
883
  async function savedSpeaker(ctx, id) {
898
884
  try {
899
885
  return await ctx.api.get(path("/v1/speakers/", id), undefined, ctx.signal);
@@ -910,66 +896,240 @@ async function patchSpeaker(ctx, id, body) {
910
896
  noSavedSpeaker(e);
911
897
  }
912
898
  }
913
- async function setSpeakerClonedVoice(a, ctx) {
899
+ async function updateSavedSpeaker(a, ctx) {
914
900
  const id = a.id("speakerId");
915
- const on = onArg(a);
901
+ if (present(a, "save"))
902
+ throw bad("`save` is for a speaker in one transcription (transcriptionId with speaker); this one is already saved");
903
+ let name;
904
+ const given = a.raw.name;
905
+ if (given !== undefined && given !== null) {
906
+ if (typeof given !== "string")
907
+ throw bad("`name` must be a string");
908
+ name = given.trim();
909
+ const n = [...name].length;
910
+ if (n === 0 || n > 60)
911
+ throw bad("a saved speaker's `name` must be 1 to 60 characters");
912
+ }
913
+ const cloned = optBool(a, "clonedVoice");
916
914
  const consent = a.bool("consent");
917
- if (on && !consent) {
915
+ if (name === undefined && cloned === undefined)
916
+ throw bad("give `name`, `clonedVoice` or both to change a saved speaker");
917
+ if (cloned === true && !consent) {
918
918
  throw bad("Turning a saved speaker's cloned voice on needs consent: true, confirming that person agreed to have their voice cloned.");
919
919
  }
920
- const cur = await savedSpeaker(ctx, id);
921
- if (on) {
922
- if (cur.consent === "refused") {
923
- throw new ToolError("invalid_state", "This speaker refused to be cloned and their audio was deleted; save them again from a transcription (save_speaker with consent) to clone them.");
920
+ const report = (s) => {
921
+ const out = {
922
+ speakerId: s.id,
923
+ name: s.name,
924
+ consent: s.consent,
925
+ clonedVoice: s.voice?.enabled === true && s.consent === "granted",
926
+ };
927
+ if (s.voice)
928
+ put(out, "voiceState", s.voice.state);
929
+ return out;
930
+ };
931
+ if (cloned === undefined) {
932
+ try {
933
+ return report((await ctx.api.request("PATCH", path("/v1/speakers/", id), { json: { name }, signal: ctx.signal })).data);
934
+ }
935
+ catch (e) {
936
+ noSavedSpeaker(e);
924
937
  }
938
+ }
939
+ const cur = await savedSpeaker(ctx, id);
940
+ if (cloned === true && cur.consent === "refused") {
941
+ throw new ToolError("invalid_state", "This speaker refused to be cloned and their audio was deleted; save them again from a transcription (update_speaker with save and consent) to clone them.");
942
+ }
943
+ if (name !== undefined)
944
+ await patchSpeaker(ctx, id, { name });
945
+ if (cloned === true) {
925
946
  let s;
926
947
  try {
927
948
  s = (await ctx.api.request("POST", path("/v1/speakers/", id, "/consent"), { json: { consent: "granted" }, signal: ctx.signal })).data;
928
949
  }
929
950
  catch (e) {
930
951
  if (e instanceof ToolError && e.code === "invalid_state" && e.message.includes("no sample stored")) {
931
- throw new ToolError("invalid_state", "This saved speaker has no stored sample to clone their voice from; save them again from a transcription (save_speaker with consent).");
952
+ throw new ToolError("invalid_state", "This saved speaker has no stored sample to clone their voice from; save them again from a transcription (update_speaker with save and consent).");
932
953
  }
933
954
  noSavedSpeaker(e);
934
955
  }
935
956
  if (s?.voice && s.voice.enabled === false)
936
957
  await patchSpeaker(ctx, id, { enabled: true });
937
958
  }
938
- else if (cur.voice?.enabled === true) {
959
+ else if (cloned === false && cur.voice?.enabled === true) {
939
960
  await patchSpeaker(ctx, id, { enabled: false });
940
961
  }
941
- const s = await savedSpeaker(ctx, id);
942
- const out = {
943
- speakerId: s.id,
944
- name: s.name,
945
- consent: s.consent,
946
- clonedVoice: s.voice?.enabled === true && s.consent === "granted",
947
- };
948
- if (s.voice)
949
- put(out, "voiceState", s.voice.state);
950
- return out;
962
+ return report(await savedSpeaker(ctx, id));
951
963
  }
952
- async function setClonedVoices(a, ctx) {
953
- if (clonedVoicesTarget(a))
954
- return setSpeakerClonedVoice(a, ctx);
955
- const id = a.id("transcriptionId");
956
- const on = onArg(a);
964
+ async function updateSpeaker(a, ctx) {
965
+ if (speakerTarget(a))
966
+ return updateSavedSpeaker(a, ctx);
967
+ if (present(a, "clonedVoice")) {
968
+ throw bad("`clonedVoice` is for a saved speaker (speakerId); for everyone in one transcription use update_transcription with clonedVoices");
969
+ }
970
+ const save = optBool(a, "save") ?? false;
957
971
  const consent = a.bool("consent");
972
+ if (consent && !save) {
973
+ throw bad("`consent` with `transcriptionId` goes with `save: true` (saving and cloning this person); to clone a saved speaker use `speakerId` with `clonedVoice`");
974
+ }
975
+ const id = a.id("transcriptionId");
976
+ const number = a.int("speaker", 1, 1, 1000);
977
+ const given = a.raw.name;
978
+ if (given === undefined || given === null)
979
+ throw bad('`name` is required with `transcriptionId` and `speaker` ("" clears the name)');
980
+ if (typeof given !== "string")
981
+ throw bad('`name` must be a string ("" clears the name)');
982
+ const name = [...given.trim()].slice(0, 80).join("");
983
+ if (save && (name.length === 0 || [...given.trim()].length > 60))
984
+ throw bad("`name` must be 1 to 60 characters");
958
985
  await transcription(ctx, id);
959
- let t;
986
+ if (save)
987
+ return { transcriptionId: id, speaker: number, name, ...(await saveSpeaker(ctx, id, number, given.trim(), consent)) };
960
988
  try {
961
- t = (await ctx.api.request("PATCH", path("/v1/transcriptions/", id), {
962
- json: { settings: { voiceCloning: on, voiceCloningConsent: consent } },
989
+ await ctx.api.request("PUT", path("/v1/transcriptions/", id, "/appearances/", String(number)), {
990
+ json: { name: name || null },
963
991
  signal: ctx.signal,
964
- })).data;
992
+ });
965
993
  }
966
994
  catch (e) {
967
- if (e instanceof ToolError && e.message === VOICE_CLONING_NEEDS_CONSENT) {
968
- throw bad("Turning cloned voices on needs consent: true, confirming everyone speaking agreed to have their voice cloned.");
995
+ if (e instanceof ToolError && e.code === "not_found") {
996
+ throw new ToolError("not_found", `This transcription has no Speaker ${number}; get_transcription shows the speaker numbers.`);
969
997
  }
970
998
  throw e;
971
999
  }
972
- return { transcriptionId: t.id, name: t.name, clonedVoices: t.settings?.voiceCloning === true };
1000
+ return { transcriptionId: id, speaker: number, name: name || null };
1001
+ }
1002
+ const VOICE_CLONING_NEEDS_CONSENT = "turning voiceCloning on needs voiceCloningConsent: true — confirm you have permission from everyone speaking";
1003
+ const NEEDS_CONSENT = "Turning cloned voices on needs consent: true, confirming everyone speaking agreed to have their voice cloned.";
1004
+ function consentError(e) {
1005
+ if (e instanceof ToolError && e.message === VOICE_CLONING_NEEDS_CONSENT)
1006
+ throw bad(NEEDS_CONSENT);
1007
+ throw e;
1008
+ }
1009
+ async function updateTranscription(a, ctx) {
1010
+ const id = a.id("transcriptionId");
1011
+ let name = a.str("name");
1012
+ if (name !== undefined) {
1013
+ name = name.trim();
1014
+ const n = [...name].length;
1015
+ if (n === 0 || n > 200)
1016
+ throw bad("`name` must be 1 to 200 characters");
1017
+ }
1018
+ const share = optBool(a, "shareLink");
1019
+ const restore = optBool(a, "restore");
1020
+ if (restore === false)
1021
+ throw bad("`restore` takes only true (bring it back from the trash); delete_transcription moves it there");
1022
+ const summary = optBool(a, "summary");
1023
+ const cloned = optBool(a, "clonedVoices");
1024
+ const consent = a.bool("consent");
1025
+ if (summary === false)
1026
+ throw bad("`summary` takes only true (write one now); a summary is never deleted");
1027
+ if (name === undefined && share === undefined && summary === undefined && cloned === undefined && restore === undefined) {
1028
+ throw bad("give at least one of `name`, `shareLink`, `summary`, `clonedVoices` or `restore` to change");
1029
+ }
1030
+ if (cloned === true && !consent)
1031
+ throw bad(NEEDS_CONSENT);
1032
+ let t = await transcription(ctx, id);
1033
+ const restored = restore === true && t.lifecycle === "archived";
1034
+ if (restored) {
1035
+ t = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/restore"), { signal: ctx.signal })).data;
1036
+ }
1037
+ else if (t.lifecycle && t.lifecycle !== "active") {
1038
+ throw new ToolError("invalid_state", "This transcription is in the trash; pass restore: true to bring it back.");
1039
+ }
1040
+ const written = summary === true ? await writeSummary(ctx, id, t) : undefined;
1041
+ if (name !== undefined || cloned !== undefined) {
1042
+ const body = {};
1043
+ if (name !== undefined)
1044
+ body.name = name;
1045
+ if (cloned !== undefined)
1046
+ body.settings = { voiceCloning: cloned, voiceCloningConsent: consent };
1047
+ try {
1048
+ t = (await ctx.api.request("PATCH", path("/v1/transcriptions/", id), { json: body, signal: ctx.signal })).data;
1049
+ }
1050
+ catch (e) {
1051
+ consentError(e);
1052
+ }
1053
+ }
1054
+ let links = (await ctx.api.get(path("/v1/transcriptions/", id, "/share-links"), undefined, ctx.signal))?.links ?? [];
1055
+ if (share === true && links.length === 0) {
1056
+ const l = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/share-links"), { json: { label: "Shared link" }, signal: ctx.signal })).data;
1057
+ links = [l];
1058
+ }
1059
+ else if (share === false) {
1060
+ for (const l of links)
1061
+ await ctx.api.request("DELETE", path("/v1/share-links/", l.id), { signal: ctx.signal });
1062
+ links = [];
1063
+ }
1064
+ const out = { transcriptionId: t.id, name: t.name, shareUrl: links[0]?.url ?? null, clonedVoices: t.settings?.voiceCloning === true };
1065
+ if (restore !== undefined)
1066
+ out.restored = restored;
1067
+ if (written)
1068
+ out.summary = written;
1069
+ return out;
1070
+ }
1071
+ async function updateBroadcast(a, ctx) {
1072
+ const id = a.id("broadcastId");
1073
+ const name = a.str("name");
1074
+ const access = a.raw.access === undefined || a.raw.access === null ? undefined : a.oneOf("access", ["public", "private"], "public");
1075
+ const password = a.str("password");
1076
+ const spokenRaw = a.str("spokenLanguage");
1077
+ const speak = optBool(a, "spokenTranslations");
1078
+ const cloned = optBool(a, "clonedVoices");
1079
+ const consent = a.bool("consent");
1080
+ const restore = optBool(a, "restore");
1081
+ if (restore === false)
1082
+ 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);
1084
+ if (!changes && restore === undefined) {
1085
+ throw bad("give at least one of `name`, `access`, `password`, `spokenLanguage`, `spokenTranslations`, `clonedVoices` or `restore` to change");
1086
+ }
1087
+ if (cloned === true && !consent)
1088
+ throw bad(NEEDS_CONSENT);
1089
+ let b = await broadcast(ctx, id);
1090
+ const restored = restore === true && b.lifecycle === "archived";
1091
+ if (restored)
1092
+ b = (await ctx.api.request("POST", path("/v1/broadcasts/", id, "/restore"), { signal: ctx.signal })).data;
1093
+ const body = {};
1094
+ if (name !== undefined)
1095
+ body.name = name;
1096
+ if (access !== undefined)
1097
+ body.access = access;
1098
+ if (password !== undefined && access !== "public")
1099
+ body.password = password;
1100
+ const settings = {};
1101
+ if (spokenRaw !== undefined) {
1102
+ const l = spokenRaw.trim().toLowerCase();
1103
+ settings.spokenLanguage = l === "" || l === "auto" ? null : l;
1104
+ }
1105
+ if (speak !== undefined)
1106
+ settings.translationTts = speak;
1107
+ if (cloned !== undefined) {
1108
+ settings.voiceCloning = cloned;
1109
+ settings.voiceCloningConsent = consent;
1110
+ }
1111
+ if (Object.keys(settings).length)
1112
+ body.settings = settings;
1113
+ if (changes)
1114
+ try {
1115
+ b = (await ctx.api.request("PATCH", path("/v1/broadcasts/", id), { json: body, signal: ctx.signal })).data;
1116
+ }
1117
+ catch (e) {
1118
+ if (e instanceof ToolError && e.code === "invalid_state") {
1119
+ throw new ToolError("invalid_state", "This broadcast is in the trash; pass restore: true to bring it back.");
1120
+ }
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
+ consentError(e);
1125
+ }
1126
+ return {
1127
+ ...brief(b),
1128
+ spokenLanguage: b.settings?.spokenLanguage ?? "auto",
1129
+ spokenTranslations: b.settings?.translationTts === true,
1130
+ clonedVoices: b.settings?.voiceCloning === true,
1131
+ ...(restore !== undefined ? { restored } : {}),
1132
+ };
973
1133
  }
974
1134
  const ON_AIR = "This broadcast is already on air; stop it first (stop_broadcast) or use another broadcast.";
975
1135
  async function startBroadcast(a, ctx) {
@@ -1084,15 +1244,15 @@ export const handlers = {
1084
1244
  get_transcription: getTranscription,
1085
1245
  list_transcriptions: listTranscriptions,
1086
1246
  search_transcriptions: search,
1087
- get_summary: summary,
1088
- rename_speaker: renameSpeaker,
1247
+ update_transcription: updateTranscription,
1089
1248
  delete_transcription: deleteTranscription,
1090
- set_cloned_voices: setClonedVoices,
1091
1249
  list_speakers: speakers,
1092
- save_speaker: saveSpeaker,
1250
+ update_speaker: updateSpeaker,
1093
1251
  delete_speaker: deleteSpeaker,
1094
1252
  list_broadcasts: listBroadcasts,
1095
1253
  start_broadcast: startBroadcast,
1254
+ update_broadcast: updateBroadcast,
1096
1255
  stop_broadcast: stopBroadcast,
1097
1256
  delete_broadcast: deleteBroadcast,
1257
+ get_account: getAccount,
1098
1258
  };
package/dist/tools.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
- "instructions": "VocalStack transcribes and translates recorded or live audio and video in about 100 languages, with speaker labels.\nRecorded audio: create_transcription (a link or a file) returns a transcriptionId at once; get_transcription with waitS waits for it and reads the text, in any language with lang.\nFind: list_transcriptions (ids, newest first); search_transcriptions (mode words for words or names, meaning for a question).\nOne transcription: get_summary; rename_speaker; set_cloned_voices; delete_transcription (to the trash, restorable in the Dashboard).\nLive streams: start_broadcast, then get_transcription while it runs, stop_broadcast to end it; list_broadcasts shows them; delete_broadcast removes one.\nPeople: list_speakers, save_speaker (voice cloned only with the person's consent), rename_speaker, set_cloned_voices with speakerId, delete_speaker.\nOnly transcription is billed; everything else, and listening, is free. Retry a start with the same idempotencyKey.\nErrors are results with isError true: error, message, retryable, and retryAfterS or topUpUrl when they apply.",
2
+ "instructions": "VocalStack transcribes and translates recorded or live audio and video in about 100 languages, with speaker labels.\nRecorded audio: create_transcription (a link or a file) returns a transcriptionId at once; get_transcription with waitS waits for it and reads the text, in any language with lang.\nFind: list_transcriptions (ids, newest first); search_transcriptions (mode words for words or names, meaning for a question).\nOne transcription: get_transcription with format summary for its title and summary; update_transcription (name, share link, summary, cloned voices); delete_transcription (to the trash; update_transcription with restore brings it back).\nLive streams: start_broadcast, then get_transcription while it runs, stop_broadcast to end it; list_broadcasts shows them; update_broadcast changes access, language and spoken translations; delete_broadcast removes one.\nPeople: list_speakers, update_speaker (names; save true remembers a person, their voice cloned only with their consent; a saved speaker's cloned voice), delete_speaker.\nCredit and usage: get_account (balance, plan, whether a new transcription would start, limits).\nOnly transcription is billed; everything else, and listening, is free. Retry a start with the same idempotencyKey.\nErrors are results with isError true: error, message, retryable, and retryAfterS or topUpUrl when they apply.",
3
3
  "tools": [
4
4
  {
5
5
  "name": "create_transcription",
6
6
  "title": "Create a transcription",
7
- "description": "Start transcribing a finished recording, from a public link or a file sent inline; returns a transcriptionId at once, before any text.\nUse: audio or video that has ended (a file, podcast episode, YouTube video or public post). A stream playing now: start_broadcast. The result: get_transcription with waitS, no polling needed.\nList price: $0.20 an hour of audio, billed per second transcribed; Pay as you go bills at least 5 minutes per transcription. Each call is a new, billed transcription unless it repeats an idempotencyKey; a refused call costs nothing; summary and shareLink are free.\nNew transcriptions an hour per account: 10 on Pay as you go, 100 on Premium.\nTranscriptions running at once per account: 5 on Pay as you go, 50 on Premium; more wait their turn instead of failing.\nReturns: transcriptionId, state (queued, fetching, transcribing, then done, failed or stopped), progress, shareUrl when shareLink is true, replayed true for a repeated key.\nErrors: invalid_options (neither or both of url and fileBase64, not a public http(s) link, bad base64, too large), invalid_audio (empty file), idempotency_key_reused, insufficient_credit (with topUpUrl), quota_exceeded, rate_limited (with retryAfterS). A source that cannot be read ends in state failed, with error.",
7
+ "description": "Start transcribing a finished recording, from a public link or a file sent inline; returns a transcriptionId at once, before any text.\nUse: audio or video that has ended (a file, podcast episode, YouTube video or public post). A stream playing now: start_broadcast. The result: get_transcription with waitS, no polling needed.\nArguments: exactly one source: url, or fileBase64 with filename (over 10 MiB: host the file and give url). startS and endS clip both what is transcribed and what is billed. spokenLanguage helps short or noisy audio; speakerLabels is fixed once created, while summary and shareLink can also be turned on later with update_transcription.\nBehaviour: VocalStack's servers download the link once, as a visitor who is not signed in; nothing is posted to or changed on the source site.\nList price: $0.20 an hour of audio, billed per second transcribed; Pay as you go bills at least 5 minutes per transcription. Each call is a new, billed transcription unless it repeats an idempotencyKey; a refused call costs nothing; summary and shareLink are free.\nNew transcriptions an hour per account: 10 on Pay as you go, 100 on Premium.\nTranscriptions running at once per account: 5 on Pay as you go, 50 on Premium; more wait their turn instead of failing.\nReturns: transcriptionId, state (queued, fetching, transcribing, then done, failed or stopped), progress, shareUrl when shareLink is true, replayed true for a repeated key.\nErrors: invalid_options (neither or both of url and fileBase64, not a public http(s) link, bad base64, too large), invalid_audio (empty file), idempotency_key_reused, insufficient_credit (with topUpUrl), quota_exceeded, rate_limited (with retryAfterS). A source that cannot be read ends in state failed, with error.",
8
8
  "inputSchema": {
9
9
  "additionalProperties": false,
10
10
  "properties": {
@@ -84,7 +84,7 @@
84
84
  },
85
85
  "summary": {
86
86
  "default": false,
87
- "description": "Also write a title and summary when it is done, at no extra cost (get_summary reads it). Never for recordings under a minute.",
87
+ "description": "Also write a title and summary when it is done, at no extra cost (get_transcription with format summary reads it). Never for recordings under a minute.",
88
88
  "type": "boolean"
89
89
  },
90
90
  "url": {
@@ -111,16 +111,17 @@
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: as it was 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: get_summary. Finding a passage: 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 create_transcription's shareLink, or in the Dashboard), 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. 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 when waitS is set and 4 waits are already open for this key (8 for the account).",
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.",
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; 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 subtitles and exact times; summary: the title and summary only, for an overview; none: status only (with waitS: wait without reading).",
121
121
  "enum": [
122
122
  "text",
123
123
  "segments",
124
+ "summary",
124
125
  "none"
125
126
  ]
126
127
  },
@@ -130,7 +131,7 @@
130
131
  "type": "boolean"
131
132
  },
132
133
  "lang": {
133
- "description": "Code of a language to read the whole text in, one of about 100 (e.g. es, de, ja): the transcription must be finished (state done, or a stopped live one). The language already spoken returns the original with translated false. Omit for the original.",
134
+ "description": "Code of a language to read the whole text (or, with format summary, the summary) in, one of about 100 (e.g. es, de, ja): the transcription must be finished (state done, or a stopped live one). The language already spoken returns the original with translated false. Omit for the original.",
134
135
  "examples": [
135
136
  "es",
136
137
  "ja"
@@ -191,7 +192,7 @@
191
192
  {
192
193
  "name": "list_transcriptions",
193
194
  "title": "List transcriptions",
194
- "description": "List this account's transcriptions, newest first, a page at a time: files, links and live ones, including those broadcasts recorded.\nUse: to find a transcriptionId or see what exists. What was said: search_transcriptions. Broadcasts: list_broadcasts.\nBehaviour: free. lifecycle archived lists the trash: deleted transcriptions, which the VocalStack Dashboard can restore for 30 days. A cursor this tool did not give out is refused.\nReturns: transcriptions (transcriptionId, name, createdAt, kind file or live, state, durationS and title when known, broadcastId for a broadcast's), and nextCursor while more remain. None: an empty list.\nErrors: invalid_options for an unknown cursor.",
195
+ "description": "List this account's transcriptions, newest first, a page at a time: files, links and live ones, including those broadcasts recorded.\nUse: to find a transcriptionId or see what exists. What was said: search_transcriptions. Broadcasts: list_broadcasts.\nBehaviour: free. Ordered by creation time, so pages are stable: transcriptions made or deleted while paging never repeat or shift another out of its page. lifecycle archived lists the trash: deleted transcriptions, restorable for 30 days with update_transcription restore true. A cursor this tool did not give out is refused.\nReturns: transcriptions (transcriptionId, name, createdAt, kind file or live, state, durationS and title when known, broadcastId for a broadcast's), and nextCursor while more remain. None: an empty list.\nErrors: invalid_options for an unknown cursor; rate_limited (with retryAfterS) past 600 calls a minute per API key.",
195
196
  "inputSchema": {
196
197
  "additionalProperties": false,
197
198
  "properties": {
@@ -232,7 +233,7 @@
232
233
  {
233
234
  "name": "search_transcriptions",
234
235
  "title": "Search transcriptions",
235
- "description": "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).\nUse: words when you know what was said; meaning for a question or topic, in any language. Text around a hit: get_transcription with offset. One transcription's overview: get_summary.\nBehaviour: free; no paging. words ranks whole words first, then close spellings, then newest, and searches the query's English translation too. meaning returns up to 10 passages, closest first. Searches by meaning an hour per account: 60 on Pay as you go, no limit on Premium.\nReturns: words: query, queryEn, hits (transcriptionId, name, mediaStart in seconds, speaker, text, score, live, recordedAt, rendered with lang). meaning: query, state (ready, or unavailable or off when it cannot run), passages (transcriptionId, name, mediaStart, mediaEnd, text, similarity 0 to 1, live), searchesLeftThisHour when capped. Cite the transcription and second. No match: an empty list.\nErrors: not_found for an unknown transcriptionId; invalid_options for lang or limit with mode meaning; rate_limited (with retryAfterS) past the hourly searches by meaning.",
236
+ "description": "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).\nUse: words when you know what was said; meaning for a question or topic, in any language. Text around a hit: get_transcription with offset. One transcription's overview: get_transcription with format summary.\nArguments: query is phrased differently per mode: a few words or a name for words, a whole question for meaning. transcriptionId narrows either mode to one transcription. lang and limit work with words only, and lang changes only how hits are shown, never which lines match.\nBehaviour: free; no paging. words ranks whole words first, then close spellings, then newest, and searches the query's English translation too, and finds a line once it is final, so the last seconds of a live transcription may not show yet. The trash is never searched. meaning returns up to 10 passages, closest first, and covers finished recordings only (they are indexed after they end). Searches by meaning an hour per account: 60 on Pay as you go, no limit on Premium.\nReturns: words: query, queryEn, hits (transcriptionId, name, mediaStart in seconds, speaker, text, score, live, recordedAt, rendered with lang). meaning: query, state (ready, or unavailable or off when it cannot run), passages (transcriptionId, name, mediaStart, mediaEnd, text, similarity 0 to 1, live), searchesLeftThisHour when capped. Cite the transcription and second. No match: an empty list.\nErrors: not_found for an unknown transcriptionId; invalid_options for lang or limit with mode meaning; rate_limited (with retryAfterS) past the hourly searches by meaning.",
236
237
  "inputSchema": {
237
238
  "additionalProperties": false,
238
239
  "properties": {
@@ -295,75 +296,47 @@
295
296
  }
296
297
  },
297
298
  {
298
- "name": "get_summary",
299
- "title": "Get a summary",
300
- "description": "Get the title and summary of a finished transcription, writing one the first time if it has none.\nUse: for an overview. Full text, or the whole text in another language: get_transcription. A specific question: search_transcriptions with mode meaning.\nArguments: transcriptionId of a finished transcription (state done, or a stopped live one), from create_transcription, list_transcriptions or search_transcriptions. lang is optional, a language code such as fr: it translates only when the transcription was made with summary translations on and lang differs from the language the summary is in; otherwise the original comes back, without lang in the result.\nBehaviour: free. Writing a first summary needs the write scope and keeps it for later calls; reading an existing one needs read only.\nReturns: state ready with title and summary (and lang when translated); pending while it is written or the transcription still runs (call again in a few seconds); not_requested for recordings under a minute; unavailable when the transcription failed.\nErrors: not_found; forbidden when a summary must be written and the key is read-only.",
299
+ "name": "update_transcription",
300
+ "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.",
301
302
  "inputSchema": {
302
303
  "additionalProperties": false,
303
304
  "properties": {
304
- "lang": {
305
- "description": "Optional language code for the title and summary, honoured when the transcription was made with summary translations on; otherwise the original comes back without lang.",
306
- "examples": [
307
- "fr"
308
- ],
309
- "type": "string"
305
+ "clonedVoices": {
306
+ "description": "true: translations of each speaker's own words are read aloud in that speaker's own cloned voice (needs consent true); false: stock voices.",
307
+ "type": "boolean"
308
+ },
309
+ "consent": {
310
+ "default": false,
311
+ "description": "Must be true with clonedVoices true: confirms everyone speaking in it agreed to have their voice cloned. Recorded with your account and the time. Not needed to turn cloned voices off.",
312
+ "type": "boolean"
310
313
  },
311
- "transcriptionId": {
312
- "description": "A transcriptionId from create_transcription, list_transcriptions, search_transcriptions or start_broadcast.",
313
- "examples": [
314
- "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
315
- ],
316
- "format": "uuid",
317
- "type": "string"
318
- }
319
- },
320
- "required": [
321
- "transcriptionId"
322
- ],
323
- "type": "object"
324
- },
325
- "annotations": {
326
- "title": "Get a summary",
327
- "readOnlyHint": false,
328
- "destructiveHint": false,
329
- "idempotentHint": true,
330
- "openWorldHint": false
331
- }
332
- },
333
- {
334
- "name": "rename_speaker",
335
- "title": "Rename a speaker",
336
- "description": "Name or rename a speaker: one person in one transcription, so its transcript shows the name instead of \"Speaker N\", or a saved speaker, everywhere they are recognised.\nUse: labelling who spoke here, or correcting a saved speaker's name. To recognise the person in later transcriptions too: save_speaker (it also names them here). Saved speakers: list_speakers.\nArguments: give exactly one of transcriptionId with speaker (the number in \"Speaker 2\" from get_transcription, not a name or an id) or speakerId (from list_speakers). name is trimmed; in a transcription it is cut to 80 characters and an empty name undoes it; a saved speaker's name is 1 to 60 characters. Calling again replaces the name.\nBehaviour: free and reversible; in a transcription it applies to that person in every recording of it, and listeners following it live see it at once. The person's speaker number never changes. Renaming a saved speaker changes nothing else about them (fingerprint, consent, cloned voice).\nReturns: transcriptionId, speaker, name (null when cleared); or, with speakerId, speakerId and name.\nErrors: invalid_options for both or neither kind of target, or a saved speaker's name out of 1 to 60; not_found for an unknown transcription, speaker number or speakerId; forbidden for a read-only key.",
337
- "inputSchema": {
338
- "additionalProperties": false,
339
- "properties": {
340
314
  "name": {
341
- "description": "The name to show instead of \"Speaker N\", trimmed: 1 to 80 characters in one transcription (longer is cut; an empty string clears it back to \"Speaker N\"), 1 to 60 for a saved speaker (never empty).",
315
+ "description": "New display name, shown in lists and on the share page; trimmed, 1 to 200 characters.",
342
316
  "examples": [
343
- "Maria Lopez",
344
- ""
317
+ "Board meeting, 19 November"
345
318
  ],
346
- "maxLength": 80,
319
+ "maxLength": 200,
320
+ "minLength": 1,
347
321
  "type": "string"
348
322
  },
349
- "speaker": {
350
- "description": "With transcriptionId: the N of \"Speaker N\" in get_transcription's text, or speakerNumber in its segments; it stays the same after naming.",
323
+ "restore": {
324
+ "description": "true: bring it back from the trash (after delete_transcription, within the restore window) with everything it had; other fields given apply after. false is not accepted.",
351
325
  "examples": [
352
- 2
326
+ true
353
327
  ],
354
- "minimum": 1,
355
- "type": "integer"
328
+ "type": "boolean"
356
329
  },
357
- "speakerId": {
358
- "description": "Instead of transcriptionId and speaker: a saved speaker's id (id in list_speakers, or speakerId from save_speaker), renamed everywhere they are recognised.",
359
- "examples": [
360
- "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
361
- ],
362
- "format": "uuid",
363
- "type": "string"
330
+ "shareLink": {
331
+ "description": "true: make a public link anyone can open to read the transcript without signing in (an existing one is kept; shareUrl in the result). false: every public link of it stops working at once.",
332
+ "type": "boolean"
333
+ },
334
+ "summary": {
335
+ "description": "true: write a title and summary now if it has none (free; the transcription must be finished and at least a minute long). Read it with get_transcription format summary. false is not accepted: a summary is never deleted.",
336
+ "type": "boolean"
364
337
  },
365
338
  "transcriptionId": {
366
- "description": "With speaker: the transcription the speaker is in (from create_transcription, list_transcriptions, search_transcriptions or start_broadcast). Leave out with speakerId.",
339
+ "description": "A transcriptionId from create_transcription, list_transcriptions, search_transcriptions or start_broadcast.",
367
340
  "examples": [
368
341
  "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
369
342
  ],
@@ -372,12 +345,12 @@
372
345
  }
373
346
  },
374
347
  "required": [
375
- "name"
348
+ "transcriptionId"
376
349
  ],
377
350
  "type": "object"
378
351
  },
379
352
  "annotations": {
380
- "title": "Rename a speaker",
353
+ "title": "Update a transcription",
381
354
  "readOnlyHint": false,
382
355
  "destructiveHint": false,
383
356
  "idempotentHint": true,
@@ -387,7 +360,7 @@
387
360
  {
388
361
  "name": "delete_transcription",
389
362
  "title": "Delete a transcription",
390
- "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 it can be restored unchanged from the trash in the VocalStack Dashboard (list_transcriptions with lifecycle archived lists it); after that it is erased for good. Saved speakers stay (delete_speaker). A broadcast itself: delete_broadcast.\nBehaviour: 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.",
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.",
391
364
  "inputSchema": {
392
365
  "additionalProperties": false,
393
366
  "properties": {
@@ -413,56 +386,10 @@
413
386
  "openWorldHint": false
414
387
  }
415
388
  },
416
- {
417
- "name": "set_cloned_voices",
418
- "title": "Turn cloned voices on or off",
419
- "description": "Turn cloned voices on or off for spoken translations: for one transcription, or for one saved speaker everywhere they are recognised.\nOn: the speaker's translated words are read in that speaker's own cloned voice, never anyone else's; a speaker without a usable clone gets a stock voice. Off: stock voices. Voices are chosen by VocalStack; this is the only voice choice.\nArguments: give exactly one of transcriptionId (every speaker in it) or speakerId (a saved speaker, from list_speakers). on is required; consent must be true to turn on.\nConsent: turning on records, with your account and the time, that everyone speaking (or that saved speaker) agreed. For a transcription it releases its clones waiting for consent; speakers who refused are never cloned. For a saved speaker saved without consent it starts their clone from their stored sample. Off keeps the saved speaker's fingerprint, consent and clone, only unused; to erase the clone and their samples: delete_speaker.\nBehaviour: free and reversible; lines read aloud after the change use the new setting.\nReturns: transcriptionId, name, clonedVoices; or, with speakerId, speakerId, name, consent, clonedVoice, and voiceState (training, then ready) when cloned.\nErrors: invalid_options for on without consent or both or neither target; invalid_state for a deleted transcription, a speaker who refused, or one with no stored sample to clone from; not_found; forbidden for a read-only key.",
420
- "inputSchema": {
421
- "additionalProperties": false,
422
- "properties": {
423
- "consent": {
424
- "default": false,
425
- "description": "Must be true to turn cloned voices on: confirms everyone speaking (with speakerId: that person) agreed to have their voice cloned. Recorded with your account and the time. Not needed to turn them off.",
426
- "type": "boolean"
427
- },
428
- "on": {
429
- "description": "true: translations of the speaker's own words are read in their own cloned voice; false (the default for a transcription): stock voices.",
430
- "type": "boolean"
431
- },
432
- "speakerId": {
433
- "description": "Instead of transcriptionId, for one saved speaker everywhere they are recognised: id in list_speakers, or speakerId from save_speaker.",
434
- "examples": [
435
- "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
436
- ],
437
- "format": "uuid",
438
- "type": "string"
439
- },
440
- "transcriptionId": {
441
- "description": "For one transcription's spoken translations: a transcriptionId from create_transcription, list_transcriptions, search_transcriptions or start_broadcast. Leave out with speakerId.",
442
- "examples": [
443
- "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
444
- ],
445
- "format": "uuid",
446
- "type": "string"
447
- }
448
- },
449
- "required": [
450
- "on"
451
- ],
452
- "type": "object"
453
- },
454
- "annotations": {
455
- "title": "Turn cloned voices on or off",
456
- "readOnlyHint": false,
457
- "destructiveHint": false,
458
- "idempotentHint": true,
459
- "openWorldHint": false
460
- }
461
- },
462
389
  {
463
390
  "name": "list_speakers",
464
391
  "title": "List saved speakers",
465
- "description": "List the speakers this account has saved: people recognised by name in every new transcription.\nUse: to see who is known or find a speakerId for delete_speaker. Save one: save_speaker. Names inside one transcription come from get_transcription and are set with rename_speaker, which saves no one.\nBehaviour: free; no paging.\nReturns: speakers, newest first, each with id, name, gender when known, cloned (their voice was cloned, with consent, to read translations of their own words) and, when cloned, voiceReady. None saved: an empty list.",
392
+ "description": "List the speakers this account has saved: people recognised by name in every new transcription.\nUse: to see who is known, before saving someone (update_speaker with save), or to find a speakerId for update_speaker or delete_speaker. Names inside one transcription come from get_transcription.\nBehaviour: free; no paging.\nReturns: speakers, newest first, each with id, name, gender when known, cloned (their voice was cloned, with consent, to read translations of their own words) and, when cloned, voiceReady. None saved: an empty list.",
466
393
  "inputSchema": {
467
394
  "additionalProperties": false,
468
395
  "properties": {},
@@ -477,36 +404,53 @@
477
404
  }
478
405
  },
479
406
  {
480
- "name": "save_speaker",
481
- "title": "Save a speaker",
482
- "description": "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.\nUse: remembering a person across transcriptions. This transcription only: rename_speaker. Who is saved: list_speakers. Remove: delete_speaker.\nArguments: transcriptionId and speaker point at one person: speaker is the number in \"Speaker 2\" from get_transcription, who must have spoken (a live transcription can still be running). name is 1 to 60 characters, trimmed; renaming later: rename_speaker with speakerId. consent is true only when that person agreed to be cloned; leaving it out or false keeps only their fingerprint.\nBehaviour: free; also names them in this transcription. Each call saves a new speaker, so check list_speakers first. Without consent only a voice fingerprint is kept; with it the voice is cloned too, recorded with your account and the time.\nReturns: speakerId, name, consent (granted or pending), cloned, voiceState (training, then ready) when cloned.\nErrors: not_found for an unknown transcription or speaker number; invalid_options for too little speech of them (the message says how much there is); forbidden for a read-only key.",
407
+ "name": "update_speaker",
408
+ "title": "Name or save a speaker",
409
+ "description": "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.\nUse: labelling who spoke here; remembering a person across transcriptions (save true); correcting a saved speaker's name or turning their cloned voice on with their consent. Who is saved: list_speakers. Forgetting someone: delete_speaker.\nArguments: give exactly one target: transcriptionId with speaker (the number in \"Speaker 2\" from get_transcription, not a name or an id) and name, plus save and consent; or speakerId (from list_speakers) with name, clonedVoice or both. A name in a transcription is cut to 80 characters and an empty one undoes it; a saved speaker's, or one with save, is 1 to 60. clonedVoice true needs consent true. Examples: {transcriptionId, speaker: 2, name: \"Maria Lopez\"}; {transcriptionId, speaker: 2, name: \"Maria Lopez\", save: true}; {speakerId, clonedVoice: true, consent: true}.\nBehaviour: free; calling again replaces the name and saves no one twice. In a transcription it applies to that person in every recording of it, and listeners following live see it at once; their speaker number never changes. save keeps their voice fingerprint (and, with consent, clones their voice from their speech here, voiceState training then ready); the person must have spoken, and a live transcription can still be running. clonedVoice true clones a saved speaker from their stored sample if they have no clone yet; false keeps the clone, unused (delete_speaker erases it). Nothing else about the person changes.\nReturns: transcriptionId, speaker, name (null when cleared), and with save speakerId, saved (false when they were already saved), consent, cloned and voiceState; or, with speakerId, speakerId, name, consent, clonedVoice, and voiceState when cloned.\nErrors: invalid_options for both or neither kind of target, nothing to change, a bad name, save or clonedVoice with the wrong target, too little of their speech to save (the message says how much there is), or clonedVoice true without consent; invalid_state for a saved speaker who refused cloning or has no sample; not_found for an unknown transcription, speaker number or speakerId; forbidden for a read-only key.",
483
410
  "inputSchema": {
484
411
  "additionalProperties": false,
485
412
  "properties": {
413
+ "clonedVoice": {
414
+ "description": "With speakerId only: true reads translations of this person's own words in their own cloned voice (needs consent true; cloned from their stored sample if not yet), false back to a stock voice (the clone is kept, unused).",
415
+ "type": "boolean"
416
+ },
486
417
  "consent": {
487
418
  "default": false,
488
- "description": "true only when this person agreed to have their voice cloned: it is then cloned too, from their own speech in this transcription, so translations of their words can be read in their voice. false: only their fingerprint is saved. Never set it without the person's agreement.",
419
+ "description": "true only when this person agreed to have their voice cloned: needed with clonedVoice true, and with save it clones them too, from their own speech in this transcription. Recorded with your account and the time. Never set it without the person's agreement; not needed to turn a cloned voice off.",
489
420
  "type": "boolean"
490
421
  },
491
422
  "name": {
492
- "description": "The person's name, shown in this and later transcriptions.",
423
+ "description": "The name to show instead of \"Speaker N\", trimmed: up to 80 characters in one transcription (an empty string clears it back to \"Speaker N\"), 1 to 60 for a saved speaker or with save. Required with transcriptionId.",
493
424
  "examples": [
494
- "Maria Lopez"
425
+ "Maria Lopez",
426
+ ""
495
427
  ],
496
- "maxLength": 60,
497
- "minLength": 1,
428
+ "maxLength": 80,
498
429
  "type": "string"
499
430
  },
431
+ "save": {
432
+ "default": false,
433
+ "description": "With transcriptionId and speaker only: true also saves this person to the account's saved speakers, so later transcriptions recognise and name them; their own speech here is the sample. A person already saved from this transcription is not saved twice.",
434
+ "type": "boolean"
435
+ },
500
436
  "speaker": {
501
- "description": "The N of \"Speaker N\" in get_transcription's text, or speakerNumber in its segments. Works while a live transcription is still running.",
437
+ "description": "With transcriptionId: the N of \"Speaker N\" in get_transcription's text, or speakerNumber in its segments; it stays the same after naming.",
502
438
  "examples": [
503
439
  2
504
440
  ],
505
441
  "minimum": 1,
506
442
  "type": "integer"
507
443
  },
444
+ "speakerId": {
445
+ "description": "Instead of transcriptionId and speaker: a saved speaker's id (id in list_speakers, or speakerId from update_speaker with save), changed everywhere they are recognised.",
446
+ "examples": [
447
+ "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
448
+ ],
449
+ "format": "uuid",
450
+ "type": "string"
451
+ },
508
452
  "transcriptionId": {
509
- "description": "A transcriptionId from create_transcription, list_transcriptions, search_transcriptions or start_broadcast.",
453
+ "description": "With speaker: the transcription the speaker is in (from create_transcription, list_transcriptions, search_transcriptions or start_broadcast). Leave out with speakerId.",
510
454
  "examples": [
511
455
  "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
512
456
  ],
@@ -514,30 +458,25 @@
514
458
  "type": "string"
515
459
  }
516
460
  },
517
- "required": [
518
- "transcriptionId",
519
- "speaker",
520
- "name"
521
- ],
522
461
  "type": "object"
523
462
  },
524
463
  "annotations": {
525
- "title": "Save a speaker",
464
+ "title": "Name or save a speaker",
526
465
  "readOnlyHint": false,
527
466
  "destructiveHint": false,
528
- "idempotentHint": false,
467
+ "idempotentHint": true,
529
468
  "openWorldHint": false
530
469
  }
531
470
  },
532
471
  {
533
472
  "name": "delete_speaker",
534
473
  "title": "Delete a saved speaker",
535
- "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: rename_speaker.\nArguments: speakerId is a saved speaker's id, the id field of list_speakers or the speakerId save_speaker returned; not a speaker number (\"Speaker 2\") and not a transcriptionId. To unname someone in one transcription instead: rename_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.",
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.",
536
475
  "inputSchema": {
537
476
  "additionalProperties": false,
538
477
  "properties": {
539
478
  "speakerId": {
540
- "description": "A saved speaker's id: id in list_speakers, or speakerId from save_speaker.",
479
+ "description": "A saved speaker's id: id in list_speakers, or speakerId from update_speaker with save.",
541
480
  "examples": [
542
481
  "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
543
482
  ],
@@ -561,7 +500,7 @@
561
500
  {
562
501
  "name": "list_broadcasts",
563
502
  "title": "List broadcasts",
564
- "description": "List this account's broadcasts, or get one in detail. A broadcast is a public link where listeners follow a live transcription in their own language.\nUse: to find a broadcastId for start_broadcast, stop_broadcast or delete_broadcast, see which are on air, or (with broadcastId) a broadcast's recorded transcriptions and streams. Text: get_transcription; they also appear in list_transcriptions.\nBehaviour: free; most recently updated first, up to 500 per lifecycle, no paging.\nReturns: broadcasts (broadcastId, name, link, access, onAir, listenersNow, lastRecordedAt once it has recorded, archived for one in the trash; while on air transcriptionId, state, onAirSince). With broadcastId, one item that adds transcriptions (up to 20: transcriptionId, name, recording, lastRecordedAt) and streams (name, url). None: an empty list.\nErrors: not_found for an unknown broadcastId.",
503
+ "description": "List this account's broadcasts, or get one in detail. A broadcast is a public link where listeners follow a live transcription in their own language.\nUse: to find a broadcastId for start_broadcast, stop_broadcast or delete_broadcast, see which are on air, or (with broadcastId) a broadcast's recorded transcriptions and streams. Text: get_transcription; they also appear in list_transcriptions.\nBehaviour: free; most recently updated first, up to 500 per lifecycle, no paging; rate_limited (with retryAfterS) past 600 calls a minute per API key.\nReturns: broadcasts (broadcastId, name, link, access, onAir, listenersNow, lastRecordedAt once it has recorded, archived for one in the trash; while on air transcriptionId, state, onAirSince). With broadcastId, one item that adds transcriptions (up to 20: transcriptionId, name, recording, lastRecordedAt) and streams (name, url). None: an empty list.\nErrors: not_found for an unknown broadcastId.",
565
504
  "inputSchema": {
566
505
  "additionalProperties": false,
567
506
  "properties": {
@@ -596,7 +535,7 @@
596
535
  {
597
536
  "name": "start_broadcast",
598
537
  "title": "Start a broadcast",
599
- "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. idempotencyKey: any string you choose, reused only to retry this same call.\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. It runs until stop_broadcast or the stream ends.\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: each call starts a new run unless it repeats an idempotencyKey; omitting broadcastId makes a new broadcast with a new link.\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.",
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.",
600
539
  "inputSchema": {
601
540
  "additionalProperties": false,
602
541
  "properties": {
@@ -660,10 +599,92 @@
660
599
  "openWorldHint": true
661
600
  }
662
601
  },
602
+ {
603
+ "name": "update_broadcast",
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.",
606
+ "inputSchema": {
607
+ "additionalProperties": false,
608
+ "properties": {
609
+ "access": {
610
+ "description": "public: anyone with the link can follow it; private: listeners must enter password. Changing it signs out every current listener.",
611
+ "enum": [
612
+ "public",
613
+ "private"
614
+ ]
615
+ },
616
+ "broadcastId": {
617
+ "description": "A broadcastId from list_broadcasts or start_broadcast.",
618
+ "examples": [
619
+ "0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
620
+ ],
621
+ "format": "uuid",
622
+ "type": "string"
623
+ },
624
+ "clonedVoices": {
625
+ "description": "With spokenTranslations: true reads each speaker's translated words in that speaker's own cloned voice (needs consent true); false: stock voices.",
626
+ "type": "boolean"
627
+ },
628
+ "consent": {
629
+ "default": false,
630
+ "description": "Must be true with clonedVoices true: confirms everyone speaking on it agreed to have their voice cloned. Recorded with your account and the time. Not needed to turn cloned voices off.",
631
+ "type": "boolean"
632
+ },
633
+ "name": {
634
+ "description": "New name shown to listeners; trimmed, 1 to 120 characters.",
635
+ "examples": [
636
+ "Sunday service"
637
+ ],
638
+ "maxLength": 120,
639
+ "minLength": 1,
640
+ "type": "string"
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"
650
+ },
651
+ "restore": {
652
+ "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.",
653
+ "examples": [
654
+ true
655
+ ],
656
+ "type": "boolean"
657
+ },
658
+ "spokenLanguage": {
659
+ "description": "Code of the language spoken (e.g. en, es), or auto to detect it. Applies from the next start_broadcast.",
660
+ "examples": [
661
+ "en",
662
+ "auto"
663
+ ],
664
+ "type": "string"
665
+ },
666
+ "spokenTranslations": {
667
+ "description": "true: each translation is also read aloud, so listeners can hear it in their language; false: text only. Applies from the next start_broadcast. Listening stays free.",
668
+ "type": "boolean"
669
+ }
670
+ },
671
+ "required": [
672
+ "broadcastId"
673
+ ],
674
+ "type": "object"
675
+ },
676
+ "annotations": {
677
+ "title": "Update a broadcast",
678
+ "readOnlyHint": false,
679
+ "destructiveHint": false,
680
+ "idempotentHint": true,
681
+ "openWorldHint": false
682
+ }
683
+ },
663
684
  {
664
685
  "name": "stop_broadcast",
665
686
  "title": "Stop a broadcast",
666
- "description": "Stop the live transcription a broadcast is running, which also stops its billing.\nUse: when the event is over. To remove the transcript afterwards: delete_transcription; the broadcast and its link: delete_broadcast.\nArguments: broadcastId of a broadcast on air: from start_broadcast's result, or list_broadcasts (onAir true); not the transcriptionId. A second call is refused with invalid_state and changes nothing, so a retry is safe.\nBehaviour: free. The transcript is kept (get_transcription and get_summary work on it once state is done); the broadcastId and its link stay, ready for the next start_broadcast.\nReturns: the stopped transcription's status (transcriptionId, name, kind live, state finishing then done, startedAt, endedAt, durationS) with broadcastId and link.\nErrors: invalid_state when not on air, not_found for an unknown broadcastId, forbidden for a key without the recordings:publish scope.",
687
+ "description": "Stop the live transcription a broadcast is running, which also stops its billing.\nUse: when the event is over. To remove the transcript afterwards: delete_transcription; the broadcast and its link: delete_broadcast.\nArguments: broadcastId of a broadcast on air: from start_broadcast's result, or list_broadcasts (onAir true); not the transcriptionId. A second call is refused with invalid_state and changes nothing, so a retry is safe.\nBehaviour: free. The transcript is kept (get_transcription reads it, and its summary, once state is done); the broadcastId and its link stay, ready for the next start_broadcast.\nReturns: the stopped transcription's status (transcriptionId, name, kind live, state finishing then done, startedAt, endedAt, durationS) with broadcastId and link.\nErrors: invalid_state when not on air, not_found for an unknown broadcastId, forbidden for a key without the recordings:publish scope.",
667
688
  "inputSchema": {
668
689
  "additionalProperties": false,
669
690
  "properties": {
@@ -692,7 +713,7 @@
692
713
  {
693
714
  "name": "delete_broadcast",
694
715
  "title": "Delete a broadcast",
695
- "description": "Move a broadcast to the trash: its public link and stream addresses stop working for listeners.\nUse: a broadcast that will not run again. For 30 days it can be restored from the trash in the VocalStack Dashboard (list_broadcasts with lifecycle archived lists it); after that the broadcast is erased for good. Ending a live run: stop_broadcast.\nArguments: broadcastId from list_broadcasts or start_broadcast; not a transcriptionId.\nBehaviour: free. A broadcast on air is refused: stop it first (stop_broadcast). The transcriptions it recorded are not deleted: while it is in the trash they leave list_transcriptions with it, get_transcription still reads them by id, and delete_transcription deletes one. Deleting again changes nothing.\nReturns: broadcastId, name, deleted true, deletedAt, restorableUntil.\nErrors: invalid_state while on air; not_found for an unknown broadcastId; forbidden for a read-only key.",
716
+ "description": "Move a broadcast to the trash: its public link and stream addresses stop working for listeners.\nUse: a broadcast that will not run again. For 30 days update_broadcast with restore true brings it back with the same link (list_broadcasts with lifecycle archived lists the trash); after that the broadcast is erased for good. Ending a live run: stop_broadcast.\nArguments: broadcastId, a 36-character UUID (8-4-4-4-12 hex digits) from list_broadcasts or start_broadcast; not a transcriptionId (delete_transcription removes its recordings) and not the short code in its link, both of which are 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 every connected listener is signed out and its link and stream addresses answer not found. A broadcast on air is refused: stop it first (stop_broadcast). The transcriptions it recorded are not deleted: while it is in the trash they leave list_transcriptions and search_transcriptions with it, get_transcription still reads them by id, and delete_transcription deletes one. Restoring brings back the same link and its transcriptions.\nReturns: broadcastId, name, deleted true, deletedAt, restorableUntil.\nErrors: invalid_state while on air; not_found for an unknown broadcastId; forbidden for a read-only key.",
696
717
  "inputSchema": {
697
718
  "additionalProperties": false,
698
719
  "properties": {
@@ -717,6 +738,23 @@
717
738
  "idempotentHint": true,
718
739
  "openWorldHint": false
719
740
  }
741
+ },
742
+ {
743
+ "name": "get_account",
744
+ "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.",
746
+ "inputSchema": {
747
+ "additionalProperties": false,
748
+ "properties": {},
749
+ "type": "object"
750
+ },
751
+ "annotations": {
752
+ "title": "Check credit and usage",
753
+ "readOnlyHint": true,
754
+ "destructiveHint": false,
755
+ "idempotentHint": true,
756
+ "openWorldHint": false
757
+ }
720
758
  }
721
759
  ]
722
760
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vocalstack/mcp",
3
- "version": "1.4.0",
3
+ "version": "1.5.2",
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",