feat(analyzer): add region measurement capture across processing stages

[flexiondotorg]

Summary

• Implement three-stage measurement capture (Input → Filtered → Final) for elected silence and speech regions
• Add MeasureOutputSilenceRegion and MeasureOutputSpeechRegion functions capturing 20+ metrics per region
• Expand report tables to display comprehensive three-column comparisons across all measurement fields
• Fix ebur128 timestamp discontinuity, missing metadata flags, and peak unit conversion issues
• Add debug logging infrastructure for measurement function tracing

Problem

The processing pipeline had no visibility into how elected silence and speech regions evolved through the four-pass architecture. This made it impossible to:

• Validate that noise reduction actually improved silence regions
• Track how compression and limiting affected speech characteristics
• Diagnose measurement anomalies in region analysis
• Tune adaptive parameters based on inter-pass comparisons

Additionally, several bugs caused incorrect or missing measurements:

• ebur128 sliding window calculations failed due to timestamp discontinuities after atrim
• Speech region ebur128 lacked metadata=1 flag, producing no frame metadata
• Peak values displayed as linear ratios instead of dB

Solution

Phase 1-2: Upgraded data structures and implemented full-spectrum measurement functions using astats + aspectralstats + ebur128 filter chains.

Phase 3-4: Wired measurement capture into Pass 2 (filtering) and Pass 4 (normalisation) with non-fatal error handling.

Phase 5: Expanded report tables to show Input/Filtered/Final columns for all 20+ metrics including amplitude, spectral, and loudness characteristics.

Bug fixes:

• Added asetpts=PTS-STARTPTS after atrim to reset timestamps for ebur128
• Added metadata=1:peak=sample+true to speech region ebur128 filter spec
• Added linearRatioToDB() conversion for TruePeak and SamplePeak values
• Improved edge case display (digital silence, infinite reduction, undefined spectral)

Testing

• Added comprehensive unit tests for both measurement functions with synthetic audio generation
• Extended processor tests to verify SilenceSample and SpeechSample population
• Added table formatting tests for new report helpers
• Manual verification with real podcast recordings

---

Summary by cubic

Adds three-stage region measurement (Input → Filtered → Final) for elected silence and speech, and expands reports to compare 20+ metrics per region. Improves accuracy of loudness and peak data and adds debug logging for measurement tracing.

• New Features

  • Capture full metrics for elected regions via MeasureOutputSilenceRegion and MeasureOutputSpeechRegion (astats + aspectralstats + ebur128), recorded in Pass 2 and Pass 4.
  • Store rich region data in OutputMeasurements (SilenceSample, SpeechSample) with 20+ fields for amplitude, spectral, and loudness.
  • Expand Noise Floor and Speech Region tables to three columns with better formatting (dB/LUFS floors, digital silence, “Character” row).
  • Add formatting helpers and processor.DebugLog; include unit and processor tests for new paths.

• Bug Fixes

  • Reset timestamps after atrim (asetpts=PTS-STARTPTS) to fix ebur128 sliding window discontinuities.
  • Enable ebur128 metadata and true/sample peak reporting (metadata=1:peak=sample+true).
  • Convert ebur128 peak ratios to dB (linearRatioToDB) and handle digital silence/undefined spectral values in reports.

^{Written for commit 07c7ae6. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 10 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="internal/processor/analyzer.go">

<violation number="1" location="internal/processor/analyzer.go:3730">
P3: Comment says "for silence" but this is in the speech measurement function. Appears to be a copy-paste error.</violation>
</file>

<file name="internal/logging/table.go">

<violation number="1" location="internal/logging/table.go:185">
P2: Missing positive infinity check in `formatMetricLUFS`. Unlike the similar `formatMetricDB` function which handles `math.IsInf(value, 1)`, this function would format `+Inf` as a string instead of returning `MissingValue`. Add the infinity check for consistency and defensive programming.</violation>
</file>

<file name="internal/processor/processor_test.go">

<violation number="1" location="internal/processor/processor_test.go:86">
P2: Same nil pointer dereference risk as above. Add a nil guard for `result.Measurements` before accessing `SpeechProfile`.</violation>
</file>

<file name="internal/processor/normalise.go">

<violation number="1" location="internal/processor/normalise.go:679">
P1: Potential nil pointer dereference: `inputMeasurements` is a pointer that could be nil. Check `inputMeasurements != nil` before accessing its fields to prevent a panic.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}