MoonTVPlus/EMBY_USAGE_GUIDE.md

Emby 集成使用指南

🎉 实现完成

Emby 已经成功集成到 MoonTVPlus 项目中！所有核心功能都已实现并可以使用。

---

📋 已实现的功能

1. 核心基础设施

• ✅ EmbyConfig 类型定义 (src/lib/admin.types.ts)
• ✅ Emby 客户端 (src/lib/emby.client.ts)

2. API 端点

• ✅ /api/emby/list - 媒体列表（分页）
• ✅ /api/emby/detail - 媒体详情
• ✅ /api/emby/cms-proxy/[token] - CMS API 代理（核心）
• ✅ /api/admin/emby - 管理配置

3. 前台集成

• ✅ 私人影库页面集成 CapsuleSwitch（OpenList ↔ Emby 切换）
• ✅ 播放页面支持 source=emby 参数

4. 管理面板

• ✅ Emby 配置区域（服务器地址、API Key、用户名/密码）
• ✅ 连接测试功能
• ✅ 保存配置功能

---

🚀 快速开始

步骤 1: 配置 Emby

1. 登录管理面板
2. 找到 "Emby 媒体库" 配置区域
3. 填写以下信息：
   • 服务器地址: 你的 Emby 服务器地址（如 http://192.168.1.100:8096）
   • API Key（推荐）: 在 Emby 设置中生成 API Key
   • 或者填写 用户名 和 密码
4. 点击 "测试连接" 验证配置
5. 点击 "保存配置"
6. 启用 "启用 Emby 媒体库" 开关

步骤 2: 访问私人影库

1. 访问 "私人影库" 页面
2. 使用顶部的 CapsuleSwitch 切换到 "Emby"
3. 浏览你的 Emby 媒体库
4. 点击任意视频即可播放

步骤 3: TVBOX 订阅（可选）

如果你启用了 TVBOX 订阅功能，Emby 会自动添加到订阅源中：

订阅地址格式:

http://your-domain.com/api/emby/cms-proxy/{TVBOX_SUBSCRIBE_TOKEN}

在 TVBOX 中添加此订阅源，即可在 TVBOX 中浏览和播放 Emby 媒体库。

---

🔧 配置说明

Emby 服务器地址

• 格式: http://IP:PORT 或 https://domain.com
• 示例: http://192.168.1.100:8096
• 注意: 确保 MoonTVPlus 服务器能够访问 Emby 服务器

认证方式

方式 1: API Key（推荐）

• 在 Emby 设置中生成 API Key
• 优点: 更安全，不需要存储密码
• 获取方式: Emby 设置 → 高级 → API Keys

方式 2: 用户名/密码

• 使用 Emby 用户账号
• 优点: 简单直接
• 注意: 密码会加密存储在数据库中

---

📖 功能特性

1. 网页播放

• 统一入口: 私人影库页面
• 无缝切换: CapsuleSwitch 在 OpenList 和 Emby 之间切换
• 完整支持: 电影、剧集、季、集
• 自动播放: 点击即播，无需额外配置

2. CMS-Proxy

Emby 的 CMS-Proxy 将 Emby 媒体库转换为苹果 CMS V10 格式，实现：

• ✅ 网页播放复用现有逻辑
• ✅ TVBOX 直接支持
• ✅ 统一接口，降低维护成本
• ✅ 扩展性强，未来可添加 Jellyfin、Plex 等

3. 播放链接

直接播放（默认）:

http://emby-server:8096/Videos/{itemId}/stream?Static=true&api_key={apiKey}

转码播放（可选）:

http://emby-server:8096/Videos/{itemId}/master.m3u8?api_key={apiKey}

---

🎯 使用场景

场景 1: 家庭媒体中心

• 在家中搭建 Emby 服务器
• 使用 MoonTVPlus 作为统一的观影入口
• 在私人影库中浏览和播放 Emby 媒体

场景 2: 多源聚合

• OpenList: 云存储媒体
• Emby: 本地媒体服务器
• CMS 源: 在线资源
• 统一在 MoonTVPlus 中管理和播放

