ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
analysis.c File Reference

Audio Analysis Implementation. More...

Go to the source code of this file.

Macros

#define FRAME_SIZE   960
#define MAX_GAP_SAMPLES   100
#define MAX_PACKET_SAMPLES   200
#define ECHO_BUFFER_SIZE   48000
#define ECHO_DELAY_COUNT   5
#define BEEP_WINDOW_SIZE   480

Functions

int audio_analysis_init (void)
 Measurements used to diagnose sent or received audio quality.
void audio_analysis_track_sent_sample (float sample)
 Track sent audio sample.
void audio_analysis_track_sent_packet (size_t size)
 Track sent packet.
void audio_analysis_track_received_sample (float sample)
 Track received audio sample.
void audio_analysis_track_received_packet (size_t size)
 Track received packet.
const audio_analysis_stats_t * audio_analysis_get_sent_stats (void)
 Get sent audio statistics.
const audio_analysis_stats_t * audio_analysis_get_received_stats (void)
 Get received audio statistics.
void audio_analysis_set_aec3_metrics (double echo_return_loss, double echo_return_loss_enhancement, uint64_t delay_ns)
 Set AEC3 echo cancellation metrics.
void audio_analysis_print_report (void)
 Print audio analysis report.
void audio_analysis_destroy (void)
 Cleanup audio analysis.

Detailed Description

Audio Analysis Implementation.

Definition in file analysis.c.

Macro Definition Documentation

◆ BEEP_WINDOW_SIZE

#define BEEP_WINDOW_SIZE   480

Definition at line 105 of file analysis.c.

Referenced by audio_analysis_track_received_sample().

◆ ECHO_BUFFER_SIZE

#define ECHO_BUFFER_SIZE   48000

◆ ECHO_DELAY_COUNT

#define ECHO_DELAY_COUNT   5

◆ FRAME_SIZE

#define FRAME_SIZE   960

Definition at line 62 of file analysis.c.

◆ MAX_GAP_SAMPLES

#define MAX_GAP_SAMPLES   100

Definition at line 69 of file analysis.c.

Referenced by audio_analysis_track_received_sample().

◆ MAX_PACKET_SAMPLES

#define MAX_PACKET_SAMPLES   200

Definition at line 76 of file analysis.c.

Referenced by audio_analysis_print_report(), and audio_analysis_track_received_packet().

Function Documentation

◆ audio_analysis_destroy()

void audio_analysis_destroy ( void )

Cleanup audio analysis.

Definition at line 839 of file analysis.c.

839 {
840 g_analysis_enabled = false;
841
842 // Close WAV files if they were open
843 if (g_sent_wav) {
844 wav_writer_close(g_sent_wav);
845 g_sent_wav = NULL;
846 log_info("Closed sent audio WAV file");
847 }
848 if (g_received_wav) {
849 wav_writer_close(g_received_wav);
850 g_received_wav = NULL;
851 log_info("Closed received audio WAV file");
852 }
853}
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
void wav_writer_close(wav_writer_t *writer)
Close WAV file and finalize header.
Definition wav_writer.c:116

References log_info, and wav_writer_close().

◆ audio_analysis_get_received_stats()

const audio_analysis_stats_t * audio_analysis_get_received_stats ( void )

Get received audio statistics.

Returns
Pointer to analysis stats (do not free)

Definition at line 507 of file analysis.c.

507 {
508 g_received_stats.dc_offset = g_received_stats.total_samples ? (float)(g_received_mean / g_received_stats.total_samples) : 0.0f;
509 g_received_stats.rms_level = g_received_rms_sample_count ? sqrtf(g_received_rms_accumulator / g_received_rms_sample_count) : 0.0f;
510 return &g_received_stats;
511}

References audio_analysis_stats_t::dc_offset.

Referenced by audio_analysis_print_report().

◆ audio_analysis_get_sent_stats()

const audio_analysis_stats_t * audio_analysis_get_sent_stats ( void )

Get sent audio statistics.

Returns
Pointer to analysis stats (do not free)

Definition at line 501 of file analysis.c.

501 {
502 g_sent_stats.dc_offset = g_sent_stats.total_samples ? (float)(g_sent_mean / g_sent_stats.total_samples) : 0.0f;
503 g_sent_stats.rms_level = g_sent_rms_sample_count ? sqrtf(g_sent_rms_accumulator / g_sent_rms_sample_count) : 0.0f;
504 return &g_sent_stats;
505}

References audio_analysis_stats_t::dc_offset.

Referenced by audio_analysis_print_report().

◆ audio_analysis_init()

int audio_analysis_init ( void )

Measurements used to diagnose sent or received audio quality.

Initialize audio analysis

Returns
0 on success, negative on error

Definition at line 113 of file analysis.c.

