Troubleshooting¶

Common issues and solutions for MediaX.

Installation Issues¶

Package Not Found¶

Symptom: dpkg reports package not found or dependency issues.

Solution:

# Update package list
sudo apt update

# Install dependencies first
sudo apt install libgstreamer1.0-0 gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad

# Retry installation
sudo dpkg -i mediax-runtime-*.deb

# Fix broken dependencies
sudo apt --fix-broken install

Wrong Architecture¶

Symptom: Package architecture doesn't match system.

Solution:

Check your architecture:

dpkg --print-architecture

Download the correct package:

amd64 - 64-bit Intel/AMD
arm64 - 64-bit ARM (Raspberry Pi 4/5)

Build Issues¶

CMake Cannot Find Dependencies¶

Symptom: CMake reports missing packages.

Solution:

# Install build dependencies
sudo apt install cmake build-essential pkg-config \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    libswscale-dev libva-dev

# For Qt6 support
sudo apt install qt6-base-dev qt6-multimedia-dev

# For Python bindings
sudo apt install swig python3-dev

GStreamer Plugin Missing¶

Symptom: Build fails with missing GStreamer element.

Solution:

# List available plugins
gst-inspect-1.0

# Install additional plugins
sudo apt install gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

# For VAAPI
sudo apt install gstreamer1.0-vaapi

Runtime Issues¶

No Video Received¶

Symptom: Depayloader starts but no frames arrive.

Checklist:

Verify sender is transmitting:

bash # Check for multicast traffic sudo tcpdump -i eth0 host 239.192.1.1 and port 5004

Check multicast routing:

```bash # Verify multicast support ip link show | grep MULTICAST

# Add route if needed sudo ip route add 239.0.0.0/8 dev eth0 ```

Check firewall:

```bash # Allow UDP traffic sudo iptables -A INPUT -p udp --dport 5004 -j ACCEPT

# Or disable firewall temporarily sudo ufw disable ```

Verify stream parameters match:
Hostname/IP address
Port number
Resolution
Colorspace

SAP Announcements Not Received¶

Symptom: SAP listener shows no streams.

Solution:

# Check SAP multicast traffic
sudo tcpdump -i eth0 host 239.255.255.255 and port 9875

# Allow SAP traffic
sudo iptables -A INPUT -d 239.255.255.255 -p udp --dport 9875 -j ACCEPT

# Check if IGMP snooping is blocking multicast
# (Common on managed switches)

High Latency¶

Symptom: Video has noticeable delay.

Solutions:

Use uncompressed video for lowest latency
Reduce resolution to lower processing time
Check network:

```bash # Test network latency ping

# Check for packet loss iperf3 -c -u -b 100M ```

Use hardware encoding (VAAPI, NVENC)

Frame Drops¶

Symptom: Video stutters or skips frames.

Solutions:

Increase buffer sizes
Check bandwidth:

bash # Calculate required bandwidth # RGB24: width × height × 3 bytes × fps × 8 bits # 1920×1080×3×30×8 = 1.49 Gbps

Use compressed video for limited bandwidth
Enable jumbo frames on local networks:

bash sudo ip link set eth0 mtu 9000

Python Binding Issues¶

Import Error¶

Symptom: ImportError: No module named 'mediax'

Solution:

import sys
sys.path.append('/usr/local/lib/python3/dist-packages')
import mediax

Undefined Symbol¶

Symptom: ImportError: undefined symbol: gst_deinit

Solution:

This indicates missing GStreamer linkage. Rebuild MediaX:

cd build
cmake -DBUILD_PYTHON=ON ..
make
sudo make install

SWIG Version Mismatch¶

Symptom: SWIG-generated wrapper errors.

Solution:

# Install SWIG 4.x
sudo apt install swig

# Verify version
swig -version

Hardware Acceleration Issues¶

VAAPI Not Working¶

Symptom: Software encoding used instead of hardware.

Solution:

# Check VAAPI support
vainfo

# Install drivers
# Intel:
sudo apt install intel-media-va-driver-non-free

# AMD:
sudo apt install mesa-va-drivers

# Verify GStreamer plugin
gst-inspect-1.0 vaapih264enc

NVENC Not Working¶

Symptom: NVIDIA hardware encoding fails.

Solution:

# Check NVIDIA driver
nvidia-smi

# Install GStreamer NVENC plugin
sudo apt install gstreamer1.0-plugins-bad

# Verify plugin
gst-inspect-1.0 nvh264enc

Network Configuration¶

Multicast Not Working¶

Symptom: Multicast streams don't reach destination.

Solutions:

Enable multicast on interface:

bash sudo ip link set eth0 multicast on

Add multicast route:

bash sudo ip route add 239.0.0.0/8 dev eth0

Check switch configuration:
Enable IGMP snooping
Configure multicast routing
Use unicast for testing:

cpp stream_info.hostname = "192.168.1.100"; // Direct IP

Port Already in Use¶

Symptom: bind: Address already in use

Solution:

# Find process using port
sudo netstat -tulpn | grep 5004

# Kill process or use different port
stream_info.port = 5006;

Getting Help¶

If issues persist:

Website: https://astutesys.com/support
Email: [email protected]

Include in support requests:

Operating system and version
MediaX version
Error messages (full output)
Steps to reproduce
Network configuration

Edit this page on GitHub