觅影 OmniPlay

May 14, 2026 · View on GitHub

觅影 OmniPlay 是一款原生开发的海报墙播放器，支持mac、win双系统。mac采用swift开发，win采用C# + .net + Avalonia UI。底层播放器核心为 MPVKit-GPL / libmpv / FFmpeg 相关组件。 ios版正在开发中。

软件截图

览影首页览影详情页

功能特色

UI

UI简洁且美观，海报墙没有做过多的分类功能，只有搜索、排序功能。

海报墙媒体库

支持海报墙和分集剧照
采用TMDB刮削，增加了更宽松的刮削规则和自定义编辑功能。避免重命名和硬链接。

媒体源管理

支持添加本地文件夹、WebDAV、SMB、plex、emby、jellyfin。mac版因为开发一直有bug，不支持SMB直连，请在访达中挂载SMB，再在软件中添加本地文件夹，间接连接SMB。可以将访达挂载的SMB添加到开机自启
不需要将电影、剧集分不同文件夹进行挂载，软件自动识别。

自动扫描与刮削

支持公共 TMDB 源，也支持自定义 TMDB API Key / v4 Token。公共源API做了限制，建议注册TMDB后获取API。如果TMDB api连通测试失败，请挂代理或改host。

离线缓存

支持一键将SMB、WebDAV下的影视离线至电脑，方便外出观影。

使用指南

由于软件设定不是扫描后就全部加载到首页，而是扫描刮削一个才显示一个，所以第一步先去设置里测试tmdb api连通性，建议去tmdb官网注册填写自己的api。如果测试不通，那么就需要挂代理。虽然改host按道理也行，但是我没有测试，建议直接挂代理。
点添加媒体源按钮添加挂载本地文件夹，通过SMB、Webdav连接局域网NAS，也可以连接jellyfin、emby、plex媒体服务器。但是建议SMB、Webdav直连。如果通过jellyfin、emby连接，软件的逻辑mkv等格式在觅影端解码，jellyfin、emby端只起传输作用。但是对BDMV、ISO格式，无法做到觅影端解码，只能jellyfin、emby端解码，再传输给觅影，播放效果没有通过jellyfin、emby连接好。
后面挂载文件夹后就是等待扫描刮削，然后观影。

自行编译教程

环境要求

建议环境：

macOS，版本需满足项目当前 MACOSX_DEPLOYMENT_TARGET。
Xcode，需包含项目当前使用的 macOS SDK。
可联网环境，用于首次解析 Swift Package 与下载二进制产物。
Apple Developer 账号或本地签名环境，用于导出可分发 App。

当前工程配置中：

PRODUCT_BUNDLE_IDENTIFIER = nan.OmniPlay
PRODUCT_NAME = 觅影
MARKETING_VERSION = 1.0
CURRENT_PROJECT_VERSION = 1
MACOSX_DEPLOYMENT_TARGET = 14.0
DEVELOPMENT_TEAM = DT95MB3RG4
ENABLE_HARDENED_RUNTIME = YES

如果你的系统或 Xcode SDK 低于工程配置，请在 Xcode 的 Build Settings 中调整 Deployment Target 后再编译。如果不是项目原签名团队成员，请在 Xcode 中修改 Team 和 Bundle Identifier，或改成本机调试签名后再归档导出。

依赖说明

主要依赖包括：

SwiftUI / AppKit：界面与 macOS 集成。
GRDB：SQLite 数据库访问，仓库内以本地 Swift Package 形式存在于 GRDB.swift-master/。
MPVKit-GPL：mpv 播放器相关 Swift Package。
FFmpeg / libmpv 相关二进制框架：用于媒体播放与解码链路。
TMDB API：用于媒体信息、海报和剧照刮削。

MPVKit 来源锁定在 OmniPlay.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved，当前为 https://github.com/mpvkit/MPVKit 的固定 revision。首次打开工程或首次命令行编译时，Xcode 会解析 Swift Package。若网络不可用，可能会停在依赖解析阶段。

使用 Xcode 编译运行

打开项目：
```
open OmniPlay.xcodeproj
```
在 Xcode 顶部 Scheme 选择 OmniPlay。
运行目标选择 My Mac。
如果需要自己的签名，进入项目设置：
```
OmniPlay Target -> Signing & Capabilities
```
修改 Team 和 Bundle Identifier。
点击 Run 运行。

使用命令行 Debug 编译

在仓库根目录执行：

xcodebuild \
  -project OmniPlay.xcodeproj \
  -scheme OmniPlay \
  -configuration Debug \
  -sdk macosx \
  -derivedDataPath /tmp/omniplay-build \
  build

编译成功后，App 通常位于：