113 {
114 SAFE_MEMSET(&g_sent_stats, sizeof(g_sent_stats), 0, sizeof(g_sent_stats));
115 SAFE_MEMSET(&g_received_stats, sizeof(g_received_stats), 0, sizeof(g_received_stats));
116
117 g_sent_mean = g_received_mean = 0.0;
118 g_sent_rms_accumulator = g_received_rms_accumulator = 0.0f;
119 g_sent_rms_sample_count = g_received_rms_sample_count = 0;
120
121 // Reset stuttering/gap tracking
122 SAFE_MEMSET(g_received_gap_intervals_ms, sizeof(g_received_gap_intervals_ms), 0, sizeof(g_received_gap_intervals_ms));
123 g_received_gap_count = 0;
124 g_received_silence_start_sample = 0;
125 g_received_last_silence_end_sample = 0;
126 SAFE_MEMSET(g_received_packet_times_ns, sizeof(g_received_packet_times_ns), 0, sizeof(g_received_packet_times_ns));
127 g_received_packet_times_count = 0;
128 SAFE_MEMSET(g_received_packet_sizes, sizeof(g_received_packet_sizes), 0, sizeof(g_received_packet_sizes));
129
130 // Reset echo detection
131 SAFE_MEMSET(g_echo_buffer, sizeof(g_echo_buffer), 0, sizeof(g_echo_buffer));
132 g_echo_buffer_pos = 0;
133 g_echo_correlation_sample_count = 0;
134 for (int i = 0; i < ECHO_DELAY_COUNT; i++) {
135 g_echo_correlation_strength[i] = 0;
136 g_echo_match_count[i] = 0;
137 }
138 g_detected_echo_delay_ms = 0;
139
140 // Reset beep detection
141 SAFE_MEMSET(g_received_beep_window, sizeof(g_received_beep_window), 0, sizeof(g_received_beep_window));
142 g_received_beep_window_idx = 0;
143 g_received_beep_events = 0;
144 g_received_tonal_samples = 0;
145 g_in_beep_burst = false;
146 g_beep_burst_samples = 0;
147
148 int64_t now_us = (int64_t)time_ns_to_us(time_get_ns());
149
150 g_sent_stats.timestamp_start_ns = now_us;
151 g_received_stats.timestamp_start_ns = now_us;
152
153 g_sent_last_sample = 0.0f;
154 g_received_last_sample = 0.0f;
155 g_sent_last_packet_time_us = now_us;
156 g_received_last_packet_time_us = now_us;
157
158 // Initialize WAV file dumping if enabled
159 if (wav_dump_enabled()) {
160 char tmp[PLATFORM_MAX_PATH_LENGTH];
161 if (platform_get_temp_dir(tmp, sizeof(tmp))) {
162 char path[PLATFORM_MAX_PATH_LENGTH];
163 safe_snprintf(path, sizeof(path), "%s/sent_audio.wav", tmp);
164 g_sent_wav = wav_writer_open(path, 48000, 1);
165 safe_snprintf(path, sizeof(path), "%s/received_audio.wav", tmp);
166 g_received_wav = wav_writer_open(path, 48000, 1);
167 }
168 if (g_sent_wav) {
169 log_info("Dumping sent audio to temp dir");
170 }
171 if (g_received_wav) {
172 log_info("Dumping received audio to temp dir");
173 }
174 }
175
176 g_analysis_enabled = true;
177 log_info("Audio analysis enabled");
178 return 0;
179}
#define ECHO_DELAY_COUNT
Definition analysis.c:88
#define SAFE_MEMSET(dest, dest_size, ch, count)
#define PLATFORM_MAX_PATH_LENGTH
bool platform_get_temp_dir(char *temp_dir, size_t path_size)
Definition util.c:81
bool wav_dump_enabled(void)
Check if audio dumping is enabled via environment.
Definition wav_writer.c:142
wav_writer_t * wav_writer_open(const char *filepath, int sample_rate, int channels)
Open WAV file for writing.
Definition wav_writer.c:52

References ECHO_DELAY_COUNT, log_info, platform_get_temp_dir(), PLATFORM_MAX_PATH_LENGTH, SAFE_MEMSET, wav_dump_enabled(), and wav_writer_open().

◆ audio_analysis_print_report()

void audio_analysis_print_report ( void )

Print audio analysis report.

Definition at line 522 of file analysis.c.

