docs(logging): add rejection summary for silence candidates

flexiondotorg · flexiondotorg · commit 6d51b60395e5 · 2026-03-14T10:24:20.000Z
- Show counts of rejected silence candidates grouped by reason
- Extract rejection reason from TransientWarning field
- Display summary in analysis output and diagnostic report
- Classify reasons: digital silence, crosstalk, transient contamination,
  too loud

Signed-off-by: Martin Wimpress &lt;code@wimpress.io&gt;
diff --git a/internal/logging/analysis_display.go b/internal/logging/analysis_display.go
@@ -136,6 +136,9 @@ func DisplayAnalysisResults(w io.Writer, inputPath string, metadata *audio.Metad
 				fmt.Fprintln(w)
 			}
 		}
+
+		// Rejection summary: count zero-scored candidates by reason
+		writeSilenceRejectionSummary(w, measurements.SilenceCandidates)
 	} else if measurements.NoiseProfile != nil {
 		fmt.Fprintf(w, "  Sample:         %.1fs at %s\n",
 			measurements.NoiseProfile.Duration.Seconds(), formatTimestamp(measurements.NoiseProfile.Start))
@@ -298,6 +301,55 @@ func writeSilenceCandidateMetrics(w io.Writer, c processor.SilenceCandidateMetri
 	fmt.Fprintf(w, "      Centroid:    %.0f Hz\n", c.Spectral.Centroid)
 }
 
+// writeSilenceRejectionSummary outputs a compact summary of rejected silence candidates.
+// Groups zero-scored candidates by rejection reason extracted from TransientWarning.
+func writeSilenceRejectionSummary(w io.Writer, candidates []processor.SilenceCandidateMetrics) {
+	reasonCounts := make(map[string]int)
+	for _, c := range candidates {
+		if c.Score != 0.0 {
+			continue
+		}
+		reason := classifyRejectionReason(c.TransientWarning)
+		reasonCounts[reason]++
+	}
+
+	if len(reasonCounts) == 0 {
+		return
+	}
+
+	// Build summary parts in a stable order
+	order := []string{"digital silence", "crosstalk", "transient contamination", "too loud"}
+	var parts []string
+	for _, reason := range order {
+		if count, ok := reasonCounts[reason]; ok {
+			parts = append(parts, fmt.Sprintf("%d %s", count, reason))
+			delete(reasonCounts, reason)
+		}
+	}
+	// Any unexpected reasons
+	for reason, count := range reasonCounts {
+		parts = append(parts, fmt.Sprintf("%d %s", count, reason))
+	}
+
+	fmt.Fprintf(w, "  Rejected:       %s\n", strings.Join(parts, ", "))
+}
+
+// classifyRejectionReason maps a TransientWarning string to a short label.
+func classifyRejectionReason(warning string) string {
+	switch {
+	case strings.Contains(warning, "digital silence"):
+		return "digital silence"
+	case strings.Contains(warning, "crosstalk"):
+		return "crosstalk"
+	case strings.Contains(warning, "transient contamination"):
+		return "transient contamination"
+	case warning == "":
+		return "too loud"
+	default:
+		return "too loud"
+	}
+}
+
 // writeAnalysisSection writes a section header for analysis output.
 func writeAnalysisSection(w io.Writer, title string) {
 	fmt.Fprintln(w, title)
diff --git a/internal/logging/report.go b/internal/logging/report.go
@@ -1659,6 +1659,9 @@ func writeDiagnosticSilence(f *os.File, measurements *processor.AudioMeasurement
 					i+1, c.Region.Duration.Seconds(), c.Region.Start.Seconds(), c.Score, c.RMSLevel)
 			}
 		}
+
+		// Rejection summary for zero-scored candidates
+		writeReportRejectionSummary(f, measurements.SilenceCandidates)
 	} else if measurements.NoiseProfile != nil {
 		fmt.Fprintf(f, "Silence Sample:      %.1fs at %.1fs\n",
 			measurements.NoiseProfile.Duration.Seconds(),
@@ -1678,6 +1681,36 @@ func writeDiagnosticSilence(f *os.File, measurements *processor.AudioMeasurement
 	fmt.Fprintln(f, "")
 }
 
+// writeReportRejectionSummary outputs a compact summary of rejected silence candidates to the report file.
+func writeReportRejectionSummary(f *os.File, candidates []processor.SilenceCandidateMetrics) {
+	reasonCounts := make(map[string]int)
+	for _, c := range candidates {
+		if c.Score != 0.0 {
+			continue
+		}
+		reason := classifyRejectionReason(c.TransientWarning)
+		reasonCounts[reason]++
+	}
+
+	if len(reasonCounts) == 0 {
+		return
+	}
+
+	order := []string{"digital silence", "crosstalk", "transient contamination", "too loud"}
+	var parts []string
+	for _, reason := range order {
+		if count, ok := reasonCounts[reason]; ok {
+			parts = append(parts, fmt.Sprintf("%d %s", count, reason))
+			delete(reasonCounts, reason)
+		}
+	}
+	for reason, count := range reasonCounts {
+		parts = append(parts, fmt.Sprintf("%d %s", count, reason))
+	}
+
+	fmt.Fprintf(f, "Rejected:            %s\n", strings.Join(parts, ", "))
+}
+
 // writeDiagnosticSpeech outputs detailed speech detection diagnostics.
 func writeDiagnosticSpeech(f *os.File, measurements *processor.AudioMeasurements) {
 	if measurements == nil {
diff --git a/internal/processor/analyzer_candidates.go b/internal/processor/analyzer_candidates.go
@@ -1117,6 +1117,10 @@ func scoreSilenceCandidate(m *SilenceCandidateMetrics) float64 {
 		m.Region.Start.Seconds(), m.CrestFactor, isCrosstalk)
 	if isCrosstalk {
 		debugLog("scoreSilenceCandidate: REJECTING candidate at %.3fs (returning score=0.0)", m.Region.Start.Seconds())
+		m.TransientWarning = fmt.Sprintf(
+			"rejected: crosstalk detected (crest %.1f dB, centroid %.0f Hz)",
+			m.CrestFactor, m.Spectral.Centroid,
+		)
 		return 0.0 // Reject this candidate
 	}
 
