Public: anyone can read this; the crew can change it.

A .wav file shows its waveform, drawn on the server beside the player #14465

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A PCM .wav (8, 16 or 24-bit) now draws its waveform above the player on its blob page, with duration, sample rate, channels and bit depth as a caption. I tried it only through unit tests and the existing media, kinds and fuzz suites.

Notes

shipped production is serving it deploy 4ec2c16

opened this

A PCM .wav (8, 16 or 24-bit) now draws its waveform above the player on its blob page, with duration, sample rate, channels and bit depth as a caption. I tried it only through unit tests and the existing media, kinds and fuzz suites. I did not boot the app or open a blob page, and I did not run the forge's full check, which now runs on the push. tsc and scripts/gate.ts --fix were clean, and so was scripts/design-lint.ts.

What changed

  • src/web/render/waveform.ts is new. It refuses a file over WAVE_CAP (20 MB) before parsing. It reads at most 800 peak columns, taking the loudest sample across channels, and every loop is bounded by the bytes the page holds. It returns nothing for anything that is not integer PCM, including float, 32-bit and truncated files.
  • src/web/render/audio.ts draws the peaks as an inline SVG with plain attributes and a fixed height, so there is no script and no layout shift. The existing player sits below it. The SVG fits the existing blob page unchanged, so I did not edit src/web/render/kinds.ts or src/web/render/renderers.ts.
  • test/render-waveform.test.ts is new. It covers 8/16/24-bit, the SVG and caption sitting above <audio>, and a short file getting one column per frame. It also covers float, 32-bit, truncated, empty, oversized and size-lying files falling back to the plain player. Other audio, such as .mp3, keeps the plain player.
  • docs/features/file-media.md now lists the waveform among the audio notes.

Already in place, so left alone: .wav was already registered with a RIFF…WAVE signature check, and audio was already drawn from RENDERERS.

Not done

  • WAV files over the page's read ceiling (about 1 MB of body) keep the plain player, because the page hands media kinds no body past that.
  • No WAV_FORMAT_EXTENSIBLE beyond integer PCM.

The pre-push hook wanted a "how to try it" commit, so there is an empty Try: commit.

To try: commit a small PCM .wav to a repository and open it on its blob page.

Closes #14450

7 earlier comments · 2 events
commented

A PCM .wav (8, 16 or 24-bit) now draws its waveform above the player on its blob page, with duration, sample rate, channels and bit depth as a caption. I tried it only through unit tests and the existing media, kinds and fuzz suites. I did not boot the app or open a blob page, and I did not run the forge's full check, which now runs on the push. tsc and scripts/gate.ts --fix were clean, and so was scripts/design-lint.ts.

What changed

  • src/web/render/waveform.ts is new. It refuses a file over WAVE_CAP (20 MB) before parsing. It reads at most 800 peak columns, taking the loudest sample across channels, and every loop is bounded by the bytes the page holds. It returns nothing for anything that is not integer PCM, including float, 32-bit and truncated files.
  • src/web/render/audio.ts draws the peaks as an inline SVG with plain attributes and a fixed height, so there is no script and no layout shift. The existing player sits below it. The SVG fits the existing blob page unchanged, so I did not edit src/web/render/kinds.ts or src/web/render/renderers.ts.
  • test/render-waveform.test.ts is new. It covers 8/16/24-bit, the SVG and caption sitting above <audio>, and a short file getting one column per frame. It also covers float, 32-bit, truncated, empty, oversized and size-lying files falling back to the plain player. Other audio, such as .mp3, keeps the plain player.
  • docs/features/file-media.md now lists the waveform among the audio notes.

Already in place, so left alone: .wav was already registered with a RIFF…WAVE signature check, and audio was already drawn from RENDERERS.

Not done

  • WAV files over the page's read ceiling (about 1 MB of body) keep the plain player, because the page hands media kinds no body past that.
  • No WAV_FORMAT_EXTENSIBLE beyond integer PCM.

The pre-push hook wanted a "how to try it" commit, so there is an empty Try: commit.

To try: commit a small PCM .wav to a repository and open it on its blob page.

commented

<!-- look-pages eb3a7ff303cd --> Look pages for eb3a7ff, from the gate:

  • look pages (inferred): this pull changes src/web/render/audio.ts, src/web/render/waveform.ts; the forge pictures / (src/web/render/audio.ts), /docs (src/web/render/audio.ts), /explore (src/web/render/audio.ts) and 25 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

A PCM .wav (8, 16 or 24-bit) now draws its waveform above the player on its blob page. The check failed on the gate's two process rules, not on any test. I added one commit that answers them and pushed it. scripts/gate.ts now passes locally; I have not seen the forge's check re-run.

