tvOS: Menu dropdown flickers during playback — currentTime publisher causes parent re-renders

[ohjey]

What happened?

Description:
I am building a custom video player UI on top of AetherEngine (tvOS 26, SwiftUI). I used native Menu with .menuStyle(.button) for subtitle/audio track selection during playback. The menu dropdown flickers — the focused item's highlight blinks on and off while the video is playing.
Root cause: AetherEngine publishes @published var currentTime at ~10 Hz (via addPeriodicTimeObserver(forInterval: 0.1)). Any SwiftUI view that observes the engine (via @EnvironmentObject or mirrored through an @ObservedObject PlayerViewModel) re-renders its body on every tick. This causes SwiftUI to recreate the Menu struct, which tears down the native UIMenu on tvOS and rebuilds it — that's the flicker.

I've tried throttling currentTime in our view model, isolating the menu into a separate ObservableObject, .equatable(), UIViewRepresentable wrappers, and suppressing UI updates while the menu is open. None fully fix it — tvOS treats the native UIMenu as a black box that gets torn down on any parent view-tree update.

Questions:

1. Is there a recommended way to attach custom UI (like track selection menus) alongside AetherEngine on tvOS that avoids this?
2. Should I be using AVPlayerViewController (the system player) instead of a fully custom UI? Does AetherEngine recommend embedding in AVPlayerViewController?
3. Is there a way to observe playback time without getting per-frame @published updates — e.g., a lower-frequency callback or a read-only polling API?

Steps to reproduce

1. Load any video with multiple audio/subtitle tracks using AetherEngine
2. Build a SwiftUI overlay with a native Menu (.menuStyle(.button)) that reads engine.audioTracks and calls engine.selectAudioTrack(index:)
3. Observe the engine via @EnvironmentObject or @ObservedObject in the view that contains the Menu
4. Play the video, focus the menu button, press select to open the dropdown
5. The focused item inside the dropdown flickers at the engine's currentTime publish rate

AetherEngine version or commit SHA

639fc95

Host app

Custom / my own integration

Platform

tvOS

OS version

tvOS 26.5

Device / chip

Apple TV 4K (3rd Gen)

Playback path

Native AVPlayer

Source media (for playback bugs)

No response

Error codes / log lines

Anything else

No response

[DrHurt]

AVPlayerViewController with additional menus for the custom subtitles and audio track selection is definitely a good & valid approach.

See this for how to add custom buttons to AVPlayerViewController
https://developer.apple.com/documentation/avkit/customizing-the-tvos-playback-experience

AVPlayerViewController Is the default UI for AVPlayer and allows controlling platform native features like reduce loud sounds and enhance dialogue etc. individually during playback.

You’ve uncovered a genuine bug (or rather use case issue)! Thanks for pointing this out.

[superuser404notfound]

Your root-cause analysis was exactly right, and this was a design flaw in the engine's API surface, not something a host can work around: as long as currentTime was @Published on the engine itself, every view observing the engine re-rendered at 10 Hz no matter what it actually read.

Fixed as of 92ffa37 with a breaking API change. The continuously ticking values (currentTime, sourceTime, progress, and the live-edge fields) moved to a separate ObservableObject exposed as engine.clock. The engine's objectWillChange no longer fires on clock ticks, so a view that reads engine.audioTracks for a track menu stays untouched during playback and the native Menu no longer gets torn down. This mirrors AVFoundation's own shape: AVPlayer exposes time via addPeriodicTimeObserver, not as observable state.

To your questions:

