SAP/SDP Discovery

SAP/SDP Protocol

Session Announcement Protocol (SAP) and Session Description Protocol (SDP) for stream discovery and configuration.

Overview

MediaX uses SAP/SDP for automatic stream discovery:

  • SAP: Multicast announcements of available streams
  • SDP: Stream metadata and connection information

This enables receivers to automatically discover and configure streams without manual IP/port configuration.

How It Works

┌─────────────┐         SAP Announcement          ┌─────────────┐
│   Sender    │ ────────────────────────────────> │  Receiver   │
│             │       (multicast 239.255.255.255) │             │
├─────────────┤                                   ├─────────────┤
│  Payloader  │         RTP Video Stream          │ Depayloader │
│             │ ────────────────────────────────> │             │
└─────────────┘       (multicast 239.192.x.x)     └─────────────┘
  1. Sender announces stream via SAP multicast
  2. Receiver listens for SAP announcements
  3. Receiver extracts SDP from announcement
  4. Receiver configures depayloader from SDP
  5. Receiver joins RTP multicast and receives video

SAP Announcer

Announce streams on the network:

#include "sap/sap_announcer.h"

mediax::sap::SapAnnouncer announcer;

// Create stream information
mediax::rtp::StreamInformation stream_info;
stream_info.session_name = "camera-feed";
stream_info.hostname = "239.192.1.1";
stream_info.port = 5004;
stream_info.width = 1920;
stream_info.height = 1080;
stream_info.framerate = 30;
stream_info.encoding = mediax::rtp::ColourspaceType::kColourspaceRgb24;

// Add stream to announcer
announcer.AddSapAnnouncement(stream_info);

// Start announcing
announcer.Start();

// ... announcer runs in background ...

// Stop when done
announcer.Stop();
announcer.DeleteAllSapAnnouncements();

SAP Listener

Discover streams on the network:

#include "sap/sap_listener.h"

mediax::sap::SapListener listener;

// Start listening for announcements
listener.Start();

// Wait for announcements (or use callback)
std::this_thread::sleep_for(std::chrono::seconds(2));

// Get discovered streams
auto& streams = listener.GetSapAnnouncements();

for (const auto& [name, stream] : streams) {
    std::cout << "Found stream: " << stream.session_name << std::endl;
    std::cout << "  Address: " << stream.hostname 
              << ":" << stream.port << std::endl;
    std::cout << "  Resolution: " << stream.width 
              << "x" << stream.height << std::endl;
}

listener.Stop();

SDP Format

SDP describes stream parameters in a text format:

v=0
o=- 0 0 IN IP4 192.168.1.100
s=camera-feed
c=IN IP4 239.192.1.1/32
t=0 0
m=video 5004 RTP/AVP 96
a=rtpmap:96 raw/90000
a=fmtp:96 sampling=RGB; width=1920; height=1080; depth=8

SDP Fields

Field Description
v= Protocol version (always 0)
o= Origin (session ID, version, address)
s= Session name
c= Connection information (multicast address)
t= Timing (0 0 = permanent)
m= Media description (type, port, protocol, format)
a=rtpmap: RTP payload type mapping
a=fmtp: Format parameters

SAP Multicast Addresses

SAP announcements use well-known multicast addresses:

Address Scope
239.255.255.255 Global (default)
224.2.127.254 Administrative

Callback-Based Discovery

For event-driven stream discovery:

#include "sap/sap_listener.h"

mediax::sap::SapListener listener;

// Register callback for new streams
listener.RegisterCallback([](const mediax::rtp::StreamInformation& stream) {
    std::cout << "New stream discovered: " << stream.session_name << std::endl;

    // Automatically configure depayloader
    // ...
});

listener.Start();

Python Example

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

# Create listener
listener = mediax.sap.SapListener()
listener.Start()

# Wait for announcements
import time
time.sleep(2)

# Get streams
streams = listener.GetSapAnnouncements()
for name, info in streams.items():
    print(f"Stream: {name}")
    print(f"  Address: {info.hostname}:{info.port}")
    print(f"  Size: {info.width}x{info.height}")

listener.Stop()

Network Configuration

Firewall Rules

Allow SAP multicast traffic:

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

Multicast Routing

Ensure multicast is enabled on your interface:

# Check multicast support
ip link show | grep MULTICAST

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

Troubleshooting

Announcements Not Received

  1. Verify multicast routing is enabled
  2. Check firewall rules
  3. Ensure sender and receiver on same network segment
  4. Use tcpdump to verify SAP packets:

bash sudo tcpdump -i eth0 host 239.255.255.255 and port 9875

Stream Information Incorrect

  • Verify StreamInformation fields match actual stream
  • Check SDP format in announcements
  • Ensure colorspace encoding matches payload format

Support

Edit this page on GitHub