522 {
523 if (!g_analysis_enabled) {
524 return;
525 }
526
527 int64_t now_us = (int64_t)time_ns_to_us(time_get_ns());
528
529 g_sent_stats.timestamp_end_ns = now_us;
530 g_received_stats.timestamp_end_ns = now_us;
531
532 int64_t sent_duration_ms = (g_sent_stats.timestamp_end_ns - g_sent_stats.timestamp_start_ns) / NS_PER_MS_INT;
533 int64_t recv_duration_ms = (g_received_stats.timestamp_end_ns - g_received_stats.timestamp_start_ns) / NS_PER_MS_INT;
534
537 float sent_rms = sent->rms_level;
538 float recv_rms = received->rms_level;
539
540 log_plain("================================================================================");
541 log_plain(" AUDIO ANALYSIS REPORT ");
542 log_plain("================================================================================");
543 log_plain("SENT AUDIO (Microphone Capture):");
544 log_plain(" Duration: %lld ms", (long long)sent_duration_ms);
545 log_plain(" Total Samples: %llu", (unsigned long long)g_sent_stats.total_samples);
546 log_plain(" Peak Level: %.4f (should be < 1.0)", g_sent_stats.peak_level);
547 log_plain(" RMS Level: %.4f (audio energy/loudness)", sent_rms);
548 log_plain(" DC Offset: %.6f (signal mean)", sent->dc_offset);
549 log_plain(" Clipping Events: %llu samples (%.2f%%)", (unsigned long long)g_sent_stats.clipping_count,
550 g_sent_stats.total_samples > 0 ? (100.0 * g_sent_stats.clipping_count / g_sent_stats.total_samples) : 0);
551 log_plain(" Silent Samples: %llu samples (%.2f%%)", (unsigned long long)g_sent_stats.silent_samples,
552 g_sent_stats.total_samples > 0 ? (100.0 * g_sent_stats.silent_samples / g_sent_stats.total_samples) : 0);
553 if (g_sent_max_silence_burst > 0) {
554 log_plain(" Max Silence Burst: %llu samples", (unsigned long long)g_sent_max_silence_burst);
555 }
556 log_plain(" Packets Sent: %u", g_sent_stats.packets_count);
557 log_plain(" Status: %s", g_sent_stats.clipping_count > 0 ? "CLIPPING DETECTED!" : "OK");
558
559 log_plain("RECEIVED AUDIO (Playback):");
560 log_plain(" Duration: %lld ms", (long long)recv_duration_ms);
561 log_plain(" Total Samples: %llu", (unsigned long long)g_received_stats.total_samples);
562 log_plain(" Peak Level: %.4f", g_received_stats.peak_level);
563 log_plain(" RMS Level: %.4f (audio energy/loudness)", recv_rms);
564 log_plain(" DC Offset: %.6f (signal mean)", received->dc_offset);
565 log_plain(" Clipping Events: %llu samples (%.2f%%)", (unsigned long long)g_received_stats.clipping_count,
566 g_received_stats.total_samples > 0 ? (100.0 * g_received_stats.clipping_count / g_received_stats.total_samples) : 0);
567 log_plain(" Silent Samples: %llu samples (%.2f%%)", (unsigned long long)g_received_stats.silent_samples,
568 g_received_stats.total_samples > 0 ? (100.0 * g_received_stats.silent_samples / g_received_stats.total_samples) : 0);
569 if (g_received_max_silence_burst > 0) {
570 log_plain(" Max Silence Burst: %llu samples", (unsigned long long)g_received_max_silence_burst);
571 }
572 double low_energy_pct = g_received_stats.total_samples > 0 ? (100.0 * g_received_low_energy_samples / g_received_stats.total_samples) : 0;
573 log_plain(" Very Quiet Samples: %llu samples (%.1f%%) [amplitude < 0.05]", (unsigned long long)g_received_low_energy_samples, low_energy_pct);
574 log_plain(" Packets Received: %u", g_received_stats.packets_count);
575 log_plain(" Status: %s", g_received_stats.total_samples == 0 ? "NO AUDIO RECEIVED!" : "Receiving");
576
577 log_plain("QUALITY METRICS (Scratchy/Distorted Audio Detection):");
578 log_plain("SENT:");
579 log_plain(" Jitter Events: %llu (rapid amplitude changes)", (unsigned long long)g_sent_stats.jitter_count);
580 log_plain(" Discontinuities: %llu (packet arrival gaps > 100ms)", (unsigned long long)g_sent_stats.discontinuity_count);
581 log_plain(" Max Gap Between Packets: %u ms (expected ~20ms per frame)", g_sent_stats.max_gap_ns);
582
583 log_plain("RECEIVED:");
584 log_plain(" Jitter Events: %llu (rapid amplitude changes)", (unsigned long long)g_received_stats.jitter_count);
585 log_plain(" Discontinuities: %llu (packet arrival gaps > 100ms)", (unsigned long long)g_received_stats.discontinuity_count);
586 log_plain(" Max Gap Between Packets: %u ms (expected ~20ms per frame)", g_received_stats.max_gap_ns);
587
588 // Beep/tone artifact detection
589 if (g_received_beep_events > 0 || g_received_tonal_samples > 0) {
590 double tonal_pct = g_received_stats.total_samples > 0 ? (100.0 * g_received_tonal_samples / g_received_stats.total_samples) : 0;
591 log_plain("BEEP/TONE ARTIFACTS:");
592 log_plain(" Beep Events: %llu (short tonal bursts < 500ms)", (unsigned long long)g_received_beep_events);
593 log_plain(" Tonal Samples: %llu samples (%.1f%%) [consistent frequency content]", (unsigned long long)g_received_tonal_samples, tonal_pct);
594
595 if (g_received_beep_events > 10) {
596 log_plain(" 🔴 BEEPING DETECTED: %llu short tonal bursts - likely codec artifacts or system sounds!", (unsigned long long)g_received_beep_events);
597 log_plain(" Possible causes:");
598 log_plain(" - Opus codec producing tonal artifacts during silence/transitions");
599 log_plain(" - Buffer underruns creating synthetic tones");
600 log_plain(" - AEC3 suppressor resonance");
601 log_plain(" - System notification sounds bleeding through");
602 } else if (g_received_beep_events > 3) {
603 log_plain(" ⚠️ Some beep artifacts detected (%llu events)", (unsigned long long)g_received_beep_events);
604 }
605 }
606
607 log_plain("DIAGNOSTICS:");
608 if (g_sent_stats.peak_level == 0) {
609 log_plain(" No audio captured from microphone!");
610 }
611 if (g_received_stats.total_samples == 0) {
612 log_plain(" No audio received from server!");
613 } else if (g_received_stats.peak_level < 0.01f) {
614 log_plain(" ⚠️ Received audio is very quiet (peak < 0.01)");
615 }
616 if (g_sent_stats.clipping_count > 0) {
617 log_plain(" Microphone input is clipping - reduce microphone volume");
618 }
619
620 // Echo detection diagnostics
621 log_plain("ECHO DETECTION (Echo Cancellation Quality Check):");
622 if (g_echo_correlation_sample_count > 0 && g_sent_stats.total_samples > 0) {
623 uint64_t max_matches = 0;
624 int best_delay_idx = -1;
625
626 // Find which delay has the most matches (if any)
627 for (int i = 0; i < ECHO_DELAY_COUNT; i++) {
628 if (g_echo_match_count[i] > max_matches) {
629 max_matches = g_echo_match_count[i];
630 best_delay_idx = i;
631 }
632 }
633
634 double echo_threshold_pct = 5.0; // If > 5% of samples match at a delay, it's echo
635
636 if (best_delay_idx >= 0) {
637 double match_pct = (100.0 * g_echo_match_count[best_delay_idx]) / g_echo_correlation_sample_count;
638 log_plain(" Echo correlation at different delays:");
639 for (int i = 0; i < ECHO_DELAY_COUNT; i++) {
640 double pct = (100.0 * g_echo_match_count[i]) / g_echo_correlation_sample_count;
641 const char *status = pct > echo_threshold_pct ? "⚠️ ECHO DETECTED" : "✓ OK";
642 log_plain(" %3u ms delay: %.1f%% match rate %s", g_echo_delays_ms[i], pct, status);
643 }
644
645 if (match_pct > echo_threshold_pct) {
646 g_detected_echo_delay_ms = g_echo_delays_ms[best_delay_idx];
647 log_plain(" 🔴 ECHO CANCELLATION NOT WORKING: Strong echo at %u ms delay!", g_detected_echo_delay_ms);
648 log_plain(" Received audio contains %.1f%% samples matching sent audio from %u ms ago", match_pct, g_detected_echo_delay_ms);
649 } else {
650 log_plain(" ✓ Echo cancellation working: No significant echo detected");
651 }
652 }
653 } else {
654 log_plain(" Insufficient data for echo detection (need both sent and received audio)");
655 }
656
657 // AEC3 metrics from WebRTC (if available)
658 if (g_aec3_metrics_available) {
659 log_plain("AEC3 METRICS (from WebRTC GetMetrics()):");
660 log_plain(" Echo Return Loss (ERL): %.2f dB (how much echo is attenuated; >10 dB is good)", g_aec3_echo_return_loss);
661 log_plain(" Echo Return Loss Enhancement (ERLE): %.2f dB (residual echo suppression)", g_aec3_echo_return_loss_enhancement);
662 log_plain(" Estimated Echo Delay: %d ms", g_aec3_delay_ns);
663
664 if (g_aec3_echo_return_loss > 10.0) {
665 log_plain(" ✓ Good echo attenuation (ERL > 10 dB)");
666 } else if (g_aec3_echo_return_loss > 3.0) {
667 log_plain(" ⚠️ Moderate echo attenuation (3-10 dB)");
668 } else {
669 log_plain(" 🔴 Poor echo attenuation (ERL < 3 dB)");
670 }
671 }
672
673 // Audio quality diagnostics
674 if (recv_rms < 0.005f) {
675 log_plain(" ⚠️ CRITICAL: Received audio RMS is extremely low (%.6f) - barely audible!", recv_rms);
676 } else if (recv_rms < 0.02f) {
677 log_plain(" ⚠️ WARNING: Received audio RMS is low (%.6f) - may sound quiet or muddy", recv_rms);
678 }
679
680 // Silence analysis
681 double received_silence_pct = g_received_stats.total_samples > 0 ? (100.0 * g_received_stats.silent_samples / g_received_stats.total_samples) : 0;
682
683 if (received_silence_pct > 30.0) {
684 log_plain(" ⚠️ SCRATCHY AUDIO DETECTED: Too much silence in received audio!");
685 log_plain(" - Silence: %.1f%% of received samples (should be < 10%%)", received_silence_pct);
686 log_plain(" - Max silence burst: %llu samples", (unsigned long long)g_received_max_silence_burst);
687 log_plain(" - This creates jittery/choppy playback between audio bursts");
688 } else if (received_silence_pct > 15.0) {
689 log_plain(" ⚠️ WARNING: Moderate silence detected (%.1f%%)", received_silence_pct);
690 }
691
692 // Sharp transition analysis (clicks/pops)
693 double sent_sharp_pct = g_sent_transition_samples > 0 ? (100.0 * g_sent_sharp_transitions / g_sent_transition_samples) : 0;
694 double recv_sharp_pct = g_received_transition_samples > 0 ? (100.0 * g_received_sharp_transitions / g_received_transition_samples) : 0;
695
696 // Zero crossing rate analysis (spectral content)
697 // Music: 1-5%, Speech: 5-15%, Static/Noise: 15-50%
698 double sent_zero_cross_pct = g_sent_stats.total_samples > 0 ? (100.0 * g_sent_zero_crossings / g_sent_stats.total_samples) : 0;
699 double recv_zero_cross_pct = g_received_stats.total_samples > 0 ? (100.0 * g_received_zero_crossings / g_received_stats.total_samples) : 0;
700
701 log_plain("WAVEFORM ANALYSIS (Is it clean music or corrupted/static?):");
702 log_plain("SENT AUDIO:");
703 log_plain(" Zero crossings: %.2f%% of samples (music: 1-5%%, noise: 15-50%%)", sent_zero_cross_pct);
704 log_plain(" Sharp transitions (clicks/pops): %.2f%% of samples", sent_sharp_pct);
705 log_plain(" Clipping samples: %llu (%.3f%%)", (unsigned long long)g_sent_clipping_samples, g_sent_stats.total_samples > 0 ? (100.0 * g_sent_clipping_samples / g_sent_stats.total_samples) : 0);
706
707 log_plain("RECEIVED AUDIO:");
708 log_plain(" Zero crossings: %.2f%% of samples (music: 1-5%%, noise: 15-50%%)", recv_zero_cross_pct);
709 log_plain(" Sharp transitions (clicks/pops): %.2f%% of samples", recv_sharp_pct);
710 log_plain(" Clipping samples: %llu (%.3f%%)", (unsigned long long)g_received_clipping_samples,
711 g_received_stats.total_samples > 0 ? (100.0 * g_received_clipping_samples / g_received_stats.total_samples) : 0);
712 log_plain(" Zero crossing increase: %.2f%% higher than sent (indicates corruption)", recv_zero_cross_pct - sent_zero_cross_pct);
713
714 // Musicality verdict
715 log_plain("SOUND QUALITY VERDICT:");
716 if (recv_zero_cross_pct > 10.0) {
717 log_plain(" ⚠️ SOUNDS LIKE STATIC/DISTORTED: Excessive zero crossings (%.2f%%) = high frequency noise", recv_zero_cross_pct);
718 log_plain(" Increase from sent: %.2f%% (waveform corruption detected)", recv_zero_cross_pct - sent_zero_cross_pct);
719 log_plain(" Likely causes: Opus codec artifacts, jitter buffer issues, or packet delivery gaps");
720 } else if (recv_zero_cross_pct - sent_zero_cross_pct > 3.0) {
721 log_plain(" ⚠️ SOUNDS CORRUPTED: Zero crossing rate increased by %.2f%% (should be ±0.5%%)", recv_zero_cross_pct - sent_zero_cross_pct);
722 log_plain(" Indicates waveform distortion from network/processing artifacts");
723 } else if (recv_sharp_pct > 2.0) {
724 log_plain(" ⚠️ SOUNDS LIKE STATIC: High click/pop rate (%.2f%%) indicates audio artifacts", recv_sharp_pct);
725 log_plain(" Likely causes: Packet loss, jitter buffer issues, or frame discontinuities");
726 } else if (g_received_clipping_samples > (g_received_stats.total_samples / 1000)) {
727 log_plain(" ⚠️ SOUNDS DISTORTED: Significant clipping detected (%.3f%%)", 100.0 * g_received_clipping_samples / g_received_stats.total_samples);
728 log_plain(" Likely causes: AGC too aggressive, gain too high, or codec compression artifacts");
729 } else if (low_energy_pct > 50.0 && recv_rms < 0.05f) {
730 log_plain(" ⚠️ SOUNDS MUDDY/QUIET: Over 50%% very quiet samples + low RMS");
731 log_plain(" Audio may sound unclear or like background noise rather than music");
732 } else if (received_silence_pct > 10.0) {
733 log_plain(" ⚠️ SOUNDS SCRATCHY: Excessive silence (%.1f%%) causes dropouts", received_silence_pct);
734 } else if (recv_rms > 0.08f && recv_zero_cross_pct < 6.0 && recv_sharp_pct < 1.0 && g_received_clipping_samples == 0) {
735 log_plain(" ✓ SOUNDS LIKE MUSIC: Good RMS (%.4f), clean waveform (%.2f%% zero crossings), minimal artifacts", recv_rms, recv_zero_cross_pct);
736 log_plain(" Audio quality acceptable for communication");
737 } else {
738 log_plain(" ? BORDERLINE: Check specific metrics above");
739 }
740
741 // Low energy audio analysis
742 if (low_energy_pct > 50.0) {
743 log_plain(" ⚠️ WARNING: Over 50%% of received samples are very quiet (< 0.05 amplitude)");
744 log_plain(" - This makes audio sound muddy, unclear, or hard to understand");
745 log_plain(" - Caused by: Mixing other clients' audio with your own at wrong levels");
746 }
747
748 // Stuttering/periodic gap detection using packet inter-arrival times
749 if (g_received_packet_times_count >= 5) {
750 uint32_t inter_arrival_times_ms[MAX_PACKET_SAMPLES - 1];
751 uint32_t inter_arrival_count = 0;
752 uint32_t min_interval_ms = 0xFFFFFFFF;
753 uint32_t max_interval_ms = 0;
754 uint64_t sum_intervals_ms = 0;
755 uint32_t intervals_around_50ms = 0; // Count intervals ~40-60ms
756
757 // Calculate inter-packet arrival times
758 for (uint32_t i = 1; i < g_received_packet_times_count; i++) {
759 uint64_t prev_ns = g_received_packet_times_ns[i - 1];
760 uint64_t curr_ns = g_received_packet_times_ns[i];
761
762 uint64_t gap_ns = time_elapsed_ns(prev_ns, curr_ns);
763 uint32_t gap_ms = (uint32_t)time_ns_to_ms(gap_ns);
764
765 inter_arrival_times_ms[inter_arrival_count++] = gap_ms;
766 if (gap_ms < min_interval_ms)
767 min_interval_ms = gap_ms;
768 if (gap_ms > max_interval_ms)
769 max_interval_ms = gap_ms;
770 sum_intervals_ms += gap_ms;
771
772 // Check if interval is ~50ms (within 15ms tolerance for network jitter)
773 if (gap_ms >= 35 && gap_ms <= 70) {
774 intervals_around_50ms++;
775 }
776 }
777
778 uint32_t avg_interval_ms = (uint32_t)(sum_intervals_ms / inter_arrival_count);
779 uint32_t interval_consistency = (intervals_around_50ms * 100) / inter_arrival_count;
780
781 // Calculate how much audio is in each packet
782 // Total decoded samples / number of packets = average samples per packet
783 // At 48kHz, 960 samples = 1 Opus frame = 20ms
784 double avg_samples_per_packet = g_received_stats.total_samples > 0 ? (double)g_received_stats.total_samples / inter_arrival_count : 0;
785 double frames_per_packet = avg_samples_per_packet / 960.0; // 960 samples = 1 frame @ 48kHz
786 double ms_audio_per_packet = frames_per_packet * 20.0; // 20ms per frame
787
788 // Detect if stuttering is periodic (consistent ~50ms intervals)
789 if (intervals_around_50ms >= (inter_arrival_count * 2 / 3)) {
790 // More than 66% of packets are ~50ms apart - clear periodic stuttering
791 log_plain(" 🔴 PERIODIC STUTTERING DETECTED: Server sends packets every ~%u ms (should be ~20ms)!", avg_interval_ms);
792 log_plain(" - Packet inter-arrival: %u-%u ms (avg: %u ms)", min_interval_ms, max_interval_ms, avg_interval_ms);
793 log_plain(" - %u/%u packets (~%u%%) are ~50ms apart (CLEAR STUTTERING PATTERN)", intervals_around_50ms, inter_arrival_count, interval_consistency);
794
795 log_plain(" - PACKET ANALYSIS:");
796 log_plain(" - Total audio samples: %llu over %u packets", (unsigned long long)g_received_stats.total_samples, inter_arrival_count);
797 log_plain(" - Avg samples per packet: %.0f (= %.2f Opus frames = %.1f ms)", avg_samples_per_packet, frames_per_packet, ms_audio_per_packet);
798
799 if (frames_per_packet < 1.5) {
800 log_plain(" - ❌ PROBLEM: Each packet contains < 1.5 frames (should be 2-3 frames!)");
801 log_plain(" - With only %.1f frames per packet arriving every %u ms, there are gaps between chunks", frames_per_packet, avg_interval_ms);
802 log_plain(" - Audio plays for ~%.0f ms, then %u ms gap, then plays again", ms_audio_per_packet, avg_interval_ms - (uint32_t)ms_audio_per_packet);
803 } else if (frames_per_packet > 2.5) {
804 log_plain(" - ✓ Packets contain %.1f frames (~%.0f ms audio each)", frames_per_packet, ms_audio_per_packet);
805 log_plain(" - Should play smoothly if jitter buffer is large enough");
806 log_plain(" - If still stuttering, issue is jitter buffer depth or timing precision");
807 } else {
808 log_plain(" - Packets contain %.1f frames (~%.0f ms)", frames_per_packet, ms_audio_per_packet);
809 log_plain(" - Borderline: buffer needs to hold %.0f ms to bridge %.u ms gap", ms_audio_per_packet, avg_interval_ms - (uint32_t)ms_audio_per_packet);
810 }
811 } else if (avg_interval_ms > 30) {
812 log_plain(" ⚠️ AUDIO DELIVERY INCONSISTENCY: Server packets arrive every ~%u ms (expected ~20ms)", avg_interval_ms);
813 log_plain(" - Interval range: %u-%u ms", min_interval_ms, max_interval_ms);
814 log_plain(" - This causes dropouts and buffering issues");
815 }
816 }
817
818 // Packet delivery gaps
819 if (g_received_stats.max_gap_ns > 40) {
820 log_plain(" ⚠️ DISTORTION DETECTED: Packet delivery gaps too large!");
821 log_plain(" - Max gap: %u ms (should be ~20ms for smooth audio)", g_received_stats.max_gap_ns);
822 if (g_received_stats.max_gap_ns > 80) {
823 log_plain(" - SEVERE: Gaps > 80ms cause severe distortion and dropouts");
824 } else if (g_received_stats.max_gap_ns > 50) {
825 log_plain(" - Gaps > 50ms cause noticeable distortion");
826 }
827 }
828 if (g_received_stats.discontinuity_count > 0) {
829 log_plain(" Packet delivery discontinuities: %llu gaps > 100ms detected", (unsigned long long)g_received_stats.discontinuity_count);
830 }
831 if (g_received_stats.jitter_count > (g_received_stats.total_samples / 100)) {
832 log_plain(" High jitter detected: > 1%% of samples have rapid amplitude changes");
833 log_plain(" - May indicate buffer underruns from sparse packet delivery");
834 }
835
836 log_plain("================================================================================");
837}
const audio_analysis_stats_t * audio_analysis_get_sent_stats(void)
Get sent audio statistics.
Definition analysis.c:501
#define MAX_PACKET_SAMPLES
Definition analysis.c:76
const audio_analysis_stats_t * audio_analysis_get_received_stats(void)
Get received audio statistics.
Definition analysis.c:507
unsigned int uint32_t
unsigned long long uint64_t
#define log_plain(...)
Plain logging - writes to both log file and stderr without timestamps or log levels.
Definition log/log.h:659
#define NS_PER_MS_INT
Definition time.h:172
uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns)
Calculate elapsed time with wraparound safety.
Definition time.c:117
Measurements used to diagnose sent or received audio quality.
Definition analysis.h:31

