NewsBlur 自动开启 YouTube 视频字幕（Captions）功能解析：从偏好设置到 URL 实时改写

NewsBlur 的个人新闻阅读器中，订阅源里经常内嵌 YouTube 视频。本指南围绕 2025 年 12 月官方博客发布的 "Auto-enable captions on YouTube videos" 更新，完整讲解该功能的开启方式、实现原理与适用场景：如何在 Preferences > Stories 中勾选 "YouTube Captions"，为什么它能对所有订阅源"一次开启、处处生效"，以及底层如何通过 cc_load_policy=1 参数对嵌入 URL 进行实时改写而不触碰原始内容。读完本文，你将理解 NewsBlur 前端偏好、后端 API 与故事内容处理管线三者如何协作，并掌握该功能的源码级实现细节。

功能概述：一句话开启所有 YouTube 视频字幕

NewsBlur 于 2025 年 12 月 22 日发布的博客文章（见 blog/_posts/2025-12-22-youtube-captions.md）宣布了一项新偏好：自动开启订阅内容中 YouTube 视频的字幕。用户只需进入 Preferences > Stories，勾选新的 "YouTube Captions" 选项即可：

开启后，任意订阅源中的任何 YouTube 视频，在开始播放时都会自动显示字幕（前提是该视频本身提供字幕）。该功能尤其适合：

• 在嘈杂环境中观看视频；
• 无障碍（accessibility）需求，例如听障用户；
• 学习语言时对照字幕跟读。

开启后的实际播放效果如下：

该偏好默认关闭，因此不勾选时，原有播放行为完全不变，用户可以按需选择加入（opt-in）。

实现原理：cc_load_policy=1 与实时 URL 改写

这项功能不修改任何订阅源的原始内容，而是由 NewsBlur 在后端对故事内容中的 YouTube 嵌入 URL 即时追加 cc_load_policy=1 参数。cc_load_policy 是 YouTube 播放器的官方参数：取值为 1 时，播放器会在加载后立即显示字幕（若该视频有可用字幕），等效于用户手动点击播放器上的 "CC" 按钮。

从源码结构看，这一逻辑被封装在 Feed 模型的静态方法 apply_youtube_captions 中（apps/rss_feeds/models.py）：

@staticmethod
def apply_youtube_captions(story_content):
    """
    Transform YouTube embed URLs to enable captions by adding cc_load_policy=1.
    This makes captions show by default when videos are played.
    """
    if not story_content:
        return story_content

    def add_captions_param(match):
        url = match.group(0)
        if "cc_load_policy" in url:
            return url
        if "?" in url:
            if url.endswith('"') or url.endswith("'"):
                quote = url[-1]
                return url[:-1] + "&cc_load_policy=1" + quote
            return url + "&cc_load_policy=1"
        else:
            if url.endswith('"') or url.endswith("'"):
                quote = url[-1]
                return url[:-1] + "?cc_load_policy=1" + quote
            return url + "?cc_load_policy=1"

    return Feed.YOUTUBE_EMBED_RE.sub(add_captions_param, story_content)

该方法的关键设计：

• 空内容短路：story_content 为空时直接返回，避免无谓的正则处理；
• 幂等性：URL 中已包含 cc_load_policy 时原样返回，防止重复注入参数；
• 分隔符感知：URL 已有查询串（含 ?）时追加 &cc_load_policy=1，否则追加 ?cc_load_policy=1；
• 引号保护：匹配结果以 " 或 ' 结尾（即 HTML 属性边界）时，参数插入在引号之前，保证改写后的 HTML 依然合法。

匹配目标：YOUTUBE_EMBED_RE 正则

改写动作由预编译正则 YOUTUBE_EMBED_RE 驱动（apps/rss_feeds/models.py）：

# Compiled regex for YouTube embed URL matching (used by apply_youtube_captions)
YOUTUBE_EMBED_RE = re.compile(
    r'src=["\']https?://(?:www\.)?(?:youtube\.com|youtube-nocookie\.com)/embed/[^"\']*["\']'
)

该模式精确匹配：

• HTML src 属性，且属性值以 " 或 ' 包裹；
• 协议为 http:// 或 https://；
• 主机为 www.youtube.com、youtube.com 或隐私友好的 www.youtube-nocookie.com；
• 路径必须为 /embed/...（即 iframe 嵌入形式），这与订阅源中常见的标准 YouTube 嵌入写法一致——例如 apps/rss_feeds/fixtures/motherjones2.xml 中的示例：

<iframe width="600" height="360" src="http://www.youtube.com/embed/AzphPZakPaA?rel=0" frameborder="0" allowfullscreen=""></iframe>

这类 URL 会被改写成：

