255 lines
6.7 KiB
Markdown
255 lines
6.7 KiB
Markdown
# LunaTV 弹幕功能集成说明
|
||
|
||
## 概述
|
||
|
||
LunaTV 已成功集成弹幕功能，支持自动搜索、手动选择和实时显示弹幕。弹幕数据来自 danmu_api 项目。
|
||
|
||
## 前置条件
|
||
|
||
### 1. 启动 danmu_api 服务
|
||
|
||
在使用弹幕功能之前，需要先启动 danmu_api 服务：
|
||
|
||
```bash
|
||
cd D:\projects\danmu_api
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
默认情况下，danmu_api 服务将在 http://localhost:9321 启动。
|
||
|
||
### 2. 配置环境变量（可选）
|
||
|
||
弹幕请求通过 LunaTV 后端代理转发，需要在后端配置 danmu_api 的地址。
|
||
|
||
如果您的 danmu_api 服务运行在不同的地址或使用了自定义 token，可以在项目根目录创建 `.env.local` 文件：
|
||
|
||
```env
|
||
# 弹幕 API 地址（默认: http://localhost:9321）
|
||
DANMAKU_API_BASE=http://localhost:9321
|
||
|
||
# 弹幕 API Token（默认: 87654321）
|
||
DANMAKU_API_TOKEN=87654321
|
||
```
|
||
|
||
**注意**：
|
||
- 环境变量配置的是服务端地址，不是浏览器端
|
||
- 如果 danmu_api 和 LunaTV 在同一台机器，使用默认配置即可
|
||
- 如果在不同机器，请使用完整的 URL（如 `http://192.168.1.100:9321`）
|
||
|
||
## 功能特性
|
||
|
||
### 1. 弹幕选项卡
|
||
|
||
- 位置：视频播放页面，在"选集"和"换源"选项卡之上
|
||
- 功能：
|
||
- 搜索动漫弹幕
|
||
- 浏览搜索结果
|
||
- 选择剧集并加载弹幕
|
||
- 显示当前选择的弹幕信息
|
||
|
||
### 2. 自动搜索弹幕
|
||
|
||
- 视频播放时自动根据视频标题搜索并加载弹幕
|
||
- 自动记忆上次选择的弹幕源
|
||
- 根据当前集数智能匹配对应的弹幕
|
||
|
||
### 3. 弹幕播放器控制
|
||
|
||
在播放器设置菜单中提供以下弹幕控制选项：
|
||
|
||
#### 弹幕开关
|
||
- 一键开启/关闭弹幕显示
|
||
|
||
#### 弹幕不透明度
|
||
- 10%、25%、50%、75%、100% 五档可选
|
||
- 默认：75%
|
||
|
||
#### 弹幕字体大小
|
||
- 小（20px）
|
||
- 中（25px，默认）
|
||
- 大（30px）
|
||
- 特大（35px）
|
||
|
||
#### 弹幕速度
|
||
- 很慢、慢（默认）、正常、快、很快
|
||
|
||
### 4. 弹幕记忆功能
|
||
|
||
- 自动记忆每个视频的弹幕选择
|
||
- 下次播放同一视频时自动加载上次选择的弹幕
|
||
- 最多保存 100 个视频的弹幕选择记录
|
||
|
||
## 使用方法
|
||
|
||
### 手动搜索和选择弹幕
|
||
|
||
1. 打开视频播放页面
|
||
2. 点击"弹幕"选项卡
|
||
3. 在搜索框输入动漫名称
|
||
4. 点击"搜索"按钮
|
||
5. 在搜索结果中选择对应的动漫
|
||
6. 在剧集列表中选择当前集数
|
||
7. 弹幕会自动加载到播放器
|
||
|
||
### 自动搜索弹幕
|
||
|
||
- 视频播放时，系统会自动根据视频标题搜索弹幕
|
||
- 如果找到匹配的弹幕，会自动加载到播放器
|
||
- 如果有记忆的弹幕选择，会优先使用记忆的选择
|
||
|
||
### 控制弹幕显示
|
||
|
||
1. 点击播放器右下角的设置按钮
|
||
2. 在设置菜单中找到"弹幕开关"
|
||
3. 点击切换弹幕显示/隐藏
|
||
4. 可调整弹幕不透明度、字体大小、速度等参数
|
||
|
||
## 技术实现
|
||
|
||
### 架构设计
|
||
|
||
弹幕功能采用后端代理模式，所有弹幕请求通过 Next.js API 路由转发到 danmu_api：
|
||
|
||
```
|
||
前端组件 → Next.js API 路由 (代理) → danmu_api 服务 → 返回数据
|
||
```
|
||
|
||
**优点**：
|
||
- 前端不直接暴露 danmu_api 地址
|
||
- 避免 CORS 跨域问题
|
||
- 可在后端实现缓存和请求控制
|
||
- 更好的安全性
|
||
|
||
### 集成的文件
|
||
|
||
1. **类型定义**
|
||
- `src/lib/danmaku/types.ts` - 弹幕相关的类型定义
|
||
|
||
2. **前端 API 封装**
|
||
- `src/lib/danmaku/api.ts` - 弹幕 API 客户端（调用本地代理）
|
||
|
||
3. **后端代理路由**
|
||
- `src/app/api/danmaku/search/route.ts` - 搜索动漫代理
|
||
- `src/app/api/danmaku/episodes/route.ts` - 获取剧集列表代理
|
||
- `src/app/api/danmaku/comment/route.ts` - 获取弹幕代理
|
||
- `src/app/api/danmaku/match/route.ts` - 自动匹配代理
|
||
|
||
4. **弹幕管理面板**
|
||
- `src/components/DanmakuPanel.tsx` - 弹幕搜索和选择界面
|
||
|
||
5. **修改的文件**
|
||
- `src/components/EpisodeSelector.tsx` - 添加弹幕选项卡
|
||
- `src/app/play/page.tsx` - 集成弹幕到播放器
|
||
|
||
### 使用的插件
|
||
|
||
- `artplayer-plugin-danmuku` - ArtPlayer 官方弹幕插件
|
||
|
||
### 弹幕数据流
|
||
|
||
```
|
||
前端: 视频标题 → 调用 /api/danmaku/search
|
||
↓
|
||
后端代理: → 转发到 danmu_api
|
||
↓
|
||
danmu_api: 搜索弹幕 → 返回动漫列表
|
||
↓
|
||
前端: 选择动漫 → 调用 /api/danmaku/episodes
|
||
↓
|
||
后端代理: → 转发到 danmu_api
|
||
↓
|
||
danmu_api: → 返回剧集列表
|
||
↓
|
||
前端: 选择剧集 → 调用 /api/danmaku/comment
|
||
↓
|
||
后端代理: → 转发到 danmu_api
|
||
↓
|
||
danmu_api: → 返回弹幕数据
|
||
↓
|
||
前端: 转换格式 → 加载到播放器 → 显示弹幕
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **danmu_api 服务必须运行**
|
||
- 弹幕功能依赖 danmu_api 服务
|
||
- 确保服务在配置的地址和端口上运行
|
||
- 后端代理会自动转发请求，前端无需配置
|
||
|
||
2. **网络连接**
|
||
- LunaTV 服务器必须能够访问 danmu_api 服务
|
||
- 如果 danmu_api 在其他机器，确保网络可达
|
||
- 检查防火墙和端口开放情况
|
||
|
||
3. **环境变量配置**
|
||
- 配置在后端（`.env.local`），不是前端
|
||
- 修改配置后需要重启 Next.js 服务器
|
||
- 可参考 `.env.example` 文件
|
||
|
||
4. **弹幕数据源**
|
||
- 弹幕数据来自多个视频平台
|
||
- 部分视频可能没有匹配的弹幕
|
||
- 可在 danmu_api 中配置数据源优先级
|
||
|
||
5. **性能考虑**
|
||
- 弹幕数量较多时可能影响性能
|
||
- 可通过设置菜单调整弹幕显示数量
|
||
- 后端代理可添加缓存机制（未来实现）
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 弹幕无法显示？
|
||
|
||
**检查项：**
|
||
1. danmu_api 服务是否正常运行？
|
||
2. 浏览器控制台是否有错误信息？
|
||
3. 是否有匹配的弹幕数据？
|
||
4. 弹幕开关是否开启？
|
||
|
||
### Q2: 弹幕搜索失败？
|
||
|
||
**可能原因：**
|
||
1. danmu_api 服务未启动
|
||
2. 后端无法连接到 danmu_api（网络问题）
|
||
3. 环境变量配置错误（检查 `.env.local`）
|
||
4. 视频标题与弹幕库不匹配
|
||
|
||
**调试方法：**
|
||
1. 检查浏览器 Network 标签，查看 `/api/danmaku/search` 请求
|
||
2. 检查服务器日志，查看后端转发是否成功
|
||
3. 直接访问 danmu_api 测试是否正常：`http://localhost:9321/api/v2/search/anime?keyword=测试`
|
||
|
||
### Q3: 如何清除弹幕记忆？
|
||
|
||
打开浏览器开发者工具，在 Console 中执行：
|
||
```javascript
|
||
localStorage.removeItem('danmaku_memories');
|
||
```
|
||
|
||
### Q4: 如何重置弹幕设置？
|
||
|
||
在 Console 中执行：
|
||
```javascript
|
||
localStorage.removeItem('danmaku_settings');
|
||
```
|
||
|
||
## 未来改进方向
|
||
|
||
1. 支持弹幕发送功能
|
||
2. 添加弹幕过滤规则编辑界面
|
||
3. 支持更多弹幕数据源
|
||
4. 弹幕显示效果优化
|
||
5. 弹幕高级搜索功能
|
||
|
||
## 相关资源
|
||
|
||
- [danmu_api 项目](D:\projects\danmu_api)
|
||
- [ArtPlayer 文档](https://artplayer.org)
|
||
- [artplayer-plugin-danmuku 文档](https://github.com/zhw2590582/ArtPlayer/tree/master/packages/artplayer-plugin-danmuku)
|
||
|
||
---
|
||
|
||
**版本**: 1.0
|
||
**最后更新**: 2025-12-01
|