✨ YouTube 字幕 API ✨

这是一个 Python API，允许你获取指定 YouTube 视频的字幕/副标题。它也适用于自动生成的字幕，支持字幕翻译，并且不需要无头浏览器，这与其他基于 Selenium 的解决方案不同！

这个项目的维护得益于所有的贡献者和赞助商。如果你想赞助这个项目并在下方显示你的头像或公司标志，点击这里。 💖

安装

pip install youtube-transcript-api

如果你想从源代码使用，你需要手动安装依赖：

pip install -r requirements.txt

你可以将此模块集成到现有应用程序中，或者通过命令行界面使用它。

API

获取给定视频字幕的最简单方法是执行：

from youtube_transcript_api import YouTubeTranscriptApi

YouTubeTranscriptApi.get_transcript(video_id)

注意： 默认情况下，这将尝试访问视频的英文字幕。如果你的视频使用不同的语言，或者你对获取其他语言的字幕感兴趣，请阅读下面的部分。

这将返回一个字典列表，看起来类似这样：

[
    {
        'text': '嘿，你好',
        'start': 7.58,
        'duration': 6.13
    },
    {
        'text': '你好吗',
        'start': 14.08,
        'duration': 7.58
    },
    # ...
]

获取不同语言

如果你想确保以你想要的语言获取字幕（默认为英语），可以添加 languages 参数。

YouTubeTranscriptApi.get_transcript(video_id, languages=['de', 'en'])

这是一个按降序优先级排列的语言代码列表。在这个例子中，它会首先尝试获取德语字幕（'de'），如果失败则获取英语字幕（'en'）。如果你想先了解有哪些可用语言，可以查看list_transcripts()函数。

如果你只想要一种语言，仍然需要将languages参数格式化为列表：

YouTubeTranscriptApi.get_transcript(video_id, languages=['de'])

批量获取字幕

要获取多个视频ID的字幕，可以调用：

YouTubeTranscriptApi.get_transcripts(["video_id1", "video_id2"], languages=['de', 'en'])

这里的languages参数也是可选的。

保留格式

如果你想保留HTML格式元素，如<i>（斜体）和<b>（粗体），可以添加preserve_formatting=True：

YouTubeTranscriptApi.get_transcripts(video_ids, languages=['de', 'en'], preserve_formatting=True)

列出可用字幕

如果你想列出给定视频的所有可用字幕，可以调用：

transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)

这将返回一个可迭代的TranscriptList对象，它提供了方法来筛选特定语言和类型的字幕列表，比如：

transcript = transcript_list.find_transcript(['de', 'en'])

默认情况下，如果请求的语言同时有手动创建和自动生成的字幕，该模块总是优先选择手动创建的字幕。TranscriptList允许你绕过这个默认行为，搜索特定类型的字幕：

# 筛选手动创建的字幕
transcript = transcript_list.find_manually_created_transcript(['de', 'en'])

# 或自动生成的字幕
transcript = transcript_list.find_generated_transcript(['de', 'en'])

find_generated_transcript、find_manually_created_transcript、find_transcript方法返回Transcript对象。它们包含字幕的元数据：

print(
    transcript.video_id,
    transcript.language,
    transcript.language_code,
    # 是否为手动创建或由YouTube生成
    transcript.is_generated,
    # 该字幕是否可翻译
    transcript.is_translatable,
    # 字幕可翻译的语言列表
    transcript.translation_languages,
)

并提供了获取实际字幕数据的方法：

transcript.fetch()

翻译字幕

YouTube有一个可以自动翻译字幕的功能。本模块也可以访问这个功能。Transcript对象提供了一个translate()方法，它返回一个新的翻译后的Transcript对象：

transcript = transcript_list.find_transcript(['en'])
translated_transcript = transcript.translate('de')
print(translated_transcript.fetch())

示例

from youtube_transcript_api import YouTubeTranscriptApi

# 获取可用字幕
transcript_list = YouTubeTranscriptApi.list_transcripts('video_id')

# 遍历所有可用字幕
for transcript in transcript_list:

    # Transcript对象提供元数据属性
    print(
        transcript.video_id,
        transcript.language,
        transcript.language_code,
        # 是否为手动创建或由YouTube生成
        transcript.is_generated,
        # 该字幕是否可翻译
        transcript.is_translatable,
        # 字幕可翻译的语言列表
        transcript.translation_languages,
    )

    # 获取实际字幕数据
    print(transcript.fetch())

    # 翻译字幕将返回另一个字幕对象
    print(transcript.translate('en').fetch())

# 你也可以直接筛选你要找的语言，使用字幕列表
transcript = transcript_list.find_transcript(['de', 'en'])  

# 或只筛选手动创建的字幕  
transcript = transcript_list.find_manually_created_transcript(['de', 'en'])  

# 或自动生成的字幕  
transcript = transcript_list.find_generated_transcript(['de', 'en'])

使用格式化器

格式化器旨在对你传递的字幕进行额外的处理层。目标是将字幕从其Python数据类型转换为特定"格式"的一致字符串。比如基本文本（.txt）或甚至有明确规范的格式，如JSON（.json）、WebVTT（.vtt）、SRT（.srt）、逗号分隔格式（.csv）等。

formatters子模块提供了一些基本的格式化器，用于包装你的字幕数据，以便在需要输出特定格式然后将该格式写入文件时使用。可能是为了备份/存储，以便稍后运行另一个脚本。