References audio_analysis_get_received_stats(), audio_analysis_get_sent_stats(), audio_analysis_stats_t::dc_offset, ECHO_DELAY_COUNT, log_plain, MAX_PACKET_SAMPLES, NS_PER_MS_INT, audio_analysis_stats_t::rms_level, and time_elapsed_ns().

◆ audio_analysis_set_aec3_metrics()

void audio_analysis_set_aec3_metrics ( double echo_return_loss,
double echo_return_loss_enhancement,
uint64_t delay_ns )

Set AEC3 echo cancellation metrics.

Parameters
echo_return_lossEcho return loss (dB) - how much echo is attenuated
echo_return_loss_enhancementAdditional echo suppression (dB)
delay_nsEstimated echo delay in nanoseconds

Definition at line 513 of file analysis.c.

513 {
514 // Store AEC3 metrics for reporting
515 // These come from WebRTC EchoControl::GetMetrics() call
516 g_aec3_echo_return_loss = echo_return_loss;
517 g_aec3_echo_return_loss_enhancement = echo_return_loss_enhancement;
518 g_aec3_delay_ns = delay_ns;
519 g_aec3_metrics_available = true;
520}

Referenced by client_audio_pipeline_process_duplex().

◆ audio_analysis_track_received_packet()

void audio_analysis_track_received_packet ( size_t size)

