🛡️ 广告过滤功能使用指南

KVideo 新增了强大的 M3U8 广告过滤系统，支持多种过滤模式，可有效去除视频中插入的切片广告。

✨ 功能特性

多模式选择：支持关闭、关键词过滤、智能启发式过滤(Beta)和激进模式。
UI 集成：在播放器设置菜单中直接切换模式，实时生效。
自定义关键词：支持通过环境变量扩展过滤关键词。
高性能：基于流式处理，对播放加载速度几乎无影响。

🎮 使用说明

打开任意视频播放。
点击播放器左上角的 (···) 按钮。
在 广告过滤 下拉菜单中选择模式：
- 关闭：不过滤任何内容（默认）。
- 关键词：仅过滤 URL 中包含特定广告关键词（如 adjump, pre-roll）的片段。安全稳定，误杀率极低。
- 智能(Beta)：推荐使用。结合关键词、文件名特征、时间戳跳变标记 (DISCONTINUITY) 和 HLS 标签进行综合评分。能识别大多数无明显关键词的广告。
- 激进：降低判定阈值，过滤更多疑似广告，但可能会误伤正片。仅在智能模式无效时尝试。
⚠️重要提示：添加关键词时，请勿使用类似ad ads video 20260118 这类简短相对通用的词汇，会造成误杀率极高。

🛠️ 部署配置指南

你可以通过环境变量 NEXT_PUBLIC_AD_KEYWORDS 自定义额外的广告关键词。

1. 本地开发 (Local Development)

在项目根目录的 .env.local 文件中添加。支持多行格式（推荐使用引号包裹）：

# 单行模式
NEXT_PUBLIC_AD_KEYWORDS=spam,promo,intro-ad

# 多行模式 (更清晰)
NEXT_PUBLIC_AD_KEYWORDS="
spam
promo
intro-ad
/unwanted-segment/
"

2. Docker 部署 (运行时热加载)

我们支持三种方式注入关键词，优先级从高到低：

文件加载 (推荐)：通过挂载文件并在运行时读取。
运行时环境变量：直接通过 -e 传入 AD_KEYWORDS。
构建时环境变量：构建镜像时打入的 NEXT_PUBLIC_AD_KEYWORDS。

方案 A：挂载配置文件 (支持运行时修改)

创建一个关键词文件 ad_keywords.txt：

spam
promo
/ad-segment/
intro

运行 Docker 时挂载该文件并设置 AD_KEYWORDS_FILE 环境变量：

docker run -d -p 3000:3000 \
  -v $(pwd)/ad_keywords.txt:/app/ad_keywords.txt \
  -e AD_KEYWORDS_FILE=/app/ad_keywords.txt \
  --name kvideo kuekhaoyang/kvideo:latest

注：修改宿主机文件后重启容器即可生效，无需重新构建镜像。

方案 B：直接注入环境变量

docker run -d -p 3000:3000 \
  -e AD_KEYWORDS="spam,promo,intro-ad" \
  --name kvideo kuekhaoyang/kvideo:latest

3. Vercel 部署

进入 Vercel 项目 Dashboard。
点击 Settings -> Environment Variables。
添加新变量：
- Key: NEXT_PUBLIC_AD_KEYWORDS
- Value: spam,promo,intro-ad
重新部署项目以生效。

4. Cloudflare Pages 部署

进入 Cloudflare Pages 项目 Dashboard。
点击 Settings -> Environment variables。
添加变量：
- Variable name: NEXT_PUBLIC_AD_KEYWORDS
- Value: spam,promo,intro-ad
重新部署项目 (Retry deployment) 以生效。

🔍 技术实现细节

广告检测逻辑位于 lib/utils/m3u8-ad-detector.ts，采用分块评分机制：

Block 解析：将 M3U8 播放列表按 #EXT-X-DISCONTINUITY 分割成多个块。
特征学习：分析最长的块（通常是正片）提取特征，如文件命名模式、路径前缀等。
评分系统：
- HLS 标签：#EXT-X-CUE-OUT/IN (+10分，确认为广告)
- 路径前缀：与正片路径不一致 (+5分，高度疑似)
- 关键词：URL 包含已知广告词 (+2.5分)
- 文件名模式：与正片命名规则不符 (+1.5分)
决策过滤：
- 智能模式：移除评分 >= 5.0 的块。
- 激进模式：移除评分 >= 3.0 的块。

4.0 KiB Raw Blame History Unescape Escape