/tmp/omniplay-build/Build/Products/Debug/觅影.app

使用命令行 Release 编译

xcodebuild \
  -project OmniPlay.xcodeproj \
  -scheme OmniPlay \
  -configuration Release \
  -sdk macosx \
  -derivedDataPath /tmp/omniplay-release-build \
  build

Release 产物通常位于：

/tmp/omniplay-release-build/Build/Products/Release/觅影.app

归档 Archive

用于后续导出 .app、签名或分发：

xcodebuild \
  -project OmniPlay.xcodeproj \
  -scheme OmniPlay \
  -configuration Release \
  -sdk macosx \
  -archivePath /tmp/OmniPlay.xcarchive \
  archive

归档产物：

/tmp/OmniPlay.xcarchive

导出 App

创建导出配置文件，例如 /tmp/OmniPlayExportOptions.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key>
  <string>developer-id</string>
  <key>signingStyle</key>
  <string>automatic</string>
  <key>teamID</key>
  <string>你的 Team ID</string>
</dict>
</plist>

导出：

xcodebuild \
  -exportArchive \
  -archivePath /tmp/OmniPlay.xcarchive \
  -exportPath /tmp/OmniPlayExport \
  -exportOptionsPlist /tmp/OmniPlayExportOptions.plist

导出结果通常位于：

/tmp/OmniPlayExport/觅影.app

如果只是本机调试，可以直接使用 Debug/Release build 产物；如果要分发给其他用户，建议使用 Developer ID 签名并完成公证。

打包为 DMG

导出 .app 后，可以先创建一个 DMG 根目录，把 App 和 /Applications 快捷方式放进去：

mkdir -p /tmp/OmniPlayDmgRoot
ditto "/tmp/OmniPlayExport/觅影.app" "/tmp/OmniPlayDmgRoot/觅影.app"
ln -sfn /Applications /tmp/OmniPlayDmgRoot/Applications

再用系统工具创建 DMG：

hdiutil create \
  -volname "觅影" \
  -srcfolder /tmp/OmniPlayDmgRoot \
  -ov \
  -format UDZO \
  /tmp/OmniPlay.dmg

如果要做正式分发，建议：

使用 Developer ID 签名。
对 .app 或 .dmg 执行 notarization。
使用 stapler 附加公证票据。

示例：

xcrun notarytool submit /tmp/OmniPlay.dmg \
  --apple-id "你的 Apple ID" \
  --team-id "你的 Team ID" \
  --password "App 专用密码" \
  --wait

xcrun stapler staple /tmp/OmniPlay.dmg

常见问题

1. 首次编译卡在 Resolve Package Graph

通常是 Swift Package 或二进制产物下载较慢。请确认网络可访问 GitHub，并重试：

xcodebuild -resolvePackageDependencies -project OmniPlay.xcodeproj

开发说明

代码结构

OmniPlay/
  OmniPlayApp.swift                 App 入口与数据库初始化
  ContentView.swift                 主视图入口
  PosterWallView.swift              首页海报墙、媒体源管理、WebDAV 入口
  MovieDetailView.swift             详情页、分集卡片、播放入口
  PlayerScreen.swift                播放窗口 UI
  MPVPlayerManager.swift            mpv 播放管理
  MediaLibraryManager.swift         扫描、刮削、WebDAV 扫描
  DatabaseModels.swift              数据模型与 Keychain 凭据
  ThumbnailManager.swift            分集剧照获取与缓存
  PosterManager.swift               海报缓存
  OfflineCacheManager.swift         离线缓存
  SettingsView.swift                偏好设置

测试

仓库包含业务集成测试和 WebDAV Mock 测试：

OmniPlayTests/
OmniPlayUITests/

可在 Xcode 中运行测试，或使用命令行：

xcodebuild \
  -project OmniPlay.xcodeproj \
  -scheme OmniPlay \
  -configuration Debug \
  -sdk macosx \
  -derivedDataPath /tmp/omniplay-test-build \
  test

许可证与三方组件

本项目包含或依赖多个开源组件和媒体框架。请在分发前确认：

GRDB 的 MIT 许可证要求。
mpv / FFmpeg / MPVKit 相关许可证要求。
LGPL/GPL 组件的再分发义务。
App 内“开源组件详情与许可证线索”页面展示的信息。
OmniPlay/OpenSourceLicenses/ 中随附的许可证文本。

如果你重新打包、修改播放器栈或替换二进制框架，请重新审查对应许可证和源码提供义务。

免责声明

觅影 OmniPlay 仅用于管理和播放用户有权访问的本地或 NAS 媒体文件。TMDB 元数据、海报和剧照版权归各自权利方所有。请遵守所在地区法律法规以及相关服务条款。