
phonto 工具可将视频设为 macOS 锁屏壁纸
来源标题:Your Video on the macOS lock screen needs temporal sub-layers, even empty ones
命令行工具 phonto 能通过一条命令把视频放上 macOS 锁屏,并在反复锁屏、休眠唤醒后持续播放。关键做法是为视频编码时加入临时子层(即使内容为空),重新编码后 20 秒 4K 文件约 125 至 250 MB。该工具已在 macOS 26 和 27 的 Apple Silicon 设备上验证,系统更新 Aerials 目录后需重新执行命令。
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
phonto puts a video on the macOS lock screen with one command. Getting it to play past the first lock comes down to one encoder setting.
phonto is a small command-line tool that plays video as your wallpaper. On macOS it can also put that video on the lock screen:
$phonto install-live-lockscreen ~/Videos/harbour.mp4
Open System Settings → Wallpaper, pick the video in the Phonto section and lock the screen. It plays. Unlock, lock again, put the Mac to sleep and wake it. Still playing.
We’ve run it on macOS 26 and 27, on Apple Silicon. A macOS update that ships a new Aerials catalog takes phonto’s videos out of System Settings, and you run the command again. The lock screens page has the steps and the options.
The command takes a while because it encodes your video again first, and the new file is 125 to 250 MB for 20 seconds of 4K. That encode is most of this post. The rest is a JSON file Apple would probably rather you left alone.
The obvious approach is a window behind the desktop icons that plays the video. phonto does that for the desktop, and it’s useless for the lock screen. As soon as the screen locks, macOS hides every window. There’s no public API for putting your own wallpaper there either.
So phonto doesn’t play anything on the lock screen. macOS does. WallpaperAerialsExtension plays Apple’s Aerials, the slow aerial shots of coastlines and cities. It’s a signed system extension, and macOS lets it draw on the lock screen. It reads its list of Aerials from a file in your home folder, and you can write to that file. You can see where this is going.
~/Library/Application Support/com.apple.wallpaper/aerials/manifest/entries.json
The videos and thumbnails sit next to it in aerials/videos/ and aerials/thumbnails/, each named by a UUID. phonto writes its own video and thumbnail into those folders, adds an entry to entries.json and restarts WallpaperAgent, which brings up a fresh copy of the extension. This is the entry it writes for harbour.mp4:
{ "id": "CB528B3F-C8B5-58FC-BB89-8B0ED2436C9B", "categories": ["8C75F1C2-7E7E-4B5C-9C5C-50484F4E544F"], "subcategories": ["8C75F1C2-7E7E-4B5C-9C5C-535542434154"], "previewImage": "file:///Users/you/Library/Application%20Support/com.apple.wallpaper/aerials/thumbnails/CB528B3F-C8B5-58FC-BB89-8B0ED2436C9B.png", "accessibilityLabel": "harbour", "localizedNameKey": "harbour", "includeInShuffle": false, "pointsOfInterest": {}, "preferredOrder": 0, "shotID": "PHONTO_CB528B3F", "showInTopLevel": true, "url-4K-SDR-240FPS": "file:///Users/you/Library/Application%20Support/com.apple.wallpaper/aerials/videos/CB528B3F-C8B5-58FC-BB89-8B0ED2436C9B.mov" }
The id is a UUIDv5 of the path you installed from. Installing the same file again replaces its entry instead of adding a second one, and --remove with the same path finds it even if the file has gone. The two fixed IDs are phonto’s category and subcategory. Read the last twelve hex digits of each as ASCII and you get PHONTO and SUBCAT.
The video key says 240 fps. Apple’s own Aerials really are 240 fps, and on macOS 27 it’s the only video key in the whole catalog. Every phonto video goes under it, whatever its frame rate.
The file is strict, and when it breaks, it breaks somewhere else:
phonto’s category has preferredOrder: -1, which puts the Phonto section above Apple’s.
Every value here is valid. System Settings shows Phonto’s section above Apple’s.
A category with no subcategories. The extension rejects the whole catalog, and System Settings shows no Aerials at all, Apple’s included.
An empty representativeAssetID on the category does the same: the whole catalog goes.
An empty previewImage on the category does the same. phonto won’t write an entry at all if it couldn’t make the thumbnail.
An asset that names no category. The extension rejects the whole catalog.
An asset that names no subcategory. The extension rejects the whole catalog.
A raw space where the URL needs %20. The catalog loads, Phonto’s section with it, and the video doesn’t.
Apple’s categories run from 0 to 5. At 6, Phonto sorts after them. phonto writes -1 to put it first.
The first lock plays the video. Unlock, then lock again, and the screen is black. Close the lid, open it, still black.
We looked the unified log. On macOS 26, the extension logs Play Called and StartReadingItem on the first lock, and the decoder starts. About 2.3 seconds of frames in, it stops. Later locks log nothing from the player at all, apart from the occasional FigVideoQueueGMStats: 0 frames enqueued in the last 6 seconds, the most honest line in the entire log.
On macOS 27 it fails differently. The player logs Play Called on every lock. The tell is VideoSampleReadingErrors Code=4, then the extension trying to re-download the video, as if a file on your own disk might have come from Apple’s CDN. The extension also plays the video in 'idle', a mode WallpaperAgent switches to after the extension starts and after every unlock. In the run below the video played there first, and the very first lock was the one that failed.
installed file encoded with BaseLayerFrameRate 30
phonto restarts WallpaperAgent after an install, which brings up a fresh WallpaperAerialsExtension with a fresh video player inside it.
WallpaperAgent tells every wallpaper extension what the wallpaper is doing. Here it switches to 'idle' after the extension starts and after every unlock, and the player plays the video there as well as on the lock screen.
The screen locks. WallpaperAgent switches to 'locked', and the extension passes the change on to its player.
Unlocking switches the mode back to 'default'.
The extension tells its player to play. It does that on every switch to 'idle' or 'locked', whether any frames follow or not.
The player opens the video and starts reading frames from it.
The player can’t read a frame, and the lock screen stays black. One reverse-engineered list of these errors names code 4 noTemporalInfo, and this file has no tscl. The video had already played once, in 'idle', and the very first lock is the one that fails.
CoreMedia’s video queue reports how many frames reached it in the last six seconds. The extension runs eight queues, and this is the busiest.
All eight queues report 0. Nothing reached the screen in the last six seconds.
One more lock and unlock, from 19:22:36.979 to 19:22:38.442, left out here.
The catalog entry never needed to change. The file did.
The fix is one key on the encoder, kVTCompressionPropertyKey_BaseLayerFrameRate, set to 30. It makes VideoToolbox split the stream into temporal sub-layers: a base layer of up to 30 fps, and a layer above it for the frames in between.
To check it was this key and nothing else, we took one 30 fps clip and one 60 fps clip and encoded each the way phonto does, changing nothing between encodes except that key. We copied each file over an installed video and locked the screen three times. With the setting, both clips played on all three locks. Without it, both played on the first lock and went black after that. So it is the setting. Why the player cares is still a guess.
A compressed video stores very few whole pictures, and those are the keyframes. Every other frame is stored as the changes from an earlier one. Lose a frame and you lose everything built from it, up to the next keyframe. Sub-layers sort frames by what they’re built from. Frames in the base layer are built only from each other. A frame in a higher layer can be built from its own layer and the ones under it, and nothing in a lower layer is ever built from it.
One frame dropped. Four more were built from it and won’t decode until the next keyframe.
The name for this is temporal scalability. A player can drop the top layers and decode at a lower frame rate, which is handy when your source is 240 fps and your screen isn’t. Two sub-layers is the smallest stream of that shape. With the base layer at 30 fps, phonto’s encode of a 60 fps clip puts every second frame in the layer on top.
A .mov is a tree of boxes, each one a size, a four-letter name and its contents. The frames sit in one big box, mdat. Everything that describes them sits in another, moov. The setting shows up in two places inside moov: the decoder’s configuration, and the sample groups that label each frame.
HEVC in a .mov comes with a small configuration record, the hvcC box: profile, level, bit depth, chroma format. Comparing those fields got us nowhere. The box even has a numTemporalLayers field, and VideoToolbox writes 1 there whether the stream has one temporal layer or two.
The difference is a level down, in the parameter sets that the box carries. The first of those is the video parameter set, the VPS. Here it is for the same frames, encoded by VideoToolbox with phonto’s settings, once without BaseLayerFrameRate and once with it:
without 40 01 0c 01 ff ff 22 20 00 00 03 00 b0 00 00 03 00 00 03 00 99 17 02 40 with 40 01 0c 02 ff ff 22 20 00 00 03 00 b0 00 00 03 00 00 03 00 99 00 00 17 02 40
The first two bytes are the NAL unit header. The next two pack six fields, and the fourth byte is where the two streams differ:
0x01 0000 000 1 vps_max_sub_layers_minus1 = 0 vps_temporal_id_nesting_flag = 1 0x02 0000 001 0 vps_max_sub_layers_minus1 = 1 vps_temporal_id_nesting_flag = 0
The first four bits are the end of vps_max_layers_minus1, which is 0 in both. The next three are the number of temporal sub-layers, minus one. The last bit is a nesting flag. The spec requires it to be 1 when there’s only one sub-layer, and VideoToolbox clears it once there are two. One sub-layer against two.
The two extra zero bytes come from profile_tier_level(). Once a stream has more than one sub-layer, it carries two flags for each sub-layer below the top one, saying whether that sub-layer has its own profile and level, and pads them out to sixteen bits. Both flags are 0 here. Sixteen zero bits. The 03s scattered through both lines are emulation-prevention bytes, which stop the payload from looking like a start code.
The SPS gets the same sixteen bits in its own copy of profile_tier_level(). The rest of what changes in the SPS and PPS is the encoder picking a different reference structure, not sub-layer syntax.
The sample groups are the second place. With the setting on, VideoToolbox tags every frame with its temporal level, and AVAssetWriter turns the tags into groups in the track’s sample table. tscl has one entry for each layer the frames are in, with that layer’s profile, level and frame rate, and a csgm box says which entry each frame belongs to. tsas marks the frames where a player can start decoding a higher layer. phonto’s file from a 60 fps clip has two tscl entries and a tsas. From a 30 fps clip it has one tscl entry and no tsas, because every frame is in the base layer. Without the setting no frame is tagged, and the writer writes none of them.
Apple’s catalog lists a download URL for every Aerial. We fetched the first few megabytes of twelve of them, picked across Apple’s different naming schemes, and parsed them. They all agree, and here they are next to phonto’s output:
Apple’s VPS starts 40 01 0c 08. That fourth byte is 0000 100 0, which makes vps_max_sub_layers_minus1 4. The base layer runs at 15 fps and each layer above it doubles that, to 30, 60, 120 and finally 240. Apple’s tscl has an entry for each of the five, and the files carry a tsas too.
The table also rules two things out. Apple’s files use B-frames and five-second gaps between keyframes. Whatever the player objects to, it isn’t those.
We don’t know, but we have a guess. VideoToolbox’s decoder has a documented property, kVTDecompressionProperty_TemporalLevelLimit, that makes it decode only up to a given sub-layer. That’s exactly what you’d reach for to play a 240 fps file on a 60 Hz display. A player built around it could take a different path for a stream it thinks has a single layer, one that doesn’t come back after the first lock.
The strange part is that f
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。