saneSAR admits small-but-wrong ratios: bound the resulting display aspect, not just the components

[kskchaitanya1993]

saneSAR bounds each SAR component to 256, which catches the pathological values (the 1088:1 the comment mentions) but still admits small-but-wrong ratios that stretch the picture into an unwatchable strip.

Observed on a live 1080p H.264 IPTV channel that declared SAR 3:1, then 2:1 on a later run — both well inside the existing gate. 3:1 applied to 1920x1080 yields a 5.33:1 display aspect; 2:1 yields 3.55:1. The picture renders as a horizontally smeared band. The user-visible workaround is switching the aspect mode to Fill, which is a real tell that the ratio itself is wrong rather than the content being unusual.

The magnitude gate can't distinguish these, because the problem isn't the size of the numbers — it's the aspect they produce.

What we do locally

Bound the resulting display aspect rather than the component magnitudes, in the same helper:

static func saneSAR(_ sar: AVRational) -> AVRational? {
    guard sar.num > 0, sar.den > 0, sar.num <= 256, sar.den <= 256 else { return nil }
    // Reject an implausibly extreme pixel aspect (e.g. a bogus 3:1 that stretches 1920x1080 into a
    // 5760x1080 strip). No real PAR stretches a frame more than ~2.5x on either axis.
    let ratio = Double(sar.num) / Double(sar.den)
    guard ratio <= 2.5, ratio >= 1.0 / 2.5 else { return nil }
    return sar
}

Rejecting returns nil, which falls back to square pixels — for a stream lying about its SAR that is the correct picture, and for a stream telling the truth it's never reached, since no legitimate PAR is that extreme.

On the threshold

2.5 is a judgement call and I'd expect you to want a different one. The widest genuine PARs in circulation are the anamorphic DVD/broadcast set — 16:11 (~1.45), 12:11, 64:45, and the 4:3-into-16:9 cases around 1.8 — so 2.5 leaves a lot of headroom above anything real while still rejecting the 3:1 above. Verified on our side that legitimate anamorphic content is unaffected: a 720x576 PAL source at 16:11 still resolves to ~16:9 and renders correctly.

This refines the gate you added in #177 rather than replacing it — both checks are useful, they just catch different failures. Raising as an issue rather than a PR since the bound is a policy choice; happy to send it either way.

---

This issue was auto-generated by Claude on behalf of @kskchaitanya1993.

[superuser404notfound]

Fixed on main in 51d7c8e9, and the diagnosis pulled a second defect out with it (d3fd6e8c, below). Unreleased for now, both go out with the next release.

You are right that the component gate is the wrong instrument, and I took the bound one step further than your patch: onto the display aspect rather than the ratio. Two numbers from the standard VUI table decided it, and both are in your own domain.

A cap of 2.5 leaves your second observation broken. 2:1 is 2.0, so it passes, and 1920x1080 at 2:1 is still the 3.56:1 band you reported. Any cap low enough to catch it has to sit below 2.0.

A cap below 2.91 rejects real broadcast SD. 32:11 is ff_h2645_pixel_aspect idc 8 (H.264 Table E-1), it is 2.909, and it is exactly right on 352x576 half-D1, where it resolves to 16:9. That is ordinary DVB SD, so on an IPTV client it is not a hypothetical.

Those two bracket the useful range out of existence, which is the actual finding here: the magnitude of a SAR carries no information about whether it is a lie. 2:1 on 960x1080 is correct and resolves to 16:9; the same 2:1 on 1920x1080 is the defect. Only the frame it applies to can tell them apart. So PixelAspectPolicy keeps your component gate as a cheap pre-filter and bounds what the ratio produces:

static let maxDisplayAspect: Double = 3.0
static let minDisplayAspect: Double = 1.0 / 3.0

Nothing real is wider. Ultra Panavision 70, the widest format ever shot, is 2.76, and anamorphic SD resolves to 16:9 by construction. Wider pictures do exist (32:9 desktop captures) but they store square pixels, and square pixels are never judged at all: they correct nothing, so there is no claim to disbelieve. Three details beyond the bound itself:

• A rejected candidate drops through the frame -> codec context -> stream order instead of ending resolution, so a lying frame SAR can still fall back to a believable container one, and to square pixels only when nothing survives.
• The FrameExtractor resolves through the same policy now. It had no gate at all, so the same lying ratio was scaling thumbnails to the same band.
• One line per stream names what was dropped: [SWDecoder] SAR 3:1 rejected on 1920x1080: display aspect 5.33 outside 0.33...3.00, using square pixels. A smeared picture should identify its own cause rather than look like a renderer bug.

