Skip to content

fix(mediaplayer): recover H.264 frame size on a mid-stream join over TS/RIST and RTMP#969

Merged
dooly123 merged 1 commit into
BasisVR:developerfrom
towneh:fix/mediaplayer-h264-midstream-dimensions
Jul 17, 2026
Merged

fix(mediaplayer): recover H.264 frame size on a mid-stream join over TS/RIST and RTMP#969
dooly123 merged 1 commit into
BasisVR:developerfrom
towneh:fix/mediaplayer-h264-midstream-dimensions

Conversation

@towneh

@towneh towneh commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator

Summary

Video over MPEG-TS/RIST and RTMP could fail to play after a mid-stream join, erroring out with a 0x0 frame size ("video track ... announced no frame size"). The TS/RIST and RTMP demuxers read the frame dimensions from the first access unit they saw and then latched the announced format. On a live join between keyframes that first AU carries no SPS, so they announced 0x0, the decoder refused to configure, and the SPS in the following keyframe was never read.

  • basis_ts.c (TS/RIST): for H.264, hold the format announce until an access unit actually carries an SPS with valid dimensions, dropping the undecodable pre-IDR AUs and waiting for the next keyframe.
  • basis_rtmp.c: drop media that arrives before the avcC sequence header rather than announcing 0x0 (RTMP always carries the SPS in that header).
  • basis_win_decode.cpp: the no-frame-size diagnostic now names the actual codec and states the observable failure, instead of always attributing it to H.265.

RTSP is unaffected — it takes its dimensions from the SDP parameter sets before media flows.

Windows x64 DLL and Android arm64 .so rebuilt (RIST-enabled).

Required checks

All boxes below must be ticked before this PR can merge. If a check is genuinely N/A, tick it anyway and explain under Notes.

  • Tested — I built and ran this locally. The change works in the editor and (where relevant) in a built player.
  • Transform access is combined and limited — In hot paths, transform reads/writes go through TransformAccessArray or are otherwise batched. I have not added per-frame transform.position / transform.rotation / transform.localPosition calls inside loops. Whenever I need both position and rotation, I use the combined APIs — SetPositionAndRotation / SetLocalPositionAndRotation for writes, GetPositionAndRotation / GetLocalPositionAndRotation for reads — instead of two separate property accesses; the combined call does one local-to-world matrix traversal instead of two.
  • Addressables used for asset/memory loading — Any new asset loads go through Addressables. No new Resources.Load, no direct asset references that pull large content into memory on scene load.
  • No new GetComponent / AddComponent where avoidable — Where unavoidable, the result is cached on a field, and any GetComponent<T> is replaced with TryGetComponent<T>(out var x) — bare GetComponent will be denied. TryGetComponent is the modern API (Unity 2019.2+) and skips the Editor-only GC allocation GetComponent causes when a component is missing: Unity wraps the null return in a managed "fake null" object so its overloaded == operator can still detect destroyed C++ objects, and constructing that wrapper allocates; TryGetComponent returns a bool plus out parameter and never builds the wrapper. None of these calls run inside Update, LateUpdate, FixedUpdate, jobs, or other per-frame code paths.
  • Per-frame work is scheduled through BasisEventDriver — Any new per-frame work hooks into BasisEventDriver rather than adding standalone Update / LateUpdate / FixedUpdate callbacks on a MonoBehaviour.
  • Anything added to BasisEventDriver is bulletproof, or guarded by try/catchBasisEventDriver runs the single per-frame tick that drives the whole framework (network apply, local player sim, blendshapes, JigglePhysics, nameplates, and more) as one sequential chain. An unhandled exception anywhere in that chain aborts the rest of the tick, so every step after the throwing one is silently skipped for that frame. New work added to the driver must either be guaranteed not to throw, or be wrapped in a try/catch that contains the failure and surfaces it through BasisDebug — logged once / rate-limited, never every frame (see the existing HVRBasisBuiltInAddresses.Simulate() guard for the pattern). Expect this to be scrutinized closely in review.
  • Considered jobification — I asked whether this work can be moved to a Unity Job (Burst-compiled where possible). If it can, it is. If it cannot, the reason is in Notes.
  • No needless { get; set; } properties or access lockdowns — Public fields are fine; Basis is meant to be read and modified freely, so don't wall things off private/internal without a real reason. Don't wrap a field in { get; set; } when the accessors do nothing — property accessors have a real performance cost vs direct field access, and the lead maintainer prefers plain fields (or a method / setter-only property when only the setter needs logic) over a noop-getter pair. For .Instance singletons, callers reassigning Type.Instance is allowed; if that would break your code, log a warning or throw — don't block the assignment. Locking down access is not your call.
  • Camera access goes through BasisLocalCameraDriver — Code that needs the local camera (transform, projection, rig data, etc.) pulls it from BasisLocalCameraDriver rather than looking one up itself. Don't roll a separate camera discovery path.
  • Logging uses BasisDebug — All new logging calls go through BasisDebug.Log / BasisDebug.LogWarning / BasisDebug.LogError (with an appropriate LogTag) instead of UnityEngine.Debug.Log / Debug.LogWarning / Debug.LogError. BasisDebug routes through Basis's tagged, color-coded logger and respects the project-wide LoggingDisabled toggle so logging can be killed at runtime; bare Debug.Log calls bypass that and will be denied.
  • No scene-wide discovery for dependencies — New code is architected so it does not need FindObjectOfType / FindObjectsOfType / GameObject.Find / FindGameObjectsWithTag to locate what it depends on. References are wired in — registered through an existing manager/driver, injected at init, or passed in by the caller — rather than discovered by scanning the scene at runtime. If a scene scan is genuinely unavoidable, justify it under Notes.
  • No allocations in hot paths — Per-frame code (Update / LateUpdate / FixedUpdate, simulation loops, jobs, anything called once per frame or more) does not allocate. No new on reference types, no LINQ, no string concatenation/interpolation, no boxing, no foreach over interface-typed collections. Allocate once at init and reuse the buffer.
  • No debugging in hot paths — No log calls of any kind on per-frame paths, including BasisDebug. Hot-path logging floods the console and incurs cost on every frame regardless of whether the message is filtered out downstream. If a hot-path log is needed while iterating, gate it behind #if UNITY_EDITOR and remove (or leave gated) before merge.
  • Hot-path collection access is optimized — Cache .Count (lists) / .Length (arrays) into a local int before the loop instead of re-reading the property each iteration. Prefer T[] (with a separate length int when the array is over-sized) over List<T> where the data is hot — Unity's mono BCL doesn't expose CollectionsMarshal.AsSpan(List<T>), so a list can't be fed into Span<T> / unsafe paths cleanly. Where the perf justifies it, drop into Span<T> / ref locals / Unsafe.As / unsafe pointer code to skip bounds checks and copies, and call out the invariants you're relying on under Notes so reviewers can sanity-check them.

