YouTube Transcript API 部署与使用教程

本教程将指引您安装、配置并使用 youtube-transcript-api，这是一个无需API密钥即可获取YouTube视频字幕的Python库。

📋 1. 准备工作

  • Python环境：确保已安装 Python 3.8 或更高版本。
  • 包管理工具：推荐使用 pip 或 poetry。
  • 网络环境：能够正常访问 YouTube。

🚀 2. 安装

推荐使用 pip 进行安装，这是最直接的方式。

打开您的终端（命令行）并执行：

1
pip install youtube-transcript-api

如果您希望进行开发或贡献代码，可以克隆仓库并使用 poetry 安装包含测试和开发依赖的完整环境：

1
2
3
git clone https://github.com/jdepoix/youtube-transcript-api.git
cd youtube-transcript-api
poetry install --with test,dev

💻 3. 基本使用 (API)

3.1 获取单个视频的字幕

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from youtube_transcript_api import YouTubeTranscriptApi

# 初始化API客户端
ytt_api = YouTubeTranscriptApi()

# 视频ID是URL中"v="后面的部分，例如：https://www.youtube.com/watch?v=VIDEO_ID
video_id = "YOUR_VIDEO_ID_HERE"

# 获取字幕（默认尝试英文）
fetched_transcript = ytt_api.fetch(video_id)

# 访问字幕片段
for snippet in fetched_transcript:
    print(f"{snippet.start}s - {snippet.text}")

# 或者获取原始数据（列表字典形式）
raw_data = fetched_transcript.to_raw_data()
print(raw_data)

注意：fetch() 方法默认获取英文字幕。如果视频没有英文字幕，会抛出异常。

3.2 指定字幕语言

通过 languages 参数指定语言代码（按优先级顺序）：

1
2
3
4
5
# 优先获取德文（'de'），如果没有则获取英文（'en'）
fetched_transcript = ytt_api.fetch(
    video_id,
    languages=['de', 'en']
)

3.3 列出视频所有可用字幕

1
2
3
4
5
6
7
8
9
10
11
12
# 获取字幕列表对象
transcript_list = ytt_api.list(video_id)

# 查找特定语言的字幕（返回Transcript对象）
transcript = transcript_list.find_transcript(['en', 'zh-Hans'])

# 获取该字幕的实际内容
fetched_transcript = transcript.fetch()

# 也可以按类型筛选
manual_transcript = transcript_list.find_manually_created_transcript(['en'])
generated_transcript = transcript_list.find_generated_transcript(['en'])

3.4 翻译字幕

利用YouTube的自动翻译功能：

1
2
3
4
5
6
7
8
# 先获取英文字幕的Transcript对象
transcript_en = transcript_list.find_transcript(['en'])

# 翻译成德语，返回新的Transcript对象
transcript_de = transcript_en.translate('de')

# 获取翻译后的内容
fetched_transcript_de = transcript_de.fetch()

3.5 保留格式

通过 preserve_formatting=True 保留 <i> 和 <b> 等HTML格式标签：

1
2
3
4
fetched_transcript = ytt_api.fetch(
    video_id,
    preserve_formatting=True
)

🛠️ 4. 高级配置

4.1 自定义HTTP客户端

您可以通过传递 requests.Session 对象来自定义网络请求：

1
2
3
4
5
6
7
8
from requests import Session

http_client = Session()
http_client.headers.update({"Accept-Encoding": "gzip, deflate"})
http_client.verify = "/path/to/certfile"  # 自定义CA证书

ytt_api = YouTubeTranscriptApi(http_client=http_client)
fetched_transcript = ytt_api.fetch(video_id)

4.2 使用代理（应对IP封锁）

YouTube可能会封锁某些IP（特别是云服务商的IP），您可以使用代理来解决。

方案一：使用Webshare（推荐，已集成）

  1. 注册 Webshare 账户并购买“Residential”代理套餐。
  2. 在Proxy Settings中找到“Proxy Username”和“Proxy Password”。
  3. 在代码中配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import WebshareProxyConfig

