Trimmed the tooltips, gathered every explainer into one file, and reworked the Inspect cards

[CodyCBakerPhD]

Every ⓘ popover and hover title is cut back to what it has to say, and copy that repeated a figure shown right beside it is gone entirely: the codec box no longer restates the profile and level, the chroma box no longer names the format, the atom map no longer re-explains the box tree, the two plots on the GOP card drop their captions, and a finished sweep square's tooltip no longer lists the change, the factor, the projected size and the time that are printed on its face. Progress notes stop narrating the bar beside them — no Encoding… 45%, no Done. under a full bar.

A size factor now reads original 2.4× larger or encoded 1.3× larger instead of 2.4× reduction / 1.3× inflation, so which file the factor belongs to is on the readout rather than left to the reader. Matrix squares widen by 24px to hold it.

All of the app's teaching copy now lives in src/lib/explainers.ts, ordered as the app reads: tab by tab left to right, card by card down each page, with copy shown on two tabs sitting where it first appears. The knowledge bases' prose came with it — the container records, codec descriptions, metadata tag seeds and encoder-signature hints — leaving codecKb, containerKb and metadataTagKb holding only the lookup and parsing that read those tables. ContainerInfo moves to lib/types so the copy and the lookup do not import each other. The QuickTime tag table splits in two: the four-character ilst atoms, grouped by subject, and the reverse-DNS keys an mdta handler declares, which are a table and an origin of their own; ©cpy and cprt no longer both render as plain "Copyright".

Inspect is reorganized. Each card leads with what it measured and reads its teaching text under that, and every figure sits on a tinted card as wide as its own label and value, with <code> values inset on a background that holds up in either theme. The faststart badge and explainer move to the MP4 Box / Atom Structure card, above the map that draws the box order they report. This File's Container folds into Video Container Overview, which names the container in its heading, drops the Type row, and sets its four figures on one line with an explainer for the MIME type beneath them. The panel reads overview, video track, atom map, GOP/keyframe, bitrate, audio — the keyframe structure follows the box order that decides it, and the audio track comes last. The page takes a wider column whatever the Educational switch says, so a row of figures is not left wrapping one card onto a line of its own; the cap leaves the fixed corner watermarks their margins. The Full Analysis document follows the same layout and order.

The Video Track card now reports the chroma format it read out of the file's codec configuration record (avcC, hvcC, av1C, vpcC), falling back to what the codec parameter string settles on its own, and stays quiet where neither says — rather than naming yuv420p on every file, as the explainer used to.

On the atom map, the container explainer's mention of the Atom Map links to that section, zooming stops at a box that already fills the view instead of taking click after click on the same range, and the legend keys only the box families it actually drew.

The two encoding tabs are tightened as well. A sample run's Side-by-Side comparison sits in the Try It on a Sample card that produced it. A saved encode is named for what it went through — video-reencoded.mp4, or video-transcoded.mp4 where the container changed — and the command says the same. The builder keeps its Scaler field on show at every resolution, inert until one resamples, and drops the GOP equation and the flag notes on its checkboxes. The sweep's settings bar works its axes out to a total (2 × 5 × 2 = 20), the Reuse earlier measurements tick is retired in favour of always reading back what an earlier run of the file measured, and Estimate Detail reads as two lines: what was sampled, then what it projects to.

Two controls move. The Educational switch is one fixture in the header beside the light/dark toggle, a preference next to a preference, rather than one instance in the first card of Inspect and another in Reencode. And the ⓘ button's "i" is drawn rather than typed: a letter sits where its font puts it, so the italic serif one rode off-centre in its circle, differently again wherever Georgia is not installed.

Prompts

trim the length of all tooltips, especially on the 'compare quality' page

and restate a.bx reduction/inflation as "original video is c.dx larger than the reencoded version"

please consolidate all educational text under the 'explainers' file so they can all be in one place

