FrameRateSnap requests 23.976 Hz for 24.000 fps sources, so Match Frame Rate repeats a frame about every 42 seconds #884

What happened?

A source whose video stream is 24.000 fps is programmed as 23.976 Hz. FrameRateSnap.snap maps the whole 23.5 to 24.05 window to 23.976 (Sources/AetherEngine/Display/FrameRateSnap.swift:32, unchanged in 7.47.0). The engine's own mode check then shows the mismatch:

[DisplayCriteria] mode check (native): content=24.000 requested=23.976 panel=23.977Hz (nominal 23.977) player=24.186fps

At 23.976 Hz, 24.000 fps content gains one frame every 1001 frames, so the panel has to repeat or drop one about every 41.7 s. That is a visible hitch on a pan, which is the judder Match Frame Rate is meant to remove.

The comment says 23.976 is the conservative choice because a panel with 24 Hz also has 23.976, not necessarily the reverse. Could the window distinguish the two instead? A 24/1 avg_frame_rate (or anything within a few thousandths of 24.000) would go to 24, and 24000/1001 and probes nearer 23.976 would stay at 23.976. If a panel without 24 Hz is the concern, that seems better handled as a fallback than by sending every 24p source to 23.976.

Steps to reproduce

1. Match Content on (Match Frame Rate on).
2. Load a 1080p H.264 MKV whose video stream is 24.000 fps on the native path.
3. The load line reads rate=23.976, [DisplayCriteria] SET … rate=23.976, and the mode check line above.

AetherEngine version or commit SHA

Seen on 7.32.3 and 7.42.0; the snap code is unchanged in 7.47.0

Host app

Custom / my own integration (Rivulet)

Platform

tvOS

OS version

tvOS 26.6 (23L773)

Device / chip

Apple TV 4K (3rd generation), AppleTV14,1

Playback path

Native AVPlayer

Source media (for playback bugs)

MKV, H.264 High, 1920x1080, 24.000 fps, SDR, E-AC-3 5.1

Error codes / log lines

[AetherEngine] load … source-format=sdr effective-format=sdr rate=23.976
[DisplayCriteria] SET: format=sdr codec=hvc1 rate=23.976 extensions=none
[DisplayCriteria] mode check (native): content=24.000 requested=23.976 panel=23.977Hz (nominal 23.977) player=24.186fps