Testing details

Tick the platforms you actually tested on. Leave the rest unticked — these are informational and do not block merge.

  • Windows
  • Linux
  • Android
  • iOS
  • macOS

Input / control mode coverage:

  • Tested in VR (note headset under Notes)
  • Tested in desktop / non-VR mode
  • Tested with phone controls (mobile touch input)
  • N/A — change does not touch player/XR/input code

Where applicable, confirm these flows still work after your changes:

  • Hot-switching (desktop ↔ VR mode swap at runtime)
  • Avatar swapping
  • Server swapping (joining / leaving / changing servers)
  • N/A — change does not touch any of the above

Notes

This is a native C/C++ plugin change (the MPEG-TS and RTMP demuxers plus the Windows decoder-config guard) with no Unity C# surface, so the transform / Addressables / GetComponent / BasisEventDriver / jobification / property / camera / logging / hot-path required-checks are all N/A and ticked as such.

Verification (Windows) — done with the plugin-loading probe harness, which loads the shipped basis_media_native.dll and drives real playback, against live feeds:

  • Live H.264 RIST feed: previously errored at 0x0, now plays at 1920x1080 with the position advancing.
  • HTTP-TS H.264 live: recovers the same way (same mid-GOP join path).
  • HEVC-over-TS: still refuses cleanly via the sizeless-track guard, now with a codec-named message.
  • H.264 in MP4: unchanged.

These line up with the mediaplayer TESTING.md transport rows (RIST plain, HTTP-TS live) and the HEVC-in-TS refusal case.

RTMP is code-only here — it isn't exercised end-to-end yet, as there's no public RTMP-pull endpoint stood up to drive it. The change is the direct analogue of the TS fix (wait for the header carrying the SPS) and leaves the RTSP and MP4 paths untouched.

Android — the arm64 .so is rebuilt with the shared demuxer fix but has not been run on-device; the Windows x64 DLL is the binary verified above.

…TS/RIST and RTMP

The TS/RIST and RTMP demuxers announced the video format from the first
access unit they saw and then latched it. On a live join between keyframes
that AU has no SPS, so they announced a 0x0 frame size, the decoder refused
to configure, and the parameter sets in the following keyframe were never
read.

- basis_ts.c: for H.264, hold the announce until an access unit carries an
  SPS, dropping the pre-IDR AUs (they can't decode without the keyframe).
- basis_rtmp.c: drop media that arrives before the avcC sequence header
  rather than announcing 0x0.
- basis_win_decode.cpp: name the actual codec in the no-frame-size error
  instead of always blaming H.265.

RTSP is unaffected — it takes its dimensions from the SDP parameter sets.

Verified end to end against a live H.264 RIST feed: previously errored with
a 0x0 frame size, now plays at 1920x1080. HTTP-TS H.264 recovers the same
way; HEVC-over-TS still refuses cleanly; H.264 in MP4 is unchanged. Windows
x64 and Android arm64 plugins rebuilt.
@towneh towneh added the bug Something isn't working label Jul 17, 2026
@towneh
towneh requested a review from dooly123 July 17, 2026 20:22
@dooly123
dooly123 merged commit 39c789d into BasisVR:developer Jul 17, 2026
14 checks passed
@towneh
towneh deleted the fix/mediaplayer-h264-midstream-dimensions branch July 17, 2026 22:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants