Start a transcription job and return its id immediately.

source is either an absolute local path (~ is expanded) or a URL — YouTube, Instagram, TikTok, X, Vimeo, Reddit and anything else yt-dlp supports, plus direct media URLs. Relative paths are refused, and a playlist or channel URL is refused as ambiguous: pass one video.

The call never waits for work. Poll transcript_status, and read partial output with transcript_get while it runs.

captions decides whether to use a platform's existing subtitles instead of transcribing: manual_only (default) takes human-written captions when present, which are usually better than Whisper; prefer also accepts auto-generated ones, which are usually worse; never always transcribes. The result reports origin so you know which you got.

language is an ISO code to force; omit it for automatic detection. force bypasses the cache and re-transcribes.

Sources longer than four hours are refused. Login-walled, private, members-only or age-restricted URLs fail with auth_required — set TRANSCRIPTOR_COOKIES_FROM_BROWSER (chrome, safari, firefox, brave) or TRANSCRIPTOR_COOKIES_FILE in the server's .env and retry.

Inspect a source without transcribing it, and without downloading it.

Says how long it is, whether captions already exist (which would make it near-instant), whether it needs cookies, and whether you have already transcribed it under these exact settings. Pass the same language and captions you would pass to transcript_create, so existing reports what would happen rather than what might.

Where a job stands: status, stage, progress, elapsed and ETA.

status is one of queued, running, paused, done, failed, cancelled, interrupted. resumable says whether retrying helps — do not parse the error message to decide.

Once the job has produced anything, the response also carries download_urls (txt, srt, vtt, json) and view_url — loopback links served by this process. Give them to the user when a job finishes: clicking one downloads the transcript, which is a better answer than pushing thousands of words through the chat.

Present a link as a markdown link inside a sentence, not inside a code block — fenced blocks are not clickable, so the user has to copy and paste. Prefer offering view_url alone: that page already links to all four formats, so one link beats five.

Transcript text, rendered from segments on demand.

format is txt, srt, vtt or json. mode="preview" is the default deliberately: a long transcript returned whole floods the calling agent's context. Use mode="full" when the user has actually asked for the whole transcript — the default exists to stop unprompted flooding, not to refuse a direct request.

The response also carries download_urls and view_url, which are usually the better answer for a long transcript: the user gets a file they can keep, and your context stays free for the work. Offer them as markdown links in a sentence — a URL in a code block cannot be clicked.

Works on a running job — you get what is committed so far, with partial: true.

Find a phrase in a transcript, with timestamps.

The intended way into a long transcript, together with transcript_segments — pulling the whole thing would flood your context. Works on a running job: it searches what has been committed so far. Falls back to fuzzy matching when nothing matches whole words, which is what helps when you half-remember a phrase.

Pull a time window of the transcript.

Segments overlapping the window are returned, not only those contained by it, so a segment straddling the boundary still appears. include_words roughly triples the response size, so it is off by default.

Recent jobs, newest first.

Filter by status (queued, running, paused, done, failed, cancelled, interrupted) for a board-level view of what is in flight, what is stuck and what is finished.

Write a transcript to a file at a path you choose.

The only thing Transcriptor writes to disk, and only on request. dest_path must be absolute. Nothing partial is left behind if the write fails.

The response also carries download_urls and view_url. If the user asked for a link rather than a path, give them those — they are served by this process and need no file at all. Write them as markdown links in a sentence; a URL fenced in a code block has to be copied by hand.

Stop a job.

A queued job stops at once; a running one stops at the next chunk boundary, so allow up to about two minutes. Everything already transcribed survives and the job can be resumed later.

Delete a transcript. Destructive and not reversible.

Removes the job and its segments, chunks, events and cached renders. delete_media=True also removes any scratch audio still on disk. Refuses while the job is running — cancel it first.

Queue every media file in a folder, one job each.

folder must be absolute. Not recursive — recursing would silently pull in a backup directory nobody meant to transcribe. Files already transcribed under these settings come back as reused rather than being queued again. Poll the returned job_ids with transcript_status, or watch the whole set with transcript_list.

Find self-contained, high-density moments worth cutting into clips.

Scored on words per second, but only runs that begin at the start of a sentence and end at the end of one are considered — a moment that opens mid-clause is worthless however dense it is. Selected clips never overlap.

Returns, per clip: the ffmpeg command to cut it, the command to crop it to 9:16, and an SRT rebased to the clip's own clock for burning in. The commands are returned, not run — nothing is written to disk.

Engine state, real memory pressure, queue depth, degraded tasks.

engine and device say what is actually running here — mlx on Metal, or faster-whisper on cuda or cpu. Worth reading before promising a user how long something will take: the same model differs by an order of magnitude between them. On a machine with a discrete GPU the report also carries vram_*; on unified memory those keys are absent, because there the GPU spends the memory system_available_gb already accounts for.

Also reports whether the transcript download viewer is serving. If viewer.available is false, viewer.error says why — usually the port is already taken by another Transcriptor.

Memory numbers come from the monitor task's most recent sample rather than being measured inline, so this stays a database-and-memory read.