The second defect, which may matter more to you than the first. Building a fixture to verify this end to end (a VP9 MKV declaring SAR in the container, since VP9 cannot carry it in the bitstream) the engine resolved frame=0:1 ctx=0:1 stream=0:1 and attached nothing at all. The container-SAR fallback read codecpar->sample_aspect_ratio only, and that is the one field a container-declared ratio never reaches: Matroska writes its DisplayWidth quotient to st->sample_aspect_ratio (matroskadec.c), MP4 does the same with pasp (mov.c). So the fallback was dead in precisely the case it was written for, and only MPEG-2 sources hid it, because their ratio arrives per frame from the sequence header. Both fields are consulted now, in the decoder and in the FrameExtractor. If you have anamorphic MKV or MP4 sources that route to the software path, they were drawing at coded dimensions before this.

One thing I would still like to know, since the gate protects the picture without explaining the stream: what does the [SWDecoder] SAR ... line say on that channel, specifically whether the 3:1 arrives as frame=, ctx= or stream=? A VUI genuinely declaring 3:1 and a mid-stream join misparsing an SPS are different problems, and the second one would be worth chasing on its own.

Thanks for raising it as a policy question rather than sending the patch. The threshold was the right thing to be unsure about, and the two table entries only turned up because you flagged it.

[kskchaitanya1993]

The 2:1 point lands, and it means our patch never fixed the second case we reported. 2.0 passes a 2.5 cap, so the 1920x1080 at 2:1 channel was still drawing at 3.56:1 with the patch in place — we had reported both ratios in the same breath and then shipped a bound that only caught one of them. Bounding the display aspect instead of the ratio is obviously the right instrument, and the 32:11 entry is the part I would not have found: capping anywhere under 2.91 to catch 2:1 would have broken ordinary DVB SD, which is a large slice of what our users watch.

The framing that the magnitude of a SAR carries no information about whether it is a lie — 2:1 correct on 960x1080, the defect on 1920x1080 — is the actual finding, and it's a better one than the issue asked for.

On your question about frame= / ctx= / stream=: I can't answer it yet, and I'd rather say so than guess. That channel is a third-party IPTV live stream we no longer have a capture of, and the observation is from late July. Our patch sits in saneSAR, which only ever sees the ratio, so nothing on our side recorded which axis it arrived on — the log line that would have distinguished them is the one you just added. When the release lands I'll watch for [SWDecoder] SAR … across the live catalogue and report the axis if it recurs. If it turns out to be a mid-stream join misparsing an SPS rather than a VUI genuinely declaring 3:1, that seems worth its own issue as you say.

Two things I can offer in the meantime:

• The ratios were varying within one session — 3:1 on one run, 2:1 on a later one, same channel. I don't know whether that points at a mid-stream join or at a genuinely inconsistent encoder, but a stable VUI declaration would presumably not move.
• It was a live 1080p H.264 MPEG-TS channel on the software path, so if the container-SAR fallback you found in d3fd6e8c is involved at all, it would be through the stream axis rather than a Matroska/MP4 pasp.

On the second defect: that one probably matters more to us than the first, yes. Anamorphic MKV on the software path is a real shape in our library, and "resolved frame=0:1 ctx=0:1 stream=0:1 and attached nothing" would have looked to us like content that simply had no SAR rather than a fallback that couldn't read the field it was written for. We'd have had no reason to suspect it. I'll retest anamorphic MKV and MP4 explicitly once the release is out — our test bed has a 720x576 PAL 16:11 fixture that currently only exercises the frame axis, so I'll add a container-declared twin that carries the ratio in the container and nowhere else, which is the case that was dead.

Thanks for taking the threshold seriously rather than just applying the number I suggested.

---

This issue was auto-generated by Claude on behalf of @kskchaitanya1993.

[superuser404notfound]

Shipped in 6.6.0 (51d7c8e9, plus d3fd6e8c for the container-SAR fallback that turned up while verifying it: it read codecpar->sample_aspect_ratio alone, which is the one place a Matroska or MP4 container ratio never lands, so it was dead in exactly the case it was written for). The gate is on the display aspect the ratio resolves to on its own frame, bounded to 1:3 ... 3:1, rather than on the components: a 3:1 on 1920x1080 is rejected and says so, while the same value on a 960x1080 broadcast frame stays legal.

[kskchaitanya1993]

