fix(player): force NV12 pixel format for subtitle rendering - #1476
Open
LTe wants to merge 1 commit into
Open
Conversation
CoreImage (used by composite OSD) doesn't support y420 (planar YUV) but does support NV12 (420v biplanar). This ensures subtitles render correctly when software decoding produces y420p frames.
Contributor
|
This pull request has merge conflicts. Please resolve the conflicts so the PR can be successfully reviewed and merged. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📦 Pull Request
🔖 Summary
Force NV12 pixel format in the mpv video filter pipeline to ensure subtitles render correctly when software decoding produces planar YUV (y420p) frames.
🏷️ Ticket / Issue
🛠️ What's Changed
vf=format=fmt=nv12option to mpv initialization to convert all decoded frames to NV12 (biplanar) before they reach the CoreImage-based subtitle compositing pipeline.📋 Details
When mpv falls back to software decoding (e.g., for codecs not supported by VideoToolbox, or on the iOS Simulator which lacks hardware decoding), decoded frames use the y420p pixel format (triplanar YUV — 3 separate planes: Y, U, V). The subtitle overlay system (composite OSD) uses Apple's CoreImage to blend subtitles onto video frames, but CoreImage does not support triplanar y420p — it only works with biplanar formats like NV12 (
420v).This causes subtitles to silently fail to render whenever software decoding is active — notably, subtitles were completely broken on the iOS Simulator.
The fix inserts a video filter (
vf=format=fmt=nv12) that converts all frames to NV12 before rendering, ensuring CoreImage always receives a compatible pixel format. This fixes subtitle rendering on both the Simulator and on physical devices during software decoding fallback.None.
🔐 Security & Privacy Impact
None.
⚡ Performance Impact
Minimal. The format conversion (
y420p → nv12) is a lightweight pixel rearrangement (interleaving U and V planes) that occurs in the CPU pipeline. When hardware decoding is active, frames are already NV12, so the filter is effectively a no-op.🖼️ Screenshots / GIFs (if UI)
Subtitles now render correctly during software decoding fallback. Previously they were invisible.
✅ Checklist
bunscripts)🔍 Testing Instructions
git fetch origin pull/<PR_ID>/head:branchname && git checkout branchnamebun installbun run ios⚙️ Deployment Notes
No additional configuration needed. The change is contained within the mpv player native module initialization on iOS.
📝 Additional Notes
modules/mpv-player/ios/MPVLayerRenderer.swift)