[docs] Added and updated description of useful test applications (#2191)

Haivision · Dec 6, 2021 · 545700f · 545700f
1 parent 1d808c1
commit 545700f
Show file tree

Hide file tree

Showing 5 changed files with 142 additions and 52 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -46,12 +46,14 @@
 
 ## Sample Applications
 
-| Document Title                                               |            Folder             | File Name                                         | Description                                                  |
-| :----------------------------------------------------------- | :---------------------------- | :------------------------------------------------ | :----------------------------------------------------------- |
-| [Using the<br /> `srt-live-transmit` App](apps/srt-live-transmit.md) | [apps](apps/)         | [srt-live-transmit.md](apps/srt-live-transmit.md) | A sample application to transmit a live stream from<br />source medium (UDP/SRT/`stdin`) to the target medium<br />(UDP/SRT/`stdout`). |
-| [Using the<br /> `srt-multiplex` App](apps/srt-multiplex.md) |         [apps](apps/)         | [srt-multiplex.md](apps/srt-multiplex.md)         | Description of sample program for sending multiple streams.  |
-| [Using the<br /> `srt-tunnel` App](apps/srt-tunnel.md)       |         [apps](apps/)         | [srt-tunnel.md](apps/srt-tunnel.md)               | A sample application to set up an SRT tunnel for TCP traffic. |
-| <img width=200px height=1px/>                                | <img width=100px height=1px/> | <img width=200px height=1px/>                     | <img width=500px height=1px/>                                |
+| Document Title                                                         |            Folder     | File Name                                           | Description                                                   |
+| :--------------------------------------------------------------------- | :-------------------- | :-------------------------------------------------- | :------------------------------------------------------------ |
+| [Using the<br /> `srt-live-transmit` App](apps/srt-live-transmit.md)   | [apps](apps/)         | [srt-live-transmit.md](apps/srt-live-transmit.md)   | A sample application to transmit a live stream from<br />source medium (UDP/SRT/`stdin`) to the target medium<br />(UDP/SRT/`stdout`). |
+| [Using the<br /> `srt-file-transmit` App](apps/srt-file-transmit.md)   | [apps](apps/)         | [srt-file-transmit.md](apps/srt-file-transmit.md)   | A sample application to transmit a file over SRT              |
+| [Using the<br /> `srt-tunnel` App](apps/srt-tunnel.md)                 | [apps](apps/)         | [srt-tunnel.md](apps/srt-tunnel.md)                 | A sample application to set up an SRT tunnel for TCP traffic. |
+| [Using the<br /> `srt-test-multiplex` App](apps/srt-test-multiplex.md) | [apps](apps/)         | [srt-test-multiplex.md](apps/srt-test-multiplex.md) | Testing application that allows to send multiple streams over one UDP link. |
+| [Using the<br /> `srt-test-relay` App](apps/srt-test-relay.md)         | [apps](apps/)         | [srt-test-relay.md](apps/srt-test-relay.md)         | Testing application for bidirectional stream sending over one connection.   |
+| <img width=200px height=1px/>                                  | <img width=100px height=1px/> | <img width=200px height=1px/>                       | <img width=500px height=1px/>                                      |
 
 ## Miscellaneous
 

diff --git a/docs/apps/srt-file-transmit.md b/docs/apps/srt-file-transmit.md
@@ -0,0 +1,55 @@
+# srt-file-transmit
+
+The `srt-file-transmit` tool is a tool for transmitting files over SRT.
+
+You need:
+
+ - a file to transmit
+ - a destination to store it into
+ - this application run on both sides, one sending, one receiving
+
+## Introduction
+
+The `srt-file-transmit` application will transmit your file over the SRT connection,
+the application on the other side will receive it and store to the desired location.
+Both caller-listener and rendezvous arrangement of the connection are possible
+and in whatever direction.
+
+The `streamid` socket option will be used to pass the filename to the other side
+so that it is either written with this name or matched with the filename internally.
+
+The application the will be sending a file should use the file path as source and
+SRT URI as a destination, and vice versa for receiving.
+
+## Caller mode
+
+If you use sender in caller mode, then the caller SRT URI destination should be
+specified, and the "root name" from the file path will be set to `streamid`.
+This will allow the listener to use it when writing.
+
+If a receiver is used as a caller, then the destination filepath's rootname
+will be also passed as `streamid` so that the listener receiver can pick up the
+file by name.
+
+In caller mode you must specify the full filename path of the received or sent
+file.
+
+## Listener mode
+
+If you use sender in listener mode, then you start it with specifying either the
+full filename path, or only the directory where the file is located; in the latter
+case the filename will be tried from the `streamid` option extracted from the
+connected socket (as set by the other side's caller). If the full filename was
+specified, it must match the rootname extraced from this option, or otherwise
+transmission will not be done.
+
+If you use receiver in listener mode, then you start it with specifying either
+the full filename path, or just the directory. In the latter case the root name
+will be extracted from `streamid` socket option, and this one will be transmitted.
+
+## Usage
+
+```
+srt-file-transmit [options] <input-uri> <output-uri>
+```
+
diff --git a/docs/apps/srt-multiplex.md → docs/apps/srt-test-multiplex.md b/docs/apps/srt-multiplex.md → docs/apps/srt-test-multiplex.md
@@ -1,26 +1,27 @@
-## srt-multiplex
+# srt-test-multiplex
 
-**srt-multiplex** (formerly called "SIPLEX") is a sample program that can send 
-multiple streams in one direction. This tool demonstrates two SRT features:
+**srt-test-multiplex** (formerly called "SIPLEX") is a sample program that can
+send multiple streams in one direction. This tool demonstrates two SRT features:
  - the ability to use a single UDP link (a source and destination pair 
  specified by IP address and port) for multiple SRT connections
  - the use of the `streamid` socket option to identify multiplexed resources
 
-NOTE: due to changes in the common code that can't be properly handled in the
-current form of srt-multiplex, this application is temporarily blocked. Instead
-the `srt-test-multiplex` application was added with the same functionality,
-although it's recommended for testing purposes only.
+NOTE: To make this application compiled, you need the `-DENABLE_TESTING=1`
+cmake option.
 
-#### Usage
+Note also that this application is intended for demonstration only. It can
+simply exit with error message in case of wrong usage or broken connection.
 
-`srt-multiplex <SRT-URI> -i <INPUT-URI1>[id] <INPUT-URI2>[id]...`
 
-  - Multiplexes data from one or more input URIs to transmit as an SRT stream. 
-  The application reads multiple streams (INPUT URIs), each using a separate SRT 
-  connection. All of the traffic from these connections is sent through the 
-  same UDP link.
+## Usage
 
-`srt-multiplex <SRT-URI> -o <OUTPUT-URI1>[id] <OUTPUT-URI2>[id]...`
+`srt-test-multiplex <SRT-URI> -i <INPUT-URI1>[id1] <INPUT-URI2>[id2]...`
+
+  - Reads all given input streams and sends them each one over a separate
+  SRT connection, all using the same remote address and source port (hence
+  using the same UDP link).
+
+`srt-test-multiplex <SRT-URI> -o <OUTPUT-URI1>[id] <OUTPUT-URI2>[id]...`
 
   - Transmits data from a multiplexed SRT stream to the specified output URI(s).
 
@@ -29,41 +30,41 @@ options. When `-i` is specified, the URIs provided are used as input, and will
 be output over the `<SRT URI>` socket. The reverse is true for any output URIs 
 specified by `-o`.
 
-Separate connections will be created for every specified URI, although all will 
-be using the same UDP link. When SRT is in caller mode, the SRT socket created 
-for transmitting data for a given URI will be set to the `streamid` socket option 
-from this URI's `id` parameter. When SRT is in listener mode, the `streamid` 
-option will already be set on the accepted socket, and will be matched with a 
-URI that has the same value in its `id` parameter.
-
-This `streamid` is the SRT socket option (`SRTO_STREAMID` in the API). The idea 
-is that it can be set on a socket used for connecting. When a listener is 
-getting an accepted socket for that connection, the `streamid` socket option 
-can be read from it, with the result that it will be the same as was set on 
-the caller side.
-
-So, in caller mode, for every stream media URI (input or output) there will be
-a separate SRT socket created. This socket will have its `socketid` option 
-set to the value that is given by user as the `id` parameter attached to a 
-particular URI. In listener mode this happens in the opposite direction — the 
-value of the `streamid` option is extracted from the accepted socket, and then 
-matched against all ids specified with the stream media URIs:
+If SRT-URI is caller mode, then for every declared input or output medium a
+separate connection will be made, each one using the same source port (if
+specified, the same will be used for all connections, otherwise the first one
+will be automatically selected and then reused for all next ones) and with the
+`streamid` socket option set to the value extracted from the medium's
+`id` specified parameter:
 ```
 URI1?id=a --> s1(streamid=a).connect(remhost:2000)
 URI2?id=b --> s2(streamid=b).connect(remhost:2000)
 URI3?id=c --> s3(streamid=c).connect(remhost:2000)
 ```
-And on the listener side:
+
+If SRT-URI is listener mode, then it will extract the value from `streamid`
+socket option and every accepted connection will be matched against the `id`
+parameter of the specified input or output medium.
 ```
 (remhost:2000) -> accept --> s(SRT socket) --> in URI array find such that uri.id == s.streamid
 ```
 
-#### Examples
+Note that the rendezvous mode is not supported because you cannot make
+multiple connections over the same UDP link in rendezvous mode.
+
+This `streamid` is the SRT socket option (`SRTO_STREAMID` in the API). The idea 
+is that it can be set on a socket used for connecting. When a listener is 
+getting an accepted socket for that connection, the `streamid` socket option 
+can be read from it, with the result that it will be the same as was set on 
+the caller side.
+
+
+## Examples
 
   - **Sender:**  
-    - `srt-multiplex srt://remhost:2000 -i udp://:5000?id=low udp://:6000?id=high`
+    - `srt-test-multiplex srt://remhost:2000 -i udp://:5000?id=low udp://:6000?id=high`
   - **Receiver:**
-    - `srt-multiplex srt://:2000 -o output-high.ts?id=high output-low.ts?id=low`
+    - `srt-test-multiplex srt://:2000 -o output-high.ts?id=high output-low.ts?id=low`
 
 In this example a Sender is created which will connect to `remhost` port 2000 
 using multiple SRT sockets, all of which will be using the same outgoing port. 
@@ -72,7 +73,7 @@ sockets will reuse that port. Alternatively you can enforce the outgoing port
 using the `port` parameter with the `<SRT URI>`.
 
   - **Sender:**  
-    - `srt-multiplex srt://remhost:2000?port=5555 ...`
+    - `srt-test-multiplex srt://remhost:2000?port=5555 ...`
 
 A separate connection is made for every input resource. An appropriate resource 
 ID will be set to each socket assigned to that resource according to the `id` 
@@ -90,9 +91,9 @@ port=5555 -|  --------- (   multiplexed UDP stream   ) ----------  |- port=2000
            +--                                                   --+
 ```
 When a socket is accepted on the listener side (the Receiver in this example), 
-srt-multiplex will search for the resource ID among the registered resources 
+srt-test-multiplex will search for the resource ID among the registered resources 
 (input/output URIs) and set an ID that matches the one on the caller side. If 
 the resource is not found, the connection is closed immediately. 
 
-The srt-multiplex program works the same way for connections initiated by a 
+The srt-test-multiplex program works the same way for connections initiated by a 
 caller or a listener.
diff --git a/docs/apps/srt-test-relay.md b/docs/apps/srt-test-relay.md
@@ -0,0 +1,34 @@
+# srt-test-relay
+
+**srt-test-relay** is a sample program that can utilize SRT connection for
+bidirectional traffic. Hence beside the SRT connection you can specify both
+input and output media to and from which the traffic will be flipped.
+
+Effectively the specified input will be sent through the SRT connection as
+output, and the input read from the SRT connection will be redirected to
+the given output media.
+
+NOTE: To make this application compiled, you need the `-DENABLE_TESTING=1`
+cmake option.
+
+Note also that this application is intended for demonstration only. It can
+simply exit with error message in case of wrong usage or broken connection.
+
+## Usage
+
+`srt-test-relay <SRT-URI> -i <INPUT URI> -o <OUTPUT URI>`
+
+Establish a connection, send to it the stream received from INPUT URI and
+write the data read from the SRT connection to OUTPUT URI.
+
+`srt-test-relay <SRT-URI> -e -o <OUTPUT URI> <OUTPUT URI2>`
+
+Establish a connection, read the data from the SRT connection, and write
+them back over the SRT connection, and additionally write them as well
+to OUTPUT URI and OUTPUT URI2.
+
+Note that you can also control the single portion of data to be sent
+at once by one sending call by `-c` option and you can use both live
+and file mode for the connection (the latter should be simply enforced
+by `transtype` socket option).
+
diff --git a/docs/apps/srt-tunnel.md b/docs/apps/srt-tunnel.md
@@ -1,8 +1,7 @@
-SRT Tunnel
-==========
+# srt-tunnel
 
-Purpose
--------
+
+## Purpose
 
 SRT Tunnel is a typical tunnelling application, that is, it simply passes the
 transmission from a given endpoint to another endpoint in both directions.
@@ -22,8 +21,7 @@ longer distance, leaving TCP close to the caller and listener locations:
   --> <Tunnel: SRT->TCP> --> <TCP server>
 ```
 
-Usage
------
+## Usage
 
 The `srt-tunnel` command line accepts two argument, beside the options:
 * Listener: the URI at which this tunnel should await connections