🎬 弹幕API功能配置指南
本文档详细介绍 Web UI 中"弹幕"页面下的所有功能模块和配置项。
Anime 接口
接口说明
本服务兼容 dandanplay API 规范，提供以下核心接口：
| 接口 | 说明 |
|---|---|
/api/v2/search/anime | 搜索动画作品 |
/api/v2/match | 匹配文件获取弹幕 |
/api/v2/comment/{episodeId} | 获取分集弹幕 |
/api/v2/related/{episodeId} | 获取相关弹幕 |
/api/v2/extcomment | 获取扩展弹幕 |
指令输入
⚠️ 注意: 指令操作仅在 anime 接口 中支持。具体哪些播放器支持 anime 接口，请查看 客户端配置 - 支持的播放器 中的表格。
在搜索接口中支持特殊指令，用于执行特定操作：
| 指令格式 | 说明 |
|---|---|
@QLHC | 清理缓存 |
使用方式： 在搜索框中输入 @QLHC 并执行，即可清理系统缓存。
适用场景：
- 缓存数据过多需要清理时
- 系统响应变慢时
- 需要刷新缓存数据时
Token管理
功能说明: 管理API访问令牌,用于控制第三方应用对弹幕API的访问权限。
创建Token
操作步骤:
- 打开 Web UI,进入 "弹幕" → "Token管理" 页面
- 点击 "创建Token" 按钮
- 填写Token信息:
- Token名称: 用于识别Token的名称(如 "我的播放器")
- 有效期: 选择Token的有效期(如 30天、90天、永久)
- 每日调用限制: 设置每日最大调用次数(可选)
- 点击 "确认" 创建
Token格式: 系统自动生成20位随机字符串(包含大小写字母和数字)
管理Token
功能:
- 查看Token列表: 显示所有已创建的Token及其状态
- 复制Token: 点击复制按钮快速复制Token字符串
- 删除Token: 删除不再使用的Token
- 查看统计: 查看Token的调用次数和有效期
使用场景:
- 为不同的播放器客户端分配独立Token
- 为第三方应用提供API访问权限
- 限制单个Token的调用频率
弹幕输出控制
功能说明: 调整弹幕API的输出行为,优化客户端性能。
弹幕输出上限
配置项: 弹幕输出上限
说明: 设置弹幕API返回的弹幕最大数量。
配置值:
-1: 无限制,返回所有弹幕正整数: 限制返回的弹幕数量(建议 3000-5000)
工作原理:
- 当弹幕总数超过限制时,系统会按时间段均匀采样
- 确保弹幕在整个视频时长中分布均匀
- 避免客户端因弹幕过多而卡顿
推荐配置:
- 移动设备: 3000
- 桌面设备: 5000
- 高性能设备: 8000 或更高
弹幕存储配置
功能说明: 自定义弹幕文件的存储路径和命名规则。
启用自定义路径
配置项: 启用自定义弹幕路径
说明: 开启后,可以自定义弹幕文件的存储位置和命名模板。
电影弹幕配置
配置项:
电影弹幕目录路径: 电影弹幕的存储根目录电影弹幕文件名模板: 电影弹幕文件的命名规则
默认配置:
目录路径: /app/config/danmaku/movies
文件名模板: ${title}/${episodeId}支持的变量:
| 变量 | 说明 |
|---|---|
${title} | 原始标题 |
${titleBase} | 标准化标题（去除特殊字符） |
${season} | 季数 |
${season:02d} | 季数（两位数格式，如 01、02） |
${episode} | 集数 |
${episode:02d} | 集数（两位数格式，如 01、02） |
${episode:03d} | 集数（三位数格式，如 001、002） |
${year} | 上映年份 |
${provider} | 弹幕源提供商 |
${animeId} | 作品ID |
${episodeId} | 分集ID |
${sourceId} | 源ID |
电视节目弹幕配置
配置项:
电视弹幕目录路径: 电视节目弹幕的存储根目录电视弹幕文件名模板: 电视节目弹幕文件的命名规则
默认配置:
目录路径: /app/config/danmaku/tv
文件名模板: ${animeId}/${episodeId}高级设置
匹配后备
配置项: 启用匹配后备
功能说明: 当播放器使用 /match 接口请求弹幕时,如果本地没有匹配的弹幕,系统会自动从弹幕源搜索并导入。
工作原理:
- 播放器发送
/match请求,包含文件名、文件Hash等信息 - 系统检查本地是否已有匹配的弹幕
- 如果没有,自动使用配置的弹幕源搜索
- 找到匹配后,自动导入弹幕并返回给播放器
适用场景:
- 希望完全自动化获取弹幕
- 不想手动在 Web UI 中搜索和导入
- 配合 Webhook 实现新媒体入库自动获取弹幕
后备搜索
配置项: 启用后备搜索
功能说明: 当播放器使用 /search/anime 接口搜索弹幕时,如果本地没有结果,系统会自动从弹幕源搜索并返回结果。
工作原理:
- 播放器发送
/search/anime请求 - 系统先检查本地是否有匹配结果
- 如果没有,自动从配置的弹幕源搜索
- 返回搜索结果供用户选择
适用场景:
- 希望在播放器中直接搜索弹幕
- 作为匹配后备的补充方案
顺延机制
配置项: 启用顺延机制
功能说明: 当选中的弹幕源没有有效分集时(如只有预告片被过滤掉),自动尝试下一个候选源,提高导入成功率。
工作原理:
- 系统从搜索结果中选择最佳匹配源
- 检查该源是否有有效分集(过滤预告片等无效内容)
- 如果没有有效分集,自动尝试下一个候选源
- 重复步骤2-3,直到找到有效源或尝试完所有候选源
适用场景:
- 某些搜索源只有预告片或特典
- 提高自动导入的成功率
- 减少手动重试的次数
依赖条件:
- 需要启用"匹配后备"或"后备搜索"
- 如果两者都未启用,此选项将被禁用
预下载
配置项: 启用预下载
功能说明: 当播放当前集时,系统会自动在后台下载下一集的弹幕(如果下一集存在且没有弹幕)。
工作原理:
- 播放器请求当前集的弹幕(如 S01E01)
- 系统检查下一集(S01E02)是否存在
- 如果下一集存在但没有弹幕,触发后台下载任务
- 下载完成后,用户播放下一集时弹幕已准备就绪
优势:
- 提升观看体验: 播放下一集时弹幕已准备好
- 减少等待时间: 无需等待弹幕下载
- 无感知下载: 后台自动完成,不影响当前播放
依赖条件:
- 需要启用"匹配后备"或"后备搜索"
- 如果两者都未启用,此选项将被禁用
匹配后备Token授权
功能说明: 为匹配后备功能配置专用的API Token,用于访问第三方弹幕源。
配置项:
Token列表: 添加多个Token,系统会自动轮换使用Token状态: 显示每个Token的可用状态和剩余配额
使用场景:
- 某些弹幕源需要API Token才能访问
- 提高API调用限额(多个Token轮换使用)
- 避免单个Token被限流
匹配后备黑名单
功能说明: 配置匹配后备功能的黑名单,阻止特定作品或源被自动导入。
配置项:
作品黑名单: 阻止特定作品的弹幕被自动导入源黑名单: 阻止特定弹幕源的内容被自动导入
使用场景:
- 某些作品的弹幕质量差,不希望自动导入
- 某些弹幕源经常匹配错误,需要屏蔽
- 避免导入不需要的内容
常见问题
Q: 匹配后备和后备搜索有什么区别?
A:
- 匹配后备: 播放器使用
/match接口时触发,自动匹配并导入弹幕 - 后备搜索: 播放器使用
/search/anime接口时触发,返回搜索结果供用户选择
Q: 为什么顺延机制和预下载被禁用?
A: 这两个功能依赖于"匹配后备"或"后备搜索"。如果两者都未启用,这两个功能将被禁用。
Q: 预下载会影响性能吗?
A: 不会。预下载是异步后台任务,不会阻塞当前播放或影响系统性能。