//----------------------------------------------------------------------------
//
// TSDuck - The MPEG Transport Stream Toolkit
// Copyright (c) 2005-2025, Thierry Lelegard
// BSD-2-Clause license, see LICENSE.txt file or https://tsduck.io/license
//
// Documentation for options in class ts::SRTSocket.
//
// tags: <none>
//
//----------------------------------------------------------------------------

[.usage]
SRT options

[.opt]
*--backlog* _value_

[.optdoc]
With `--listener`, specify the number of allowed waiting incoming clients.

[.optdoc]
The default is one.

[.opt]
*--bufferapi*

[.optdoc]
When set, this socket uses the Buffer API.
The default is Message API.

[.opt]
*-c* _address:port_ +
*--caller* _address:port_

[.optdoc]
Use SRT in caller (or rendezvous) mode.
The parameter specifies the IP remote address (or host name) and UDP port.

[.optdoc]
If `--listener` is also specified, the SRT socket works in rendezvous mode.

[.opt]
*--conn-timeout* _value_

[.optdoc]
Connect timeout. SRT cannot connect for RTT > 1500 msec (2 handshake exchanges) with the default connect timeout of 3 seconds.
This option applies to the caller and rendezvous connection modes.
The connect timeout is 10 times the value set for the rendezvous mode
(which can be used as a workaround for this connection problem with earlier versions).

[.opt]
*--enforce-encryption*

[.optdoc]
This option enforces that both connection parties have the same passphrase set
(including empty, that is, with no encryption), or the connection is rejected.

[.opt]
*--ffs* _value_

[.optdoc]
Flight Flag Size (maximum number of bytes that can be sent without being acknowledged).

[.opt]
*--final-statistics*

[.optdoc]
Report SRT usage statistics when the SRT socket is closed.

[.optdoc]
This option is implicit with `--statistics-interval`.

[.opt]
*--input-bw* _value_

[.optdoc]
This option is effective only if `SRTO_MAXBW` is set to 0 (relative).

[.optdoc]
It controls the maximum bandwidth together with `SRTO_OHEADBW` option according to the formula: +
`MAXBW = INPUTBW * (100 + OHEADBW) / 100`.

[.optdoc]
When this option is set to 0 (automatic) then the real `INPUTBW` value will be estimated from the rate of the input
(cases when the application calls the `srt_send()` function) during transmission.

[.optdoc]
Recommended: set this option to the predicted bitrate of your live stream and keep default 25% value for `SRTO_OHEADBW`.

[.opt]
*--iptos* _value_

[.optdoc]
IPv4 Type of Service (see `IP_TOS` option for IP) or IPv6 Traffic Class (see `IPV6_TCLASS` of IPv6)
depending on socket address family.

[.optdoc]
Applies to sender only.
Sender: user configurable, default: 0xB8.

[.opt]
*--ipttl* _value_

[.optdoc]
IPv4 Time To Live (see `IP_TTL` option for IP) or IPv6 unicast hops (see `IPV6_UNICAST_HOPS` for IPV6)
depending on socket address family.

[.optdoc]
Applies to sender only, default: 64.

[.opt]
**--json-line**__[='prefix']__

[.optdoc]
With `--statistics-interval` or `--final-statistics`, report the statistics as one single line in JSON format.

[.optdoc]
The optional string parameter specifies a prefix to prepend on the log line before the JSON text
to facilitate the filtering of the appropriate line in the logs.

[.opt]
*--kmpreannounce* _value_

[.optdoc]
The interval (defined in packets) between when a new Stream Encrypting Key (SEK) is sent and when switchover occurs.
This value also applies to the subsequent interval between when switchover occurs and when the old SEK is decommissioned.

[.optdoc]
Note: The allowed range for this value is between 1 and half of the current value of `SRTO_KMREFRESHRATE`.
The minimum value should never be less than the flight window
(i.e. the number of packets that have already left the sender but have not yet arrived at the receiver).

[.opt]
*--kmrefreshrate* _value_

[.optdoc]
The number of packets to be transmitted after which the Stream Encryption Key (SEK), used to encrypt packets, will be switched to the new one.

[.optdoc]
Note that the old and new keys live in parallel for a certain period of time (see `SRTO_KMPREANNOUNCE`) before and after the switchover.

[.opt]
*--latency* _value_

[.optdoc]
This flag sets both `SRTO_RCVLATENCY` and `SRTO_PEERLATENCY` to the same value.

[.optdoc]
Note that prior to version 1.3.0 this is the only flag to set the latency,
however this is effectively equivalent to setting `SRTO_PEERLATENCY`, when the side is sender
(see `SRTO_SENDER`) and `SRTO_RCVLATENCY` when the side is receiver,
and the bidirectional stream sending in version 1.2.0 is not supported.

[.opt]
*--linger* _value_

[.optdoc]
Linger time on close.

[.optdoc]
Recommended value: 0

[.opt]
*-l* _[address:]port_ +
*--listener* _[address:]port_

[.optdoc]
Use SRT in listener (or rendezvous) mode.
The parameter specifies the IP local address and UDP port on which the SRT socket listens.
The address is optional, the port is mandatory.

[.optdoc]
If `--caller` is also specified, the SRT socket works in rendezvous mode.

[.opt]
*--local-interface* _address_

[.optdoc]
In caller mode, use the specified local IP interface for outgoing connections.

[.optdoc]
This option is incompatible with `--listener`.

[.opt]
*--lossmaxttl* _value_

[.optdoc]
The value up to which the Reorder Tolerance may grow.