Track received packet.

Parameters
sizePacket size in bytes

Definition at line 468 of file analysis.c.

468 {
469 (void)size; // Unused parameter - reserved for future per-packet analysis
470 if (!g_analysis_enabled)
471 return;
472
473 uint64_t now_ns = time_get_ns();
474 int64_t now_us = (int64_t)time_ns_to_us(now_ns);
475
476 // Track packet timing for stuttering detection
477 if (g_received_packet_times_count < MAX_PACKET_SAMPLES) {
478 g_received_packet_times_ns[g_received_packet_times_count++] = now_ns;
479 }
480
481 // Detect gaps between consecutive packets (discontinuity)
482 if (g_received_stats.packets_count > 0) {
483 int64_t gap_us = now_us - g_received_last_packet_time_us;
484 int32_t gap_ms = (int32_t)(gap_us / 1000);
485
486 // Expected: ~20ms per Opus frame, flag if gap > 100ms
487 if (gap_ms > 100) {
488 g_received_stats.discontinuity_count++;
489 }
490
491 // Track max gap
492 if (gap_ms > (int32_t)g_received_stats.max_gap_ns) {
493 g_received_stats.max_gap_ns = (uint32_t)gap_ms;
494 }
495 }
496
497 g_received_last_packet_time_us = now_us;
498 g_received_stats.packets_count++;
499}

