AppexSaverMinimal

简体中文 | English

简体中文

一个适用于 macOS 14 Sonoma 及更高版本的视频屏幕保护程序。它由一个管理应用和一个现代 .appex 屏保扩展组成。

功能

• 从系统屏保的“选项…”页面导入 MP4、MOV 或 M4V 视频。
• 导入前检查文件是否包含可播放的视频轨道。
• 将视频复制到屏保扩展自己的沙盒，之后可以移动或删除原文件。
• 静音、循环、铺满屏幕播放视频。
• 支持多个显示器，每个显示器分别播放完整视频。
• 可以随时替换或移除已导入的视频。
• 管理应用关闭后，屏保仍由 macOS 自动运行。

系统要求

• macOS 14.0 或更高版本
• Xcode 15 或更高版本（从源码构建时需要）
• 首次解析 Swift Package 时需要访问 GitHub

构建

1. 用 Xcode 打开 AppexSaverMinimal.xcodeproj。
2. 本机长期自用时，将两个 Target 的 Team 留空，使用 Sign to Run Locally。这种 ad-hoc 签名不依赖 Personal Team 的短期 Provisioning Profile。
3. 执行 File > Packages > Resolve Package Versions，解析 PaperSaver 及其依赖。
4. Scheme 选择 AppexSaverMinimal，运行目标选择 My Mac，按 Command-R。

也可以在终端构建 Release 版本：

xcodebuild \
  -project AppexSaverMinimal.xcodeproj \
  -scheme AppexSaverMinimal \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64' \
  build

安装和设置

1. 将 Release 应用放在固定位置，推荐 /Applications/AppexSaverMinimal.app。不要长期从 Xcode 的 DerivedData 目录运行屏保。
2. 打开 AppexSaverMinimal。
3. 点击 Install 注册屏保扩展。
4. 点击 Enable as Screensaver，将它设置到所有显示器。
5. 点击 Open Screen Saver Settings。
6. 在“系统设置 > 屏幕保护程序”中选择 AppexSaverMinimal，点击“选项…”。
7. 点击“选择视频”，导入视频，然后点击“完成”。

配置完成后可以关闭管理应用。只要 /Applications/AppexSaverMinimal.app 仍然存在，macOS 就能在需要时启动其中的屏保扩展。

视频存储

导入的视频保存在扩展容器中：

~/Library/Containers/com.xiahua.AppexSaverMinimal.Extension/
  Data/Library/Application Support/AppexSaverMinimal/

重新导入会替换旧视频；配置页面的删除按钮会移除扩展保存的视频。应用包本身不包含用户导入的视频。

启动屏保

自动启动时间在“系统设置 > 屏幕保护程序”中配置。显示器关闭时间必须晚于屏保启动时间，否则显示器会先进入睡眠。

立即启动屏保：

open /System/Library/CoreServices/ScreenSaverEngine.app

也可以在“系统设置 > 桌面与程序坞 > 触发角”中设置“启动屏幕保护程序”，或者把上面的命令加入 macOS“快捷指令”并分配键盘快捷键。

屏保和锁屏不是同一功能：

• 启动屏保会播放导入的视频。
• 电源键或 Control-Command-Q 会直接锁屏或休眠，不会播放视频。
• 将“屏幕保护程序启动或显示器关闭后需要密码”设置为“立即”，可以在播放屏保的同时保护电脑；退出屏保时会要求密码或 Touch ID。
• macOS 不允许第三方屏保替换锁屏界面的背景。

注意事项

• 同一台 Mac 只保留一个注册位置。开发完成后使用 /Applications 版本，避免 DerivedData 和 /Applications 中的同名扩展互相覆盖。
• ad-hoc 签名适合本机长期自用，不适合直接分发给其他用户。对外分发需要 Developer ID 签名和 Apple 公证。
• 屏保扩展使用了 macOS ScreenSaver.framework 中尚未公开声明的扩展类。系统升级后应重新测试兼容性，也不应假设它能通过 Mac App Store 审核。
• 双屏持续播放视频会增加 CPU、GPU 和电量消耗。建议保留合理的显示器自动关闭时间。

常见问题

• Missing package product 'PaperSaverKit'：执行 File > Packages > Resolve Package Versions。如果 GitHub 无法访问，先配置网络或代理。
• “选项…”无反应或仍显示旧界面：完全退出“系统设置”，确认只注册了一个扩展位置，再重新打开。
• 清理 Xcode Derived Data 后屏保消失：将 Release 应用安装到 /Applications，并从该应用重新点击 Install。

