解锁Emby/Jellyfin媒体播放新境界：本地播放器深度集成与进度同步完全指南

【免费下载链接】embyToLocalPlayeretlp - Emby/Jellyfin 调用外部本地播放器，并回传播放记录。适配 Plex。项目地址: https://gitcode.com/gh_mirrors/em/embyToLocalPlayer

你是否厌倦了Emby、Jellyfin或Plex内置播放器的限制？想要使用自己熟悉的PotPlayer、mpv或VLC，却又不想放弃媒体库的观看进度同步功能？embyToLocalPlayer正是解决这一痛点的完美工具。这个开源项目让你能够在Emby/Jellyfin网页中直接调用本地播放器，同时自动回传播放记录到媒体服务器，实现播放器自由与进度同步的双重体验。

🎯 核心功能亮点：不只是简单的播放器调用

多播放器无缝切换支持

embyToLocalPlayer支持市面上几乎所有主流播放器，包括mpv系列、PotPlayer、MPC-HC/BE、VLC以及macOS上的IINA。通过简单的配置文件修改，你可以轻松切换默认播放器。项目提供了embyToLocalPlayer_config.ini配置文件，让你可以灵活配置各种播放器路径：

[exe] mpv = C:\Green\mpv\mpv.exe pot = C:\Program Files\DAUM\PotPlayer\PotPlayerMini64.exe vlc = C:\Green\vlc\vlc.exe iina = /Applications/IINA.app/Contents/MacOS/iina-cli

embyToLocalPlayer与Emby完美集成，在播放界面显示详细的媒体信息和豆瓣评分

智能播放进度同步机制

最令人印象深刻的是其播放进度同步功能。当你使用本地播放器观看影片时，工具会实时记录播放位置，并在播放器关闭时自动同步到媒体服务器。这意味着你可以：

1. 在电脑上用PotPlayer观看电影
2. 关闭播放器后，进度自动保存到Emby服务器
3. 在手机或电视上继续从上次停止的位置观看

这种无缝的进度同步体验，让本地播放器的强大功能与媒体服务器的便利性完美结合。

高级播放列表管理

embyToLocalPlayer支持连续播放功能，能够自动加载下一集并保持相同版本。这对于追剧用户来说极为便利，无需手动选择每一集。配置文件中的播放列表设置允许你精细控制：

[playlist] enable_host = local, 127.0, 192.168, 192-168-, example.com:8096 version_filter = 720|1080|2160|4k|remux|hevc|265|264 item_limit = -1

🔧 安装配置：三步完成部署

第一步：安装浏览器扩展

首先需要安装用户脚本管理器，推荐使用Tampermonkey或Violentmonkey。然后安装embyToLocalPlayer的用户脚本，该脚本会在Emby/Jellyfin网页中添加调用本地播放器的功能。

第二步：下载并配置后端服务

从项目仓库下载最新版本：

git clone https://gitcode.com/gh_mirrors/em/embyToLocalPlayer

根据你的操作系统选择对应的版本：

• Windows用户推荐使用etlp-mpv-py-embed-win32.zip（包含mpv播放器）
• 跨平台用户使用embyToLocalPlayer.zip（需要Python环境）

第三步：编辑配置文件

复制配置文件模板并编辑embyToLocalPlayer_config.ini：

[emby] player = mpv # 选择你喜欢的播放器 update_progress = yes # 启用进度回传 fullscreen = yes # 自动全屏 [src] # 服务器端路径前缀 a = /mnt/disk1/media [dst] # 本地路径前缀 a = D:\Media

集成Bangumi功能，自动同步番剧观看进度到bgm.tv，实现跨平台追番记录管理

🚀 高级功能探索

路径转换与本地文件访问

如果你的媒体文件同时存在于服务器和本地，可以启用"读取硬盘模式"。这种模式下，工具会将服务器路径转换为本地路径，直接从本地硬盘播放，避免网络传输延迟：

[src] a = /mnt/nas/media/movies b = /mnt/nas/media/tvshows [dst] a = E:\Media\Movies b = F:\Media\TVShows

第三方服务集成

embyToLocalPlayer支持与bangumi.tv和Trakt.tv同步观看记录。这意味着你的观看历史可以自动同步到这些第三方服务：

[bangumi] enable_host = localhost, 127.0.0.1 username = your_bgm_username access_token = your_bgm_token [trakt] enable_host = example.com:8096 user_name = your_trakt_username client_id = your_client_id client_secret = your_client_secret

下载完成自动播放

与qbittorrent WebUI集成，实现下载完成后的自动播放功能。通过安装qbittorrent_webui_open_file.js脚本，可以在下载完成后直接调用本地播放器：

qBittorrent WebUI集成，下载完成后显示"打开播放"按钮，一键启动本地播放器

⚙️ 技术实现深度解析

HTTP服务器架构

embyToLocalPlayer的核心是一个本地HTTP服务器（默认运行在127.0.0.1:58000），它作为浏览器脚本与本地播放器之间的桥梁。当你在Emby网页点击播放时：