场景 3: TVBOX 集成

• 在 TVBOX 中添加 Emby 订阅源
• 在电视上浏览和播放 Emby 媒体
• 无需单独安装 Emby 客户端

---

🔍 故障排查

问题 1: 连接测试失败

可能原因:

• Emby 服务器地址错误
• 网络不通（防火墙、端口未开放）
• API Key 或用户名/密码错误

解决方法:

1. 检查 Emby 服务器地址是否正确
2. 确保 MoonTVPlus 服务器能够访问 Emby 服务器
3. 验证 API Key 或用户名/密码是否正确
4. 检查 Emby 服务器日志

问题 2: 媒体列表为空

可能原因:

• Emby 媒体库为空
• 用户权限不足
• 媒体库未扫描完成

解决方法:

1. 在 Emby 中检查媒体库是否有内容
2. 确保使用的用户有访问媒体库的权限
3. 等待 Emby 完成媒体库扫描

问题 3: 播放失败

可能原因:

• 媒体文件损坏
• 网络带宽不足
• 浏览器不支持视频格式

解决方法:

1. 在 Emby 客户端中测试播放
2. 检查网络连接
3. 尝试使用其他浏览器
4. 考虑启用转码

---

📊 性能优化

1. 缓存策略

• 媒体列表缓存: 减少对 Emby 服务器的请求
• 播放链接缓存: 提高播放响应速度

2. 网络优化

• 使用本地网络: Emby 服务器和 MoonTVPlus 在同一网络
• 启用转码: 根据网络情况动态调整码率

3. 媒体库优化

• 定期清理无效媒体
• 使用 SSD 存储媒体文件
• 优化 Emby 服务器配置

---

🔐 安全建议

1. 使用 HTTPS: 在生产环境中使用 HTTPS 访问 Emby
2. 强密码: 使用强密码保护 Emby 账号
3. API Key: 优先使用 API Key 而不是用户名/密码
4. 防火墙: 限制 Emby 服务器的访问来源
5. 定期更新: 保持 Emby 和 MoonTVPlus 更新到最新版本

---

🎨 自定义

修改播放链接格式

编辑 src/lib/emby.client.ts 中的 getStreamUrl 方法：

getStreamUrl(itemId: string, direct: boolean = true): string {
  if (direct) {
    // 直接播放
    return `${this.serverUrl}/Videos/${itemId}/stream?Static=true&api_key=${this.apiKey}`;
  }
  // 转码播放
  return `${this.serverUrl}/Videos/${itemId}/master.m3u8?api_key=${this.apiKey}&VideoCodec=h264`;
}

添加媒体库过滤

在 src/lib/admin.types.ts 中的 EmbyConfig 添加 Libraries 字段，然后在 API 中使用：

const result = await client.getItems({
  ParentId: config.EmbyConfig.Libraries?.[0], // 指定媒体库
  IncludeItemTypes: 'Movie,Series',
  // ...
});

---

🚧 已知限制

1. 字幕支持: 当前版本不支持加载 Emby 字幕（计划中）
2. 转码设置: 不支持用户自定义转码参数（计划中）
3. 多用户: 不支持不同用户看到不同的媒体库（计划中）
4. 收藏同步: 不支持与 Emby 的收藏同步（计划中）

---

🔮 未来计划

• 字幕支持
• 转码设置
• 多用户支持
• 收藏同步
• 观看历史同步
• Jellyfin 支持（API 与 Emby 类似）
• Plex 支持

---

📞 支持

如果遇到问题或有建议，请：

1. 查看本文档的故障排查部分
2. 查看 Emby 服务器日志
3. 查看 MoonTVPlus 服务器日志
4. 在 GitHub 上提交 Issue

---

🎉 总结

Emby 集成为 MoonTVPlus 带来了强大的本地媒体服务器支持，通过 CMS-Proxy 的设计，实现了：

• ✅ 统一的播放体验
• ✅ TVBOX 无缝集成
• ✅ 代码复用和维护简化
• ✅ 良好的扩展性

享受你的 Emby 媒体库吧！🎬