更底层的 .appex 屏保架构说明见 BACKGROUND.md。

English

A video screen saver for macOS 14 Sonoma and later. It consists of a management app and a modern .appex screen saver extension.

Features

• Imports MP4, MOV, or M4V videos from the screen saver's Options sheet.
• Verifies that the selected file contains a playable video track.
• Copies the video into the extension's sandbox, so the original file can be moved or removed afterward.
• Plays the video silently, continuously, and full screen.
• Supports multiple displays, with the complete video playing independently on each display.
• Replaces or removes the imported video at any time.
• Continues to work after the management app is closed; macOS launches the extension when needed.

Requirements

• macOS 14.0 or later
• Xcode 15 or later when building from source
• GitHub access when resolving Swift Packages for the first time

Build

1. Open AppexSaverMinimal.xcodeproj in Xcode.
2. For long-term use on the current Mac, leave Team empty for both targets and use Sign to Run Locally. This ad-hoc signature does not depend on a short-lived Personal Team provisioning profile.
3. Run File > Packages > Resolve Package Versions to resolve PaperSaver and its dependencies.
4. Select the AppexSaverMinimal scheme and My Mac, then press Command-R.

To create a Release build from Terminal:

xcodebuild \
  -project AppexSaverMinimal.xcodeproj \
  -scheme AppexSaverMinimal \
  -configuration Release \
  -destination 'platform=macOS,arch=arm64' \
  build

Install and Configure

1. Keep the Release app at a stable location, preferably /Applications/AppexSaverMinimal.app. Do not rely on Xcode's DerivedData location for permanent use.
2. Open AppexSaverMinimal.
3. Click Install to register the screen saver extension.
4. Click Enable as Screensaver to select it on every display.
5. Click Open Screen Saver Settings.
6. In System Settings > Screen Saver, select AppexSaverMinimal and click Options....
7. Click 选择视频 (Choose Video), import a video, and click 完成 (Done).

The management app can be closed after setup. As long as /Applications/AppexSaverMinimal.app remains installed, macOS can launch its screen saver extension when required.

Video Storage

Imported videos are stored in the extension container:

~/Library/Containers/com.xiahua.AppexSaverMinimal.Extension/
  Data/Library/Application Support/AppexSaverMinimal/

Importing another video replaces the previous one. The remove button in the Options sheet deletes the extension's stored video. User-imported videos are not bundled inside the application.

Start the Screen Saver

Configure the automatic start delay in System Settings > Screen Saver. The display sleep delay must be longer than the screen saver delay, or the display will sleep before the screen saver starts.

Start it immediately with:

open /System/Library/CoreServices/ScreenSaverEngine.app

You can also assign Start Screen Saver to a Hot Corner in System Settings > Desktop & Dock, or add the command above to the Shortcuts app and assign a keyboard shortcut.

The screen saver and Lock Screen are separate macOS features:

• Starting the screen saver plays the imported video.
• Pressing the power button or Control-Command-Q locks or sleeps the Mac directly and does not play the video.
• Set Require password after screen saver begins or display is turned off to Immediately to secure the Mac while the screen saver is playing. Exiting it will require a password or Touch ID.
• macOS does not allow a third-party screen saver to replace the Lock Screen background.

Notes and Limitations

• Keep only one registered copy on a Mac. After development, use the /Applications build to avoid conflicts between extensions in DerivedData and /Applications.
• Ad-hoc signing is appropriate for long-term local use, but not for distributing the app to other users. Distribution requires Developer ID signing and Apple notarization.
• The extension relies on screen saver extension classes in ScreenSaver.framework that are not publicly declared by the SDK. Retest after macOS upgrades, and do not assume Mac App Store acceptance.
• Continuous video playback on multiple displays increases CPU, GPU, and battery usage. Keep a reasonable automatic display sleep delay.

Troubleshooting

• Missing package product 'PaperSaverKit': run File > Packages > Resolve Package Versions. Configure network access or a proxy if GitHub is unavailable.
• Options does not open or shows an old interface: quit System Settings completely, verify that only one extension location is registered, and reopen it.
• The screen saver disappears after cleaning Xcode Derived Data: install the Release app in /Applications, then click Install from that copy.

See BACKGROUND.md for lower-level details about the .appex screen saver architecture.

License

MIT © 2026 Guillaume Louel