Retested on 6.6.0 on the Apple TV. d3fd6e8c is confirmed on device, and it fires exactly where you said it would.

I built the fixture the case actually needs: VP9 in Matroska with -aspect 16:9, 640x480 stored. VP9 cannot carry a ratio in its bitstream, so the 4:3 exists only in DisplayWidth/DisplayHeight — nothing on the frame, nothing on the codec context.

[SWDecoder] Opened: 640x480, codec=vp9, threads=5, 8-bit
[SWDecoder] SAR latched 4:3 (frame=0:1 ctx=0:1 stream=4:3)
AETHER first REAL video frame rendered (backend=software, t+1.0s)

frame=0:1 ctx=0:1 stream=4:3 is your diagnosis verbatim — both of the fields the old fallback consulted are empty, and the ratio is on the stream axis alone. It resolves and latches now instead of dropping to square pixels.

Worth saying plainly: we would never have caught this ourselves. Our existing anamorphic fixture is H.264 via -vf setsar=16/11, and libx264 writes that into the VUI, so it arrives on the frame axis and the fallback is never consulted. A whole class of content — anamorphic MKV and MP4 on the software path — was drawing at coded dimensions and our test bed said everything was fine. The container-only fixture is a permanent entry now.

On your frame= / ctx= / stream= question: still can't answer it for the reported channel, but the position is better than last time. I now know what the line looks like and that it names all three axes, so when that channel or another one trips the bound I can read the axis straight off it rather than guessing. I've got a live catalogue to watch and will report the axis if the 3:1 recurs. If it turns out to be a mid-stream join misparsing an SPS rather than a VUI genuinely declaring it, I'll open that separately as you suggested.

One small thing that helps here: the rejection line naming the resolved display aspect and the frame it applied to is the difference between "the picture looks wrong" and a diagnosis. We had the smeared-picture symptom for weeks with nothing in any log pointing at the SAR.

---

This comment was drafted and posted automatically by Claude, working on behalf of @kskchaitanya1993.

[superuser404notfound]

frame=0:1 ctx=0:1 stream=4:3 on a VP9 Matroska is the exact shape, thanks for building the fixture that carries the case rather than one that merely mentions it.

That distinction is worth naming, because this issue produced it twice from opposite directions. A -vf setsar=16/11 on libx264 records the intent, but libx264 writes the value into the VUI, so it arrives on the frame axis and the container fallback is never reached: the fixture is green and says nothing about the path under test. I walked into the same trap while verifying the gate. My first attempt used MPEG-2, which can express only four display aspects, so setsar=3/1 silently became a 1:1 on the frame that won ahead of the container ratio, and the test looked like a pass while exercising nothing. An encoder flag states what you asked for, not where the value landed, and only a probe of the finished file settles it.

Two things about that log line before the axis hunt, since both change how it reads.

stream= is not "the container". It is bitstream-first: codecpar->sample_aspect_ratio when populated, otherwise AVStream->sample_aspect_ratio. Matroska and MP4 leave codecpar empty, which is why your fixture shows the container ratio there. MPEG-TS has nowhere to declare a container ratio at all, so on that channel stream= would be the parser's reading of the SPS VUI at open time, while frame= is what the decoder attached from the SPS in force for that frame. That makes the two axes more informative than they look for the case you are chasing: if they disagree, the stream changed its declaration between the join and the frame, which is the mid-stream-join fingerprint. If they agree, the VUI genuinely says 3:1 and the encoder is the problem.

Both lines fire once per decoder session, and the rejection line only before anything has latched. A ratio that changes mid-stream will not produce a second line, and the latch keeps the first sane non-square value for the rest of that session by design, so per-field oscillation cannot flicker the geometry. Per tune is therefore the granularity you get, which suits a catalogue sweep but will not show a change within one continuous session. If the 3:1 turns out to move while the picture stays up, say so and I will look at what a change-of-declaration line should cost.

Leaving this open until that channel is observed on 6.6.0. The container defect is confirmed and the gate is verified against constructed fixtures, but the reported symptom is the one thing still untested against the stream that produced it, and there is no rush on that.

On the rejection line naming the resolved display aspect: that is the lesson I took from this one. A picture that is merely wrong tends to get attributed to the renderer, and weeks of a smeared channel with nothing in any log pointing at the SAR is the cost of a policy that declines silently.

[kskchaitanya1993]

Device confirmation of the gate on the reported band, plus one finding about the axis question itself.

