Understanding UDP URL

This page provides an in-depth description of URL address used to receive UDP traffic with VLC.

URL complete structure

VLC UDP access URL use the following format:

udp://[server_addr[:server_port]][@[bind_addr]:[bind_port]]

  • server_addr: server address, aka the source address of the stream.

  • server_port: server port, aka the source port of the stream.

  • bind_addr: binding address, aka the destination address of the stream.

  • bind_port: binding port, aka the destination port of the stream.

Note

If the server address or binding address is omitted, any packet with the proper port is captured.

A lot of parameters are optional, but it differs drastically between the different reception scenarios.

Receiving a Unicast Stream

Here is simple example of a streamer device sending a multimedia sample (sample.mp4) to a receiver device using MPEG-TS format on UDP in unicast:

digraph udp_unicast1 { rankdir=TB; node [shape=circle]; { rank=same; sender_command [shape=plaintext,label="$ vlc sample.mp4 --sout=\"#std{access=udp,\nmux=ts, dst=10.0.0.2:1234}"]; sender_device [label="Streamer \n IP: 10.0.0.1"]; } { rank=same; receiver_command [shape=plaintext,label="$ vlc udp://@:1234 "]; receiver_device [label="Receiver \n IP: 10.0.0.2"]; } sender_device -> receiver_device [label="The streamer sends the stream to\nReceiver IP 10.0.0.2 and port 1234"]; sender_command -> sender_device [style=invis]; receiver_command -> receiver_device [style=invis]; }

As destination address is the Receiver’s local IP address, the Receiver does not have to declare the destination port:

  • udp://@:1234 will work: it captures any packet received locally from and to any IP, but with the destination port 1234.

  • udp://@10.0.0.2:1234 will work: it captures any packet received locally from any but with destination IP 10.0.0.2 and port 1234.

  • udp://10.0.0.1@10.0.0.2:1234 will work: it captures any packet received locally with a source address of 10.0.0.1, destination address of 10.0.0.2, and destination port of 1234.

  • udp://10.0.0.42@10.0.0.2:1234 with NOT work in the previous example, as no device with the IP 10.0.0.42 is streaming to the Receiver’s IP address.

Receiving a Multicast Stream

One of the main difference between unicast and multicast is that the multicast address is not an IP address owned by a device: it defines a group where devices can subscribe to send and receive packets.

Here is simple example of a streamer device sending a multimedia sample (sample.mp4) using MPEG-TS format on UDP in multicast:

digraph udp_unicast1 { rankdir=TB; node [shape=circle]; { rank=same; sender_command [shape=plaintext,label="$ vlc sample.mp4 --sout=\"#std{access=udp,\nmux=ts, dst=225.0.0.42:1234}"]; sender_device [label="Streamer \n IP: 10.0.0.1"]; } switch [shape=square,label="Network\nSwitch"]; { rank=same; receiver_command [shape=plaintext,label="$ vlc udp://@225.0.0.42:1234 "]; receiver_device [label="Receiver \n IP: 10.0.0.2"]; } sender_device -> switch [label="The streamer sends the stream to the\nmulticast address 225.0.0.42 on port 1234"]; switch -> receiver_device [label="The receiver join the multicast group 225.0.0.42\n and receive the stream on port 1234"]; sender_command -> sender_device [style=invis]; receiver_command -> receiver_device [style=invis]; }

As destination address is multicast group and not the Receiver’s local IP address, the destination address becomes mandatory in the URL:

  • udp://@225.0.0.42:1234 will work: the Receiver will join the multicast address 225.0.0.42 and captures any packet received with destination IP 225.0.0.42 and port 1234.

  • udp://10.0.0.1@225.0.0.42:1234 will work: the only difference with the previous URL is the source IP (the streamer’s IP) is filtered.

  • udp://10.0.0.42@225.0.0.42:1234 with NOT work in the previous example, as no device with the IP 10.0.0.42 is streaming on this multicast address.

  • udp://@:1234 will NOT work: it captures any packet received locally from and to any IP with destination port 1234, but the Receiver needs to actively join the multicast group with the address 225.0.0.42.