@vocalstack/mcp 1.5.0 → 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 +6 -6
- package/dist/api.js +1 -1
- package/dist/handlers.js +147 -37
- package/dist/tools.json +63 -85
- package/package.json +1 -1
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
|
|
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
|
-
- `update_transcription`: Change a transcription: its name, its public share link, its summary,
|
|
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.
|
|
69
69
|
- `delete_transcription`: Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.
|
|
70
70
|
- `list_speakers`: List the speakers this account has saved: people recognised by name in every new transcription.
|
|
71
|
-
- `
|
|
72
|
-
- `update_speaker`: Change a speaker: name one person in one transcription (instead of "Speaker N"), or rename a saved speaker and switch their cloned voice on or off, everywhere they are recognised.
|
|
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.
|
|
73
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.
|
|
74
73
|
- `list_broadcasts`: List this account's broadcasts, or get one in detail.
|
|
75
|
-
- `start_broadcast`: Start live transcription and translation of a stream playing now, on a public link listeners open in their own language.
|
|
76
|
-
- `update_broadcast`: Change a broadcast's settings: its name, who can listen (public, or private
|
|
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.
|
|
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/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;
|
|
@@ -701,14 +720,10 @@ async function speakers(_a, ctx) {
|
|
|
701
720
|
function noSpeaker(number) {
|
|
702
721
|
return new ToolError("not_found", `This transcription has no Speaker ${number} who has spoken; get_transcription shows the speaker numbers.`);
|
|
703
722
|
}
|
|
704
|
-
async function saveSpeaker(
|
|
705
|
-
const
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
if ([...name].length > 60)
|
|
709
|
-
throw bad("`name` must be 1 to 60 characters");
|
|
710
|
-
const consent = a.bool("consent");
|
|
711
|
-
await transcription(ctx, id);
|
|
723
|
+
async function saveSpeaker(ctx, id, number, name, consent) {
|
|
724
|
+
const n = [...name].length;
|
|
725
|
+
if (n === 0 || n > 60)
|
|
726
|
+
throw bad("with `save`, `name` must be 1 to 60 characters");
|
|
712
727
|
const snap = await snapshot(ctx, id);
|
|
713
728
|
const spoken = spokenSegments(snap).filter((l) => l.speaker >= 0);
|
|
714
729
|
const numbers = numbering(spoken, snap);
|
|
@@ -719,6 +734,17 @@ async function saveSpeaker(a, ctx) {
|
|
|
719
734
|
.sort((x, y) => x - y)[0];
|
|
720
735
|
if (appearance === undefined)
|
|
721
736
|
throw noSpeaker(number);
|
|
737
|
+
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());
|
|
738
|
+
if (known) {
|
|
739
|
+
let s = known;
|
|
740
|
+
if (consent && s.consent !== "granted") {
|
|
741
|
+
s = (await ctx.api.request("POST", path("/v1/speakers/", s.id, "/consent"), { json: { consent: "granted" }, signal: ctx.signal })).data;
|
|
742
|
+
}
|
|
743
|
+
const out = { speakerId: s.id, saved: false, consent: s.consent, cloned: s.voice != null };
|
|
744
|
+
if (s.voice)
|
|
745
|
+
put(out, "voiceState", s.voice.state);
|
|
746
|
+
return out;
|
|
747
|
+
}
|
|
722
748
|
let s;
|
|
723
749
|
try {
|
|
724
750
|
s = (await ctx.api.request("POST", "/v1/speakers/from-appearance", {
|
|
@@ -731,11 +757,32 @@ async function saveSpeaker(a, ctx) {
|
|
|
731
757
|
throw noSpeaker(number);
|
|
732
758
|
throw e;
|
|
733
759
|
}
|
|
734
|
-
const out = { speakerId: s.id,
|
|
760
|
+
const out = { speakerId: s.id, saved: true, consent: s.consent, cloned: s.voice != null };
|
|
735
761
|
if (s.voice)
|
|
736
762
|
put(out, "voiceState", s.voice.state);
|
|
737
763
|
return out;
|
|
738
764
|
}
|
|
765
|
+
async function getAccount(_a, ctx) {
|
|
766
|
+
const b = await ctx.api.get("/v1/billing", {}, ctx.signal);
|
|
767
|
+
const l = b.limitsUsage ?? {};
|
|
768
|
+
const out = {
|
|
769
|
+
billingEnabled: b.enabled ?? null,
|
|
770
|
+
plan: b.plan ?? null,
|
|
771
|
+
balance: b.balance ?? null,
|
|
772
|
+
canStart: b.canStart ?? null,
|
|
773
|
+
startBlock: b.startBlock ?? null,
|
|
774
|
+
canStartLive: b.canStartLive ?? null,
|
|
775
|
+
startBlockLive: b.startBlockLive ?? null,
|
|
776
|
+
running: l.running ?? null,
|
|
777
|
+
concurrentLimit: l.concurrentLimit ?? null,
|
|
778
|
+
createdLastHour: l.createdLastHour ?? null,
|
|
779
|
+
createLimit: l.createLimit ?? null,
|
|
780
|
+
period: b.period ?? null,
|
|
781
|
+
topUpUrl: b.topUpUrl ?? null,
|
|
782
|
+
};
|
|
783
|
+
put(out, "monthlyCredit", b.monthlyCredit);
|
|
784
|
+
return out;
|
|
785
|
+
}
|
|
739
786
|
async function deleteSpeaker(a, ctx) {
|
|
740
787
|
const id = a.id("speakerId");
|
|
741
788
|
try {
|
|
@@ -870,6 +917,8 @@ async function patchSpeaker(ctx, id, body) {
|
|
|
870
917
|
}
|
|
871
918
|
async function updateSavedSpeaker(a, ctx) {
|
|
872
919
|
const id = a.id("speakerId");
|
|
920
|
+
if (present(a, "save"))
|
|
921
|
+
throw bad("`save` is for a speaker in one transcription (transcriptionId with speaker); this one is already saved");
|
|
873
922
|
let name;
|
|
874
923
|
const given = a.raw.name;
|
|
875
924
|
if (given !== undefined && given !== null) {
|
|
@@ -908,7 +957,7 @@ async function updateSavedSpeaker(a, ctx) {
|
|
|
908
957
|
}
|
|
909
958
|
const cur = await savedSpeaker(ctx, id);
|
|
910
959
|
if (cloned === true && cur.consent === "refused") {
|
|
911
|
-
throw new ToolError("invalid_state", "This speaker refused to be cloned and their audio was deleted; save them again from a transcription (
|
|
960
|
+
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.");
|
|
912
961
|
}
|
|
913
962
|
if (name !== undefined)
|
|
914
963
|
await patchSpeaker(ctx, id, { name });
|
|
@@ -919,7 +968,7 @@ async function updateSavedSpeaker(a, ctx) {
|
|
|
919
968
|
}
|
|
920
969
|
catch (e) {
|
|
921
970
|
if (e instanceof ToolError && e.code === "invalid_state" && e.message.includes("no sample stored")) {
|
|
922
|
-
throw new ToolError("invalid_state", "This saved speaker has no stored sample to clone their voice from; save them again from a transcription (
|
|
971
|
+
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).");
|
|
923
972
|
}
|
|
924
973
|
noSavedSpeaker(e);
|
|
925
974
|
}
|
|
@@ -937,6 +986,11 @@ async function updateSpeaker(a, ctx) {
|
|
|
937
986
|
if (present(a, "clonedVoice")) {
|
|
938
987
|
throw bad("`clonedVoice` is for a saved speaker (speakerId); for everyone in one transcription use update_transcription with clonedVoices");
|
|
939
988
|
}
|
|
989
|
+
const save = optBool(a, "save") ?? false;
|
|
990
|
+
const consent = a.bool("consent");
|
|
991
|
+
if (consent && !save) {
|
|
992
|
+
throw bad("`consent` with `transcriptionId` goes with `save: true` (saving and cloning this person); to clone a saved speaker use `speakerId` with `clonedVoice`");
|
|
993
|
+
}
|
|
940
994
|
const id = a.id("transcriptionId");
|
|
941
995
|
const number = a.int("speaker", 1, 1, 1000);
|
|
942
996
|
const given = a.raw.name;
|
|
@@ -945,7 +999,11 @@ async function updateSpeaker(a, ctx) {
|
|
|
945
999
|
if (typeof given !== "string")
|
|
946
1000
|
throw bad('`name` must be a string ("" clears the name)');
|
|
947
1001
|
const name = [...given.trim()].slice(0, 80).join("");
|
|
1002
|
+
if (save && (name.length === 0 || [...given.trim()].length > 60))
|
|
1003
|
+
throw bad("`name` must be 1 to 60 characters");
|
|
948
1004
|
await transcription(ctx, id);
|
|
1005
|
+
if (save)
|
|
1006
|
+
return { transcriptionId: id, speaker: number, name, ...(await saveSpeaker(ctx, id, number, given.trim(), consent)) };
|
|
949
1007
|
try {
|
|
950
1008
|
await ctx.api.request("PUT", path("/v1/transcriptions/", id, "/appearances/", String(number)), {
|
|
951
1009
|
json: { name: name || null },
|
|
@@ -977,19 +1035,26 @@ async function updateTranscription(a, ctx) {
|
|
|
977
1035
|
throw bad("`name` must be 1 to 200 characters");
|
|
978
1036
|
}
|
|
979
1037
|
const share = optBool(a, "shareLink");
|
|
1038
|
+
const restore = optBool(a, "restore");
|
|
1039
|
+
if (restore === false)
|
|
1040
|
+
throw bad("`restore` takes only true (bring it back from the trash); delete_transcription moves it there");
|
|
980
1041
|
const summary = optBool(a, "summary");
|
|
981
1042
|
const cloned = optBool(a, "clonedVoices");
|
|
982
1043
|
const consent = a.bool("consent");
|
|
983
1044
|
if (summary === false)
|
|
984
1045
|
throw bad("`summary` takes only true (write one now); a summary is never deleted");
|
|
985
|
-
if (name === undefined && share === undefined && summary === undefined && cloned === undefined) {
|
|
986
|
-
throw bad("give at least one of `name`, `shareLink`, `summary` or `
|
|
1046
|
+
if (name === undefined && share === undefined && summary === undefined && cloned === undefined && restore === undefined) {
|
|
1047
|
+
throw bad("give at least one of `name`, `shareLink`, `summary`, `clonedVoices` or `restore` to change");
|
|
987
1048
|
}
|
|
988
1049
|
if (cloned === true && !consent)
|
|
989
1050
|
throw bad(NEEDS_CONSENT);
|
|
990
1051
|
let t = await transcription(ctx, id);
|
|
991
|
-
|
|
992
|
-
|
|
1052
|
+
const restored = restore === true && t.lifecycle === "archived";
|
|
1053
|
+
if (restored) {
|
|
1054
|
+
t = (await ctx.api.request("POST", path("/v1/transcriptions/", id, "/restore"), { signal: ctx.signal })).data;
|
|
1055
|
+
}
|
|
1056
|
+
else if (t.lifecycle && t.lifecycle !== "active") {
|
|
1057
|
+
throw new ToolError("invalid_state", "This transcription is in the trash; pass restore: true to bring it back.");
|
|
993
1058
|
}
|
|
994
1059
|
const written = summary === true ? await writeSummary(ctx, id, t) : undefined;
|
|
995
1060
|
if (name !== undefined || cloned !== undefined) {
|
|
@@ -1016,6 +1081,8 @@ async function updateTranscription(a, ctx) {
|
|
|
1016
1081
|
links = [];
|
|
1017
1082
|
}
|
|
1018
1083
|
const out = { transcriptionId: t.id, name: t.name, shareUrl: links[0]?.url ?? null, clonedVoices: t.settings?.voiceCloning === true };
|
|
1084
|
+
if (restore !== undefined)
|
|
1085
|
+
out.restored = restored;
|
|
1019
1086
|
if (written)
|
|
1020
1087
|
out.summary = written;
|
|
1021
1088
|
return out;
|
|
@@ -1024,24 +1091,41 @@ async function updateBroadcast(a, ctx) {
|
|
|
1024
1091
|
const id = a.id("broadcastId");
|
|
1025
1092
|
const name = a.str("name");
|
|
1026
1093
|
const access = a.raw.access === undefined || a.raw.access === null ? undefined : a.oneOf("access", ["public", "private"], "public");
|
|
1027
|
-
const
|
|
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");
|
|
1028
1097
|
const spokenRaw = a.str("spokenLanguage");
|
|
1029
1098
|
const speak = optBool(a, "spokenTranslations");
|
|
1030
1099
|
const cloned = optBool(a, "clonedVoices");
|
|
1031
1100
|
const consent = a.bool("consent");
|
|
1032
|
-
|
|
1033
|
-
|
|
1101
|
+
const restore = optBool(a, "restore");
|
|
1102
|
+
if (restore === false)
|
|
1103
|
+
throw bad("`restore` takes only true (bring it back from the trash); delete_broadcast moves it there");
|
|
1104
|
+
const changes = [name, access, newCode, spokenRaw, speak, cloned].some((v) => v !== undefined);
|
|
1105
|
+
if (!changes && restore === undefined) {
|
|
1106
|
+
throw bad("give at least one of `name`, `access`, `newListenerCode`, `spokenLanguage`, `spokenTranslations`, `clonedVoices` or `restore` to change");
|
|
1034
1107
|
}
|
|
1035
1108
|
if (cloned === true && !consent)
|
|
1036
1109
|
throw bad(NEEDS_CONSENT);
|
|
1037
|
-
await broadcast(ctx, id);
|
|
1110
|
+
let b = await broadcast(ctx, id);
|
|
1111
|
+
const restored = restore === true && b.lifecycle === "archived";
|
|
1112
|
+
if (restored)
|
|
1113
|
+
b = (await ctx.api.request("POST", path("/v1/broadcasts/", id, "/restore"), { signal: ctx.signal })).data;
|
|
1038
1114
|
const body = {};
|
|
1039
1115
|
if (name !== undefined)
|
|
1040
1116
|
body.name = name;
|
|
1041
1117
|
if (access !== undefined)
|
|
1042
1118
|
body.access = access;
|
|
1043
|
-
|
|
1044
|
-
|
|
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;
|
|
1045
1129
|
const settings = {};
|
|
1046
1130
|
if (spokenRaw !== undefined) {
|
|
1047
1131
|
const l = spokenRaw.trim().toLowerCase();
|
|
@@ -1055,29 +1139,55 @@ async function updateBroadcast(a, ctx) {
|
|
|
1055
1139
|
}
|
|
1056
1140
|
if (Object.keys(settings).length)
|
|
1057
1141
|
body.settings = settings;
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1142
|
+
if (changes)
|
|
1143
|
+
try {
|
|
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
|
+
}
|
|
1065
1154
|
}
|
|
1066
|
-
|
|
1067
|
-
|
|
1155
|
+
catch (e) {
|
|
1156
|
+
if (e instanceof ToolError && e.code === "invalid_state") {
|
|
1157
|
+
throw new ToolError("invalid_state", "This broadcast is in the trash; pass restore: true to bring it back.");
|
|
1158
|
+
}
|
|
1159
|
+
consentError(e);
|
|
1068
1160
|
}
|
|
1069
|
-
consentError(e);
|
|
1070
|
-
}
|
|
1071
1161
|
return {
|
|
1072
1162
|
...brief(b),
|
|
1163
|
+
...(made !== undefined ? { listenerCode: made } : {}),
|
|
1073
1164
|
spokenLanguage: b.settings?.spokenLanguage ?? "auto",
|
|
1074
1165
|
spokenTranslations: b.settings?.translationTts === true,
|
|
1075
1166
|
clonedVoices: b.settings?.voiceCloning === true,
|
|
1167
|
+
...(restore !== undefined ? { restored } : {}),
|
|
1076
1168
|
};
|
|
1077
1169
|
}
|
|
1078
1170
|
const ON_AIR = "This broadcast is already on air; stop it first (stop_broadcast) or use another broadcast.";
|
|
1079
1171
|
async function startBroadcast(a, ctx) {
|
|
1080
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
|
+
}
|
|
1081
1191
|
const url = streamUrl(a);
|
|
1082
1192
|
const spoken = a.str("spokenLanguage")?.toLowerCase();
|
|
1083
1193
|
const speak = a.bool("spokenTranslations");
|
|
@@ -1191,7 +1301,6 @@ export const handlers = {
|
|
|
1191
1301
|
update_transcription: updateTranscription,
|
|
1192
1302
|
delete_transcription: deleteTranscription,
|
|
1193
1303
|
list_speakers: speakers,
|
|
1194
|
-
save_speaker: saveSpeaker,
|
|
1195
1304
|
update_speaker: updateSpeaker,
|
|
1196
1305
|
delete_speaker: deleteSpeaker,
|
|
1197
1306
|
list_broadcasts: listBroadcasts,
|
|
@@ -1199,4 +1308,5 @@ export const handlers = {
|
|
|
1199
1308
|
update_broadcast: updateBroadcast,
|
|
1200
1309
|
stop_broadcast: stopBroadcast,
|
|
1201
1310
|
delete_broadcast: deleteBroadcast,
|
|
1311
|
+
get_account: getAccount,
|
|
1202
1312
|
};
|
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_transcription with format summary for its title and summary; update_transcription (name, share link, summary, cloned voices); delete_transcription (to the trash
|
|
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": {
|
|
@@ -111,17 +111,20 @@
|
|
|
111
111
|
{
|
|
112
112
|
"name": "get_transcription",
|
|
113
113
|
"title": "Read a transcription",
|
|
114
|
-
"description": "Read one transcription
|
|
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
|
|
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
|
},
|
|
@@ -192,7 +195,7 @@
|
|
|
192
195
|
{
|
|
193
196
|
"name": "list_transcriptions",
|
|
194
197
|
"title": "List transcriptions",
|
|
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. lifecycle archived lists the trash: deleted transcriptions,
|
|
198
|
+
"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.",
|
|
196
199
|
"inputSchema": {
|
|
197
200
|
"additionalProperties": false,
|
|
198
201
|
"properties": {
|
|
@@ -233,7 +236,7 @@
|
|
|
233
236
|
{
|
|
234
237
|
"name": "search_transcriptions",
|
|
235
238
|
"title": "Search transcriptions",
|
|
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.\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.",
|
|
239
|
+
"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.",
|
|
237
240
|
"inputSchema": {
|
|
238
241
|
"additionalProperties": false,
|
|
239
242
|
"properties": {
|
|
@@ -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,
|
|
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": {
|
|
@@ -320,6 +323,13 @@
|
|
|
320
323
|
"minLength": 1,
|
|
321
324
|
"type": "string"
|
|
322
325
|
},
|
|
326
|
+
"restore": {
|
|
327
|
+
"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.",
|
|
328
|
+
"examples": [
|
|
329
|
+
true
|
|
330
|
+
],
|
|
331
|
+
"type": "boolean"
|
|
332
|
+
},
|
|
323
333
|
"shareLink": {
|
|
324
334
|
"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.",
|
|
325
335
|
"type": "boolean"
|
|
@@ -353,7 +363,7 @@
|
|
|
353
363
|
{
|
|
354
364
|
"name": "delete_transcription",
|
|
355
365
|
"title": "Delete a transcription",
|
|
356
|
-
"description": "Move a transcription to the trash, with its recordings, transcript, translations and summary; its share links stop working.\nUse: to remove one
|
|
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.",
|
|
357
367
|
"inputSchema": {
|
|
358
368
|
"additionalProperties": false,
|
|
359
369
|
"properties": {
|
|
@@ -382,7 +392,7 @@
|
|
|
382
392
|
{
|
|
383
393
|
"name": "list_speakers",
|
|
384
394
|
"title": "List saved speakers",
|
|
385
|
-
"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
|
|
395
|
+
"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.",
|
|
386
396
|
"inputSchema": {
|
|
387
397
|
"additionalProperties": false,
|
|
388
398
|
"properties": {},
|
|
@@ -396,63 +406,10 @@
|
|
|
396
406
|
"openWorldHint": false
|
|
397
407
|
}
|
|
398
408
|
},
|
|
399
|
-
{
|
|
400
|
-
"name": "save_speaker",
|
|
401
|
-
"title": "Save a speaker",
|
|
402
|
-
"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: update_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: update_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.",
|
|
403
|
-
"inputSchema": {
|
|
404
|
-
"additionalProperties": false,
|
|
405
|
-
"properties": {
|
|
406
|
-
"consent": {
|
|
407
|
-
"default": false,
|
|
408
|
-
"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.",
|
|
409
|
-
"type": "boolean"
|
|
410
|
-
},
|
|
411
|
-
"name": {
|
|
412
|
-
"description": "The person's name, shown in this and later transcriptions.",
|
|
413
|
-
"examples": [
|
|
414
|
-
"Maria Lopez"
|
|
415
|
-
],
|
|
416
|
-
"maxLength": 60,
|
|
417
|
-
"minLength": 1,
|
|
418
|
-
"type": "string"
|
|
419
|
-
},
|
|
420
|
-
"speaker": {
|
|
421
|
-
"description": "The N of \"Speaker N\" in get_transcription's text, or speakerNumber in its segments. Works while a live transcription is still running.",
|
|
422
|
-
"examples": [
|
|
423
|
-
2
|
|
424
|
-
],
|
|
425
|
-
"minimum": 1,
|
|
426
|
-
"type": "integer"
|
|
427
|
-
},
|
|
428
|
-
"transcriptionId": {
|
|
429
|
-
"description": "A transcriptionId from create_transcription, list_transcriptions, search_transcriptions or start_broadcast.",
|
|
430
|
-
"examples": [
|
|
431
|
-
"0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
|
|
432
|
-
],
|
|
433
|
-
"format": "uuid",
|
|
434
|
-
"type": "string"
|
|
435
|
-
}
|
|
436
|
-
},
|
|
437
|
-
"required": [
|
|
438
|
-
"transcriptionId",
|
|
439
|
-
"speaker",
|
|
440
|
-
"name"
|
|
441
|
-
],
|
|
442
|
-
"type": "object"
|
|
443
|
-
},
|
|
444
|
-
"annotations": {
|
|
445
|
-
"title": "Save a speaker",
|
|
446
|
-
"readOnlyHint": false,
|
|
447
|
-
"destructiveHint": false,
|
|
448
|
-
"idempotentHint": false,
|
|
449
|
-
"openWorldHint": false
|
|
450
|
-
}
|
|
451
|
-
},
|
|
452
409
|
{
|
|
453
410
|
"name": "update_speaker",
|
|
454
|
-
"title": "
|
|
455
|
-
"description": "
|
|
411
|
+
"title": "Name or save a speaker",
|
|
412
|
+
"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.",
|
|
456
413
|
"inputSchema": {
|
|
457
414
|
"additionalProperties": false,
|
|
458
415
|
"properties": {
|
|
@@ -462,11 +419,11 @@
|
|
|
462
419
|
},
|
|
463
420
|
"consent": {
|
|
464
421
|
"default": false,
|
|
465
|
-
"description": "
|
|
422
|
+
"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.",
|
|
466
423
|
"type": "boolean"
|
|
467
424
|
},
|
|
468
425
|
"name": {
|
|
469
|
-
"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. Required with transcriptionId.",
|
|
426
|
+
"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.",
|
|
470
427
|
"examples": [
|
|
471
428
|
"Maria Lopez",
|
|
472
429
|
""
|
|
@@ -474,6 +431,11 @@
|
|
|
474
431
|
"maxLength": 80,
|
|
475
432
|
"type": "string"
|
|
476
433
|
},
|
|
434
|
+
"save": {
|
|
435
|
+
"default": false,
|
|
436
|
+
"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.",
|
|
437
|
+
"type": "boolean"
|
|
438
|
+
},
|
|
477
439
|
"speaker": {
|
|
478
440
|
"description": "With transcriptionId: the N of \"Speaker N\" in get_transcription's text, or speakerNumber in its segments; it stays the same after naming.",
|
|
479
441
|
"examples": [
|
|
@@ -483,7 +445,7 @@
|
|
|
483
445
|
"type": "integer"
|
|
484
446
|
},
|
|
485
447
|
"speakerId": {
|
|
486
|
-
"description": "Instead of transcriptionId and speaker: a saved speaker's id (id in list_speakers, or speakerId from
|
|
448
|
+
"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.",
|
|
487
449
|
"examples": [
|
|
488
450
|
"0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
|
|
489
451
|
],
|
|
@@ -502,7 +464,7 @@
|
|
|
502
464
|
"type": "object"
|
|
503
465
|
},
|
|
504
466
|
"annotations": {
|
|
505
|
-
"title": "
|
|
467
|
+
"title": "Name or save a speaker",
|
|
506
468
|
"readOnlyHint": false,
|
|
507
469
|
"destructiveHint": false,
|
|
508
470
|
"idempotentHint": true,
|
|
@@ -512,12 +474,12 @@
|
|
|
512
474
|
{
|
|
513
475
|
"name": "delete_speaker",
|
|
514
476
|
"title": "Delete a saved speaker",
|
|
515
|
-
"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
|
|
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.",
|
|
516
478
|
"inputSchema": {
|
|
517
479
|
"additionalProperties": false,
|
|
518
480
|
"properties": {
|
|
519
481
|
"speakerId": {
|
|
520
|
-
"description": "A saved speaker's id: id in list_speakers, or speakerId from
|
|
482
|
+
"description": "A saved speaker's id: id in list_speakers, or speakerId from update_speaker with save.",
|
|
521
483
|
"examples": [
|
|
522
484
|
"0190f0e0-7c1a-7d3e-9b2a-5f4e3d2c1b0a"
|
|
523
485
|
],
|
|
@@ -541,7 +503,7 @@
|
|
|
541
503
|
{
|
|
542
504
|
"name": "list_broadcasts",
|
|
543
505
|
"title": "List broadcasts",
|
|
544
|
-
"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.",
|
|
506
|
+
"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.",
|
|
545
507
|
"inputSchema": {
|
|
546
508
|
"additionalProperties": false,
|
|
547
509
|
"properties": {
|
|
@@ -576,7 +538,7 @@
|
|
|
576
538
|
{
|
|
577
539
|
"name": "start_broadcast",
|
|
578
540
|
"title": "Start a broadcast",
|
|
579
|
-
"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
|
|
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.",
|
|
580
542
|
"inputSchema": {
|
|
581
543
|
"additionalProperties": false,
|
|
582
544
|
"properties": {
|
|
@@ -617,7 +579,7 @@
|
|
|
617
579
|
"type": "boolean"
|
|
618
580
|
},
|
|
619
581
|
"streamUrl": {
|
|
620
|
-
"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.",
|
|
621
583
|
"examples": [
|
|
622
584
|
"https://www.youtube.com/watch?v=jfKfPfyJRdk",
|
|
623
585
|
"https://stream.example.org/radio.m3u8"
|
|
@@ -627,9 +589,6 @@
|
|
|
627
589
|
"type": "string"
|
|
628
590
|
}
|
|
629
591
|
},
|
|
630
|
-
"required": [
|
|
631
|
-
"streamUrl"
|
|
632
|
-
],
|
|
633
592
|
"type": "object"
|
|
634
593
|
},
|
|
635
594
|
"annotations": {
|
|
@@ -643,12 +602,12 @@
|
|
|
643
602
|
{
|
|
644
603
|
"name": "update_broadcast",
|
|
645
604
|
"title": "Update a broadcast",
|
|
646
|
-
"description": "Change a broadcast's settings: its name, who can listen (public, or private
|
|
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.",
|
|
647
606
|
"inputSchema": {
|
|
648
607
|
"additionalProperties": false,
|
|
649
608
|
"properties": {
|
|
650
609
|
"access": {
|
|
651
|
-
"description": "public: anyone with the link can follow it; private: listeners must enter
|
|
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.",
|
|
652
611
|
"enum": [
|
|
653
612
|
"public",
|
|
654
613
|
"private"
|
|
@@ -680,14 +639,16 @@
|
|
|
680
639
|
"minLength": 1,
|
|
681
640
|
"type": "string"
|
|
682
641
|
},
|
|
683
|
-
"
|
|
684
|
-
"description": "
|
|
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"
|
|
645
|
+
},
|
|
646
|
+
"restore": {
|
|
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.",
|
|
685
648
|
"examples": [
|
|
686
|
-
|
|
649
|
+
true
|
|
687
650
|
],
|
|
688
|
-
"
|
|
689
|
-
"minLength": 4,
|
|
690
|
-
"type": "string"
|
|
651
|
+
"type": "boolean"
|
|
691
652
|
},
|
|
692
653
|
"spokenLanguage": {
|
|
693
654
|
"description": "Code of the language spoken (e.g. en, es), or auto to detect it. Applies from the next start_broadcast.",
|
|
@@ -747,7 +708,7 @@
|
|
|
747
708
|
{
|
|
748
709
|
"name": "delete_broadcast",
|
|
749
710
|
"title": "Delete a broadcast",
|
|
750
|
-
"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
|
|
711
|
+
"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.",
|
|
751
712
|
"inputSchema": {
|
|
752
713
|
"additionalProperties": false,
|
|
753
714
|
"properties": {
|
|
@@ -772,6 +733,23 @@
|
|
|
772
733
|
"idempotentHint": true,
|
|
773
734
|
"openWorldHint": false
|
|
774
735
|
}
|
|
736
|
+
},
|
|
737
|
+
{
|
|
738
|
+
"name": "get_account",
|
|
739
|
+
"title": "Check credit and usage",
|
|
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.",
|
|
741
|
+
"inputSchema": {
|
|
742
|
+
"additionalProperties": false,
|
|
743
|
+
"properties": {},
|
|
744
|
+
"type": "object"
|
|
745
|
+
},
|
|
746
|
+
"annotations": {
|
|
747
|
+
"title": "Check credit and usage",
|
|
748
|
+
"readOnlyHint": true,
|
|
749
|
+
"destructiveHint": false,
|
|
750
|
+
"idempotentHint": true,
|
|
751
|
+
"openWorldHint": false
|
|
752
|
+
}
|
|
775
753
|
}
|
|
776
754
|
]
|
|
777
755
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vocalstack/mcp",
|
|
3
|
-
"version": "1.5.
|
|
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",
|