<iframe ... src="http://www.youtube.com/embed/AzphPZakPaA?rel=0&cc_load_policy=1" ...></iframe>

可以推断，正则刻意将范围限定在标准的 /embed/ iframe 形式上，以兼顾匹配效率与改写安全性，避免误伤其他 YouTube 相关链接。

调用链路：偏好如何驱动故事内容改写

该功能的前端偏好与后端调用在三个位置协同工作。

前端：偏好面板中的复选框

阅读器偏好面板在 media/js/newsblur/reader/reader_preferences.js 中渲染该选项：

$.make('div', { className: 'NB-preference NB-preference-youtube-captions' }, [
    $.make('div', { className: 'NB-preference-options' }, [
        $.make('div', [
            $.make('input', { id: 'NB-preference-youtube-captions', type: 'checkbox', name: 'youtube_captions' }),
            $.make('label', { 'for': 'NB-preference-youtube-captions' }, 'Enable captions/subtitles for YouTube videos')
        ])
    ]),
    $.make('div', { className: 'NB-preference-label' }, [
        'YouTube Captions'
    ])
])

打开偏好弹窗时，复选框的选中状态会根据当前用户偏好回填（同文件 第 1244-1249 行）：

$('input[name=youtube_captions]', $modal).each(function () {
    if (NEWSBLUR.Preferences.youtube_captions) {
        $(this).prop('checked', true);
        return false;
    }
});

保存偏好时通过 save_preferences 提交（同文件第 1711-1717 行附近），将 youtube_captions 以布尔值写入用户偏好。

后端：偏好存储

后端由 apps/profile/views.py 的 set_preference 接口接收并持久化。该接口对形如 "true"/"false" 的字符串值统一转换为 Python 布尔值后写入 request.user.profile.preferences：

preferences = json.decode(request.user.profile.preferences)
for preference_name, preference_value in list(new_preferences.items()):
    if preference_value in ["true", "false"]:
        preference_value = True if preference_value == "true" else False

由于 youtube_captions 属于通用偏好，它被存进用户 profile.preferences JSON 字典，供阅读器 API 读取。

后端：在故事加载时实时改写

阅读器在两类核心接口中读取该偏好并执行改写（apps/reader/views.py）：

1. load_single_feed(request, feed_id)——单订阅源视图（第 1162 行起），在第 1424-1425 行读取偏好，第 1471-1472 行执行改写；
2. load_river_stories__redis(request)——River（合流）视图（第 2524 行起，同时服务 GET/POST 以便携带长参数），在第 2973-2974 行读取偏好，第 3053-3054 行执行改写。

两处逻辑一致：

# Check if user wants YouTube captions enabled
user_preferences = json.decode(user.profile.preferences)
youtube_captions_enabled = user_preferences.get("youtube_captions", False)
...
# Apply YouTube captions if user preference is enabled
if youtube_captions_enabled and "story_content" in story and story["story_content"]:
    story["story_content"] = Feed.apply_youtube_captions(story["story_content"])

值得注意的是改写发生在故事内容从数据库取出并组装成 API 响应的环节，而非写入存储。这意味着：

• 原始故事内容始终未被修改，符合博客中"不修改原始内容"的承诺；
• 偏好随时开关，下一次请求即生效，无需重新抓取订阅源；
• 由于单源视图与合流视图共用同一套改写逻辑，该偏好对所有订阅源统一生效。

边界与注意事项

• 依赖视频本身提供字幕：cc_load_policy=1 只控制播放器默认开启字幕，若视频作者未上传字幕、也未生成自动字幕，则无字幕可显示；
• 默认关闭、行为不变：未勾选该偏好时，youtube_captions_enabled 取默认值 False，apply_youtube_captions 不会被调用，故事内容原样返回；
• 覆盖范围：改写针对 youtube.com / youtube-nocookie.com 的 /embed/ iframe 形式；订阅源中其他形式的 YouTube 链接（如旧式 <object>/Flash 嵌入或普通 watch 链接）不在该正则匹配范围内；
• 幂等安全：对已含 cc_load_policy 的 URL 不做重复注入，避免参数叠加导致播放器行为异常。

小结

NewsBlur 的 "YouTube Captions" 偏好以极低的实现成本解决了"所有订阅源中的 YouTube 视频自动开字幕"这一高频需求：前端一个复选框、后端一个正则改写函数、两处阅读器接口各三行调用代码。其核心设计——只读的、响应时（response-time）的 URL 改写——让该功能无需改动存储层即可对全部订阅源即时生效，同时严格保持原始内容不变。对于需要在嘈杂环境观看、无障碍使用或语言学习的 NewsBlur 用户，只需在 Preferences > Stories 中勾选一次，即可获得一致的带字幕观看体验。