//----------------------------------------------------------------------------
//
// 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
//
//----------------------------------------------------------------------------

<<<
=== t2mi

[.cmd-header]
Extract T2-MI (DVB-T2 Modulator Interface) packets

This plugin extracts (or simply logs) T2-MI packets.
T2-MI is the DVB-T2 Modulator Interface.
This is a protocol which encapsulates DVT-T2 modulator commands (including TS packets) into one PID of a transport stream.
See <<ETSI-102-773>> and <<ETSI-302-755>> for more details.

This plugin selects one PID from the input transport stream.
This PID shall contain an encapsulated T2-MI stream.
This plugin extracts the embedded transport stream from one PLP (Physical Layer Pipe) of the original DVB-T2 TS.
By default, the input transport stream is completely replaced with the extracted stream.
Using the option `--output-file`, the extracted encapsulated transport stream is saved in a file and,
in that case, the input transport stream is passed unmodified.

Alternatively, the `t2mi` plugin can simply log all T2-MI packets without replacing the input transport stream.
This is typically useful for debug only.

WARNING: This plugin is currently experimental and has some limitations.
DVB-T2 is complex and this complexity has an impact on the encapsulation of TS packets inside a T2-MI stream.
This plugin may not work with all mode or stream adaptations (see <<ETSI-302-755>>).
If you encounter problems with some T2-MI streams, please report an issue (see <<TSDuck-Issues>>)
and provide a sample transport stream which exhibits the problem.

[.usage]
Usage

[source,shell]
----
$ tsp -P t2mi [options]
----

[.usage]
Options

[.opt]
*-a* +
*--append*

[.optdoc]
With `--output-file`, if the file already exists, append to the end of the file.

[.optdoc]
By default, existing files are overwritten.

[.opt]
*-e* +
*--extract*

[.optdoc]
Extract encapsulated TS packets from one PLP of a T2-MI stream.
The transport stream is completely replaced by the extracted stream.

[.optdoc]
This is the default if neither `--extract` nor `--t2mi-file` nor `--log` nor `--identify` is specified.

[.opt]
*-i* +
*--identify*

[.optdoc]
Identify all T2-MI PID's and PLP's.

[.optdoc]
If `--pid` is specified, only identify PLP's in this PID.
If `--pid` is not specified, identify all PID's carrying T2-MI and their PLP's (require a fully compliant T2-MI signalization).

[.opt]
*-k* +
*--keep*

[.optdoc]
With `--output-file`, keep existing file (abort if the specified file already exists).

[.optdoc]
By default, existing files are overwritten.

[.opt]
*-l* +
*--log*

[.optdoc]
Log all T2-MI packets using one single summary line per packet.
This is typically useful for debug only.

[.optdoc]
If `--log` is specified without `--extract`, the input transport stream is passed unmodified.
If both `--extract` and `--log` are specified,
the T2-MI packets are logged and the encapsulated stream replaces the input stream.

[.opt]
*-o* _filename_ +
*--output-file* _filename_

[.optdoc]
Specify that the extracted transport stream is saved in this file.
In that case, the main transport stream is passed unchanged to the next plugin.

[.opt]
*-p* _value_ +
*--pid* _value_

[.optdoc]
Specify the PID carrying the T2-MI encapsulated stream.
By default, the plugin automatically locates and uses the first component with a _T2MI_descriptor_ in the PMT of its service.

[.opt]
*--plp* _value_

[.optdoc]
Specify the PLP (Physical Layer Pipe) to extract from the T2-MI encapsulation.
By default, use the first PLP which is found.
This option is ignored if `--extract` is not used.

[.optdoc]
To determine which PID's carry T2-MI streams and what are the PLP's inside each stream,
use the command `tsanalyze` or the plugin `analyze`.

[.opt]
*-t* _filename_ +
*--t2mi-file* _filename_

[.optdoc]
Save all complete raw T2-MI packets in the specified binary file.

[.optdoc]
If `--plp` is specified, only save T2-MI packets for that PLP.
Otherwise, save all T2-MI packets from the selected PID.

[.optdoc]
The created binary file contains all T2-MI packets, contiguously, without any encapsulation.
Each T2-MI packet contains enough information to determine its size.
Therefore, it possible to read T2-MI packets one by one.

[.optdoc]
In short, a T2-MI packet is composed of a 6-byte header, a payload, and a 4-byte trailing CRC32.
The size of the payload in bits is stored on 16 bits, starting at byte 4 in the header.
This size is in bits, not bytes.
The size of the payload in bytes is computed from the size in bits, rounded up to the next byte boundary.
The total size of the T2-MI packet is consequently this payload size in bytes, plus 10.

[.optdoc]
See <<ETSI-102-773>> for more details on the format of T2-MI packets.

include::{docdir}/opt/group-common-plugins.adoc[tags=!*]