ytt_api = YouTubeTranscriptApi(
    proxy_config=WebshareProxyConfig(
        proxy_username="你的_Proxy_用户名",
        proxy_password="你的_Proxy_密码",
        # 可选：限制IP地理位置，例如只使用德国和美国IP
        filter_ip_locations=["de", "us"],
    )
)

fetched_transcript = ytt_api.fetch(video_id)

方案二：使用通用HTTP/HTTPS代理

1
2
3
4
5
6
7
8
9
10
11
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import GenericProxyConfig

ytt_api = YouTubeTranscriptApi(
    proxy_config=GenericProxyConfig(
        http_url="http://user:pass@my-proxy.com:port",
        https_url="https://user:pass@my-proxy.com:port",
    )
)

fetched_transcript = ytt_api.fetch(video_id)

⌨️ 5. 命令行界面 (CLI)

安装后，您可以直接在终端使用 youtube_transcript_api 命令。

5.1 基本用法

1
2
3
4
5
6
7
8
9
10
11
# 获取一个或多个视频的字幕（默认英文）
youtube_transcript_api VIDEO_ID_1 VIDEO_ID_2

# 指定语言优先级（德语优先，英文其次）
youtube_transcript_api VIDEO_ID --languages de en

# 排除自动生成的字幕
youtube_transcript_api VIDEO_ID --languages en --exclude-generated

# 排除手动创建的字幕
youtube_transcript_api VIDEO_ID --languages en --exclude-manually-created

5.2 格式化输出与保存

1
2
3
4
5
# 以JSON格式输出并保存到文件
youtube_transcript_api VIDEO_ID --format json > transcript.json

# 翻译并输出（获取英文字幕，翻译成德语）
youtube_transcript_api VIDEO_ID --languages en --translate de

5.3 列出可用字幕

1
youtube_transcript_api --list-transcripts VIDEO_ID

5.4 代理与认证 (CLI)

1
2
3
4
5
6
7
8
9
10
11
12
# 使用Webshare代理
youtube_transcript_api VIDEO_ID \
    --webshare-proxy-username "用户名" \
    --webshare-proxy-password "密码"

# 使用通用HTTP/HTTPS代理
youtube_transcript_api VIDEO_ID \
    --http-proxy http://user:pass@domain:port \
    --https-proxy https://user:pass@domain:port

# 使用Cookie文件进行认证（用于年龄限制视频，可能不适用于所有情况）
youtube_transcript_api VIDEO_ID --cookies /path/to/cookies.txt

📄 6. 格式化输出

formatters 子模块提供了多种输出格式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import JSONFormatter, TextFormatter, WebVTTFormatter, SRTFormatter

ytt_api = YouTubeTranscriptApi()
transcript = ytt_api.fetch(video_id)

# 格式化为JSON字符串（带缩进）
json_formatter = JSONFormatter()
json_string = json_formatter.format_transcript(transcript, indent=2)

# 格式化为纯文本
text_formatter = TextFormatter()
text_string = text_formatter.format_transcript(transcript)

# 格式化为WebVTT
vtt_formatter = WebVTTFormatter()
vtt_string = vtt_formatter.format_transcript(transcript)

# 格式化为SRT
srt_formatter = SRTFormatter()
srt_string = srt_formatter.format_transcript(transcript)

# 保存为文件
with open('transcript.json', 'w', encoding='utf-8') as f:
    f.write(json_string)

⚠️ 7. 重要注意事项

  1. 非官方API：此库使用的是YouTube Web客户端使用的非公开API，可能在YouTube更新时失效。
  2. IP封锁：YouTube可能会封锁已知的云服务商IP，频繁使用或部署在云服务器上时，请考虑配置代理。
  3. 年龄限制：针对年龄限制视频的Cookie认证功能目前可能无法正常工作。
  4. 语言代码：语言代码遵循ISO 639-1标准（如 en、zh-Hans）。

🤝 8. 贡献与支持

  • 贡献：欢迎提交Pull Request。请确保代码通过测试、覆盖率、格式化和Lint检查（可运行 poe precommit）。
  • 赞助：如果这个项目对您有帮助，可以考虑成为赞助商以支持其维护。

按照以上步骤，您应该可以顺利部署并使用 youtube-transcript-api 来获取YouTube视频字幕了。祝您使用顺利！