I built the case rather than waiting for the channel: VP9 in Matroska, 1920x1080 with SAR 3:1 declared in the container only — sample_aspect_ratio=3:1, display_aspect_ratio=16:3. VP9 cannot carry a ratio in its bitstream, so this is the stream axis alone, and 5.33 is the exact band we originally reported. On the Apple TV, 6.6.0:

[SWDecoder] Opened: 1920x1080, codec=vp9, threads=5, 8-bit
[SWDecoder] SAR 3:1 rejected on 1920x1080: display aspect 5.33 outside 0.33...3.00, using square pixels
AETHER first REAL video frame rendered (backend=software, t+1.0s)

Rejected, named, and the picture draws square instead of smeared.

The finding: the rejection line does not name the axis. The latch line does — SAR latched 4:3 (frame=0:1 ctx=0:1 stream=4:3) — but the rejection path prints only the ratio, the frame and the resolved display aspect. So the diagnostic you asked us for is unobtainable in precisely the case that triggers it: any channel that trips the bound is by definition rejected, so it never prints frame= / ctx= / stream=.

That inverts what I told you last time. I said I now knew what the line looked like and could read the axis straight off it when the channel recurred — that was true of the latch line, and I had not checked that the rejection path is a different line with a different payload. It isn't a criticism of the design; the rejection message answers "why is this picture square", which is the question it was written for. It just cannot also answer "which axis lied".

If you want the mid-stream-join fingerprint to be readable, the three axes on the rejection line would do it, and it is the same values already in hand at that point. Your call entirely — you know what that costs in log noise better than I do. Without it, the two hypotheses you separated (a VUI genuinely declaring 3:1 versus a join misparsing an SPS) stay indistinguishable from the field, because the rejection is the only line a bad ratio produces.

On our side: still watching the live catalogue on 6.6.0. We have the fixture path working end to end on the device now, so anything you want probed against a constructed shape, we can turn around quickly.

---

This comment was drafted and posted automatically by Claude, working on behalf of @kskchaitanya1993.

[superuser404notfound]

Confirmed, and the inversion is worth stating plainly: a rejected SAR never latches, so the latch line that names the three axes cannot fire for a ratio that trips the bound. The rejection line was the only line a bad ratio produced, and it was the one without the answer. The diagnostic was unobtainable in precisely the case that asks for it.

Fixed on main in e6cf3328, unreleased for now, it goes out with the next release. The axes ride on the rejection line in the same shape as the latch line:

[SWDecoder] SAR 3:1 rejected on 1920x1080: display aspect 5.33 outside 0.33...3.00, using square pixels (frame=0:1 ctx=0:1 stream=3:1)

That is your fixture, the container-only VP9 Matroska, through the engine here. The reading that matters more for the channel you are watching is the other one. A 1920x1080 H.264 MPEG-TS whose VUI genuinely declares 3:1 (libx264 -vf setsar=3/1, probed in the finished file rather than trusted from the flag) resolves like this:

[SWDecoder] SAR 3:1 rejected on 1920x1080: display aspect 5.33 outside 0.33...3.00, using square pixels (frame=3:1 ctx=3:1 stream=3:1)

Three agreeing axes on a transport stream is the "the encoder means it" fingerprint, since TS carries no container ratio at all: stream= there is the parser's reading of the SPS VUI at open time, ctx= is what the codec context holds, frame= is the SPS in force for that frame. Anything other than agreement on a TS channel says the declaration moved between the join and the frame, which is the other hypothesis and belongs in its own issue.

One detail that changes how the line reads. It names the first axis that actually lost on the display aspect, not the first that cleared the component gate, so with a #177-grade garbage value sitting in front of the real one you get SAR 3:1 rejected ... (frame=1088:1 ctx=3:1 stream=0:1): the headline is the ratio that would have been attached, the parenthetical is where each value sat.

Granularity is unchanged, still once per decoder session and therefore per tune. One consequence of the reject path not latching may be useful on a catalogue sweep, though: a session that starts rejected can still latch later, when a believable non-square ratio turns up on any axis while the picture is up. That prints the latch line at that moment, so a channel whose declaration moves from a lie to something legal hands you both lines with the axes at each point. The reverse stays suppressed by design: once a sane value has latched, a later lie cannot flicker the geometry.

Thanks for building the 1920x1080 case instead of waiting for the channel, and for correcting your own earlier reading of the line rather than letting it stand. The gate is confirmed on device at the reported band now, which leaves the channel itself as the only untested part, and there is no rush on that.