1. Custom UI alongside the engine works fine now. Observe the engine for state/tracks/menus, and observe engine.clock only in the leaf view that renders time (or subscribe to engine.clock.$currentTime in your view model).
2. AVPlayerViewController is a valid approach too (see DrHurt's comment), but it's no longer necessary just to dodge the re-render storm.
3. engine.clock.$currentTime is a plain Combine publisher, so .throttle(for: .seconds(1), ...) gives you any lower rate you want, and engine.currentTime remains as a read-only polling accessor.

Migration: plain reads (engine.currentTime) compile unchanged; only Combine subscriptions move, engine.$currentTime becomes engine.clock.$currentTime, same for sourceTime and the live-edge fields.

[superuser404notfound]

The clock split shipped in release 3.0.0 (https://github.com/superuser404notfound/AetherEngine/releases/tag/3.0.0), migration notes in the release body. Closing; reopen if the flicker persists for you on 3.0.0.

[ohjey]

Following up after adopting 3.0.0/3.0.1 — the clock split works exactly as described
(objectWillChange no longer fires on ticks; verified), and it was a necessary fix.
But I want to report back that it was necessary, not sufficient for the original
symptom, and one part of the remaining problem is still engine-side.

What we found after adopting engine.clock

The focused row of an open tvOS Menu blinks whenever any SwiftUI render
transaction runs in the hosting tree — even transactions fully contained in leaf views
that are unrelated to the Menu and don't share state with it. After the clock split,
our chrome no longer re-rendered on ticks, but the menu still flickered because of:

• a 1 Hz TimelineView(.periodic) wall clock (sibling view),
• a playbar leaf observing engine.clock (10 Hz, later throttled to 1 Hz — still blinked),
• a subtitle overlay leaf observing engine.clock at 10 Hz.

Minimal repro: put a SwiftUI Menu next to a TimelineView(.periodic(from: .now, by: 1))
on tvOS 26, open the menu — the focused item blinks once per second. Leaf isolation
doesn't help; only a completely static tree does, which a player UI can't be. We
confirmed the mechanism by elimination: identical ticking with a pure-SwiftUI custom
dropdown → no flicker; freezing every time-driven view while the menu is open → no
flicker; any ticking + Menu → flicker. (Filing this with Apple as a SwiftUI bug too.)

The engine-side part: liveTelemetry is a 1 Hz @Published

While digging we found the engine still has one continuously-ticking published property:
the 1 Hz live-telemetry sampler writes liveTelemetry every second of every session
(VOD included), so any view holding @EnvironmentObject var engine /
@ObservedObject re-renders once per second for the whole session — in our app that
was the screen presenting the player, which re-evaluated the player's
fullScreenCover (and a UIHostingController.rootView underneath it) every second,
blinking the open menu from outside the player entirely.

This is the same class of issue #29 fixed for the clock. Could liveTelemetry (and
anything else sampled on a timer) move off the engine's ObservableObject surface the
same way — e.g. an engine.diagnostics object, or only published while a stats overlay
opts in? That would make "observe the engine for tracks/state" safe again, which is
what the 3.0.0 release notes promise.

What actually fixed it host-side (maybe worth a docs note)

We ended up using the AVPlayerViewController.transportBarCustomMenuItems architecture:
a UIKit-owned menu button (UIButton with the tvOS 26 .glass() configuration +
button.menu + showsMenuAsPrimaryAction, all public tvOS 17+) wrapped in a
UIViewRepresentable whose updateUIView replaces the UIMenu only when the items
actually change:

func updateUIView(_ button: MenuButton, context: Context) {
    // Same-value reassignment tears down an open dropdown — skip it.
    if button.currentItems != items { applyMenu(to: button) }
}

Same native UI as SwiftUI's Menu (it's the same system menu underneath), but SwiftUI
diffing can never rebuild it while open, so the rest of the player UI ticks freely with
zero flicker. Since custom tvOS chrome on top of AetherEngine seems to be a common use
case, this might be worth a note in the integration docs (or even a small shipped
component) — "observe engine.clock in a leaf" isn't enough on tvOS if the host uses
SwiftUI Menu anywhere in the player.

Happy to share the full wrapper if useful. Thanks again for the quick turnaround on the
clock split — it was a prerequisite for everything above.

[superuser404notfound]

Thanks for the exceptionally thorough follow-up, the elimination test isolating Menu + any render transaction is exactly the kind of evidence that makes this actionable.

You're right about liveTelemetry, and it's fixed as of 9d8be9a: it was the last timer-driven @Published on the engine (I audited the rest of the surface; everything else is event-driven). It now lives on engine.diagnostics, a separate EngineDiagnostics ObservableObject mirroring the clock split. Same migration story as 3.0.0: plain reads (engine.liveTelemetry) compile unchanged through a read-only forwarder, and subscriptions move from engine.$liveTelemetry to engine.diagnostics.$liveTelemetry. The sampler keeps running unconditionally (it's cheap, and the forwarder should always be current), but it no longer touches the engine's objectWillChange, so "observe the engine for tracks/state" now holds the way the 3.0.0 notes promised.

Your menu-button pattern is also in the README now (Host setup on tvOS, "SwiftUI Menu in custom player chrome"), with the updateUIView item-diff guard and credit to you. If you can share the Apple feedback number for the Menu + TimelineView repro once filed, I'll add it to the note so other adopters can reference it.

Both ship in 3.2.0.