decoder-errata.txt

This file serves to document some of the decoder errata when using MediaCodec hardware decoders on certain devices.

1. num_ref_frames is set to 16 by NVENC which causes decoders to allocate 16+ buffers. This can cause an error or lag on some devices.
	- Affected decoders: TI OMAP4 crashes, Allwinner A20, MT8176 lags (HEVC not affected)
	
2. Some H.264 decoders have a huge per-frame latency with the unmodified SPS sent from NVENC. Setting max_dec_frame_buffering=1 fixes this latency issue.
	- Affected decoders: NVIDIA Tegra 3 and 4, Broadcom VideoCore IV

3. Some decoders strictly require that you pass BUFFER_FLAG_CODEC_CONFIG and crash upon the IDR frame if you don't
	- Affected decoders: TI OMAP4

4. Some decoders require num_ref_frames=1 and max_dec_frame_buffering=1 to avoid crashing on SPS on first I-frame
	- Affected decoders: Qualcomm in GS3 on 4.3+, Exynos 4 at 1080p only

5. Some decoders will hang or crash if max_dec_frame_buffering is not present and level_idc is >= 50
	- Affected decoders: MediaTek decoder in Fire HD 6/7 (2014)
	
6. Some decoders will hang if max_dec_frame_buffering IS present
	- Affected decoders: Exynos 5 in Galaxy Note 10.1 (2014)

7. Some decoders will not enter low latency mode if adaptive playback is enabled
	- Affected decoders: Intel decoder in Nexus Player

8. Some decoders will not enter low latency mode if the profile isn't baseline in the first SPS because B-frames may be present.
	- Affected decoders: Intel decoder in Nexus Player (prior to Android 6.0)

9. Some decoders will not enter low latency mode if the profile isn't constrained high profile because B-frames may be present.
	- Affected decoders: Intel decoder in Nexus Player (after Android 6.0)

10. Some decoders actually suffer increased latency when max_dec_frame_buffering=1
	- Affected decoders: MediaTek decoder in Fire TV 2015

11. Attempting to use reference picture invalidation at 1080p causes the decoder to crash on low-end Snapdragon SoCs. 720p is unaffected.
	- Affected decoders: Snapdragon 200, 410, 415, 430, 435, 616

12. Enabling adaptive playback causes H.265 1080p and 4K playback to fail on some MediaTek SoCs.
	- Affected decoders: MT5832 in Sony BRAVIA 4K GB (BRAVIA_ATV2) and MT5890 in Phillips 55PUS6501

13. Some HEVC decoders hang when receiving a stream with 16 reference frames
	- Affected decoders: Amlogic S905Z in Fire TV 3

14. Some HEVC decoders lag when receiving a stream with 16 reference frames
	- Affected decoders: Tegra X1 in Pixel C (but NOT in SHIELD TV darcy)

15. Some devices that support Android 11's FEATURE_LowLatency don't support it on their first compatible H.264/HEVC decoder. It is important to examine *all* decoders for FEATURE_LowLatency before deciding on one.
    - Affected devices: Pixel 4 (c2.qti.avc.decoder.low_latency vs c2.qti.avc.decoder) and Galaxy S21 Exynos (OMX.Exynos.avc.dec [FEATURE_LowLatency] vs C2.Exynos.avc.decoder [no FEATURE_LowLatency])

16. Some decoder have magic undocumented MediaFormat options to enable low latency prior to the introduction of KEY_LOW_LATENCY in Android 11. See MediaCodecHelper.java for info.
    - Affected devices: MediaTek, Amlogic, Amazon, Qualcomm, Exynos, Huawei

17. Fire TV 3's Amlogic HEVC decoder doesn't produce any output frames without setting the magic "vdec-lowlatency" MediaFormat option
    - Affected devices: Fire TV 3

2024+ device evidence review (2026-10-09; reports, not local measurements)

18. Vivo Pad3 Pro / Dimensity 9300, Android 14: the reporter observed a decode-time spike and cursor stutter when motion resumed after 2-3 seconds of a static image above 1440p. Codec/firmware cause and a client workaround are not established. Do not generalize older MTK OMX errata to all C2 MTK decoders.
    - Source: https://github.com/moonlight-stream/moonlight-android/issues/1356
    - Related codec-info evidence lists c2.mtk.hevc.decoder.lowlatency on Poco X6 Pro / Dimensity 8300 Ultra: https://github.com/moonlight-stream/moonlight-android/issues/1241#issuecomment-2833328947
    - Existing policy: MediaCodecHelper.findKnownSafeDecoder() searches all candidates for advertised FEATURE_LowLatency first. setDecoderLowLatencyOptions() prefers KEY_LOW_LATENCY on that path before vendor retries. No new MTK key or SoC blacklist is justified by these reports.

19. Samsung Galaxy S24+ (Exynos), Android 14: upstream reports high decode latency/stutter at 2560x1440/60, changing while screen recording is active. Comments contain conflicting software/workload workarounds and reports from older Exynos devices. No controlled result establishes an Exynos 2400 codec quirk or a reliable fix.
    - Source: https://github.com/moonlight-stream/moonlight-android/issues/1370
    - Existing policy: omx.exynos/c2.exynos vendor.rtc-ext-dec-low-latency.enable fallback remains. Screen recording, CPU-Z and forced GPU activity are not added as workarounds; measure the actual phone/firmware and advertised decoder first.

