Skip to content

fix(stream): fall back by codec when a decoder refuses the stream - #67

Merged
enricobuehler merged 1 commit into
mainfrom
fix/decoder-fallback
Oct 30, 2026
Merged

enricobuehler merged 1 commit into
mainfrom
fix/decoder-fallback

Conversation

@enricobuehler

Copy link
Copy Markdown
Member

Fixes the fallback half of #59. The codec selector is already there: the "Video codec" row in Settings (Automatic / HEVC / AV1 / H.264). This PR adds no setting.

The four gaps

  1. A lying isConfigSupported loops forever. A rebuild now probes only the accelerations after the one that failed before its first frame: prefer-hardware → no-preference → prefer-software. If none is left, the codec is undecodable. A new configuration from the host starts at hardware again. A decoder that has produced frames keeps its acceleration through a later error.
  2. A synchronous throw from decoder.configure() escaped. It is now counted, logged and routed to the same rebuild as the error callback.
  3. Codec-level fallback. If every acceleration refuses the stream's codec and another codec is on offer, the engine drops that codec from the offer and reconnects, the way restartInSdr() drops HDR. A launch notice then says "This browser can't decode HEVC, so the stream uses H.264." It adds ", ignoring the Video codec setting" when the player had pinned the refused codec. Each codec falls back once per stream the player starts, so two failing codecs can't ping-pong. The existing error shows only when no codec is left. pf_session_codecs no longer forces H.264 back in, so a refused H.264 really leaves the offer. An empty mask still offers H.264.
  4. The overlay names the decoder. _pf_video_decoder(accel) is a new export (0 unknown, 1 hardware, 2 software). The page calls it on a decoder's first frame. The overlay then reads WebCodecs, hardware, WebCodecs, software, or WebCodecs for no-preference.

Tested

  • npm test: 88 pass, including new video.test.ts cases and one new engine.test.ts case:
    • the ladder never re-probes hardware and ends in onUndecodable
    • a synchronous throw reaches the rebuild
    • the first frame reports hardware, and a later error keeps the acceleration
    • the engine re-offers without the refused codec, shows the notice, errors once nothing is left, and resets on the next player-started stream
  • The new cases fail against main.
  • npm run check is clean.
  • In packages/stream: cargo fmt --check, cargo clippy --all-targets and cargo clippy --target wasm32-unknown-emscripten -- -D warnings are clean, cargo test passes 21, and bash build.sh links (the emitted glue exports _pf_video_decoder).
  • Not tried on glass with a real VA-API browser.

A browser whose isConfigSupported says yes to prefer-hardware while
configure fails rebuilt with that same setting twice a second, for good:
a black screen. A rebuild now moves past the acceleration that failed
before its first frame, down to prefer-software, and a configure that
throws instead of calling error reaches the same rebuild.

A codec this browser decodes under no acceleration ended the stream
even when another codec was on offer. The engine now drops it from the
offer and reconnects, once per codec per stream the player starts, and
says which codec took over, including when that overrides the codec
setting. H.264 can leave the offer too, so a pin on it can fall back.

The overlay said WebCodecs whether the frames came from hardware or
software. It now names the acceleration once a decoder has produced
a frame.

Fixes the fallback half of #59.
@enricobuehler
enricobuehler merged commit ad97383 into main Oct 30, 2026
4 checks passed
@enricobuehler
enricobuehler deleted the fix/decoder-fallback branch October 30, 2026 17:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant