FAQ

From VoIPmonitor.org
Revision as of 16:18, 6 January 2026 by Admin (talk | contribs) (Slim down FAQ - troubleshooting content moved to GUI_troubleshooting (90% reduction))


This page contains frequently asked questions about VoIPmonitor configuration and common issues.

For GUI troubleshooting (HTTP 500 errors, blank screens, upgrade issues, database problems, etc.), see GUI_troubleshooting.

For sniffer troubleshooting (packet capture issues, missing CDRs, service problems, etc.), see Sniffer_troubleshooting.

RTP Audio Playback Not Available in GUI

If RTP streams are not available for download or playback in the GUI and no WAV files are generated, even though SIP signaling and QoS metrics are visible, the issue is that the sensor is not configured to save the audio payload of RTP packets.

Symptoms

  • SIP packets are being captured and visible (signaling works)
  • QoS metrics like jitter, packet loss, and MOS are calculated and displayed
  • No audio playback option (Play button) is available in the CDR view
  • No WAV files are being generated in the spool directory
  • PCAP files may be saved but without RTP payload data

Root Cause

By default, or in configurations optimized for low disk usage, VoIPmonitor may only save RTP packet headers (needed for QoS calculations) without capturing the RTP payload (the actual audio data). This allows QoS metrics to work but prevents audio playback and WAV file generation.

Solution

To enable audio playback in the GUI and WAV file generation, configure the sniffer to save full RTP packets.

Step 1: Enable RTP Packet Saving

Edit the `/etc/voipmonitor.conf` file and add or modify the `savertp` option: 

# Save full RTP packets (required for audio playback)
savertp = yes

Notes:

  • `savertp = yes` saves both headers and payload (enables audio playback)
  • `savertp = header` saves only headers (QoS metrics only, no audio)
  • The default setting varies by configuration and may not save audio payload

Step 2: Restart VoIPmonitor Service

Apply the configuration change by restarting the VoIPmonitor service: 

# Restart the VoIPmonitor service
systemctl restart voipmonitor

# Verify the service is running correctly
systemctl status voipmonitor

Step 3: Verify the Fix

After restarting the service:

1. Make a test call that generates RTP traffic 2. Navigate to the CDR listing in the web GUI 3. Look for a Play (▶) icon in the player column for the test call 4. Check your spool directory (typically `/var/spool/voipmonitor/`) for RTP packets containing audio data

Additional Notes

The Sniffer_configuration page documents additional audio-related options:

  • `saveaudio = wav` - Generates standalone WAV files in addition to PCAP files (adds CPU/I/O load, generally not necessary for GUI playback)
  • `wav = ` - Individual codec-specific options (not typically needed)
  • `saveaudio_stereo`, `saveaudio_from_first_invite` - Audio format controls

However, for basic GUI audio playback, setting `savertp = yes` is sufficient. The other options are for specialized use cases.

Related Information


Audio Playback or PCAP Download Fails With callidmerge_header Typo

If audio playback in the GUI does not work, or PCAP files fail to download/play, and you have configured the callidmerge_header parameter for call leg merging, the issue may be a **common typo** in the parameter name.

Symptoms

  • Audio playback button (Play icon) does not work in the GUI, even though RTP streams are present in the PCAP file
  • PCAP files can be downloaded but audio extraction/playback fails
  • savertp and saveaudio settings appear correct
  • Other GUI features work normally

Root Cause

The correct parameter name is callidmerge_header (no underscore between "callid" and "merge"). Many users accidentally type callid_merge_header (with underscore), which the voipmonitor sniffer does not recognize. This causes improper call leg association, which can break audio playback and PCAP handling.

Solution

Step 1: Check for Typo in Configuration

Open the voipmonitor configuration file: 

sudo nano /etc/voipmonitor.conf

Search for the parameter and check for the typo: 

# INCORRECT: Typo with underscore - causes problems
callid_merge_header = Parent-Call-ID

# CORRECT: No underscore - proper syntax
callidmerge_header = Parent-Call-ID

The difference is the underscore between "callid" and "merge".

Step 2: Correct the Typo

If you find callid_merge_header (with underscore), change it to callidmerge_header (no underscore): 

# Change this (WRONG):
callid_merge_header = X-PARENT-CALLID

# To this (CORRECT):
callidmerge_header = X-PARENT-CALLID

Step 3: Restart the VoIPmonitor Service

Apply the configuration change: 

sudo systemctl restart voipmonitor

Step 4: Verify the Fix

Make a new test call and verify:

  1. Audio playback works in the GUI
  2. PCAP files can be downloaded and audio extracted
  3. No errors in the voipmonitor logs related to call leg merging

Prevention

When configuring call leg merging or call correlation features, always use the exact parameter name:

  • Correct: callidmerge_header (no underscore)
  • Incorrect: callid_merge_header (with underscore - will be ignored)

For more information about call leg merging and correlation, see Merging_or_correlating_multiple_call_legs.


"Error, conversion failed, audio file was not created from pcap" Message

If you encounter the error message **"Error, conversion failed, audio file was not created from pcap"** when attempting to download a media trace (audio file) from the GUI, this indicates that while the PCAP file exists and is accessible, VoIPmonitor cannot generate audio (WAV) from it. This error typically has two distinct root causes that require different diagnostic approaches.

Symptoms

  • Error message appears when clicking the "Audio" download button in the CDR view
  • The media trace download fails with the conversion error
  • The PCAP download works correctly, but audio conversion fails
  • The error message is specific to the conversion process, not file access

Root Causes and Diagnostic Workflow

Follow this diagnostic workflow to identify which scenario applies to your case:

Step 1: Download and Examine the PCAP File

First, download the PCAP file associated with the CDR in question. Then use Wireshark or tshark to verify whether the PCAP contains actual RTP audio packets. 

# Download the PCAP from the GUI CDR view

# Method 1: Use tshark from command line (quick test)
tshark -r downloaded.pcap -Y "rtp" | head -20

# If no output, try checking for RTCP only (control packets, no audio)
tshark -r downloaded.pcap -Y "rtcp" | head -20

# Method 2: Use tcpdump (alternative)
tcpdump -r downloaded.pcap -nn 'rtp[1] & 0x7f == 0' -c 5

Scenario A: No RTP Packets Found (Most Common)

If your search returns **zero RTP packets**, this indicates that RTP audio payload was never captured or has been removed from storage. This is a data retention policy issue, not a conversion failure.

Root Cause Analysis:

Check the following possibilities:

1. **RTP was captured but removed by retention policies:** 

  # Check your retention settings in /etc/voipmonitor.conf
  grep -E "maxpoolrtp|maxpool|maxpooldays" /etc/voipmonitor.conf

  Look for:
  * maxpoolrtpsize - Size limit for RTP files
  * maxpoolrtpdays - Age limit for RTP files
  * maxpooldays - Overall age limit

  The RTP directory for this call's date may have been cleaned up while SIP files remain.

2. **RTP was never captured (configuration issue):** 

  # Check RTP capture settings
  grep -E "savertp|savertcp" /etc/voipmonitor.conf

  Possible causes:
  * savertp = no - RTP audio is disabled
  * savertp = header - Only RTP headers captured (no audio payload)
  * savertcp = yes - Saves RTCP control packets (not audio)

Solution:

Adjust your data retention policies to ensure RTP packets are kept as long as needed: 

# Edit /etc/voipmonitor.conf

# Increase RTP retention (size-based)
maxpoolrtpsize = 204800    # 200 GB for RTP files (adjust based on disk)

# OR Increase RTP retention (time-based)
maxpoolrtpdays = 30       # Keep RTP files for 30 days

# Ensure overall limit allows sufficient space
maxpoolsize = 512000      # Overall spool limit (must accommodate RTP + SIP + other)

Apply changes: 

systemctl restart voipmonitor

For detailed information on retention configuration, see Data_Cleaning.

Scenario B: RTP Packets Present but Conversion Fails

If the PCAP file contains RTP packets with actual audio payload but audio conversion still fails, this indicates a more complex issue that requires investigation.

Symptoms:

  • tshark shows RTP packets with payload
  • Wireshark "RTP Stream Analysis" shows audio data
  • Error persists despite RTP being present in the PCAP

Potential Causes:*

  • Unsupported codec or codec configuration issue
  • Corrupted or malformed RTP packets
  • Complex codec negotiation not fully understood
  • Specialized call setup or encryption causing conversion issues

Solution: Share the PCAP File with Support ===

For this scenario, the issue requires further investigation by VoIPmonitor support. Please:

1. Download the complete PCAP file from the GUI 2. Document the call details (CDR ID, calldate, codec used) 3. Share the PCAP file with VoIPmonitor support for analysis 4. Include any error messages or logs from the conversion attempt

This allows support to reproduce and diagnose the specific conversion failure.

Additional Diagnostic Tips

Symptom ! Likely Cause ! Resolution
RTP packets not captured | Check savertp setting, ensure audio recording is enabled
Only control traffic captured | Check savertcp=yes with savertp=no, audio payload not saved
Capture issues or corruption | Verify packet capture interface and check for dropped packets
Codec or payload issue | Share PCAP with support for analysis

Quick Reference: Common Configuration Issues

# Common problematic configurations:

# Problem 1: RTP audio disabled
savertp = no              # No RTP audio is captured
# Fix: savertp = yes

# Problem 2: Only RTCP control packets
savertcp = yes            # Saves RTCP (no audio)
savertp = no              # RTP audio disabled
# Fix: savertp = yes, savertcp = no (if RTCP not needed)

# Problem 3: Headers only (QoS metrics but no audio)
savertp = header          # Only RTP headers, no payload
# Fix: savertp = yes

# Problem 4: RTP retention too short
maxpoolrtpdays = 7        # RTP deleted after 7 days
maxpooldays = 60          # SIP kept for 60 days
# Fix: Increase maxpoolrtpdays to match desired retention

Related Information


AI Summary for RAG

Summary: VoIPmonitor FAQ covering common configuration questions: (1) RTP Audio Playback - requires savertp=yes in voipmonitor.conf (savertp=header for metadata only, savertp=all for both RTP and RTCP); (2) callidmerge_header typo - check for typo in voipmonitor.conf, common mistake is "callidmerge_heade" instead of "callidmerge_header"; (3) Audio conversion failed - check file retention settings (zippcap, cleandatabase), verify pcap files exist in spool directory, check sox/ffmpeg binaries.

Keywords: savertp, RTP audio, audio playback, callidmerge_header, typo, pcap download, audio conversion failed, zippcap, cleandatabase, sox, ffmpeg, voipmonitor.conf, spool directory

Key Questions:

  • Why is RTP audio playback not available in GUI?
  • What does savertp=yes do?
  • PCAP download fails - what to check?
  • Audio conversion failed error - how to fix?
  • What is callidmerge_header and common typos?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=FAQ&oldid=8950"