# 使用transcript1命令行工具

> 在终端转录视频链接和本地文件，批量处理文件夹、保存字幕，也可输出JSON供脚本和AI智能体读取。

Canonical: https://transcript1.com/zh/docs/cli
Language: zh-Hans
Last updated: 2026-10-18

用`transcript1`直接转录视频链接或本地音视频文件。链接支持YouTube、X、TikTok、Instagram、Facebook和Bluesky，其他平台的版本要求见下文。完整的平台列表和限制见[来源与选项](https://transcript1.com/zh/docs/sources-and-options)。独立版CLI不需要Node.js。

转录社交平台链接，请使用CLI 1.2.0或更高版本。CLI 1.1.0及更早版本只支持YouTube，其他平台的链接会在本地校验时被拒绝。用`transcript1 update`更新。

上述版本要求针对最初的6个平台。Twitch、Dailymotion、Pinterest、LinkedIn和Snapchat需要更新到已加入对应平台支持的CLI版本，否则链接可能在本地校验时被拒绝。

请使用公开帖子。帖子里有多个视频时，只转录第1个。支持哪些短链接、有哪些限制，见[来源与选项](https://transcript1.com/zh/docs/sources-and-options)。

## 安装CLI

macOS或Linux支持x64和ARM64，运行：

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

可执行文件默认安装到`~/.local/bin`。如果需要调整PATH，安装程序会给出提示。要改安装目录，设置`TRANSCRIPT1_INSTALL_DIR`。

安装后也可以用短命令`t1`代替`transcript1`。使用zsh时，安装程序会在`~/.zshrc`中添加`alias transcript1='noglob transcript1'`，避免不加引号的链接中的`?`被当作通配符。设置`TRANSCRIPT1_NO_MODIFY_SHELL=1`可跳过这项配置。

Windows x64请在PowerShell中运行：

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

Windows版安装在`%LOCALAPPDATA%\Programs\transcript1`，同时提供短命令`t1.cmd`，并把安装目录加入用户PATH。安装后重新打开终端即可使用。

## 登录并保存密钥

先运行登录命令：

```bash
transcript1 login
```

CLI会打开浏览器，进入transcript1.com；通过SSH连接或没有图形界面时，则在终端显示链接。确认页面上的代码与终端一致，再点击“Approve”。批准后，CLI会保存名为`transcript1 CLI (<computer name>)`的密钥，可在[“API keys”](https://transcript1.com/dashboard/account/tokens)页面查看。

不想自动打开浏览器，可以用`transcript1 login --no-browser`，只在终端显示链接。

已有API密钥时，运行`transcript1 login --with-key`后粘贴即可。也支持通过标准输入读取，例如`transcript1 login < key.txt`。

CI和AI智能体请通过`TRANSCRIPT1_API_KEY`提供密钥；它会覆盖本地保存的密钥。没有交互终端或密钥的智能体，可以运行`transcript1 login < /dev/null`，再把登录链接发给用户批准。

运行`transcript1 logout`会撤销CLI生成的密钥，并删除本地保存的密钥。如果撤销失败，CLI仍会删除本地密钥，并提示到“API keys”页面手动撤销。登录时粘贴的已有密钥，也需要在该页面撤销。

## 用链接转录视频

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

命令会等待转录完成，然后把转录文本写到stdout，进度信息写到stderr。处理YouTube、X、TikTok、Bluesky、Dailymotion和LinkedIn时，优先使用与视频原语言一致的可用字幕；没有可用字幕时，改用AI转录。

在zsh中，建议始终给链接加引号。不加引号时，`&`会拆开命令；`?`会被当作通配符，除非使用了安装程序添加的别名。

## 上传并转录本地文件

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

直接传入文件路径，CLI会上传并等待转录完成。文件上限为2GB（2,000,000,000字节），支持的扩展名为mp3、wav、m4a、flac、ogg、opus、mp4、mov、webm和mkv。

## 批量转录文件和链接

可以同时传入多个文件、链接，或直接指定文件夹：

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

支持`recordings/*.mp3`这样的文件通配符，Windows也可以使用。指定文件夹时，只读取该目录下的媒体文件，不进入子目录，并按文件名排序。批量转录默认将每项转录保存为独立文件，放在`./transcripts`。用`--jobs`设置并发数，范围为1到20，默认2。

要从stdin读取输入，用`-`代替路径，每行放1个链接或文件路径。macOS或Linux的shell示例：

```bash
transcript1 -o transcripts/ - < inputs.txt
```

CLI会跳过空行和以`#`开头的行，内容完全相同的输入只处理1次。

只有1项输入时，`-o`通常指定输出文件；路径是已有文件夹或以`/`结尾时，则作为输出目录。多项输入的`-o`始终表示目录。目录不存在时会自动创建。

处理YouTube链接和本地文件时，如果对应的输出文件已存在，CLI会跳过该项。要重新处理，加上`--overwrite`：

```bash
transcript1 --overwrite -o transcripts/ ./recordings
```

## 选择格式和转录选项

| 选项 | 用法 |
|---|---|
| `-f`、`--format` | 选择`text`（默认）、`srt`、`vtt`或`json`。JSON格式返回API中的转录对象。 |
| `--speakers` | 开启说话人分离，标记为Speaker 1、Speaker 2等。 |
| `--timestamps` | 每行开头添加`[hh:mm:ss]`，只适用于文本格式。 |
| `--language` | 指定ISO 639-1语言代码，或用`auto`自动识别（默认）。 |
| `--source` | 选择`auto`（默认）或`stt`。YouTube、X、TikTok、Bluesky、Dailymotion和LinkedIn有可用字幕轨道时，也支持`captions`。`captions`（仅字幕）不会下载音频，也不会改用语音转文字。 |
| `--fresh` | 重新转录链接，不复用最近24小时内已有的转录。 |

同时开启说话人分离和时间戳：

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

`--speakers`与`--source captions`不能同时使用。选择auto并开启说话人分离时，会跳过字幕，直接处理音频。YouTube和X仍支持字幕，TikTok、Bluesky、Dailymotion和LinkedIn也可使用可用的字幕轨道。除YouTube外，平台字幕只提供分段时间戳（`words: null`），即使是自动生成的字幕也没有逐词时间戳。各平台的支持情况和语言规则见[来源与选项](https://transcript1.com/zh/docs/sources-and-options)。

## 在脚本和AI智能体中使用

能运行shell命令的AI智能体，安装CLI并设置`TRANSCRIPT1_API_KEY`后，就可以调用`transcript1 <link>`或`transcript1 <file>`。客户端通过MCP接入时，请按[MCP服务器文档](https://transcript1.com/zh/docs/mcp)配置。

加上`--json`后，每项输入处理完就向stdout写入1行JSON，不显示进度、汇总或更新提示：

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

任务完成时，JSON包含API的转录对象，并附上`input`和`reused`。如果转录文本已保存到文件，则返回`file`，不再包含`transcript`。还没生成id就报错时，返回`input`和`error`，其中`error`包含`code`与`message`。跳过某项输入时，返回`input`、`skipped`，以及适用时的`file`；`skipped`的值为`exists`或`out_of_minutes`，其中`exists`只用于YouTube链接和本地文件。

只有1项输入且未指定`-o`时，`--json`会直接返回含转录文本的对象，忽略`-f`。多项输入未指定`-o`时，转录文本保存到`./transcripts`，每行JSON用`file`表示路径，不包含`transcript`。只要保存文件，就由`-f`决定文件格式。仅需隐藏进度和汇总时，可用`-q`或`--quiet`，转录文本和错误仍会输出。

也可以提交后立即返回，稍后再取转录文本：

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

把`<id>`换成上条命令返回的id。`--no-wait`默认输出id和状态，与`--json`合用则输出对象。`get`会等任务完成后再返回，支持`-f`、`-o`、`--timestamps`、`--no-wait`、`--json`和`-q`。

## 更新CLI

```bash
transcript1 update
```

stderr连接终端时，CLI每24小时最多检查1次更新，发现新版本会显示提示。设置`TRANSCRIPT1_NO_UPDATE_CHECK=1`可关闭检查；使用`--json`或`-q`时也不显示更新提示。

## 通过退出码判断执行情况

| 退出码 | 说明 |
|---|---|
| 0 | 全部处理成功，或因输出文件已存在而跳过；后者只适用于YouTube链接和本地文件。 |
| 1 | 至少1项处理失败，或因分钟数不足而跳过。 |
| 2 | 命令用法有误，或登录出现问题。 |
| 130 | 执行被中断。 |

完整命令和选项可通过`transcript1 --help`查看，直接运行`transcript1`也会显示帮助。