Command-line tool (CLI)

Run transcript1 with a YouTube, X, TikTok, Instagram, Facebook or Bluesky link, or a local audio or video file to get its transcript. Additional platforms and their client-version requirements are listed below. See Sources and options for accepted platforms and restrictions. The standalone CLI needs no Node.js.

Use CLI 1.2.0 or newer for social links. CLI 1.1.0 and older accept only YouTube links and reject the new links locally. Run transcript1 update to update.

That version is the baseline for the original six platforms. Twitch, Dailymotion, Pinterest, LinkedIn and Snapchat require a CLI release that includes those platforms; older clients can reject them locally.

Social posts must be public. For posts with several videos, only the first video is transcribed. See Sources and options for accepted short links and limits.

Install

On macOS or Linux (x64 or ARM64):

curl -fsSL https://transcript1.com/install.sh | sh

The installer puts the binary in ~/.local/bin and prints a PATH hint if needed. Set TRANSCRIPT1_INSTALL_DIR to choose another folder.

It also adds t1, a short alias for transcript1. If you use zsh, it adds alias transcript1='noglob transcript1' to ~/.zshrc so links with ? work unquoted; set TRANSCRIPT1_NO_MODIFY_SHELL=1 to skip that.

On Windows x64, open PowerShell:

irm https://transcript1.com/install.ps1 | iex

This installs to %LOCALAPPDATA%\Programs\transcript1, adds t1.cmd as a short alias and adds the folder to your user PATH. Open a new terminal to use it.

Sign in

Run:

transcript1 login

This opens transcript1.com in your browser. Over SSH or without a display, it prints the link instead. Compare the code shown in your terminal with the one on the page, then click Approve. The CLI waits for approval and saves a key named transcript1 CLI (<computer name>). You can find it on the API keys page.

Use transcript1 login --no-browser to print the link without opening a browser.

To paste an existing key, run transcript1 login --with-key. Piped input still works: transcript1 login < key.txt.

For CI and agents, set TRANSCRIPT1_API_KEY; it takes priority over the saved key. An agent without a terminal or a key can run transcript1 login < /dev/null and send you the link to approve.

transcript1 logout revokes the CLI key and removes it from your computer. If revocation fails, it removes the saved key and asks you to revoke it on the API keys page. Pasted keys must be revoked on that page.

Transcribe a link

transcript1 'https://youtu.be/dQw4w9WgXcQ'

The command waits for the transcript and prints text to stdout. It uses usable original-language captions from YouTube, X, TikTok, Bluesky, Dailymotion and LinkedIn when available and AI transcription otherwise. Progress goes to stderr.

Tip: in zsh, quote links. An unquoted & splits the command, and ? is a glob unless you use the alias the installer adds.

Transcribe a file

transcript1 interview.mp3
transcript1 -f srt -o interview.srt interview.mp3

Files can be up to 2 GB (2,000,000,000 bytes). Supported extensions are mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm and mkv. The CLI uploads the file and waits for the transcript.

Batches

Pass several inputs or a folder:

transcript1 interview.mp3 lecture.mp4
transcript1 -o transcripts/ ./recordings
transcript1 --jobs 4 -o transcripts/ interview.mp3 'https://youtu.be/dQw4w9WgXcQ'

File patterns like recordings/*.mp3 work, also on Windows. Folders expand to their top-level media files, sorted by name. Several inputs write one file each to ./transcripts by default. --jobs controls how many inputs run at once: 1–20, with a default of 2.

Use - to read one link or file path per line from stdin. In a shell on macOS or Linux:

transcript1 -o transcripts/ - < inputs.txt

Blank lines and lines starting with # are skipped. Exact duplicate inputs run once.

With one input, -o names an output file, or a folder if it already exists or ends in /. With several inputs, -o names a folder. Missing output folders are created.

YouTube links and local files whose output file already exists are skipped. Add --overwrite to redo them:

transcript1 --overwrite -o transcripts/ ./recordings

Formats and options

For speaker labels with timestamps:

transcript1 --speakers --timestamps --language en interview.mp3

--speakers cannot be combined with --source captions. With auto, speaker labels bypass captions. YouTube and X retain their existing caption behavior; TikTok, Bluesky, Dailymotion and LinkedIn also support available caption tracks. Non-YouTube captions have segment timing only (words: null), including auto-generated tracks. See Sources and options for the capability matrix and language rules.

Translate

Add --translate <xx> (a two-letter ISO 639-1 code such as de) to a transcription or to get <id> to also get a translation. Translation is free and uses 0 minutes; see Translation. Available from the CLI release after v1.2.0; run transcript1 update.

transcript1 --translate de -f srt -o talk.en-de.srt talk.mp3
transcript1 get --translate es --translation only <id>

--translation both|only needs --translate. both (default) is bilingual: SRT and VTT cues have two lines, the original and then the translation. only outputs the translation alone.

get --translate starts the translation if needed, also retries a failed one, and waits for it.

Output files are named <name>.<xx>.<ext> for only and <name>.<orig>-<xx>.<ext> for both. A file given with -o <file> is used as given.

A failed translation fails only that input (exit 1); other inputs continue. If the transcription has no such translation, the error is no <xx> translation for <id>.

Scripts and agents

Agents with a shell can install the CLI, set TRANSCRIPT1_API_KEY and run transcript1 <link> or transcript1 <file>. For clients using MCP, see MCP server setup.

Use --json for one JSON line per input on stdout as it finishes, with no progress, summary or update notice:

transcript1 --json 'https://youtu.be/dQw4w9WgXcQ'

Each finished job is the API transcription object plus input and reused. When a transcript is written to a file, the line includes file and omits transcript. Errors before an id exists have input and an error object with code and message. Skipped inputs have input, skipped (exists or out_of_minutes) and file when applicable. exists applies only to YouTube links and local files.

With one input and no -o, --json includes the transcript in the object and ignores -f. With several inputs and no -o, transcripts go to ./transcripts and each JSON line includes file instead of transcript. Whenever a file is written, -f selects its format. Use -q or --quiet to suppress progress and summaries while keeping transcript output and errors.

To start a job without waiting, then fetch it later:

transcript1 --no-wait interview.mp3
transcript1 get <id>

Replace <id> with the id printed by the first command. --no-wait prints the id and status, or the object with --json. get waits while the job runs; it accepts -f, -o, --timestamps, --no-wait, --json and -q.

Updates

transcript1 update

The CLI checks for a newer release at most once per 24 hours when stderr is a terminal and shows a notice if one is available. Set TRANSCRIPT1_NO_UPDATE_CHECK=1 to disable the check. --json and -q also suppress it.

Exit codes

Run transcript1 --help (or transcript1 alone) for all commands and flags.