20. iQOO 12 Pro / Snapdragon 8 Gen 3, Android 14: an upstream report describes periodic rendered-FPS drops at 3200x1440/120 with AV1/HDR and balanced pacing, while incoming FPS remains steady. This does not establish a codec-specific decoder defect or an effective vendor key.
    - Source: https://github.com/moonlight-stream/moonlight-android/issues/1371
    - Counterexample to a blanket Snapdragon blacklist: the Xiaomi Pad 7 Pro / 8s Gen 3 corruption/freeze reporter later resolved their issue by replacing the router: https://github.com/moonlight-stream/moonlight-android/issues/1471#issuecomment-2816285963
    - Existing policy: omx.qcom/c2.qti low-latency and picture-order retries remain capability-based. 8s Gen 3, 8 Gen 3 and 8 Elite are not interchangeable driver evidence.

21. Snapdragon 8 Elite, Tensor G4/Pixel 9, newer Dimensity and Exynos revisions: no verified model-specific decoder workaround or reproducible decode measurement was established by the reachable upstream issues and this code review. Absence of evidence is not certification. Keep standard low-latency capability selection, supported size/rate/profile checks and vendor-option retry fallback; do not invent SoC timings or new tuning keys.
    - Local implementation reviewed: app/src/main/java/com/limelight/binding/video/MediaCodecHelper.java and MediaCodecDecoderRenderer.java.
    - Upstream issue searches: https://github.com/moonlight-stream/moonlight-android/issues?q=is%3Aissue+%228+Elite%22 and https://github.com/moonlight-stream/moonlight-android/issues?q=is%3Aissue+%22Tensor+G4%22
    - Required phone checks, including firmware/decoder names, static-to-motion transitions and thermal runs: internal/device-checklist.md.

22. Xiaomi TV Stick MiTV-AYFR0, Android TV 14, c2.amlogic.hevc.decoder: a patched Moonlight build reports slideshow-like HEVC playback despite normal FPS statistics. Omitting setDecoderLowLatencyOptions() fixes the reported 1920x1080/60 Sunshine stream while retaining normal HEVC reference-frame invalidation detection.
    - Source: https://github.com/Viktsolovevwork278/moonlight-android-hevc-fix/releases/tag/v1.0.0 (710e90e04b3c9f940d149e29f9b74fe737b42245; decoder change 44a3bb3677270af68996acb9047571757eb153d9).
    - Related firmware-specific evidence: https://github.com/sven253/artemis-moonlight-android-hevc-fix#hevc-low-latency-options reports KEY_LOW_LATENCY as problematic on Homatics Box 4K Pro V2 / S905X5M. This does not establish a quirk for every device using that SoC.
    - Nightjar policy: Settings -> Advanced -> Low-latency decoding -> Customize -> HEVC low-latency flags is Auto, On or Off, as in Moonlight V+. Off is device-independent and omits optional standard and vendor low-latency options for HEVC in streams and the decoder benchmark, and disables HEVC RFI. Performance hints retain their own setting, with one tuned attempt followed by a fallback without optional tuning. Fire TV 3 (AFTN) on Fire OS 6 retains vdec-lowlatency in every attempt, including when tuning is disabled, to preserve output (erratum 17). The output queue follows the flags actually requested. On Auto, Codec2 Amlogic HEVC decoders (c2.amlogic) outside Fire TV (the amazon.hardware.fire_tv feature) don't get these flags (Moonlight V+ issue 499, moonlight-android#1584): configure() succeeds and the display then refreshes about once a second, so no configure fallback catches it. V+ also leaves them off omx.amlogic, but the reports above are c2.amlogic only, and Fire TV's Amlogic decoders run HEVC with low-latency decoding (erratum 17), so omx.amlogic and every Fire TV keep them on Auto. On forces them there for firmware that has fixed this. A warning names the decoder in both cases; HEVC RFI and decoder performance hints keep their own policy there, and H.264 and AV1 keep the flags.
    - Regression coverage validates startup, restart, fallback, other codecs, default behavior and benchmark invalidation; Nightjar hardware validation on these sticks is pending.

