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).

⚠️ Warning: The manager API provides powerful control over the sensor. Do not expose port 5029 directly to the public internet. Access should be restricted to trusted internal IP addresses only.

Firewall Rules: Ensure that your firewall allows the server hosting the GUI to connect to the sensor on this port.
Network Exposure: Restrict access 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: Developer guide for ChunkPlayer, a sample PHP application for embedding live audio streaming of active calls ("live spying"). Three-step process: 1) Configure configuration.php with manager API (port 5029) and DB credentials. 2) Get callreference using listcalls command via netcat. 3) Use web interface (index.html) with callreference and sensor_id. Critical security: protect port 5029/TCP, internal network only. Warning against linking internal C++ classes (causes blocking, packetbuffer: MEMORY IS FULL). Use Manager API for custom integrations.

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, port 5029

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?
How do I get the callreference for an active call?
Why should I use Manager API instead of linking against internal C++ classes?
Can custom C++ code cause packetbuffer overflow by blocking VoIPmonitor threads?