ChunkPlayer

This is a developer-focused guide explaining how to use and integrate the ChunkPlayer, a sample PHP application for listening to active calls in real-time ("live spying").

Overview

The ChunkPlayer is a sample application included with the VoIPmonitor GUI that demonstrates how to stream and play audio from a call that is currently in progress. It is intended to be used as a starting point for developers who wish to embed live monitoring functionality into their own custom dashboards or applications.

How It Works

The player functions by making a connection to the VoIPmonitor sensor's manager API (default port 5029). It authenticates and requests audio chunks for a specific, active call using two key identifiers:

• `sensor_id`: The ID of the sensor handling the call.
• `callreference`: A unique, temporary hexadecimal ID for an active call.

Step 1: Configure the ChunkPlayer

The player has its own configuration file that must be set up with your database and manager API credentials.

1. Locate the configuration file

The file is located in the GUI's web directory, typically at:

/var/www/html/api/chunkplayer/configuration.php

2. Edit the file with your details

<?php
// /var/www/html/api/chunkplayer/configuration.php

/**
 * The IP address and port of the sensor's manager API.
 * This is used if a sensor_id is not provided in the request.
 */
define('VPMANAGERHOST', '127.0.0.1');
define('VPMANAGERPORT', 5029);

/**
 * Database credentials.
 * Although not directly used for streaming, they may be required by underlying libraries.
 */
define("MYSQL_HOST", "127.0.0.1");
define("MYSQL_DB", "voipmonitor");
define("MYSQL_USER", "root");
define("MYSQL_PASS", "your_db_password");

?>

Step 2: Find a Live Call to Monitor

To use the player, you first need to get the `callreference` for a call that is currently in progress. This is done by querying the sensor's manager API with the `listcalls` command.

Connect to the sensor via `nc` (netcat)

# Replace SENSOR_IP and SENSOR_MANAGE_PORT with your sensor's details
echo 'listcalls' | nc 127.0.0.1 5029

The command will return a list of active calls. Look for the `callreference` parameter in the output. This is the ID you will need for the player.

Example output snippet

...
[call]
id: 1
caller: 1001
called: 1002
callreference: 4a3f7b2c1d  <-- THIS IS THE VALUE YOU NEED
...

Step 3: Use the Player Interface

Once you have a valid `callreference`, you can use the player.

1. Access the player's web interface

Navigate your browser to:

http://Your-GUI-IP/api/chunkplayer/index.html

2. Enter the call details

• callref: Paste the hexadecimal `callreference` value you obtained in the previous step.
• sensor id: Enter the numeric ID of the sensor that is handling the call.

3. Click "play"

The player will connect to the manager API and begin streaming the live audio from the call.

Important Security Considerations

The ChunkPlayer requires direct access to the sensor's manager API port (TCP 5029).

• Firewall Rules: Ensure that your firewall allows the server hosting the GUI to connect to the sensor on this port.
• Network Exposure: The manager API provides powerful control over the sensor. Do not expose this port directly to the public internet. Access should be restricted to trusted internal IP addresses only.

Critical Warning: Using Internal Classes vs. Manager API

The ChunkPlayer demonstrates the recommended approach for custom integration: using the Manager API (port 5029) to communicate with the sensor.

Why Not Link Against Internal Classes?

Some developers may be tempted to link their custom C++ applications directly against VoIPmonitor's internal C++ classes (the sniffer library). This approach is strongly discouraged for the following reasons:

• Blocking VoIPmonitor Threads: If your custom code performs blocking operations (such as waiting indefinitely for threads to join) that interact with VoIPmonitor's internal data structures, you can block the sniffer's critical packet processing threads. This can cause packetbuffer: MEMORY IS FULL errors even if the system has adequate resources.

• Destructor Blocking: A common source of problems is improper thread management in destructors. For example, if your code uses internal Call class objects and the destructor waits indefinitely for a listening thread to join, this will block VoIPmonitor's main processing loop.

• API Stability: The internal C++ classes are not part of the public API. They may change without notice, breaking your custom application on future VoIPmonitor updates.

Symptoms of Custom Code Blocking VoIPmonitor

If you have integrated custom code that links against VoIPmonitor's internal classes, watch for these indicators of blocking issues:

• packetbuffer: MEMORY IS FULL appears under high call load, even with adequate max_buffer_mem
• High CPU usage but packets are being dropped
• The issue occurs only when your custom application is running

Recommended Debugging Approach

If you suspect your custom code is blocking VoIPmonitor: 1. Review destructors for thread join operations that may wait indefinitely 2. Ensure all thread operations use timeouts instead of blocking waits 3. Consider profiling your application to identify critical paths where it may block VoIPmonitor's threads 4. If possible, migrate to using the Manager API instead of internal classes

For information on troubleshooting packetbuffer overflow generally, see Sniffer_configuration#Packet_Buffer_Settings.

AI Summary for RAG

Summary: This guide explains how to use the ChunkPlayer, a sample PHP application included with VoIPmonitor for embedding a live audio player for active calls ("live spying"). It details the three-step process for developers: 1) Configuring the player's `configuration.php` file with database and sensor manager API credentials. 2) Finding an active call to monitor by querying the sensor's manager API with the `listcalls` command to obtain a hexadecimal `callreference`. 3) Using the player's web interface (`index.html`) by entering the `callreference` and `sensor_id` to begin streaming the live audio. The guide concludes with a critical security warning (protect manager port 5029/TCP) and a warning against linking directly against VoIPmonitor's internal C++ classes, which can block packet processing threads and cause `packetbuffer: MEMORY IS FULL` errors. Developers are strongly advised to use the Manager API instead of internal classes to avoid blocking issues. Keywords: chunkplayer, live call, live spying, listen, active call, embed, api, manager api, `listcalls`, `callreference`, real-time, audio stream, developer, internal classes, C++, packetbuffer overflow, blocking threads, destructor Key Questions:

• What is the ChunkPlayer and how do I use it?
• How can I embed a live VoIPmonitor audio player into my own application?
• What firewall ports are needed for the ChunkPlayer?
• How to use the `listcalls` manager API command?
• Why should I use Manager API instead of linking against internal C++ classes?
• Can custom C++ code cause packetbuffer overflow by blocking VoIPmonitor threads?
• What are symptoms of custom code blocking the VoIPmonitor sniffer?