Skip to content

docs: the size score gives full points from about 140 kbps, not 64 - #493

Merged
kikootwo merged 1 commit into
mainfrom
fix/318-size-score-doc
Oct 27, 2026
Merged

kikootwo merged 1 commit into
mainfrom
fix/318-size-score-doc

Conversation

@kikootwo

Copy link
Copy Markdown
Owner

Closes #318

What changed

  • scoreSize() comments (src/lib/utils/ranking-algorithm.ts): the comment said full points at 1.0 MB/min were "~64 kbps". sizeMB is in MiB, so 1.0 MB/min is 1,048,576 × 8 / 60 ≈ 139.8 kbps. The comments now say about 140 kbps and give the points at 128 kbps (13.7), 64 kbps (6.9), 0.5 MB/min (about 70 kbps, 7.5) and 0.3 MB/min (about 42 kbps, 4.5).
  • Docs (documentation/phase3/ranking-algorithm.md): the audiobook scoring criteria had no size section. A new "4. Size Quality" section covers the formula, where full points start (about 140 kbps), the points at 128, 64 and 32 kbps, and the size notes. A Fixed Issues entry is added for Size score: the "1.0 MB/min ≈ 64 kbps" baseline is off by about 2x, so 64 kbps releases lose half their size points #318.
  • New tests/utils/ranking-size-score.test.ts pins those numbers through getScoreBreakdown(): 32 kbps 3.43, 64 kbps 6.87, 128 kbps 13.73; 139 kbps under 15, 140 and 320 kbps at 15.
  • Scoring is unchanged: no code line differs from main, only comments.

Why

The comment and the constant disagreed, as #318 showed with measured releases. The ruling was to make the comment and the docs describe what the code does, and to leave any move of the baseline to the #223 threshold work.

Which case applied: #459 (the #223 work, f5b0543) did not change the size baseline. scoreSize() is the same on main (d8011ab) as before #459, and documentation/phase3/match-gates.md lists scoreSize among the parts #459 left unchanged. So this branch changes only docs and comments. Full points still start at about 140 kbps, and a 64 kbps release still gets about 8 of the 15 size points less.

Evidence

  • tests/utils/ranking-size-score.test.ts: 4/4 pass on this branch, and 4/4 with main's src (d8011ab), since the scoring is the same.
  • tests/utils/ranking-algorithm.test.ts (it includes the existing "full size score for >= 1.0 MB/min" test) and the new file: 104/104 pass.

Checks

  • Type check and lint: PASS (tsc --noEmit clean). ESLint reports nothing new in the two touched files: one existing warning in ranking-algorithm.ts (an unused title parameter at line 416) is the same on main.
  • No image build or E2E run: comments, docs and one test file only
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • None for behaviour: only comments, docs and a test change.
  • Rollback: revert this PR.

🤖 Generated with Claude Code

…bps, not 64 (#318)

1.0 MB/min with MB in MiB is about 139.8 kbps, so a 64 kbps release scores
about 6.9 of the 15 size points. The comment said "~64 kbps". Comments and
docs now describe what the code does; scoring is unchanged. A test pins the
documented numbers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo merged commit d189e68 into main Oct 27, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/318-size-score-doc branch October 27, 2026 11:04
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.

Size score: the "1.0 MB/min ≈ 64 kbps" baseline is off by about 2x, so 64 kbps releases lose half their size points

1 participant