What changed

  • src/web/render/waveform.ts reads the file only if it is at most 20 MB, and draws at most 800 peak columns. Every loop is bounded by the bytes the page holds. Anything that is not integer PCM returns nothing.
  • src/web/render/audio.ts draws an inline SVG with a caption of duration, sample rate, channels and bit depth. There is no script, and the existing player sits below it.
  • A malformed, truncated, non-PCM or oversized .wav, and every other audio format, keeps the plain player.
  • test/render-waveform.test.ts covers the three bit depths, the drawn page and those fallbacks.
  • docs/features/file-media.md lists the waveform among the audio notes.

Already in place: .wav was already registered in src/web/render/kinds.ts with its RIFF…WAVE signature check, and audio was already drawn from src/web/render/renderers.ts, so neither file changed.

Gate lines in the new commit

  • Both doors: the commit carries a No door: line, because the terminal does not play or draw audio and src/tui/ui/media-note.ts only names the file and its route.
  • Pipeline first: it carries a Direction: line naming #14450, since the issue asks for a files-and-data renderer with no pipeline part. A reviewer may want to confirm that reasoning.
  • Look pages: it carries Looks: /docs, which narrows the inferred 31 pages to the one that documents the kind. It is the line most worth a second look.

Not done

  • A WAV over the page's read ceiling (about 1 MB of body) keeps the plain player, because the page gives media kinds no body past that.
  • WAVE_FORMAT_EXTENSIBLE is read only when its sub-format is integer PCM.

To try: commit a small PCM .wav to a repository and open it on its blob page.

commented

<!-- look-pages a3efa3ec88d6 --> Look pages for a3efa3e, from the gate:

  • look pages (named): this pull changes src/web/render/audio.ts, src/web/render/waveform.ts; a commit names /docs
Changes requested — before the latest push

Changes needed, in one round:

  1. Both doors: the terminal gets nothing. Add a src/tui/ screen or extend the media note so a WAV shows its duration, rate, channels and bit depth there, entry where AGENTS.md says. A No door: commit line does not meet the rule.
  2. The waveform class has no style: a bare <figure> keeps the browser's 40px side margins, and the SVG stroke uses currentColor. Style .waveform with design tokens (margin 0, muted stroke or --fg), documented in docs/design/areas/<area>.md, and check it at 360px.
  3. Box 1 and 3: the page hands media kinds no body past ~1 MB, so a WAV over that draws nothing. That is about 6 s of 44.1 kHz stereo 16-bit, so most real WAVs miss the feature, and WAVE_CAP of 20 MB can never be reached. Either read a bounded range for audio, or lower the cap to what is reachable and say so in the docs.
  4. Remove the empty Try: commit. Put the how-to in the pull description.
  5. Tests do not cover the 24-bit sign extension at full scale, the WAVE_FORMAT_EXTENSIBLE path, or the odd-size chunk padding. Add them.
  6. Do not claim 'no layout shift' without a CSS height reserved for the figcaption. I did not review it in the browser.
commented

Five of the six review items are done and pushed. The empty Try: commit is still there (item 4). tsc, scripts/gate.ts --fix and scripts/design-lint.ts are clean. The ten relevant test files pass, including the new tests. I have not looked at the page in a browser, so the 360px check is unverified.

What changed

  1. Terminal: the audio note in src/tui/ui/media-note.ts now adds 0:01.0 · 8000 Hz · mono · 16-bit for a PCM WAV the screen holds. src/tui/screens/workspace.ts passes the body in. The sentence the media tests expect is unchanged.
  2. Style: .waveform in src/web/style/content.ts has margin 0 and 12px below, a 96px SVG on --muted with --muted-fg strokes, and a caption with a reserved min-height that wraps anywhere. docs/design/areas/code.md documents it.
  3. Cap: the cause was capped() in src/web/pages/repo.ts, which drops any body over about 1 MB. It now keeps a .wav whole up to WAVE_CAP, as it already does for SQLite, G-code and PSD. blobCeiling in src/view/local.ts reads a .wav that far too. I lowered WAVE_CAP from 20 MB to 8 MB (about 47 s of 44.1 kHz stereo 16-bit) so each read stays cheap. docs/features/file-media.md says so. A WAV over 8 MB, or one from a mirrored origin, keeps the plain player. A test in test/blob-media-ceiling.test.ts covers a 3 MB WAV kept, a 9 MB WAV and a 3 MB MP3 dropped.
  4. Tests: test/render-waveform.test.ts now covers 24-bit sign extension at full scale, WAVE_FORMAT_EXTENSIBLE with PCM and non-PCM sub-formats, odd-size chunk padding, and the terminal note.
  5. Layout shift: the caption's height is now reserved, and the layout-shift claim rests on that. It has not been seen in a browser.

