# @danielxceron/youtube-transcript 中文文档

规范地址：https://npmcn.com/package/%40danielxceron/youtube-transcript/

版本：2\.0\.0
npm 元数据更新时间：2026-10-24T06:22:48.840Z
中文译文更新时间：2026-11-11T10:41:18.832Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40danielxceron/youtube-transcript
原文对照：https://npmcn.com/package/%40danielxceron/youtube-transcript/?lang=original
项目主页：https://github.com/danielxceron/youtube-transcript
源码仓库：https://github.com/danielxceron/youtube-transcript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：134 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2025-06-14T16:24:44.563Z
- 最新版本发布：2026-10-24T06:22:48.453Z
- 近 30 天下载量：14668（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 4 个）

## 中文简介

从YouTube视频中获取记录

## 安装

```sh
npm install @danielxceron/youtube-transcript
```

也可以使用：`pnpm add @danielxceron/youtube-transcript`、`yarn add @danielxceron/youtube-transcript`、`bun add @danielxceron/youtube-transcript`

## README

# 自动调试

[![npm version](https://img.shields.io/npm/v/@danielxceron/youtube-transcript.svg)](https://www.npmjs.com/package/@danielxceron/youtube-transcript) [![CI](https://github.com/danielxceron/youtube-transcript/actions/workflows/ci.yml/badge.svg)](https://github.com/danielxceron/youtube-transcript/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@danielxceron/youtube-transcript.svg)](https://npmcn.com/package/%40danielxceron/youtube-transcript/LICENSE)

## 关于这个叉子

这是原始的Youtube-transcript包的叉子,有弹性取出管. 它首先尝试了YouTube的"内通"API,并在需要时倒回HTML刮取,因此一个被屏蔽的单一路由不会断断记录稿检索.

## 怎么样

-   **内立方块先**: Android 和 iOS 客户端的签名字幕 URL, 自动旋转
-   **HTML 刮回倒计时** 当内tube返回无标题时
-   **可重新使用的客户端** 有超时、重试、货币限额和缓存
-   **批量获取** 包含每集视频结果
-   **有力解析器** srv1、 srv3 和 json3 标题格式
-   **完成 HTML 实体解码** 包括数字和双编码实体

见 [变动情况](https://npmcn.com/package/%40danielxceron/youtube-transcript/CHANGELOG.md) 为完整的历史.

## 从1.x升级

2.0.0版本改变可观察到的行为. 静态 `fetchTranscript` API持续工作,但这些点可能需要调整:

1.  **首选手动字幕** 超过自动的,如果没有 `lang` 给出。 没有旗帜可以恢复旧的ASR优先.
2.  **`segment.lang` 是所选音轨的语言** (单位:千美元)`de-DE`)而不是所要求的一个(`de`) (中文(简体) ). 与需要的前缀比较 :
    
    ```js
    const wanted = (segment) => segment.lang?.toLowerCase().startsWith('de');
    ```
    
3.  **无害环境管理切入点重新命名** 从 `dist/youtube-transcript.esm.js` 改为 `dist/youtube-transcript.mjs`通过软件包名称导入或更新直接的 CDN 路径.
4.  **启用缓存和重试** (单位:千美元)`5 min`, (中文(简体) ), `2 retries`, (中文(简体) ), `20 s` 暂停). 要模仿 1.x 耐久和新鲜度:
    
    ```js
    const youtube = YoutubeTranscript.create({ cache: false, retries: 0 });
    ```
    
5.  **新建错误类别**数字 : `YoutubeTranscriptNetworkError` 财务报告和审定财务报表 `YoutubeTranscriptAbortError` 现在地面运输失败.

## 安装

```bash
$ npm i @danielxceron/youtube-transcript
```

## 使用量

```js
import { YoutubeTranscript } from '@danielxceron/youtube-transcript';

const transcript = await YoutubeTranscript.fetchTranscript('videoId or URL');
console.log(transcript);
```

每段都有形状 `{ text, duration, offset, lang }`时 `duration` 财务报告和审定财务报表 `offset` 几秒钟内.

### 可重用客户端

对于服务器和长期运行的进程,创建一个客户端并共享:

```js
import { YoutubeTranscript } from '@danielxceron/youtube-transcript';

const youtube = YoutubeTranscript.create({
  timeoutMs: 15000,
  retries: 2,
  concurrency: 8,
  cache: { ttlMs: 300000, maxEntries: 500 },
});

const transcript = await youtube.fetchTranscript('videoId', { lang: 'en' });
```

### 批量获取

```js
const results = await youtube.fetchTranscripts(['videoIdA', 'videoIdB', 'videoIdC']);

for (const { videoId, transcript, error } of results) {
  if (error) console.error(videoId, error.message);
  else console.log(videoId, transcript.length);
}
```

复制的标识符只获取一次 .

### 选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `fetch` | 全局获取 | 自定义获取执行( 代理、 未编辑、 测试) |
| `timeoutMs` | `20000` | 按 HTTP 请求超时 |
| `retries` | `2` | 对网络错误进行检索, `429` 财务报告和审定财务报表 `5xx` |
| `concurrency` | `6` | 每个客户的最大飞行请求 |
| `cache` | 启用 | `false` 禁用,或 `{ ttlMs, maxEntries }` |
| `clients` | Android=iOS (英语) | 自定义内tube客户端 |
| `apiKey` | 公钥 | 内部Tube API 密钥 |
| `userAgent` | 颜色 | HTML 策略使用的用户代理 |
| `htmlFallback` | `true` | 禁用跳过 HTML 刮取 |

按呼选项: `lang`, (中文(简体) ), `timeoutMs`, (中文(简体) ), `retries`, (中文(简体) ), `signal`, (中文(简体) ), `cookie`。 。 。 .

### 支持的 URL 格式

-   标准视频 : `https://www.youtube.com/watch?v=VIDEO_ID`
-   短的 URL : `https://youtu.be/VIDEO_ID`
-   YouTube 短节目: `https://www.youtube.com/shorts/VIDEO_ID`
-   现场: `https://www.youtube.com/live/VIDEO_ID`
-   内嵌视频 : `https://www.youtube.com/embed/VIDEO_ID`
-   直接视频标识 : `VIDEO_ID`

语言匹配使用区域前缀, 所以 `lang: 'en'` 接受 `en`, (中文(简体) ), `en-US` 财务报告和审定财务报表 `en-GB`。手动字幕优于自动字幕.

## 处理错误

-   `YoutubeTranscriptTooManyRequestError`: 检测到的速率限制
-   `YoutubeTranscriptVideoUnavailableError`: 视频无法访问
-   `YoutubeTranscriptDisabledError`: 已禁用录像记录
-   `YoutubeTranscriptNotAvailableError`: 没有可用的记录
-   `YoutubeTranscriptNotAvailableLanguageError`: 所请求的语言不可用
-   `YoutubeTranscriptEmptyError`: 每一个取出策略都未返回
-   `YoutubeTranscriptNetworkError`: 复试后运输失败
-   `YoutubeTranscriptAbortError`: 请求中止通过 `signal`

每个错误都会暴露 `name`, (中文(简体) ), `videoId` (在适用时)和 `cause` (被包裹的时候).

## 发展

需要20个节点或更新(`.nvmrc` 针头22).

```bash
$ npm ci
$ npm run check         # format:check + typecheck + tests + build
$ npm test              # unit tests, mocked network
$ npm run typecheck
$ npm run format
$ npm run build
$ npm run smoke -- dQw4w9WgXcQ
```

运行单个文件或监视模式 :

```bash
$ npx vitest run tests/transcript.test.ts
$ npm run test:watch
```

现场测试真的冲击了YouTube

```bash
$ YOUTUBE_TRANSCRIPT_LIVE=1 npx vitest run tests/live.test.ts
```

CI覆盖了节点20,22和24;一个预定的工作流程每周运行一个直播套房. 发布由 GitHub 动作当 a `v*` 标签被按下,使用 `NPM_TOKEN` 秘密和npm来源.

## 环境相容性

| 战略 | 客户端 | 本地服务器 | 生产服务器 |
| --- | --- | --- | --- |
| 内部Tube API | ✅ | ✅ | ✅ |
| HTML 拼写 | ✅ | ✅ | ✅ |

## 许可证

**[麻省理工学院](https://npmcn.com/package/%40danielxceron/youtube-transcript/LICENSE)** 2026年 丹尼尔·塞隆·克拉罗斯

依据 [自动调试](https://github.com/Kakulukian/youtube-transcript) 由卡库鲁克扬所著.

## 常见问题

### @danielxceron/youtube-transcript 是什么？

从YouTube视频中获取记录

### 如何安装 @danielxceron/youtube-transcript？

在项目目录运行 npm install @danielxceron/youtube-transcript，或使用 pnpm add / yarn add / bun add。

### @danielxceron/youtube-transcript 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @danielxceron/youtube-transcript 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @danielxceron/youtube-transcript 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @danielxceron/youtube-transcript 可以商用吗？

@danielxceron/youtube-transcript 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @danielxceron/youtube-transcript 的下载量有多少？

根据 npm 官方下载统计，@danielxceron/youtube-transcript 在 2026/10/12 – 2026/11/10 这 30 天内被下载 14,668 次，日均约 489 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @danielxceron/youtube-transcript 还在维护吗？

最新版本 2\.0\.0 发布于 2026/10/24（18 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 4 个；首次发布于 2025/06/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。