我们提供了几个格式化器子类供使用：

JSONFormatter
PrettyPrintFormatter
TextFormatter
WebVTTFormatter
SRTFormatter

以下是如何从formatters模块导入的方法：

# 创建自己的格式化器时要继承的基类。
from youtube_transcript_api.formatters import Formatter

# 一些提供的子类，每个子类输出不同的字符串格式。
from youtube_transcript_api.formatters import JSONFormatter
from youtube_transcript_api.formatters import TextFormatter
from youtube_transcript_api.formatters import WebVTTFormatter
from youtube_transcript_api.formatters import SRTFormatter

提供的格式化器示例

假设我们想获取一个字幕并将该字幕以与API返回相同的格式写入JSON文件。代码看起来像这样：

# your_custom_script.py

from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import JSONFormatter

# 必须是单个字幕。
transcript = YouTubeTranscriptApi.get_transcript(video_id)

formatter = JSONFormatter()

# .format_transcript(transcript) 将字幕转换为JSON字符串。
json_formatted = formatter.format_transcript(transcript)


# 现在我们可以将其写入文件。
with open('your_filename.json', 'w', encoding='utf-8') as json_file:
    json_file.write(json_formatted)

# 现在应该有一个新的JSON文件，你可以轻松地将其读回Python中。

传递额外的关键字参数

由于JSONFormatter利用了json.dumps()，你还可以在.format_transcript(transcript)中传递关键字参数，例如通过传递indent=2关键字参数使你的文件输出更美观。

json_formatted = JSONFormatter().format_transcript(transcript, indent=2)

自定义格式化器示例

你可以实现自己的格式化器类。只需继承Formatter基类，并确保实现format_transcript(self, transcript, **kwargs)和format_transcripts(self, transcripts, **kwargs)方法，这些方法在调用你的格式化器实例时应最终返回一个字符串。


class MyCustomFormatter(Formatter):
    def format_transcript(self, transcript, **kwargs):
        # 在这里进行你的自定义工作，但返回一个字符串。
        return '你处理后的输出数据作为字符串。'

    def format_transcripts(self, transcripts, **kwargs):
        # 在这里进行你的自定义工作以格式化字幕列表，但返回一个字符串。
        return '你处理后的输出数据作为字符串。'

命令行界面

使用视频ID作为参数执行CLI脚本，结果将打印到命令行：

youtube_transcript_api <第一个视频ID> <第二个视频ID> ...

CLI还为你提供了指定首选语言列表的选项：

youtube_transcript_api <第一个视频ID> <第二个视频ID> ... --languages de en

你还可以指定是否要排除自动生成或手动创建的字幕：

youtube_transcript_api <第一个视频ID> <第二个视频ID> ... --languages de en --exclude-generated
youtube_transcript_api <第一个视频ID> <第二个视频ID> ... --languages de en --exclude-manually-created

如果你更喜欢将结果写入文件或通过管道传输到另一个应用程序，你也可以使用以下命令将结果以json格式输出：

youtube_transcript_api <第一个视频ID> <第二个视频ID> ... --languages de en --format json > transcripts.json

使用CLI翻译字幕也是可能的：

youtube_transcript_api <第一个视频ID> <第二个视频ID> ... --languages en --translate de

如果你不确定某个视频有哪些可用语言，你可以调用以下命令列出所有可用字幕：

youtube_transcript_api --list-transcripts <第一个视频ID>

如果视频的ID以连字符开头，你需要使用\来掩饰连字符，以防止CLI将其误认为是参数名。例如，要获取ID为-abc123的视频的字幕，请运行：

youtube_transcript_api "\-abc123"

代理

你可以指定一个https代理，该代理将在向YouTube发送请求时使用：

from youtube_transcript_api import YouTubeTranscriptApi  

YouTubeTranscriptApi.get_transcript(video_id, proxies={"https": "https://user:pass@domain:port"})

由于proxies字典被传递给requests.get(...)调用，它遵循requests库使用的格式。

使用CLI：

youtube_transcript_api <第一个视频ID> <第二个视频ID> --https-proxy https://user:pass@domain:port

Cookies

有些视频有年龄限制，所以没有某种认证，该模块将无法访问这些视频。要做到这一点，你需要在浏览器中访问所需的视频。然后，你需要将该页面的cookies下载到一个文本文件中。你可以使用Chrome扩展cookies.txt或Firefox扩展cookies.txt。

一旦你有了这个，你就可以使用该模块来访问有年龄限制的视频的字幕，如下所示。

from youtube_transcript_api import YouTubeTranscriptApi

YouTubeTranscriptApi.get_transcript(video_id, cookies='/path/to/your/cookies.txt')

YouTubeTranscriptApi.get_transcripts([video_id], cookies='/path/to/your/cookies.txt')

使用命令行界面：

youtube_transcript_api <第一个视频ID> <第二个视频ID> --cookies /path/to/your/cookies.txt

警告

此代码使用了YouTube API的未公开部分，这部分由YouTube网页客户端调用。因此，如果他们改变了运作方式，无法保证它明天还能正常工作。但如果发生这种情况，我会尽最大努力尽快使其恢复正常。所以如果它停止工作，请告诉我！

捐赠

如果这个项目通过减少你的开发时间让你感到高兴，你可以通过请我喝杯咖啡来让我高兴，或者成为这个项目的赞助者 :)