e.g. lines such as A video container is the wrapper around the media, not the compression method itself. It stores the encoded tracks, the index that maps timestamps to byte ranges, and the metadata tags. The codec is what actually compresses the pixels and samples. The same H.264 video can sit in an MP4, a MOV (.mov), or a Matroska (.mkv) file unchanged: moving it from one to another copies the already-compressed frames across byte for byte, without decoding or compressing anything again, so it takes seconds and the picture that comes out is the picture that went in. Containers differ in which codecs they accept, though, so not every codec fits in every container.

im making direct changes to the file; please organize the entries in that file according to when the appear on the pages; left to right on tops and top to bottom on pages

Also I can't find the entries governing things like

MP4 (MPEG-4 Part 14, an ISO Base Media File Format (ISOBMFF) layout; .mp4, .m4v, .m4a). The default delivery container for the web: a tree of boxes (atoms) where moov holds the sample index and mdat holds the frame bytes. See the Atom Map tab for this file's layout.
Video codecs it can carry: H.264/AVC (near universal), plus H.265/HEVC, AV1, VP9 and ProRes, which the format accepts but far fewer players handle
Audio codecs: AAC (the usual pairing), MP3, AC-3/E-AC-3, plus Opus and FLAC in newer players
Playback: Plays in every browser and hardware decoder when the payload is H.264 + AAC, which is why it is the safe default.

please expose them here as well

move the faststart description and the "✓ Faststart (moov before mdat)" check out of the Video Container Overview and into the Atom Structure card

likewise abosrb the "This File's Container: MP4" into the "Video Container Overview" card and remove the "Type
MP4" value there since its now redundant

add a description for the MIME type and explain the pieces within, e.g.,

video/mp4; codecs="avc1.640028, mp4a.40.2"

That decodes as H.264 High Profile Level 4.0 plus AAC-LC. Common values:

avc1.PPCCLL — H.264, hex-encoded profile/constraints/level (avc1.42E01E = Baseline 3.0)
hvc1.* / hev1.* — HEVC; the two differ in where parameter sets live, and Apple devices are picky about it
av01.0.08M.08 — AV1, Main profile, level 4.0, 8-bit
vp09.00.10.08 — VP9
mp4a.40.2 = AAC-LC, mp4a.40.5 = HE-AAC, plus plain opus and flac

yes, retitle the card "Video Container Overview: MP4"

The current grid layout of those container values looks odd

please fit on a single line; widen card if needed

or actually, what do you think? Should the MIME type be moved to the video track section instead?

now the line looks cramped - can you widen the cards when in educational mode?

and maybe move the individual summary results to the top and the educational stuff below that

and the MIME type is a longer description, maybe make that its own info card rather than a tooltip (which are usually short, at most 2 sentences)

ok but now you can pad out those entries so they aren't so crunched together

also I shortened the MIME type description so now it can go back to being a tooltip

also mix up the emojis a bit for flavor; for the particular video info box use a movie camera

and use 🎨 for the chroma subsampling

also add little background highlights around each of those extracted values in each card, to make them pop out more

The following video track outputs are for the basic demo file

Video Track
Codec avc1.42e015
Resolution 480×272
Frame Rate 29.970 fps
Frames 1,899
Profile Baseline
Level 2.1
Color Space –
💡 H.264 / AVC (2003), Advanced Video Coding. …
💡 Chroma subsampling (yuv420p) halves the horizontal & vertical resolution of the color channels while keeping full-resolution luma. …

why is the color space "-" but then yuv420p is given in the card description?

I'd go with option to on not asserting unless known, but I'd also make more of an effort to know

Also in the interactive component for the atom structure exploration, I can infinitely navigate down to 'trak' - is this true or useful? shouldn't it stop at some point?

MP4 Box / Atom Structure
✓ Faststart (moov before mdat)
Whole file › minf › trak › trak › trak › … › moov › moov › trak