[.optdoc]
When Reorder Tolerance is > 0, then packet loss report is delayed until that number of packets come in.
Reorder Tolerance increases every time a "belated" packet has come, but it wasn't due to retransmission
(that is, when UDP packets tend to come out of order), with the difference between the latest sequence
and this packet's sequence, and not more than the value of this option.

[.optdoc]
By default it's 0, which means that this mechanism is turned off,
and the loss report is always sent immediately upon experiencing a "gap" in sequences.

[.opt]
*--max-bw* _value_

[.optdoc]
Maximum send bandwidth.

[.optdoc]
Note: This option has a default value of -1.
Although in case when the stream rate is mostly constant, it is recommended to use value 0 here
and shape the bandwidth limit using `SRTO_INPUTBW` and `SRTO_OHEADBW` options.

[.opt]
*--messageapi*

[.optdoc]
Use the Message API.
This is now the default.
Specify `--bufferapi` to use the Buffer API.

[.opt]
*--min-version* _value_

[.optdoc]
The minimum SRT version that is required from the peer.
A connection to a peer that does not satisfy the minimum version requirement will be rejected.

[.opt]
*--mss* _value_

[.optdoc]
Maximum Segment Size.
Used for buffer allocation and rate calculation using packet counter assuming fully filled packets.

[.optdoc]
The smallest MSS between the peers is used.
This is 1500 by default in the overall internet.
This is the maximum size of the UDP packet and can be only decreased,
unless you have some unusual dedicated network settings.

[.optdoc]
Not to be mistaken with the size of the UDP payload or SRT payload.
This size is the size of the IP packet, including the UDP and SRT headers.

[.opt]
*--nakreport* _value_

[.optdoc]
When this option is specified, the receiver will send `UMSG_LOSSREPORT` messages periodically
until the lost packet is retransmitted or intentionally dropped.

[.opt]
*--no-reuse-port*

[.optdoc]
With `--listener`, disable the reuse port socket option.

[.optdoc]
Do not use unless completely necessary.

[.opt]
*--ohead-bw* _value_

[.optdoc]
Recovery bandwidth overhead above input rate (see `SRTO_INPUTBW`).
It is effective only if `SRTO_MAXBW` is set to 0.

[.opt]
*--packet-filter* _value_

[.optdoc]
Set up the packet filter.
The string must match appropriate syntax for packet filter setup.

[.optdoc]
See: https://github.com/Haivision/srt/blob/master/docs/packet-filtering-and-fec.md

[.opt]
*--passphrase* _value_

[.optdoc]
Sets the passphrase for encryption.
This turns encryption on on this side (or turns it off, if empty passphrase is passed).
The passphrase must be 10 to 64 characters long.

[.opt]
*--payload-size* _value_

[.optdoc]
Sets the maximum declared size of a single call to sending function in Live mode.
Use 0 if this value isn't used (which is default in file mode).

[.optdoc]
This value shall not be exceeded for a single data sending instruction in Live mode.

[.opt]
*--pbkeylen* _value_

[.optdoc]
Sender encryption key length, can be 0, 16 (AES-128), 24 (AES-192), 32 (AES-256).

[.opt]
*--peer-idle-timeout* _value_

[.optdoc]
The maximum time in milliseconds to wait until any packet is received from peer since the last such packet reception.
If this time is passed, connection is considered broken on timeout.

[.opt]
*--peer-latency* _value_

[.optdoc]
The latency value (as described in `SRTO_RCVLATENCY`) that is set by the sender side as a minimum value for the receiver.

[.opt]
*--polling-time* _value_

[.optdoc]
Epoll timeout value in milliseconds for non-blocking mode.

[.opt]
*--rcv-latency* _value_

[.optdoc]
The time that should elapse since the moment when the packet was sent and the moment
when it's delivered to the receiver application in the receiving function.

[.opt]
*--rcvbuf* _value_

[.optdoc]
Receive Buffer Size.

[.opt]
*--sndbuf* _value_

[.optdoc]
Send Buffer Size.

[.optdoc]
Warning: configured in bytes, converted in packets, when set, based on MSS value.

[.optdoc]
For desired result, configure MSS first.

[.opt]
*--statistics-interval* _milliseconds_

[.optdoc]
Report SRT usage statistics at regular intervals, in milliseconds.

[.optdoc]
The specified interval is a minimum value, actual reporting can occur only when data are exchanged over the SRT socket.

[.opt]
*--streamid* _value_

[.optdoc]
A string limited to 512 characters that can be set on the socket prior to connecting.
This stream ID will be able to be retrieved by the listener side from the socket that is returned from `srt_accept()`
and was connected by a socket with that set stream ID (so you usually use SET on the socket used for `srt_connect()`
and GET on the socket retrieved from `srt_accept()`).
This string can be used completely free-form, however it's highly recommended to follow the SRT Access Control guidlines.

[.opt]
*--tlpktdrop*

[.optdoc]
Too-late Packet Drop.
When enabled on receiver, it skips missing packets that have not been delivered in time
and delivers the subsequent packets to the application when their time-to-play has come.
It also sends a fake ACK to the sender.
When enabled on sender and enabled on the receiving peer, sender drops the older packets
that have no chance to be delivered in time.
It is automatically enabled in sender if receiver supports it.

[.opt]
*--transtype* _value_

[.optdoc]
Sets the transmission type for the socket, in particular, setting this option sets multiple other
parameters to their default values as required for a particular transmission type.

[.opt]
*--udp-rcvbuf* _value_

[.optdoc]
UDP socket receive buffer size in bytes.

[.opt]
*--udp-sndbuf* _value_

[.optdoc]
UDP socket send buffer size in bytes.
