Create small, useful amplitude data for audio timelines.
Decide what the UI needs
A waveform is a visual summary, not a second audio file. For a timeline, calculate peak or RMS amplitude over fixed time windows and store a compact array or rendered image. Choose the number of samples from the largest expected display width, not the number of source audio samples.
Generate once per version
Decode the audio in a background job and associate the output with the exact source version. For stereo, decide whether to show separate channels or a combined magnitude. Normalize carefully: per-file normalization makes quiet files visible but can hide relative loudness differences between files.
Test seek alignment
The waveform’s duration and sample count must map to the player’s time axis, including leading silence or trimmed segments. Verify a click at the midpoint seeks to roughly the midpoint. A beautiful waveform that drifts from playback is worse than a plain progress bar.
A concrete acceptance test
Use an audio file with leading silence and a loud event near the midpoint. Compare the waveform to playback and test a click at several points along the timeline. Run this test with a realistic asset and record the observed state, output URL, and failure reason.
Implementation check
- Set waveform resolution from display width.
- Keep sample timestamps aligned with playback.
- Test files with silence and channel imbalance.
Related guides
Primary reference: Official documentation.
Related field note
Continue with Cost-aware transformations without duplicate files.