where it says "See the Atom Map tab for this file's layout." is it possible to add a nav link to that section so a user can click it?

Also I meant a background card rather like what is seen beyond each individual demo movie on the demo files page, yknow? like that (screenshot attached) but for each extracted detail about a video

thanks thats a lot better; now we do need to make the <code> background stand out a bit more in dark mode

Would it ever be useful to show the N boxes too many to draw, in the color of most of them on the atom map?

remove text "A box's color is the top-level box it belongs to; each row down is one level in."

remove text "Profile: Baseline · Level: 2.1" from within the specific video track codec card since it is right about it in the cell details

remove text "This file is 4:2:0, as its codec configuration states." from the chroma subsampling detail since it is likewise displayed right above in the details. The note about 4:2:0 being even is nice though, when that is the inferred chroma

remove the card in the atom structure section with this text

An MP4 file is a tree of boxes (also called "atoms"): ftyp declares the brand/compatibility, moov holds all metadata & the sample index (offsets, sizes, timestamps, keyframe flags), and mdat holds the raw encoded frame bytes it points to. Fragmented MP4s repeat moof+mdat pairs instead of one big mdat.
The map below is that tree on its side: left to right across the file, each row down one level of nesting. Siblings split their parent's width by how many boxes each subtree holds, so every box gets room and the whole file is on screen at once however long the video is. Width says nothing about size — hover a box for its offset and byte count, or click to zoom into it. The Full Analysis document draws this same map, minus the zooming.

entirely since it is all duplicated elsewhwhere

can you fit the text within each report value subcard better?

theres a lot of whitespace there

especially on the mime type subcard

move audio track card all teh way to the bottom; move GOP card just below the atom structure

and make the educational toggle a little more flush to the top right; also move out it out of the video container overview card and place to the left of Full Analysis

maybe move educational toggle to the right of 'compare quality' button? Any other placement you'd suggest?

yeah total top right next to light mode might be best actually good call!

remove text "
GOP length per keyframe interval (hover a bar for its frame count)";

The text for

Empirical Seeking Test
Samples N evenly-spaced timestamps across the video and measures how far back the nearest keyframe is, plus how long it takes to decode that frame.

seems different from the font sizes/style on the rest of the page, can you standardize that

also there is no vertical spacing between the "Run seeking test" button and the outputs

remove text "Keyframe distance vs. decode time; hover a point for its timestamp"

the info icon in the bitrate subcard is not centered in its circle

audo track bitrate* to be exact

keep cards wide even with educational is turned off to prevent whitespace situatins like this

In src/lib/explainers.ts, restructure the QuickTime metadata tag tables.

1. Split QUICKTIME_TAGS into two arrays.

Keep QUICKTIME_TAGS for the four-character ilst atoms only. Move the five reverse-DNS entries (com.apple.quicktime.make, .model, .software, .creationdate, .location.ISO6709) into a new exported array QUICKTIME_KEY_TAGS with the same TagSeed shape. These are written through the mdta handler — a keys atom declares reverse-DNS names and a parallel ilst holds the values — so the existing "Four characters each" comment above QUICKTIME_TAGS is currently contradicted by its own last five entries. Update that comment to describe only the four-character atoms, and give QUICKTIME_KEY_TAGS its own comment explaining the keys/ilst mechanism.

2. Remove COPYRIGHT_PREFIX_NOTE from the per-tag descriptions.

It is currently appended to 6 of the ~14 © atoms (©nam, ©ART, ©alb, ©day, ©cmt, ©too) and omitted from the rest, so a user who hovers ©wrt first never sees it. METADATA_TAGS_TEACH already explains the 0xA9 text-atom marker above the table, so drop the appends entirely rather than adding the missing ones. Keep the COPYRIGHT_PREFIX_NOTE constant itself if anything else still references it; if this table was its only consumer, delete the constant too. Do not change METADATA_TAGS_TEACH.