1. 用户脚本拦截播放请求
2. 向本地HTTP服务器发送媒体信息
3. HTTP服务器启动本地播放器并传递播放参数
4. 播放器关闭时，进度信息回传到HTTP服务器
5. HTTP服务器更新Emby服务器的播放进度

播放器接口统一化

项目通过utils/players.py模块实现了对不同播放器的统一接口封装。每个播放器都有对应的启动函数和进度获取函数：

# 播放器启动函数示例 def mpv_player_start(cmd, start_sec=None, sub_file=None, media_title=None, get_stop_sec=True, mount_disk_mode=None): # 启动mpv播放器 pass def pot_player_start(cmd: list, start_sec=None, sub_file=None, media_title=None, get_stop_sec=True): # 启动PotPlayer pass

配置管理系统

utils/configs.py模块提供了强大的配置管理功能，支持动态配置加载、路径转换、播放器选择等。配置文件采用INI格式，支持复杂的条件匹配和路径映射。

🔍 故障排除与优化技巧

常见问题解决方案

播放器无法启动问题：

1. 检查播放器路径是否正确（Windows注意使用双反斜杠）
2. 确保播放器支持命令行参数
3. 查看日志文件./log.txt获取详细错误信息

进度同步失败处理：

1. 确认Emby API密钥和用户ID配置正确
2. 检查网络连接是否正常
3. 增加同步频率：[emby]部分设置update_progress = yes

播放列表相关问题：

1. 确保播放器支持播放列表功能
2. 检查版本过滤规则是否过于严格
3. 查看播放器是否支持外挂字幕的连续播放

性能优化建议

1. 启用路径转换缓存：对于经常访问的媒体路径，启用缓存可以显著提升启动速度
2. 调整同步间隔：根据网络状况调整进度同步频率
3. 使用本地文件模式：如果媒体文件在本地有副本，优先使用本地路径播放
4. 合理配置播放器参数：根据硬件性能调整播放器启动参数

📊 实际应用场景

家庭媒体中心部署

在家庭NAS上部署Emby/Jellyfin服务器，配合embyToLocalPlayer实现：

• 在客厅电视上使用Kodi观看
• 在书房电脑上使用mpv观看
• 在卧室平板上使用内置播放器观看 所有设备共享同一观看进度

多版本媒体管理

对于收藏了多种版本（如1080p、4K、Remux）的影视作品，embyToLocalPlayer的版本过滤功能可以确保连续播放时保持相同画质版本：

[dev] version_prefer = remux, 4k, 1080p, web-dl

跨平台追番系统

结合Bangumi同步功能，实现：

1. 在Emby中观看动漫
2. 自动标记bgm.tv上的观看进度
3. 在手机App上查看追番进度
4. 多设备间无缝切换观看

🛠️ 进阶配置与自定义

自定义播放器参数

你可以在配置文件中为不同播放器添加自定义参数：

[dev] # mpv额外参数 mpv_args = --hwdec=auto --vo=gpu-next # PotPlayer额外参数 pot_args = /seek=0 /fullscreen

智能字幕处理

embyToLocalPlayer支持智能字幕选择，可以根据语言偏好自动选择字幕：

[dev] subtitle_priority = 中英特效, 双语特效, 简中特效, 简体, 中, chi, eng

网络优化配置

对于网络环境复杂的用户，可以配置代理和缓存策略：

[dev] use_system_proxy = yes script_proxy = http://127.0.0.1:7890 player_proxy = http://127.0.0.1:7890

🎯 最佳实践建议

系统兼容性优化

• Windows用户：推荐使用便携版mpv，避免系统环境问题
• macOS用户：使用IINA播放器获得最佳体验
• Linux用户：通过flatpak安装mpv确保版本兼容性

播放器选择指南

• 追求极致性能：选择mpv，轻量级且高度可定制
• 需要图形界面：选择mpv.net或PotPlayer
• 跨平台需求：VLC是最佳选择
• macOS用户：IINA提供最佳原生体验

维护与更新策略

1. 定期检查项目更新，新版本可能修复重要问题
2. 备份配置文件，避免更新时丢失自定义设置
3. 参与社区讨论，分享使用经验和问题解决方案

结语：重新定义媒体播放体验

embyToLocalPlayer不仅仅是一个简单的播放器调用工具，它代表了媒体播放体验的进化方向。通过打破服务器内置播放器的限制，它为用户提供了：

• 播放器选择的完全自由
• 跨设备进度同步的无缝体验
• 高级功能的自定义能力
• 开源社区的持续支持

无论你是追求最佳画质的影音爱好者，还是需要多设备同步的家庭用户，embyToLocalPlayer都能提供完美的解决方案。现在就开始配置，享受真正自由的媒体播放体验吧！

项目还包含更多实用工具，如utils/bangumi_sync.py用于Bangumi同步、utils/trakt_sync.py用于Trakt集成、utils/gui.py提供图形界面等，等待你的深入探索。

【免费下载链接】embyToLocalPlayeretlp - Emby/Jellyfin 调用外部本地播放器，并回传播放记录。适配 Plex。项目地址: https://gitcode.com/gh_mirrors/em/embyToLocalPlayer