617 lines
17 KiB
Markdown
617 lines
17 KiB
Markdown
# Emby 集成设计方案
|
||
|
||
## 一、可行性分析
|
||
|
||
### 1.1 Emby vs OpenList 对比
|
||
|
||
#### 相似点
|
||
| 特性 | OpenList | Emby |
|
||
|------|----------|------|
|
||
| 服务类型 | 外部 API 服务 | 外部 API 服务 |
|
||
| 认证方式 | 用户名/密码 + Token | API Key 或用户名/密码 |
|
||
| 媒体列表 | ✅ 提供 | ✅ 提供 |
|
||
| 播放链接 | ✅ 提供 | ✅ 提供 |
|
||
| 元数据 | 需自行获取 | ✅ 内置完整元数据 |
|
||
|
||
#### 关键差异
|
||
| 维度 | OpenList | Emby |
|
||
|------|----------|------|
|
||
| **元数据来源** | 项目通过 TMDB API 获取 | Emby 自带（已从 TMDB/TVDB 获取） |
|
||
| **API 结构** | 文件系统 API | 媒体库 API |
|
||
| **组织方式** | 文件夹结构 | 媒体库（Movies/TV Shows） |
|
||
| **播放链接** | 云存储直链 | 流媒体 URL（支持转码） |
|
||
| **复杂度** | 需要文件名解析 + TMDB 查询 | 直接使用 Emby 元数据 |
|
||
|
||
### 1.2 可行性结论
|
||
|
||
**✅ 完全可行！** Emby 的集成甚至比 OpenList 更简单，因为：
|
||
- Emby 自带完整元数据系统
|
||
- API 更加成熟和标准化
|
||
- 不需要复杂的文件名解析和 TMDB 查询
|
||
- 媒体已经按照标准格式组织
|
||
|
||
---
|
||
|
||
## 二、CMS-Proxy 实现方案
|
||
|
||
### 2.1 为什么使用 CMS-Proxy
|
||
|
||
项目本身是聚合 CMS API 的（苹果 CMS V10 格式），使用 CMS-Proxy 的优势：
|
||
|
||
1. **网页播放**：复用现有播放逻辑，无需单独开发
|
||
2. **TVBOX 支持**：直接支持，无需额外适配
|
||
3. **代码复用**：统一接口，降低维护成本
|
||
4. **扩展性强**：未来添加其他源（如 Jellyfin）只需实现 cms-proxy
|
||
|
||
### 2.2 CMS API 格式要求
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"msg": "数据列表",
|
||
"page": 1,
|
||
"pagecount": 1,
|
||
"limit": 20,
|
||
"total": 100,
|
||
"list": [
|
||
{
|
||
"vod_id": "唯一ID",
|
||
"vod_name": "视频名称",
|
||
"vod_pic": "海报URL",
|
||
"vod_remarks": "备注（如'电影'/'剧集'）",
|
||
"vod_year": "年份",
|
||
"vod_content": "简介",
|
||
"vod_play_from": "播放源名称",
|
||
"vod_play_url": "第1集$url1#第2集$url2#第3集$url3",
|
||
"type_name": "类型"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2.3 Emby 数据映射
|
||
|
||
```typescript
|
||
// Emby Item → CMS Format
|
||
{
|
||
vod_id: item.Id,
|
||
vod_name: item.Name,
|
||
vod_pic: `${embyUrl}/Items/${item.Id}/Images/Primary`,
|
||
vod_remarks: item.Type === 'Movie' ? '电影' : '剧集',
|
||
vod_year: item.ProductionYear?.toString() || '',
|
||
vod_content: item.Overview || '',
|
||
vod_play_from: 'Emby',
|
||
vod_play_url: buildPlayUrl(item),
|
||
type_name: item.Type === 'Movie' ? '电影' : '电视剧'
|
||
}
|
||
```
|
||
|
||
### 2.4 核心实现
|
||
|
||
#### 路由结构
|
||
```
|
||
/api/emby/cms-proxy/[token]?ac=videolist&wd=关键词
|
||
/api/emby/cms-proxy/[token]?ac=detail&ids=视频ID
|
||
```
|
||
|
||
#### 关键逻辑
|
||
|
||
**1. 搜索/列表**
|
||
```typescript
|
||
async function handleSearch(client: EmbyClient, query: string) {
|
||
const items = await client.getItems({
|
||
searchTerm: query,
|
||
IncludeItemTypes: 'Movie,Series',
|
||
Recursive: true,
|
||
Fields: 'Overview,ProductionYear',
|
||
Limit: 100
|
||
});
|
||
|
||
return items.map(item => ({
|
||
vod_id: item.Id,
|
||
vod_name: item.Name,
|
||
vod_pic: getEmbyImageUrl(item.Id),
|
||
vod_remarks: item.Type === 'Movie' ? '电影' : '剧集',
|
||
vod_year: item.ProductionYear?.toString() || '',
|
||
vod_content: item.Overview || '',
|
||
type_name: item.Type === 'Movie' ? '电影' : '电视剧'
|
||
}));
|
||
}
|
||
```
|
||
|
||
**2. 详情（关键）**
|
||
```typescript
|
||
async function handleDetail(client: EmbyClient, itemId: string) {
|
||
const item = await client.getItem(itemId);
|
||
|
||
let vodPlayUrl = '';
|
||
|
||
if (item.Type === 'Movie') {
|
||
// 电影：单个播放链接
|
||
const playUrl = buildPlayUrl(client, itemId);
|
||
vodPlayUrl = `正片$${playUrl}`;
|
||
} else if (item.Type === 'Series') {
|
||
// 剧集：获取所有季和集
|
||
const episodes = await getAllEpisodes(client, itemId);
|
||
vodPlayUrl = episodes
|
||
.map(ep => `第${ep.IndexNumber}集$${buildPlayUrl(client, ep.Id)}`)
|
||
.join('#');
|
||
}
|
||
|
||
return {
|
||
vod_id: item.Id,
|
||
vod_name: item.Name,
|
||
vod_play_url: vodPlayUrl,
|
||
vod_play_from: 'Emby',
|
||
// ... 其他字段
|
||
};
|
||
}
|
||
```
|
||
|
||
**3. 播放链接构建**
|
||
```typescript
|
||
function buildPlayUrl(client: EmbyClient, itemId: string): string {
|
||
// 方案 1: 直接返回 Emby 流媒体链接（推荐）
|
||
return `${client.serverUrl}/Videos/${itemId}/stream?api_key=${client.apiKey}&Static=true`;
|
||
|
||
// 方案 2: 通过项目代理（支持去广告等功能）
|
||
const baseUrl = process.env.SITE_BASE;
|
||
const token = process.env.TVBOX_SUBSCRIBE_TOKEN;
|
||
return `${baseUrl}/api/emby/play/${token}?id=${itemId}`;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、前台页面集成方案
|
||
|
||
### 3.1 设计思路
|
||
|
||
将 Emby 集成到现有的"私人影库"页面，使用 **CapsuleSwitch** 组件切换 OpenList 和 Emby。
|
||
|
||
**优势：**
|
||
- 统一入口，用户体验更好
|
||
- 复用现有 UI 组件（VideoCard、分页等）
|
||
- 代码更简洁，维护成本低
|
||
|
||
### 3.2 页面结构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 私人影库 │
|
||
│ 观看自我收藏的高清视频吧 │
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────┐ │
|
||
│ │ OpenList │ Emby │ ← CapsuleSwitch
|
||
│ └─────────────────────────┘ │
|
||
│ │
|
||
├─────────────────────────────────────────┤
|
||
│ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │
|
||
│ │ │ │ │ │ │ │ │ │ │ │
|
||
│ └───┘ └───┘ └───┘ └───┘ └───┘ │
|
||
│ │
|
||
│ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │
|
||
│ │ │ │ │ │ │ │ │ │ │ │
|
||
│ └───┘ └───┘ └───┘ └───┘ └───┘ │
|
||
│ │
|
||
├─────────────────────────────────────────┤
|
||
│ 上一页 第 1 / 5 页 下一页 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.3 核心代码
|
||
|
||
```typescript
|
||
// src/app/private-library/page.tsx
|
||
|
||
'use client';
|
||
|
||
import { useState, useEffect } from 'react';
|
||
import CapsuleSwitch from '@/components/CapsuleSwitch';
|
||
import VideoCard from '@/components/VideoCard';
|
||
|
||
type LibrarySource = 'openlist' | 'emby';
|
||
|
||
export default function PrivateLibraryPage() {
|
||
const [source, setSource] = useState<LibrarySource>('openlist');
|
||
const [videos, setVideos] = useState([]);
|
||
const [page, setPage] = useState(1);
|
||
|
||
// 切换源时重置页码
|
||
useEffect(() => {
|
||
setPage(1);
|
||
}, [source]);
|
||
|
||
useEffect(() => {
|
||
const endpoint = source === 'openlist'
|
||
? `/api/openlist/list?page=${page}`
|
||
: `/api/emby/list?page=${page}`;
|
||
|
||
fetch(endpoint).then(res => res.json()).then(setVideos);
|
||
}, [page, source]);
|
||
|
||
return (
|
||
<div>
|
||
<h1>私人影库</h1>
|
||
|
||
{/* 源切换器 */}
|
||
<CapsuleSwitch
|
||
options={[
|
||
{ label: 'OpenList', value: 'openlist' },
|
||
{ label: 'Emby', value: 'emby' }
|
||
]}
|
||
active={source}
|
||
onChange={(value) => setSource(value as LibrarySource)}
|
||
/>
|
||
|
||
{/* 视频网格 */}
|
||
<div className="grid">
|
||
{videos.map(video => (
|
||
<VideoCard key={video.id} {...video} source={source} />
|
||
))}
|
||
</div>
|
||
|
||
{/* 分页 */}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、完整实现步骤
|
||
|
||
### Phase 1: 基础设施
|
||
|
||
#### 1. 配置类型定义
|
||
```typescript
|
||
// src/lib/admin.types.ts
|
||
|
||
interface EmbyConfig {
|
||
Enabled: boolean
|
||
ServerURL: string // Emby 服务器地址
|
||
ApiKey?: string // API Key（推荐）
|
||
Username?: string // 或使用用户名/密码
|
||
Password?: string
|
||
UserId?: string // 用户 ID
|
||
Libraries?: string[] // 要显示的媒体库 ID
|
||
EnableTranscoding?: boolean // 是否启用转码
|
||
MaxBitrate?: number // 最大码率
|
||
LastSyncTime?: number
|
||
ItemCount?: number
|
||
}
|
||
```
|
||
|
||
#### 2. Emby 客户端
|
||
```typescript
|
||
// src/lib/emby.client.ts
|
||
|
||
export class EmbyClient {
|
||
private serverUrl: string
|
||
private apiKey?: string
|
||
private userId?: string
|
||
|
||
constructor(config: EmbyConfig) {
|
||
this.serverUrl = config.ServerURL.replace(/\/$/, '')
|
||
this.apiKey = config.ApiKey
|
||
this.userId = config.UserId
|
||
}
|
||
|
||
// 核心方法
|
||
async authenticate(username: string, password: string): Promise<AuthResult>
|
||
async getLibraries(): Promise<Library[]>
|
||
async getItems(params: GetItemsParams): Promise<ItemsResult>
|
||
async getItem(itemId: string): Promise<EmbyItem>
|
||
async getSeasons(seriesId: string): Promise<Season[]>
|
||
async getEpisodes(seriesId: string, seasonId: string): Promise<Episode[]>
|
||
async checkConnectivity(): Promise<boolean>
|
||
}
|
||
```
|
||
|
||
### Phase 2: API 端点
|
||
|
||
#### 1. CMS-Proxy（核心）
|
||
```
|
||
src/app/api/emby/cms-proxy/[token]/route.ts
|
||
```
|
||
- 支持搜索：`?ac=videolist&wd=关键词`
|
||
- 支持详情：`?ac=detail&ids=视频ID`
|
||
- 支持列表：`?ac=videolist`
|
||
- 返回苹果 CMS V10 格式
|
||
|
||
#### 2. 列表 API
|
||
```
|
||
src/app/api/emby/list/route.ts
|
||
```
|
||
- 用于前台页面显示
|
||
- 支持分页
|
||
- 返回格式与 OpenList 一致
|
||
|
||
#### 3. 详情 API
|
||
```
|
||
src/app/api/emby/detail/route.ts
|
||
```
|
||
- 获取媒体详情
|
||
- 获取剧集列表
|
||
- 返回播放链接
|
||
|
||
#### 4. 播放代理（可选）
|
||
```
|
||
src/app/api/emby/play/[token]/route.ts
|
||
```
|
||
- 代理播放请求
|
||
- 支持去广告等功能
|
||
|
||
#### 5. 管理 API
|
||
```
|
||
src/app/api/admin/emby/route.ts
|
||
```
|
||
- 保存/更新 Emby 配置
|
||
- 测试连接
|
||
- 同步媒体库
|
||
|
||
### Phase 3: 前台集成
|
||
|
||
#### 1. 修改私人影库页面
|
||
```
|
||
src/app/private-library/page.tsx
|
||
```
|
||
- 添加 CapsuleSwitch 组件
|
||
- 支持切换 OpenList/Emby
|
||
- 复用现有 VideoCard 和分页逻辑
|
||
|
||
#### 2. 修改播放页面
|
||
```
|
||
src/app/play/page.tsx
|
||
```
|
||
- 支持 `source=emby` 参数
|
||
- 处理 Emby 播放链接
|
||
|
||
#### 3. 管理面板集成
|
||
```
|
||
src/app/admin/page.tsx
|
||
```
|
||
- 添加 Emby 配置区域
|
||
- 连接测试
|
||
- 媒体库同步
|
||
|
||
#### 4. 导航集成
|
||
```
|
||
src/components/Sidebar.tsx
|
||
```
|
||
- 保持"私人影库"入口不变
|
||
- 内部通过 CapsuleSwitch 切换
|
||
|
||
### Phase 4: TVBOX 集成
|
||
|
||
#### 修改订阅接口
|
||
```typescript
|
||
// src/app/api/tvbox/subscribe/[token]/route.ts
|
||
|
||
const sites = [
|
||
// 现有的 CMS 站点
|
||
...existingSites,
|
||
|
||
// 添加 OpenList
|
||
{
|
||
key: 'openlist',
|
||
name: '私人影库-OpenList',
|
||
type: 1,
|
||
api: `${baseUrl}/api/cms-proxy?api=openlist`,
|
||
searchable: 1
|
||
},
|
||
|
||
// 添加 Emby
|
||
{
|
||
key: 'emby',
|
||
name: '私人影库-Emby',
|
||
type: 1,
|
||
api: `${baseUrl}/api/emby/cms-proxy/${token}`,
|
||
searchable: 1
|
||
}
|
||
];
|
||
```
|
||
|
||
---
|
||
|
||
## 五、文件结构
|
||
|
||
```
|
||
src/
|
||
├── app/
|
||
│ ├── api/
|
||
│ │ ├── admin/
|
||
│ │ │ └── emby/
|
||
│ │ │ └── route.ts # Emby 配置管理
|
||
│ │ └── emby/
|
||
│ │ ├── cms-proxy/
|
||
│ │ │ └── [token]/
|
||
│ │ │ └── route.ts # CMS API 代理（核心）
|
||
│ │ ├── list/
|
||
│ │ │ └── route.ts # 媒体列表
|
||
│ │ ├── detail/
|
||
│ │ │ └── route.ts # 媒体详情
|
||
│ │ └── play/
|
||
│ │ └── [token]/
|
||
│ │ └── route.ts # 播放代理（可选）
|
||
│ ├── private-library/
|
||
│ │ └── page.tsx # 私人影库页面（集成 CapsuleSwitch）
|
||
│ └── admin/
|
||
│ └── page.tsx # 管理面板（添加 Emby 配置）
|
||
├── lib/
|
||
│ ├── emby.client.ts # Emby API 客户端
|
||
│ ├── emby-adapter.ts # 数据适配器
|
||
│ ├── emby-cache.ts # 缓存层（可选）
|
||
│ └── admin.types.ts # 类型定义（添加 EmbyConfig）
|
||
└── components/
|
||
├── CapsuleSwitch.tsx # 切换组件（已存在）
|
||
└── VideoCard.tsx # 视频卡片（已存在）
|
||
```
|
||
|
||
---
|
||
|
||
## 六、关键技术点
|
||
|
||
### 6.1 Emby API 认证
|
||
|
||
```typescript
|
||
// 方式 1: API Key（推荐）
|
||
const headers = {
|
||
'X-Emby-Token': apiKey
|
||
}
|
||
|
||
// 方式 2: 用户认证
|
||
const authResponse = await fetch(`${serverUrl}/Users/AuthenticateByName`, {
|
||
method: 'POST',
|
||
body: JSON.stringify({ Username: username, Pw: password })
|
||
});
|
||
const { AccessToken, User } = await authResponse.json();
|
||
```
|
||
|
||
### 6.2 获取媒体列表
|
||
|
||
```typescript
|
||
// GET /Users/{userId}/Items
|
||
const params = new URLSearchParams({
|
||
ParentId: libraryId,
|
||
IncludeItemTypes: 'Movie,Series',
|
||
Recursive: 'true',
|
||
Fields: 'Overview,ProductionYear',
|
||
StartIndex: '0',
|
||
Limit: '20'
|
||
});
|
||
```
|
||
|
||
### 6.3 获取播放链接
|
||
|
||
```typescript
|
||
// 直接播放（无转码）
|
||
const playUrl = `${serverUrl}/Videos/${itemId}/stream?api_key=${apiKey}&Static=true`;
|
||
|
||
// 转码播放
|
||
const playUrl = `${serverUrl}/Videos/${itemId}/master.m3u8?api_key=${apiKey}&VideoCodec=h264`;
|
||
```
|
||
|
||
### 6.4 获取剧集
|
||
|
||
```typescript
|
||
// 获取季列表
|
||
const seasons = await fetch(`${serverUrl}/Shows/${seriesId}/Seasons?userId=${userId}`);
|
||
|
||
// 获取某季的所有集
|
||
const episodes = await fetch(`${serverUrl}/Shows/${seriesId}/Episodes?seasonId=${seasonId}`);
|
||
```
|
||
|
||
---
|
||
|
||
## 七、优势总结
|
||
|
||
### 7.1 相比传统方式
|
||
|
||
| 特性 | 传统方式 | CMS-Proxy 方式 |
|
||
|------|---------|---------------|
|
||
| **网页播放** | 需要单独开发 Emby 播放页面 | 复用现有播放逻辑 |
|
||
| **TVBOX 支持** | 需要单独适配 | 直接支持，无需额外开发 |
|
||
| **代码复用** | 低 | 高 |
|
||
| **维护成本** | 高（两套逻辑） | 低（统一接口） |
|
||
| **扩展性** | 每个源都要适配 | 新增源只需实现 cms-proxy |
|
||
|
||
### 7.2 相比 OpenList
|
||
|
||
| 维度 | OpenList | Emby |
|
||
|------|----------|------|
|
||
| **实现复杂度** | 复杂（需要文件名解析 + TMDB 查询） | 简单（直接使用 Emby 元数据） |
|
||
| **元数据质量** | 依赖 TMDB API | Emby 自带完整元数据 |
|
||
| **播放能力** | 云存储直链 | 支持转码、字幕、多音轨 |
|
||
| **媒体组织** | 基于文件夹 | 标准媒体库结构 |
|
||
|
||
---
|
||
|
||
## 八、预估工作量
|
||
|
||
- **核心功能**：约 800-1000 行代码
|
||
- **完整集成**：约 1200-1500 行代码
|
||
- **开发时间**：2-3 天（有 OpenList 参考）
|
||
|
||
### 代码量分解
|
||
|
||
| 模块 | 代码量 | 说明 |
|
||
|------|--------|------|
|
||
| Emby 客户端 | 200-300 行 | API 封装 |
|
||
| CMS-Proxy | 300-400 行 | 核心转换逻辑 |
|
||
| 列表/详情 API | 200-300 行 | 前台接口 |
|
||
| 前台页面修改 | 100-150 行 | CapsuleSwitch 集成 |
|
||
| 管理面板 | 150-200 行 | 配置界面 |
|
||
| 类型定义 | 50-100 行 | TypeScript 类型 |
|
||
| **总计** | **1000-1450 行** | |
|
||
|
||
---
|
||
|
||
## 九、实现建议
|
||
|
||
1. **优先使用 API Key 认证**（比用户名/密码更简单）
|
||
2. **实现良好的缓存策略**（减少对 Emby 服务器的请求）
|
||
3. **支持多媒体库**（让用户选择显示哪些库）
|
||
4. **考虑转码选项**（根据网络情况动态调整）
|
||
5. **复用现有组件**（VideoCard、播放器等）
|
||
6. **先实现 CMS-Proxy**（这样 TVBOX 和网页都能用）
|
||
7. **再实现前台集成**（CapsuleSwitch 切换）
|
||
|
||
---
|
||
|
||
## 十、测试计划
|
||
|
||
### 10.1 功能测试
|
||
|
||
- [ ] Emby 连接测试
|
||
- [ ] 媒体列表获取（电影/剧集）
|
||
- [ ] 搜索功能
|
||
- [ ] 详情页面（电影/剧集）
|
||
- [ ] 播放功能（直接播放/转码）
|
||
- [ ] 剧集切换
|
||
- [ ] 分页功能
|
||
- [ ] CapsuleSwitch 切换
|
||
|
||
### 10.2 集成测试
|
||
|
||
- [ ] 网页播放测试
|
||
- [ ] TVBOX 订阅测试
|
||
- [ ] TVBOX 搜索测试
|
||
- [ ] TVBOX 播放测试
|
||
- [ ] OpenList 和 Emby 切换测试
|
||
|
||
### 10.3 性能测试
|
||
|
||
- [ ] 大型媒体库加载速度
|
||
- [ ] 缓存效果验证
|
||
- [ ] 并发请求处理
|
||
|
||
---
|
||
|
||
## 十一、后续扩展
|
||
|
||
### 可能的增强功能
|
||
|
||
1. **媒体库过滤**：按类型、年份、评分过滤
|
||
2. **收藏功能**：标记喜欢的媒体
|
||
3. **观看历史**：记录播放进度
|
||
4. **字幕支持**：加载 Emby 字幕
|
||
5. **转码设置**：用户自定义转码参数
|
||
6. **多用户支持**：不同用户看到不同的媒体库
|
||
7. **Jellyfin 支持**：Jellyfin API 与 Emby 类似，可以复用大部分代码
|
||
|
||
---
|
||
|
||
## 十二、总结
|
||
|
||
Emby 集成方案通过 **CMS-Proxy** 和 **CapsuleSwitch** 的组合，实现了：
|
||
|
||
✅ **统一接口**：网页和 TVBOX 都使用 CMS API 格式
|
||
✅ **统一入口**：私人影库页面集成 OpenList 和 Emby
|
||
✅ **代码复用**：最大化复用现有组件和逻辑
|
||
✅ **扩展性强**：未来添加其他源（Jellyfin、Plex）只需实现 cms-proxy
|
||
✅ **用户体验好**：无缝切换，流畅播放
|
||
|
||
这是一个**优雅、高效、可扩展**的设计方案！
|