3. Disambiguate the two Copyright labels.

©cpy and cprt both currently render as "Copyright", which reads as a duplicate-entry bug in the UI. Label ©cpy "Copyright (QuickTime)" and describe cprt as the form MP4 standardized. Leave the two Description entries (©des, desc) alone — their descriptions already distinguish them.

4. Group the remaining QUICKTIME_TAGS entries by subject with comment headers: work/release, credits, description and text, rights, how the file was made, playback and presentation, capture. Do not add, drop, or reword any other tag beyond what steps 2 and 3 require.

Then update the call sites:

• Add an origin constant for the new array alongside QUICKTIME_ORIGIN, e.g. QUICKTIME_KEY_ORIGIN = "QuickTime metadata key (mdta)".
• Find every place QUICKTIME_TAGS is consumed (lib/metadataTagKb and anything else) and make sure QUICKTIME_KEY_TAGS is loaded into the same lookup with the new origin, so the com.apple.quicktime.* keys still resolve to their descriptions and still render with an ⓘ. This is the step most likely to regress — verify it rather than assuming, and say which files you touched.

Every string in this file is trusted markup rendered through innerHTML, so keep the existing <code>/<b> markup conventions and do not introduce anything that would need escaping. Run the typechecker and the existing tests when you're done.

(a rewritten QUICKTIME_TAGS / QUICKTIME_KEY_TAGS block, pasted in full and used verbatim)

completely remove the "Encodes three seconds of the video with the command above — the real ffmpeg, compiled to WebAssembly, so the bytes are the bytes it would produce — and shows the result against the same seconds of the original, zoomable to the pixel. Nothing is uploaded and the file on disk is untouched.
Which three seconds is the question worth asking, so the track below scans the whole recording: slide the band to the stretch that matters, judging it by the frame above it. A run starts at the keyframe at or before the band, since that is where the cut can be made without decoding the file from the beginning.

One stretch of a fixed length, judged by eye: there is nothing to set here beyond where it comes from. Sampling several places at once to project what a setting saves across the whole file, and sweeping several settings against each other, are the Compare Quality tab's job." description card

same with "Runs the command above over the whole video, here in the page, and saves the result to a file you choose. Nothing is uploaded: the frames are decoded and reencoded locally. Pick where to save when prompted, or the file lands in your downloads folder.
The engine is ffmpeg itself, compiled to WebAssembly, so the output is byte-for-byte what the command gives you on your own machine. It is fetched on first use (~30 MB) and runs single-threaded (no COOP/COEP headers needed on static hosting), so it is slower than realtime: for a full-length recording or a whole dataset, copy the command and run ffmpeg natively instead. What runs here is bounded by what the browser tab can hold in memory."

combine the "Side-by-Side" section and the "Try It on a Sample" card for the reencoding page

rename the output to 'video-reencoded'.mp4

even make it 'transcoded' if going from different container

remove text "Done." (and its predecessors, encoding %)

and don't bury the "original 4.6× larger" statement in a tooltip on the matrix results page; make it first-class just like on the main reencoding page

actually you do, just remove the tooltip since it duplicates

remove "Best here means the smallest encode, and only that: no picture-quality metric is computed, so the highest CRF wins nearly every sweep, and the lowest resolution wins outright when one is ticked. Read the grid, not the star, which has no idea what your tracking needs."

remove text "Re-encoding the chosen square for the A/B window…"

remove "Projected across the whole 1m 3.4s: ≈ 3.5 MB saved" in the matrix tab side-by-side estimated data savings

organize these cards on the last tab better

remove card "⌨️
What the square in the A/B window above — medium (CRF 25), superfast — comes to as an ffmpeg command, over the whole file rather than the sampled seconds. Everything the sweep does not vary (keyframe interval, B-frames, audio, faststart) is taken from the Reencode with FFmpeg tab as it is set there now."