References MAX_PACKET_SAMPLES.

◆ audio_analysis_track_received_sample()

void audio_analysis_track_received_sample ( float sample)

Track received audio sample.

Parameters
sampleAudio sample value

Definition at line 279 of file analysis.c.

279 {
280 if (!g_analysis_enabled)
281 return;
282
283 g_received_stats.total_samples++;
284
285 // Track peak level
286 float abs_sample = fabsf(sample);
287 if (abs_sample > g_received_stats.peak_level) {
288 g_received_stats.peak_level = abs_sample;
289 }
290
291 // Track clipping (samples > 1.0) - indicates distortion
292 if (abs_sample > 1.0f) {
293 g_received_stats.clipping_count++;
294 g_received_clipping_samples++;
295 }
296
297 // Detect sharp transitions (sudden amplitude jumps > 0.3) - indicates clicks/pops/artifacts
298 float amp_change = fabsf(sample - g_received_last_sample);
299 if (amp_change > 0.3f) {
300 g_received_sharp_transitions++;
301 }
302 g_received_transition_samples++;
303
304 // Accumulate for mean calculation
305 g_received_mean += sample;
306
307 // Detect zero crossings (waveform crossing zero) - indicates spectral content
308 // Use file-scope static variable for prev sample tracking
309 // (This function is called from the protocol reception thread, separate from the
310 // audio capture thread, so using distinct static variables is safe)
311 static float s_received_prev_sample_for_zero_crossing = 0.0f;
312 if ((s_received_prev_sample_for_zero_crossing > 0 && sample < 0) || (s_received_prev_sample_for_zero_crossing < 0 && sample > 0)) {
313 g_received_zero_crossings++;
314 }
315 s_received_prev_sample_for_zero_crossing = sample;
316
317 // Track silence and low-energy audio
318 if (abs_sample < 0.001f) {
319 g_received_stats.silent_samples++;
320 g_received_silence_burst++;
321
322 // Track when silence started
323 if (g_received_silence_burst == 1) {
324 g_received_silence_start_sample = g_received_stats.total_samples;
325 }
326 } else {
327 // Silence ended - track gap interval and max burst length
328 if (g_received_silence_burst > 0) {
329 // Calculate time gap between end of last silence and start of this one
330 if (g_received_last_silence_end_sample > 0) {
331 uint64_t samples_between = g_received_silence_start_sample - g_received_last_silence_end_sample;
332 uint32_t ms_between = (uint32_t)(samples_between * 1000 / 48000); // Convert samples to ms at 48kHz
333
334 // Track the gap interval if we have room
335 if (g_received_gap_count < MAX_GAP_SAMPLES) {
336 g_received_gap_intervals_ms[g_received_gap_count++] = ms_between;
337 }
338 }
339
340 g_received_last_silence_end_sample = g_received_stats.total_samples;
341
342 // Track max burst length
343 if (g_received_silence_burst > g_received_max_silence_burst) {
344 g_received_max_silence_burst = g_received_silence_burst;
345 }
346 }
347 g_received_silence_burst = 0;
348 }
349
350 // Track very quiet audio (< 0.05 amplitude) which contributes to muddy/quiet perception
351 if (abs_sample < 0.05f) {
352 g_received_low_energy_samples++;
353 }
354
355 // Detect jitter: rapid amplitude changes > 0.5 between consecutive samples
356 float delta = fabsf(sample - g_received_last_sample);
357 if (delta > 0.5f) {
358 g_received_stats.jitter_count++;
359 }
360 g_received_last_sample = sample;
361
362 // Accumulate for RMS calculation
363 g_received_rms_accumulator += sample * sample;
364 g_received_rms_sample_count++;
365
366 // Echo detection: check if received sample matches sent sample from N ms ago
367 // This detects if echo cancellation is working (it shouldn't find matches)
368 if (g_echo_correlation_sample_count < 500000) { // Limit to first ~10 seconds
369 for (int delay_idx = 0; delay_idx < ECHO_DELAY_COUNT; delay_idx++) {
370 // Calculate sample delay: delay_ms * (sample_rate / 1000)
371 uint32_t delay_samples = (g_echo_delays_ms[delay_idx] * 48000) / 1000;
372
373 // Get sent sample from that delay ago (from circular buffer)
374 uint64_t sent_pos;
375 if (g_echo_buffer_pos >= delay_samples) {
376 sent_pos = g_echo_buffer_pos - delay_samples;
377 } else {
378 sent_pos = (g_echo_buffer_pos + ECHO_BUFFER_SIZE) - delay_samples;
379 }
380
381 float sent_sample = g_echo_buffer[sent_pos];
382
383 // Check if samples match (correlation threshold = 0.1)
384 float diff = fabsf(sample - sent_sample);
385 if (diff < 0.1f && fabsf(sent_sample) > 0.01f) { // Only count if sent is not silence
386 g_echo_match_count[delay_idx]++;
387 g_echo_correlation_strength[delay_idx] += (0.1f - diff); // Accumulate strength
388 }
389 }
390 g_echo_correlation_sample_count++;
391 }
392
393 // Beep/tone artifact detection
394 // Store sample in sliding window for frequency analysis
395 g_received_beep_window[g_received_beep_window_idx] = sample;
396 g_received_beep_window_idx = (g_received_beep_window_idx + 1) % BEEP_WINDOW_SIZE;
397
398 // Analyze window every 10ms (480 samples at 48kHz)
399 if (g_received_beep_window_idx == 0 && g_received_stats.total_samples > BEEP_WINDOW_SIZE) {
400 // Calculate zero-crossing rate in this window
401 int zero_crossings = 0;
402 float min_amp = 1.0f, max_amp = 0.0f;
403 float sum_amp = 0.0f;
404 float prev = g_received_beep_window[0];
405
406 for (int i = 1; i < BEEP_WINDOW_SIZE; i++) {
407 float curr = g_received_beep_window[i];
408 float abs_curr = fabsf(curr);
409
410 // Track amplitude range
411 if (abs_curr > max_amp)
412 max_amp = abs_curr;
413 if (abs_curr < min_amp)
414 min_amp = abs_curr;
415 sum_amp += abs_curr;
416
417 // Count zero crossings
418 if ((prev > 0 && curr < 0) || (prev < 0 && curr > 0)) {
419 zero_crossings++;
420 }
421 prev = curr;
422 }
423
424 float avg_amp = sum_amp / BEEP_WINDOW_SIZE;
425 float amp_range = max_amp - min_amp;
426
427 // A beep/tone has:
428 // 1. High zero-crossing rate (>20 per 10ms = >2000Hz equivalent, or 5-20 = 500-2000Hz)
429 // 2. Consistent amplitude (range/avg < 0.5 means sine-wave like)
430 // 3. Non-trivial amplitude (avg > 0.02)
431 bool is_tonal = (zero_crossings >= 5 && zero_crossings <= 100) && // 500Hz-10kHz range
432 (avg_amp > 0.02f) && // Not silence
433 (amp_range < avg_amp * 1.5f); // Relatively consistent amplitude
434
435 if (is_tonal) {
436 g_received_tonal_samples += BEEP_WINDOW_SIZE;
437
438 if (!g_in_beep_burst) {
439 // Starting a new beep burst
440 g_in_beep_burst = true;
441 g_beep_burst_samples = BEEP_WINDOW_SIZE;
442 } else {
443 g_beep_burst_samples += BEEP_WINDOW_SIZE;
444 }
445 } else {
446 if (g_in_beep_burst) {
447 // Beep burst ended
448 // Only count as beep event if it was short (< 500ms = 24000 samples)
449 // Long tonal sounds are likely music, not artifacts
450 if (g_beep_burst_samples > 0 && g_beep_burst_samples < 24000) {
451 g_received_beep_events++;
452 g_received_stats.beep_events = g_received_beep_events;
453 }
454 g_in_beep_burst = false;
455 g_beep_burst_samples = 0;
456 }
457 }
458
459 g_received_stats.tonal_samples = g_received_tonal_samples;
460 }
461
462 // Write to WAV file if enabled
463 if (g_received_wav) {
464 wav_writer_write(g_received_wav, &sample, 1);
465 }
466}
#define MAX_GAP_SAMPLES
Definition analysis.c:69
#define ECHO_BUFFER_SIZE
Definition analysis.c:82
#define BEEP_WINDOW_SIZE
Definition analysis.c:105
int wav_writer_write(wav_writer_t *writer, const float *samples, int num_samples)
Write audio samples to WAV file.
Definition wav_writer.c:98

References BEEP_WINDOW_SIZE, ECHO_BUFFER_SIZE, ECHO_DELAY_COUNT, MAX_GAP_SAMPLES, and wav_writer_write().

Referenced by audio_process_received_samples().

◆ audio_analysis_track_sent_packet()

void audio_analysis_track_sent_packet ( size_t size)

Track sent packet.

Parameters
sizePacket size in bytes

Definition at line 252 of file analysis.c.

252 {
253 (void)size; // Unused parameter - reserved for future per-packet analysis
254 if (!g_analysis_enabled)
255 return;
256
257 int64_t now_us = (int64_t)time_ns_to_us(time_get_ns());
258
259 // Detect gaps between consecutive packets (discontinuity)
260 if (g_sent_stats.packets_count > 0) {
261 int64_t gap_us = now_us - g_sent_last_packet_time_us;
262 int32_t gap_ms = (int32_t)(gap_us / 1000);
263
264 // Expected: ~20ms per Opus frame, flag if gap > 100ms
265 if (gap_ms > 100) {
266 g_sent_stats.discontinuity_count++;
267 }
268
269 // Track max gap
270 if (gap_ms > (int32_t)g_sent_stats.max_gap_ns) {
271 g_sent_stats.max_gap_ns = (uint32_t)gap_ms;
272 }
273 }
274
275 g_sent_last_packet_time_us = now_us;
276 g_sent_stats.packets_count++;
277}