23. Fire TV AFTNE4E43F (Xiaomi FX Mini LED, Android 11), MediaTek decoders, with KEY_LOW_LATENCY: the picture turns into "rainbow" garbage or blocks that the decoder never reports. First reported on 10-bit (HDR) AV1; by the 2026-11-05 host log and video on AV1, HEVC and H.264 at 4K, H.264 in SDR too. Nothing in the decoder asks for a keyframe and the stream has no periodic one, so it lasts until the next. It often starts on a large frame (stream start on a real picture, a menu or scene change; 1.5-3.3 MB frames at 4K 160 Mbps) but also shows at 40 and 80 Mbps. The garbage is entropy or reference state gone wrong, not a surface layout problem: blocky smeared prediction and noisy bands that change every frame, while the picture before it was clean.
    - Source: Rubylight issue 56 (from Nightjar 4.0.1, RX 9070 XT host, wired). Rainbows with every low-latency combination except KEY_LOW_LATENCY off, which costs 10-11 ms decode against 2-3 ms (MediaTek "Dequeue input buffer ran long" 20-35 ms all session). With it off the 2026-11-05 test was clean on all three codecs at 16-20 ms, in short runs (4.5, 1.5 and 1.4 minutes), with spikes of 50-60 ms on H.264 and HEVC. HDR off with everything on was clean at about 2 ms on 2026-10-31, and HEVC HDR at about 4 ms on 2026-11-01 with HDR10+ off (1620p).
    - Ruled out: the MediaTek vendor keys (both presets, then only the switches in 4.3.0, then none), AV1 screen content tools, HDR10+ metadata (off in the 2026-11-01 log), split-frame encoding (one encoder instance), the input buffer (8.3 MB requested at 4K, no growth logged, one buffer per frame), HDR alone (H.264 SDR shows it) and link capacity alone (40 Mbps shows it). Loss is not ruled in or out: the 2026-11-05 host log has AV1 sessions with many keyframes and unrecoverable frames (46 of each in 109 s at 31 Mbps) and others with no loss at all, and which of those showed artifacts is unknown. An earlier version of this entry said rainbow sessions had no loss and no recovery frame; that was from fewer logs.
    - The second 2026-11-05 test, with it on and the host at amd_ltr_frames = 0: blocks less often, not gone (AV1 13 minutes, HEVC 7 minutes). They last until the next keyframe, and HEVC had none for nearly 7 minutes. Decode latency climbs 3-5-7-8-9 to about 20 ms from an average of 3 and stays there 10-15 s, and the reporter puts the start of the artifacts there, from this one test; the decoder's debt floors rose from 0.3 to 10.6, 31.2 and 49.5 ms. Encode stayed at 5.5-6 ms, and frames of 1-4.5 MB took 46-70 ms on the wire.
    - Not established: why. Candidates are an overrun (in this mode, work per frame near or over the frame interval corrupts a reference without a report, and skip blocks carry the damage until a keyframe), long-term references and the deeper picture buffer they ask for in the decoder's low-latency mode (6 pictures instead of 2; Fire TV Cube 3 hung on long-term references, Rubylight issue 73; against it, this TV is clean with them when low latency is off), a low-latency bug with frames pipelined behind a large one, frame-end CDF carry-over between pipelined frames (host test: amd_av1_cdf_frame_end = 0 changed the look on this TV and did not end it), and H.264/HEVC slices at 4K. The TCL C6K (MT9689, also c2.mtk.av1.decoder) shows no rainbows in about 50 AV1 HDR starts, so this is not a rule for every MediaTek decoder, and the gate names this model.
    - Nightjar policy, for exactly this Build.MODEL with a MediaTek decoder and no other device: Android low latency is switched off once, and again after Reset all settings, and the vendor keys stay; turning it back on is kept, and no preset sets it. With it off, RFI stays and nothing else changes: that path ran clean on all three codecs, in the short runs above. With the flag actually sent to the decoder, the rest is intended to limit the damage and is not shown to end the rainbow. The decoder declares no RFI (one reference, no long-term ones), and so does a stream the launch picks Dolby Vision for, which runs on its own decoder. Any other stream goes by its own decoder (with the HEVC override off, HEVC has no RFI in any case, as that override has always done). The pick comes before the launch: if the Dolby Vision decoder then refuses or the host announces something else, that stream runs on the base codec without RFI, as the host was told. A keyframe is asked for one second into a decode latency climb and again when it ends, on a calm picture (frames under a quarter of what the bitrate and frame rate give one, and under 64 KiB) after 10 s without one, and after 30 s whatever the picture; never within 5 s of the last, and any keyframe restarts the waits. Because the overrun theory is unproven, a climb has to pass half a frame interval (8.3 ms at 60 fps) and be well above the baseline, though past the whole frame interval and 4 ms over the baseline is enough. Repeated climb repairs back off 5, 10, 20, 30 s until a minute without a climb, and from the second in a row only a climb's end asks. A level that holds for a minute becomes the baseline with no repair for its end; the start repair of that climb has gone by then unless repairs had backed off. A frame arriving right behind the previous input waits until half a frame interval has passed, at most 20 ms. One reference on AV1 ran 30 s at 1440p60 on an RX 7900 XT host on 2026-11-05: the encoder accepted it with no long-term references, and all 1778 inter frames in the bitstream refreshed one slot and read one; the RX 9070 XT has not run it. On this TV's MediaTek decoders only the host at amd_ltr_frames = 0 has run (above); the client's declared single reference, the keyframes on a climb and the spacing have not. How long a full input blocks here and what buffer the system grants are not known, so the first report from this TV has to judge the spacing. The recent-streams row in a problem report counts climbs and settled climbs, repairs by reason, frames and time held, and gives the receive buffer granted (new engine only) and the hottest thermal level.