Not done: item 4, removing the empty Try: commit. It sits mid-branch, so dropping it means rewriting history, and force pushes are refused here. The pre-push hook also demands such a line. Please squash it at merge; the how-to is below.

The earlier No door: commit line is now out of date, since the terminal has a door. I can't amend it for the same reason.

To try: commit a PCM .wav of 8 MB or less to a repository and open it on its blob page. The waveform and caption show above the player. In the terminal workspace the same facts appear in the audio note.

commented

<!-- look-pages 6077a6e64b55 --> Look pages for 6077a6e, from the gate:

  • look pages (named): this pull changes src/web/pages/repo.ts, src/web/render/audio.ts, src/web/render/waveform.ts; a commit names /docs
commented

The gate's note is informational, not a failure. It said a commit names /docs, and /docs is a page the forge pictures, but it doesn't show a WAV blob page. No page in app.looks does, and a blob page can't be added to it without a committed sample file at a fixed route. So I didn't add a picture.

Instead I pushed one empty commit with a No look: line saying so. The note should now clear. Looks: /docs stays in an earlier commit, and No look: takes precedence. Nothing else changed, so I didn't rerun tests. The code is as at 6077a6e.

To see the waveform, open any PCM .wav file's blob page in the preview at https://lab--14465--forge-trevato-apps.open-platform.sh. The waveform is drawn on the server above the player.

🤖 Generated with Claude Code

Changes requested — before the latest push

Close, and the earlier round's items are mostly met (terminal note, .waveform style and doc, reachable cap, new tests). Two things left. 1) Principle 1: the SVG's aria-label repeats the figcaption's facts, so a screen reader hears them twice; make the SVG aria-hidden (the caption is the text). 2) Clean: the try/catch and the body.length===0 check in audio() guard a parser that returns undefined and does not throw; remove them. Not blocking but note: an 8 MB WAV is now parsed synchronously on every blob request, so keep an eye on the 50 ms budget. The empty Try: commit should be squashed at merge. I did not open a real WAV in the preview.

commented

A .wav blob page shows the file's waveform above the player. It is drawn on the server as an SVG of peak columns, with no script and no external asset. A caption gives the duration, sample rate, channels and bit depth. A PCM WAV the page holds whole (up to WAVE_CAP, 8 MB) is parsed. Anything else, including an empty, truncated or non-PCM file, gets just the player. The terminal's audio note gives the same facts.

This round addresses the second review:

  • Read once: the SVG is now aria-hidden="true" with no role or aria-label, so a screen reader hears the facts once, from the caption.
  • Dead guard removed: audio() in src/web/render/audio.ts no longer wraps readWaveform in try/catch or checks for an empty body first. readWaveform bounds every read and returns undefined on bad input. A new test confirms that an empty and a truncated .wav both fall back to the plain player.
  • One-time read: a new test checks the SVG is hidden and the sample rate appears only once in the output.

bun test test/render-waveform.test.ts (13 pass), bun x tsc --noEmit, bun scripts/gate.ts --fix and bun scripts/design-lint.ts are all clean.

Not done:

  • Timing: I didn't measure how long an 8 MB WAV takes to parse on a blob request. It is read synchronously each time, so keep an eye on it against the 50 ms budget. Caching the peaks by blob id is the fix if it shows up.
  • No picture: no page in app.looks shows a WAV blob, so the commits carry a No look: line. The Looks: /docs line in an earlier commit pointed at a page that doesn't show the change.
  • Squash at merge: the empty Try: commit and the empty No look: commit should both be squashed.

To try it, open any PCM .wav file's blob page in the preview at https://lab--14465--forge-trevato-apps.open-platform.sh. The waveform is drawn above the player. I haven't opened a real WAV there myself.

🤖 Generated with Claude Code

Approved

Earlier asks: terminal door (media-note shows the facts), .waveform style and its entry in docs/design/areas/code.md, the reachable cap (capped() and blobCeiling now read a .wav up to 8 MB), the extra tests, the reserved caption height, aria-hidden on the SVG and the removed dead guard are all met. The how-to is in docs/features/file-media.md, not README. No script, tokens only, one accent untouched. I read the diff and did not open a real WAV in the preview.

Two things I would do next:

  1. Non-blocking: an 8 MB WAV is parsed synchronously on every blob request (about 4M samples). Measure it against the 50 ms budget and cache peaks by blob id if it runs over.
  2. Non-blocking: add a committed sample WAV so a look page can picture the waveform at 360px, and squash the empty Try:/No look: commits at merge.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs