.. _udp-url:

#####################
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:

.. code-block ::

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

- :dfn:`server_addr`: server address, aka the *source* address of the stream.
- :dfn:`server_port`: server port, aka the *source* port of the stream.
- :dfn:`bind_addr`: binding address, aka the *destination* address of the stream.
- :dfn:`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 (:file:`sample.mp4`) to a receiver device using MPEG-TS format on UDP in unicast:

.. graphviz::

    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 (:file:`sample.mp4`) using MPEG-TS format on UDP in multicast:

.. graphviz::

    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.