◆ audio_analysis_track_sent_sample()

void audio_analysis_track_sent_sample ( float sample)

Track sent audio sample.

Parameters
sampleAudio sample value

Definition at line 181 of file analysis.c.

181 {
182 if (!g_analysis_enabled)
183 return;
184
185 g_sent_stats.total_samples++;
186
187 // Track peak level
188 float abs_sample = fabsf(sample);
189 if (abs_sample > g_sent_stats.peak_level) {
190 g_sent_stats.peak_level = abs_sample;
191 }
192
193 // Track clipping (samples > 1.0) - indicates distortion
194 if (abs_sample > 1.0f) {
195 g_sent_stats.clipping_count++;
196 g_sent_clipping_samples++;
197 }
198
199 // Detect sharp transitions (sudden amplitude jumps > 0.3) - indicates clicks/pops
200 float amp_change = fabsf(sample - g_sent_last_sample);
201 if (amp_change > 0.3f) {
202 g_sent_sharp_transitions++;
203 }
204 g_sent_transition_samples++;
205
206 // Accumulate for mean calculation
207 g_sent_mean += sample;
208
209 // Detect zero crossings (waveform crossing zero) - indicates spectral content
210 // Use file-scope static variable for prev sample tracking
211 // (This function is only called from the audio capture thread, but using file-scope
212 // static is clearer and avoids shadowing the existing g_sent_last_sample variable)
213 static float s_sent_prev_sample_for_zero_crossing = 0.0f;
214 if ((s_sent_prev_sample_for_zero_crossing > 0 && sample < 0) || (s_sent_prev_sample_for_zero_crossing < 0 && sample > 0)) {
215 g_sent_zero_crossings++;
216 }
217 s_sent_prev_sample_for_zero_crossing = sample;
218
219 // Track silence (very low level)
220 if (abs_sample < 0.001f) {
221 g_sent_stats.silent_samples++;
222 g_sent_silence_burst++;
223 } else {
224 // Silence ended - track max burst length
225 if (g_sent_silence_burst > g_sent_max_silence_burst) {
226 g_sent_max_silence_burst = g_sent_silence_burst;
227 }
228 g_sent_silence_burst = 0;
229 }
230
231 // Detect jitter: rapid amplitude changes > 0.5 between consecutive samples
232 float delta = fabsf(sample - g_sent_last_sample);
233 if (delta > 0.5f) {
234 g_sent_stats.jitter_count++;
235 }
236 g_sent_last_sample = sample;
237
238 // Accumulate for RMS calculation
239 g_sent_rms_accumulator += sample * sample;
240 g_sent_rms_sample_count++;
241
242 // Write to WAV file if enabled
243 if (g_sent_wav) {
244 wav_writer_write(g_sent_wav, &sample, 1);
245 }
246
247 // Store in echo detection buffer (circular)
248 g_echo_buffer[g_echo_buffer_pos] = sample;
249 g_echo_buffer_pos = (g_echo_buffer_pos + 1) % ECHO_BUFFER_SIZE;
250}

References ECHO_BUFFER_SIZE, and wav_writer_write().