get-transcript6.94 KB
View saved version →
---
name: get-transcript
description: "Retrieve a finished transcription from transcribe.so: chapters, sections, cited Q&A, speaker-labelled timestamped segments, word-level timings, subtitle files (SRT/VTT/karaoke), paste-ready timestamps, hosted captioned MP4 clips, and live cited Q&A over one transcription or the whole library. Use when the user asks for a transcript, subtitles, show notes, quotes, clips, or answers grounded in their recordings."
---
# Get a transcript and derived artifacts
All tools below live on the bundled `transcribe-so` MCP server. They work for
jobs submitted from this plugin, the REST API, or the transcribe.so web app:
same library everywhere.
## Reading results
- `getTranscriptionResult`: the main read. `include` defaults to
`chapters,sections,qna`; add `segments` (speaker-labelled
`{start_seconds, end_seconds, speaker, text}`), `acts`, `posting_chapters`,
or `all`. There is no single full-text field: join segments (or sections).
- `waitForTranscription`: long-poll a running job (~90 s per call;
`_timed_out: true` = call again).
- `search`: keyword search over titles and transcript text across the
user's library; `fetch`: one transcription as plain text.
- `searchSegments`: "who said X, and when": each hit is the SEGMENT, with its
own speaker label, `start_ms`/`end_ms` and a deep-link `url`. Speaker labels
are recording-local and `null` means unknown; never attribute a `null` line.
- `getTranscript`: the transcript as one text body (`txt` or `md`), built
from every segment; the source is never capped. The inline `content` is cut
at this tool's response budget: when `truncated` is true it is a prefix and
only `download_url` is complete. Use this for full text, not a windowed
`segments` read.
- `getTranscriptionTimestamps`: paste-ready chapter timestamps (formats:
youtube, spotify, apple_podcasts, markdown, x, threads, instagram_caption,
linkedin, plain; variants: standard, highlights, clips, quoted_sections,
show_notes, original). `cta` is opt-in and off by default. `not_ready` with
`reason: "artifact_missing"` is fixed by ONE `regeneratePostingChapters`
call.
- `getTranscriptionWords`: paginated word-level timings in ms (limit up to
2000/page; check `available`; `no_word_timestamps` means sentence-level
only). For karaoke captions and overlays, not for reading.
- `getSubtitles`: SRT / VTT / karaoke VTT / JSON subtitle file (`content`
inline up to 60k chars, `download_url` beyond; presets: youtube,
tiktok-shorts, instagram-reels, netflix, podcast, broadcast).
## Clips
- `getClipQuote`: preview before rendering. Pass `transcription_id`,
`start_seconds` and `end_seconds`; it renders nothing and writes nothing,
and returns `charge_usd` (what `renderClip` would use from the user's
existing transcribe.so account for that range) plus the normalized range and
`clip_seconds`. It runs the same range checks as `renderClip`, so it doubles
as a dry run. It takes the same options as `renderClip`, and the figure
does not depend on the output or style. It does not check what the account
can cover or how many clips are already rendering; `renderClip` enforces
those when it runs.
- `renderClip`: hosted clip of a 1-60 s range (up to 180 s where enabled) of
a completed transcription with word timestamps. `output`: `audiogram`
(default: MP4 with captions over a generated background), `video` (the
source video with captions burned in) or `audio` (M4A, no captions).
Video needs the source video: for a link source pass `rights_affirmed:
true` only after the user confirms they own the video or may reuse it (else
`invalid_request` with `error.reason: rights_required`); for an upload, the
original video must first be added in the web app. `video_unavailable`
means video cannot be made for this transcription: offer the audiogram,
which still works. `style`, `caption_position`, `words_per_line`,
`highlight_color` and `framing` tune the result; an Preview of the first 4,000 characters. Read full instructions →
transcribe-audio4.82 KB
View saved version →
---
name: transcribe-audio
description: Transcribe audio or video from a YouTube URL, platform URL (Apple Podcasts, SoundCloud, Vimeo, Twitch, Loom, public TikTok, X and Facebook video posts), direct file URL, or local file upload into speaker-labelled, timestamped segments with chapters, sections, and cited Q&A. Use when the user wants a transcript, show notes, chapters, or analysis of any recording.
---
# Transcribe audio or video
The bundled `transcribe-so` MCP server turns recordings into speaker-labelled,
timestamped transcripts with automatic chapters, sections, and cited Q&A.
## Sources
- `youtube`: a YouTube video URL
- `platform_url`: a public page URL on a supported platform (Apple Podcasts,
SoundCloud, Vimeo, Twitch, Loom and similar, plus public TikTok, X and
Facebook video posts)
- `external_url`: a direct http(s) link to an audio or video file
- `upload`: a local file (shell agents only): call `createUpload` for a presigned PUT URL
(15 minute TTL), PUT the bytes, then pass the returned `upload_id` together
with `duration_seconds`
## Flow
1. Preview before creating a job: call `getQuote` first. It starts nothing;
it returns the length, the detected title and what the job would use from
the user's existing transcribe.so account (`retail_usd`, 0 when the account
already includes it). When `retail_usd` is 0, or within a limit the user
already gave, go ahead; otherwise tell the user the figure and wait for a
go-ahead. Pass the figure the user agreed to as `max_charge_usd` to
`transcribe`; the server enforces it: if the real figure is higher the call
is refused with `max_charge_exceeded` and nothing is started. Report the
refused figure and ask; do not raise the ceiling yourself.
2. Call `transcribe` with the source. It returns `id` immediately; jobs are
asynchronous.
3. For short recordings, long-poll with `waitForTranscription` (each call
covers ~90 s; `_timed_out: true` means still processing; call it again,
this is the expected loop, not an error). For long recordings, hand the
user the dashboard link (https://transcribe.so/transcriptions); they also
get a completion email.
4. Retries: pass `idempotency_key`; without one `transcribe` is not idempotent
(check `listTranscriptions` before retrying a timed-out call). Keep the
SAME key unless one of the NEW-key cases below applies:
- SAME key: a retry with the same arguments replays the first result.
After `queue_full` or a server error (neither is stored under the key),
wait `retry_after` seconds first. If reading the source took longer than
45 seconds, retry the same key once; if that is refused the same way,
stop and tell the user (for `external_url`, pass `duration_seconds` if
you know the length). On `not_ready` saying the earlier call is already
in flight, it is still running and the server ends its preview within
45 seconds: keep retrying the same key. A `not_ready` saying the earlier
request just completed with an error recorded nothing: retry, same key.
- `not_ready` with `stale: true` (no result recorded after 120 seconds):
check `listTranscriptions` for the `client_reference` you sent. A job
there in ANY status counts as found, so do not create another; if it is
still `quoted` (not started yet), tell the user. Only if none is listed
use a new key. If you sent no `client_reference`, do not switch keys on
your own: tell the user.
- NEW key: refusals are replayed under the key for 24 hours too, so a new
key is needed only after a refusal you actually received that says
nothing was started, once its cause is fixed (for example
`insufficient_funds` or `max_charge_exceeded` after the user resolved
it, or a corrected input), or in the `stale` case above. Changed
arguments after such a refusal are a new request and take the new key.
- Key rejected because the arguments differ, and you never got an answer
Preview of the first 4,000 characters. Read full instructions →