remove tooltip for "What the source spends on the same seconds the encode covered, counted on the same terms: video frames, plus the stretch's share of the audio track and the container's overhead. This is what the encoded segment is compared against."

remove tooltip for "The source's size times the ratio the snippet came to, i.e. what the whole file would come to at these settings if the rest of it compresses like the sampled part. An extrapolation, not a measurement."

remove tooltip for "How much of the file this estimate actually saw. The smaller it is, the more the projection leans on those seconds being typical of the rest; a longer segment narrows the range."

remove "(-bf 0, recommended for seekability)" on reencode options, same for '((+movflags)"

drop the "Hence superfast as the default; run the command natively to use the slow end." from the end of that paragraph

remove "GOP size = round(interval × fps) = round(1 × 29.97) = 30 frames" equation from reencode page

reencode page is missing the scaler option like in the sweep table

remove 'sleap-io' from the parentheses of the superfast x264 dropdown option

"Scaler is the kernel scale resamples with, and it only matters below 100% resolution. lanczos is the sharper: it keeps fine detail (whiskers, tail tips, grid lines) a softer kernel averages away. bicubic is softer, and less prone to the faint ringing lanczos can leave along hard edges.
Sharper is not automatically better downstream, and the detail lanczos keeps costs a few more bits at the same CRF. Compare them in the A/B window at 100% zoom rather than assuming." -> "Scaler is the kernel used for downsampling below 100% resolution. lanczos tends to be sharper and maintains fine details such as whiskers, tail tips, or grid lines. bicubic is softer and less prone to the faint ringing lanczos can leave along hard edges."

remove tooltip for "A combination this file has already been swept at is read back rather than encoded again, including after a reload, so widening a sweep only encodes the new squares.
Only the numbers are kept, never the video: choosing a square still encodes that one combination for the A/B window. Untick to measure everything again, for fresh encoding times or a file changed under the same name."

and remove checkbox "Reuse earlier measurement" completely

calculate an "=" for "2 × 5 × 2 × 2" on the matrix sweep grid dropdown

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://brain-bbqs.github.io/encoding-helper/pr-preview/pr-35/
Built to branch gh-pages at 2026-08-31 06:41 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 67.20000% with 82 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/lib/explainers.ts	74.24%	9 Missing and 8 partials ⚠️
src/ui/analysisTab.ts	0.00%	16 Missing ⚠️
src/lib/chromaFormat.ts	71.69%	1 Missing and 14 partials ⚠️
src/ui/inBrowserEncode.ts	0.00%	11 Missing ⚠️
src/ui/inspectTab.ts	73.68%	2 Missing and 3 partials ⚠️
src/lib/mediabunnyMeta.ts	0.00%	3 Missing ⚠️
src/ui/atomsTab.ts	89.65%	2 Missing and 1 partial ⚠️
src/ui/compareTab.ts	40.00%	2 Missing and 1 partial ⚠️
src/ui/educationalToggle.ts	0.00%	3 Missing ⚠️
src/ui/seekTab.ts	66.66%	1 Missing and 1 partial ⚠️
... and 4 more

Files with missing lines	Coverage Δ
src/lib/analysisDoc.ts	97.14% <ø> (ø)
src/lib/cliCommand.ts	93.87% <100.00%> (+0.26%)	⬆️
src/lib/codecKb.ts	46.51% <ø> (ø)
src/lib/containerKb.ts	100.00% <ø> (ø)
src/lib/dom.ts	73.95% <100.00%> (+0.33%)	⬆️
src/lib/metadataTagKb.ts	93.33% <ø> (+8.48%)	⬆️
src/lib/sizeEstimate.ts	93.67% <100.00%> (ø)
src/lib/state.ts	98.27% <ø> (-0.03%)	⬇️
src/ui/demosPage.ts	52.07% <100.00%> (ø)
src/ui/elements.ts	0.00% <ø> (ø)
... and 16 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.