TSDuck User’s Guide

Preface

TSDuck is a free and open-source MPEG Transport Stream Toolkit. It contains a set of simple but flexible command-line utilities that run on Linux, Windows, macOS and BSD systems.

Through tsp, the "transport stream processor", many types of analysis and transformation can be applied on live or recorded transport streams. This utility can be extended through "plugins". Existing plugins can be enhanced, and new plugins can be developed using a library of C++ classes.

This document is the user’s guide for TSDuck. It explains the basic concepts of TSDuck and contains reference sections for all commands and plugins.

Structure of this guide:

The chapter 2 describes the data formats (transport stream, binary sections files, XML files).
The chapter 3 describes all TSDuck commands.
The chapter 4 describes all tsp plugins.
The chapter 5 provides some concrete examples of TSDuck usage.
The chapter 7 describes the level of test and support for some hardware devices, mainly DVB receivers and Dektec, HiDes or VATek devices.

The world of Digital Television is built on top of a set of robust standards from various bodies. Understanding these standards and how they interact is essential to use TSDuck. The relationships between these standards are explained in section 2.4.

A bibliography of the main standard documents, as well as other useful links, is provided in the Bibliography at the very end of this guide. Each time it is necessary to refer to a standard document, a link similar to this one is present: [ISO-13818-1]. Just follow the link to have the complete description of the document in the bibliography.

Like any technical field, Digital Television uses a lot of acronyms. A list of them is provided in section F.1.

License

TSDuck is released under the terms of the license which is commonly referred to as "BSD 2-Clause License" or "Simplified BSD License" or "FreeBSD License". This is a liberal license which allows TSDuck to be used in a large number of environments. See the appendix E or [BSD-2C] for more details.

Documentation format

The TSDuck user’s guide is now formatted for HTML. The file tsduck.html is monolithic and self-sufficient, without reference to external images. Therefore, this HTML file can be downloaded, saved, and copied, as long as the license and content are not modified.

The TSDuck user’s guide is now built using asciidoctor, from a set of text files which are maintained alongside the source code, in the same git repository. Up to TSDuck version 3.37, the user’s guide was a Microsoft Word document. The document was distributed and available online as a PDF file only.

PDF files are primarily designed as page-oriented documents for printing. The TSDuck user’s guide is now too large to be printed and a PDF file is no longer necessary because the HTML version proposes the same navigation features as the previous PDF file (expandable table of contents in a left-side panel).

A PDF version tsduck.pdf is still available. However, due to limitations in the PDF generator of asciidoctor, the rendering is sometimes not as good as the HTML document.

Documentation set

The TSDuck documentation set is made of:

TSDuck User’s Guide (also from tsduck.io and in PDF format)
TSDuck Developer’s Guide (also from tsduck.io and in PDF format)
TSDuck Programming Reference

1. Transport Stream Toolkit Overview

1.1. Operating system selection guidelines

TSDuck runs on Linux, Windows, macOS and BSD systems. Here is a brief summary of pros and cons of using TSDuck on the various operating systems.

Linux pros:
- Availability of a powerful shell environment. TSDuck is a lightweight toolkit with elementary tools and plugins which can be combined in an infinite number of ways. The user can obtain even more flexibility when combining them with the bash shell and all standard UNIX utilities (grep, sed, awk, etc.) See some complex examples in section 5.2.
Linux cons:
- When used in a mobile environment, a laptop PC with Linux is required.
- Some DVB tuners are not supported on Linux. Some supported tuners do not work well on Linux. Make sure to get fully supported DVB hardware.
Windows pros:
- Available on all "average user" laptop PC. Useful for transport stream capture and analysis in the field.
Windows cons:
- No or limited shell environment.
- Some limitations in the support of hardware DVB/ATSC/ISDB tuner devices (see section 7.1.2.2, for more details). The development of the DirectShow framework which supports these tuners seems stopped. Recent modulation schemes are not supported.
macOS pros:
- Availability of a powerful shell environment, just another UNIX system, just like Linux. Powerful user-friendly system.
macOS cons:
- Currently no support for hardware tuners and Dektec devices. So, macOS is recommended only when dealing with transport stream files, IP networking or VATek-based modulators.
BSD systems: For aficionados only.

Summary: Use Linux if you can. Use Windows when you do not have Linux (typically a Windows laptop in the field). Use macOS if you have a Mac and do not need DVB or Dektec hardware.

1.2. Developing applications using the TSDuck library

TSDuck is mainly a large C++ library for Digital TV applications. All TSDuck commands and plugins are thin wrappers on top of C++ classes from this library.

This library can be used by third-party applications, outside the TSDuck tools and plugins. To do that, you must install the "TSDuck development environment".

Using the TSDuck library, you can develop independent Digital TV applications or TSDuck plugins. The provided services include low-level features such as manipulating TS packets, intermediate features such as demuxing and packetizing tables and high-level features such as running TS processing pipelines inside your application (which means something like including tsp in your application).

See [TSDuck-Dev] and [TSDuck-Prog] for more details on the TSDuck library. This is a set of doxygen-generated pages with tutorials and reference documentation for all C++ classes in the library.

Some high-level features of the TSDuck library can also be used from Python or Java, typically running TS processing pipelines or manipulating tables and sections inside Python or Java applications. The TSDuck Python and Java bindings are also documented in [TSDuck-Prog].

The following figure illustrates the TSDuck software and how it can interact with third-party applications.

Figure 1. TSDuck software architecture

1.3. Installing TSDuck

The TSDuck installers are available from the "Download" section of the TSDuck Web site (see [TSDuck]). The basic installation provides all TSDuck tools and plugins. The command-line tools are directly accessible from the command prompt.

1.3.1. Windows

On Windows systems, TSDuck can be setup using a binary installer (traditional method) or using the winget package manager (modern method). Winget is now the preferred package manager for open source and third-party products on Windows systems. It is documented and supported by Microsoft. It should be pre-installed on all recent Windows 10 and Windows 11 systems.

The TSDuck installation command is simply winget install tsduck.

If you prefer the traditional method, binary executable installers are provided for 64-bit Windows platforms. Simply run the executable to install TSDuck.

The directory containing the command-line tools is automatically added to the Path. The TSDuck development environment is included in the installer but it is not installed by default. You must select it explicitly. The Java and Python bindings are required to run Java or Python applications. They are also optional and must be selected when needed.

Note that TSDuck is supported for Windows 10 and 11 only. TSDuck may work on older versions such as Windows 7 but without guarantee.

For users without privilege, a so-called "portable package" is provided. This is simply a zip archive file which can be expanded anywhere. The TSDuck commands are located in the bin subdirectory and can be executed from here without any additional setup. It is probably a good idea to add this bin directory in the Path environment variable of the user.

Note: Starting with version 3.34, pre-built 32-bit installers for Windows are no longer provided. However, it is still possible to build them yourself if needed. See the chapter "building and installing TSDuck" section in [TSDuck-Dev].

1.3.2. Linux

Two flavors of pre-built packages are available: .rpm for Fedora or Red Hat systems and .deb for Ubuntu or Debian systems. Currently, packages are available for Intel x64 platforms. Some packages are also available for Arm64.

All tools are in /usr/bin. There is a separate package for the TSDuck development environment.

On Linux distributions with other packaging systems, there is no pre-built binary package for TSDuck. It must be compiled and installed using the make command. See the chapter "building and installing TSDuck" section in [TSDuck-Dev].

1.3.3. macOS

On macOS, TSDuck is installed using the Homebrew packaging and delivery system (see [HomeBrew]).

The TSDuck installation command is simply brew install tsduck.

All tools are accessible from /usr/local/bin (Intel Mac) or /opt/homebrew/bin (Arm Apple Silicon Mac). This is the standard installation structure for Homebrew.

The development environment is always installed with TSDuck using Homebrew.

1.3.4. BSD systems

There is no binary package for TSDuck on BSD systems. It must be compiled and installed using the make command. See the chapter "building and installing TSDuck" section in [TSDuck-Dev].

After installation, all tools are in /usr/local/bin for FreeBSD, OpenBSD and DragonFly BSD. They are in /usr/pkg/bin for NetBSD. These are the standard locations for the installed packages on these systems.

2. Data Formats

2.1. Transport stream

Transport streams shall conform to the MPEG-2 system layer format as defined in ISO/IEC 13818-1 ([ISO-13818-1]).

2.1.1. Live transport streams

Live transport streams can be read by TSDuck from:

Live sources using specialized hardware, cheap DVB tuners or Dektec devices.
UDP/IP using various encapsulations (the encapsulation of TS packets in UDP packets does not matter since TSDuck automatically retrieves the TS packets inside UDP packets and simply ignores everything in between).
HTTP or HTTPS streams without encapsulation (ie. raw TS streams, but not manifest-based formats such as DASH or HLS).
HLS (HTTP Live Streaming) with transport stream segments (not fMP4).
SRT and RIST transport protocols.

See the documentation of the plugins dvb, dektec, ip, http, hls, srt, rist for more details on the reception of live transport streams.

The same plugins can also transmit live streams on Dektec devices, on UDP/IP streams (multicast or unicast), SRT and RIST transport protocols.

HLS output is possible with the help of an independent HTTP server such as Apache. The hls output plugin produces the playlist and segment files. These files can then be served by any HTTP server.

Additionally, output plugins are provided for HiDes and VATek modulator devices. These devices do not have input equivalent and the plugins are output only.

2.1.2. Stored transport streams

Transport streams can be read from and written to binary files, called "TS files".

A standard TS file must contain contiguous 188-byte TS packets without any encapsulation. All TS packets shall start with the MPEG-defined synchronization byte 0x47. Any packet not starting with this synchronization byte is considered invalid and rejected.

Unless specified otherwise, most TSDuck utilities and plugins can read or write several non-standard TS formats. The supported formats are listed in the table below.

The command line option --format name can be used to specify a precise file format.

On input, the file format is automatically detected for each file. But the auto-detection may fail in some cases (for instance when the first timestamp of an M2TS file starts with 0x47 in which case the file would be incorrectly identified as TS). Using the option --format forces a specific format to avoid ambiguities.

On output, the default format is a standard TS file.

The table below lists all possible format names as used with the option --format.

Table 1. Transport stream file formats
Name	Description
`autodetect`	Auto-detection of the file format. This is the default for input files and is usually appropriate. This will always work with TS files but may fail in rare cases with M2TS files. This value is not applicable to output files.
`TS`	Standard transport stream file containing contiguous 188-byte TS packets without any encapsulation. This is the default for output files.
`RS204`	Raw transport stream capture with Reed-Solomon outer FEC. Each standard 188-byte TS packet is followed by a 16-byte trailer (see section 2.1.3). On input, these 16 bytes are kept in the packet metadata. On output, they are rewritten if present or set to 0xFF if they were neither read from input nor set by a `tsp` plugin.
`M2TS`	Blu-ray compatible format. Also found in recording files from some DVR devices. This is the same as TS format, except that each 188-byte TS packet is preceded by a 4-byte time stamp. The 2 most significant bits are copy control indicators and are ignored. The 30 least significant bits represent a time stamp in 27 MHz unit (same unit as PCR values). Note that those time stamps wrap up every 39 seconds approximately since they use only 30 bits while full PCR values use 42 bits.
`duck`	This is a TSDuck proprietary format. It is similar to M2TS except that the header before each TS packet uses 14 bytes and contains all packet metada. Since this is a TSDuck proprietary format, it can be used only in pipes between instances of tsp. The only advantage of this format is to transport complete original time stamps, packet labels and other metadata between instances of `tsp`. Note that 16-byte trailers from `RS204` input files are lost.

When dealing with non-conformant TS files coming from outside, the utility tsresync can be used to extract the TS packets and recreate a pure 188-byte TS file which can be manipulated by the various utilities and plugins from the TSDuck suite.

2.1.3. Support for 204-byte packets

The standard [ISO-13818-1] defines the size of a transport stream packet as 188 bytes. In some cases, 204-byte packets are mentioned. Such a packet is made of a standard 188-byte TS packet, followed by a 16-byte trailer.

The trailer usually contains modulation artefacts for broadcast streams. The interpretation of the 16-byte trailer depends on the modulation.

With DVB modulations, the trailer contains a 16-byte Reed-Solomon outer FEC.
With ISDB-T and ISDB-Tb modulations, the trailer contains 8-byte "ISDB information", followed by a reduced 8-byte Reed-Solomon outer FEC (see [ARIB-B31]).

The Reed-Solomon codes are useless in the context of TSDuck. These codes are automatically generated by modulators and verified by demodulators. Older versions of TSDuck simply dropped the 16-byte trailers of 204-byte packets.

However, in ISDB-T and ISDB-Tb contexts, the trailers become useful. First, analyzing their content exhibits information on the original modulation. Second, it has been reported that the 16-byte trailers shall be propagated in other types of transport, for instance UDP/IP, in order to retrieve the original modulation information later, typically to reinject the stream in a modulator.

Starting with version 3.39, TSDuck extracts the 16-byte trailers, when present, from various input formats. The 16-byte trailer is propagated all along the plugin chain in a tsp command. The trailer is not not part of its packet. It is stored in the packet metadata, which also store the input timestamp and the packet labels (see the documentation of the tsp command). Then, output plugins can reinject the trailer after each packet when necessary.

The following table lists all tsp plugins which manipulate the 16-byte trailer of 204-byte packets. The default behavior is described as well as how to enforce 204-byte packet support. Read the reference documentation section of each plugin for more details.

Table 2. Plugins with 204-byte packet support
Plugin	Type	Default	Enforced
`craft`	input	None.	Option `--rs204`.
`craft`	packet	Unmodified.	Options `--rs204`, `--delete-rs204`.
`dump`	packet	Not displayed.	Options `--rs204`, `--isdb`.
`file`	input	Automatically detected and extracted.	Option `--format RS204`.
`file`	output	Dropped.	Option `--format RS204`.
`file`	packet	Dropped.	Option `--format RS204`.
`fork`	input	Automatically detected and extracted.	Option `--format RS204`.
`fork`	output	Dropped.	Option `--format RS204`.
`fork`	packet	Dropped.	Option `--format RS204`.
`ip`	input	Automatically detected and extracted.	Option `--rs204`.
`ip`	output	Dropped.	Option `--rs204`.
`ip`	packet	Dropped.	Option `--rs204`.
`merge`	packet	Automatically detected and extracted.	Option `--format RS204`.
`pcap`	input	Automatically detected and extracted.	Option `--rs204`.
`rist`	input	Automatically detected and extracted.	Option `--rs204`.
`rist`	output	Dropped.	Option `--rs204`.
`srt`	input	Automatically detected and extracted.	Option `--rs204`.
`srt`	output	Dropped.	Option `--rs204`.

2.2. Bit rates

2.2.1. Interpretation

In the manipulation of transport streams, using "bitrates" is quite common. Unless specified otherwise, all bitrate values are in bits per second, based on 188-byte TS packets.

2.2.2. Representation

Although it is quite common to manipulate bitrates as integral values, there are some cases where the fractional value may have some importance. In broadcast systems, for instance, the bitrate of a transport stream is directly computed from the modulation method and its parameters. And the result is rarely an integral value.

When manipulating multi-megabits-per-second transport streams, a fraction of bit per second is usually negligible, but not always. When a TSDuck tool runs for hours or days, these small fractions can make a difference.

There were several user requests to use more precise representations of bitrates instead of integers. However, requirements from different users are sometimes conflicting. Representing smaller fractions may lead to less accuracy or overflows in intermediate computations. There is no perfect representation for all needs.

As a consequence, TSDuck can be compiled with four different representations of bitrates. The default one provides the best balance so far between precision and performance. For specific needs, TSDuck may be rebuilt with a customized representation.

The four possible representations are listed below:

64-bit floating-point values: This is the default. The precision is preserved, there is almost no intermediate overflow. But the accuracy of computations is not always preserved.
64-bit fixed-point value with 1 decimal digit: The underlying representation is a 64-bit integer type. The performances are correct. The accurancy is better than with integers but with one decimal only. Using more than one decimal is possible but may lead to intermediate overflows.
64-bit integer values: This provides the best performance but no accuracy below one bit per second.
Fractions of two 64-bit integer values: The accuracy of bitrates is formally preserved, especially when computed from modulation parameters. But intermediate overflows are so frequent that this representation is hardly usable beyond basic usages. The performances are also worse than with any other representation.

To verify the bitrate representation of a given build of TSDuck, use the option --version=bitrate with any TSDuck command (see section 3.1.3).

2.2.3. Specifying bitrate in command lines

Many TSDuck tools or plugins get bitrates values from command line options. With all representations of bitrates, it is possible to specify integer values (see section 3.1.2 about specifying integer values in command lines).

Depending on the representation, it is also possible to specify more precise values. Using fixed-point or floating-point values, it is possible to use a decimal point. With fixed-point values, do not provide more decimal digits than the precision. With fractions, it is possible to provide fractional values, for instance 12345/67.

2.2.4. Rebuilding with a different bitrate representation

When compiling TSDuck, the default bitrate representation is a floating-point value. This is also the representation in pre-built binaries.

Rebuilding TSDuck with another representation is possible but must be consistent. All tools and shared libraries must have been built with the same representation. Special symbols and linker dependencies are generated to prevent mixing binaries and libraries with different representations.

To select a different representation of bitrates, simply define the corresponding C++ macro in the build system. See the source file src/libtsduck/base/types/tsBitRate.h for the various macros.

On Linux and macOS, the make command accepts direct parameters, one of the following:

make -j10 BITRATE_FLOAT=1
make -j10 BITRATE_FRACTION=1
make -j10 BITRATE_INTEGER=1
make -j10 BITRATE_FIXED=1 BITRATE_DECIMALS=3

The last command rebuilds with fixed-point and three decimal digits instead of one.

2.3. PSI/SI signalization

TSDuck can manipulate PSI/SI sections and tables outside of transport streams. Sections and tables can be extracted from a transport stream, saved and manipulated in various file formats and injected in other transport streams.

There are two main file formats for PSI/SI: binary section files and XML text files.

These two formats are documented in the next sections. In the general case, tools which extract PSI/SI sections and tables can save in any format and tools which use PSI/SI can read them from any format as well. The utility tstabcomp, the table compiler, can translate between the two formats.

Some key differences between the two formats are:

Binary section files contain collections of individual sections in any order, not necessarily complete tables. XML files contain complete tables only.
Binary section files contain the exact representation, byte by byte, of sections which were extracted from a transport stream. XML files contain a higher-level representation.
Binary section files are not easily modifiable. XML files contain text which can be manually edited using any text editor or XML tool.

There is a third possible format: JSON. This format is formally equivalent to XML. In practice, TSDuck uses XML as internal representation and performs an automated conversion between XML and JSON when necessary. See section 2.7.3 for more details on this conversion process. In this document, the only documented format for tables and descriptors is XML. Use the transformation rules in section 2.7.3 to determine the JSON equivalent.

2.3.1. PSI/SI binary format

A PSI/SI binary file contains one or more sections in a simple binary format. Each section is directly written in the file without any encapsulation or synchronization information. All sections are contiguous in the file.

A binary file must be read from the beginning. The header of each section contains the section length. Using this length information, it is possible to locate the next section, starting right after the current section, and so on down to the end of the file.

2.3.1.1. Creating PSI/SI binary files

PSI/SI binary files can be extracted from live streams or TS files using the command tstables or the plugin tables. The extracted sections are identical, byte by byte, to the transported sections. By default, all sections of a given table are contiguously saved in the binary file, in increasing order of section number. Thus, a complete table can be easily rebuilt by reading sections one by one.

With the option --all-sections, tstables and the plugin tables save all individual sections in their order of reception. In that case, the order and repetition of sections in the binary files are not defined.

PSI/SI binary files can also be created by tstabcomp, the table compiler. Tables are described in XML format (see section 2.3.2) and compiled into a binary file. Since tstabcomp processes complete tables, all sections of a table are also contiguously saved in the binary file, in increasing order of section number, just like tstables by default.

2.3.1.2. Using PSI/SI binary files

The content of binary section files can be viewed using tstabdump. This utility displays the content of each individual section in a human-readable format, regardless of the order of sections in the file.

Binary section files can be used to packetize or inject sections in a stream (command tspacketize and plugin inject). The sections are packetized or injected in their order of appearance in the file.

Finally, binary section files can also be decompiled by tstabcomp to recreate the corresponding XML files from the binary tables. But note that XML files contain complete tables only. This means that tables can be recreated only when their sections are contiguous and in increasing order of section number in the binary file.

2.3.2. PSI/SI XML format

An XML file containing PSI/SI tables for TSDuck uses <tsduck> as root node. The root node contains any number of tables.

Unlike binary files which may contain individual sections, XML files can only contain complete tables. The XML format represents a higher-level view of a table, regardless of the binary implementation in one or more sections.

The following sample XML file contains the definition for simple (and incomplete) PAT and PMT.

<?xml version="1.0" encoding="UTF-8"?>
<tsduck>

  <PAT version="8" transport_stream_id="0x0012" network_PID="0x0010">
    <service service_id="0x0001" program_map_PID="0x1234"/>
    <service service_id="0x0002" program_map_PID="0x0678"/>
  </PAT>

  <PMT version="4" service_id="0x0456" PCR_PID="0x1234">
    <CA_descriptor CA_system_id="0x0777" CA_PID="0x0251"/>
    <component elementary_PID="0x0567" stream_type="0x12">
      <CA_descriptor CA_system_id="0x4444" CA_PID="0x0252"/>
      <ISO_639_language_descriptor>
        <language code="fre" audio_type="0x45"/>
        <language code="deu" audio_type="0x78"/>
      </ISO_639_language_descriptor>
    </component>
  </PMT>

</tsduck>

All XML files shall be encoded in UTF-8 format to allow international character sets in service names or event descriptions for instance. The initial declaration line <?xml version="1.0" encoding="UTF-8"?> is optional but recommended. The complete definition of the XML model can be found in appendix D.

2.4. Compatibility and conflicts between standards

2.4.1. Supported standards

The imbrication of digital TV standards is complex and sometimes problematic for the user who wants to analyze the structure of a transport stream. TSDuck tries to help, either using command line utilities and plugins, and C++ classes for applications which are built on top of the TSDuck library.

The first layer of standard is MPEG [ISO-13818-1]. It is the common root of all regional or international standards in digital TV. The MPEG standard defines the transport stream format, PES, sections and descriptors, the PSI (Program-Specific Information such as PAT, CAT, PMT) and several descriptors. The allocated ranges of tables ids and descriptor tags for MPEG is reserved and never conflicts with other standards.

The DVB-defined table-specific descriptors are exceptions. These descriptors reuse MPEG-defined descriptor tags but are used only in very specific DVB-defined sections where the MPEG-defined descriptors with the same tags are normally not used.

At the second layer, then come the regional standards: DVB (Europe), ATSC (USA), ISDB (Japan). Note that these standards are also used in other parts of the world, in addition to their original regions.

The third layer is made of ANSI/SCTE standards. They are application-level standards such as emergency alerts [SCTE-18], splice signalization for advertisement [SCTE-35] or encryption [SCTE-52]. These standards were originally designed to complement ATSC in the USA but they are sometimes used in conjunction with DVB (especially [SCTE-35]). Parts of the [SCTE-52] standard were also reused in ATIS-defined standards for IP-TV encryption.

DVB and ATSC are independent and mutually exclusive standards. They are never used together in the same transport stream. Most of their table ids and descriptor tags use distinct ranges. It is consequently easy to "guess" the second layer of standard of a transport stream, when one of their specific sections or descriptors is used.

DVB adds a non-ambiguous concept of private descriptors where properly registered entities, operators or industries may define their own privately defined descriptors.

ISDB is the troublemaker which makes things complicated and often requires manual setup using TSDuck command line options or default configuration.

ISDB was originally defined in Japan by ARIB in two flavors, ISDB-T and ISDB-S.
ISDB was later adopted by other countries, starting with Brazil, for terrestrial TV. At this time, the standards were redefined by ABNT (Brazil) under the name ISDB-Tb, to amend features which were too Japanese-specific, creating two branches of ISDB. The two branches diverged until a "harmonization committee" was created to limit the conflicts between the two.
ISDB reuses some parts of DVB but not all. Each iteration of the standard incorporates more DVB descriptors, making it hard to define a stable common subset between DVB and ISDB.
While ISDB reuses sections and descriptors ids and syntax, it sometimes redefines the semantics of some fields such as character sets or time reference.
The semantics of some DVB-defined fields even varies between the variants of ISDB. As an example, time values are defined as UTC in DVB. In Japan, ARIB-defined ISDB redefines the same fields as JST (Japan Standard Time). In South America, ABNT-defined ISDB-Tb redefines it as UTC-3. In African countries, the field is loosely defined as local time, without more details.
ISDB even redefines tiny details of the syntax of some DVB descriptors it reuses. This is the case for the satellite_delivery_system_descriptor for instance.

Therefore, an ISDB stream is sometimes hard to characterize. A transport stream first appears as MPEG-defined when we get the PAT and PMT’s. Then, it looks like DVB when tables such as SDT or TDT are encountered. But later it can appear as ISDB when ISDB-specific tables such as a BIT or CDT are found. The problem is that, as this time, all information such as dates and time in TDT which were previously interpreted in the DVB semantics shall be retroactively reinterpreted in the ISDB semantics (or the multiple possible ISDB semantics in the case of date and time).

TSDuck tries to dynamically guess the type of standard based on the sections and descriptors it progressively discovers in the stream. The list of standards is consequently evolving along the packet processing. It usually starts with "MPEG" and may later evolve to "MPEG, DVB" or "MPEG, ATSC" or "MPEG, DVB, SCTE" or "MPEG, DVB, ISDB".

Because of this progressive discovery of the standards, it is possible that data structures are incorrectly interpreted in the initial phase, before a new standard becomes clear. This is especially critical in the case of ISDB where a transport stream is often initially interpreted as a DVB one.

TSDuck defines a few command-line options which can be used to specify the right standards from the beginning (see section 2.4.2). Some default options are also available in the user’s TSDuck configuration file (see appendix A).

Also note that the appendix D lists the XML format of all tables and descriptors, structured by original standards.

2.4.2. TSDuck options for default standard selection

By default, TSDuck tries to guess the standards which are used in a transport stream. The following options can be used to indicate from the beginning how tables and descriptors should be interpreted. They are briefly repeated in the documentation of all commands to which they apply.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants.

ISDB streams are normally automatically detected from their signalization but there is no way to determine if this is an original ARIB-defined ISDB or an ABNT-defined variant.

--atsc

Assume that the transport stream is an ATSC one.

ATSC streams are normally automatically detected from their signalization. This option is only useful when ATSC-related stuff is found in the TS before the first ATSC-specific table. For instance, when a PMT with ATSC-specific descriptors is found before the first ATSC MGT or VCT.

--brazil

A synonym for --isdb --abnt --time-reference UTC-3.

This is a handy shortcut when working on South American ISDB-Tb transport streams.

--default-pds value

Specify a default DVB-defined Private Data Specifier (PDS). The specified value is used as private data specifier to interpret private descriptors in the absence of preceding private_data_specifier_descriptor.

This option is meaningful only when the signalization is incorrect, when DVB private descriptors appear in tables without a preceding private_data_specifier_descriptor.

This type of invalid signalization is sometimes seen in operator-controlled networks, when operators specify their receivers and do not always care about the standards.

The specified PDS value must be either a 32-bit integer or one of the predefined identifiers from the table below. These identifiers are not case-sensitive.

Table 3. Values for option `--default-pds`
Name	Value	Description
`AOM`	`0x414F4D53`	Alliance for Open Media
`Australia`	`0x00003200`	Free TV Australia
`AVSA`	`0x41565341`	AVS Audio Working Group of China
`AVSV`	`0x41565356`	AVS Video Working Group of China
`BskyB`	`0x00000002`	BskyB British TV operator
`CanalPlus`	`0x000000C0`	Canal+ French TV operator
`cuvv`	`0x63757676`	UHD World Association (UWA)
`EACEM`	`0x00000028`	European Association of Consumer Electronics Manufacturers, now renamed as DigitalEurope
`EICTA`	`0x00000028`	European Information, Communications and Consumer Electronics Technology Industry Associations. Merged with EACEM.
`Eutelsat`	`0x0000055F`	Eutelsat European satellite provider
`Logiways`	`0x000000A2`	Former CAS vendor
`Nagra`	`0x00000009`	Kudelski, Nagravision, CAS vendor
`NorDig`	`0x00000029`	NorDig standard committee (Northern Europe and Ireland)
`OFCOM`	`0x0000233A`	British regulator, formerly ITC
`TPS`	`0x00000010`	Former French TV operator

--ignore-leap-seconds

Do not explicitly include leap seconds in some precise UTC computations where leap seconds are specified as important.

According to Wikipedia, "a leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC), to accommodate the difference between precise time (as measured by atomic clocks) and imprecise observed solar time (known as UT1 and which varies due to irregularities and long-term slowdown in the Earth’s rotation)."

Most computer systems (Linux, macOS, Windows) don’t include leap seconds in their evaluation of UTC time, making their reported UTC times formally incorrect.

Some parts of Digital TV standards specify that leap seconds should be included in some specific computations. By default, TSDuck explicitly adds the leap seconds to the UTC time, as reported by the operating system, when necessary.

This option can be useful to disable the addition of leap seconds in the presence of some non-conformant external equipment which ignore leap seconds.

Currently, this option applies to SCTE 35 splice_schedule() commands only.

This option can also be set from the TSDuck user’s configuration file using option leap.seconds (see section A.2).

--isdb

Assume that the transport stream is an ISDB one.

ISDB streams are normally automatically detected from their signalization. This option is only useful when ISDB-related stuff is found in the TS before the first ISDB-specific table.

--japan

A synonym for --isdb --time-reference JST.

This is a handy shortcut when working on Japanese transport streams.

Beyond ISDB standard, in most applications this option also uses ARIB STD-B24 character sets, uses Japan as default region name for UHF/VHF bands and activates some specificities for Japan such as different semantics for component types.

--philippines

A synonym for --isdb --abnt --time-reference UTC+8. This is a handy shortcut when working on Philippines transport streams.

--time-reference name

Use a non-standard (non-UTC) time reference in DVB-defined TDT/TOT.

This is typically used in ARIB-defined ISDB and ABNT-defined ISDB-Tb standards. These standards reuse DVB-defined SI but change the semantics of the date and time fields, using another time reference.

The specified name can be either UTC (the DVB-defined default), JST (Japan Standard Time) or UTC+|-hh[:mm].

Examples: UTC+9 (same as JST, for ARIB-defined ISDB), UTC-3 (for ABNT-defined ISDB-Tb in Brazil and South America) or UTC+2:30 (if such reference should be used).

--usa

A synonym for --atsc --hf-band-region usa.

This is a handy shortcut when working on North American transport streams.

2.5. Character sets

2.5.1. Standards and character sets

Each standard defines its own way of representing characters in tables and descriptors.

DVB:

Each string is encoded using one single character set. The default character set is a modified version of ISO-6937. For strings which cannot be encoded using ISO-6937, another character set can be selected using a specific leading binary sequence. Since DVB character sets include UTF-8 and UTF-16, all Unicode characters can be eventually represented. See [ETSI-300-468], annex A.

ISDB (ARIB):

Each string is encoded using ARIB STD-B24 (see [ARIB-B24] part 2, chapter 7). A string may alternate between several character sets, typically Kanji, Hiragana, Katakana and alpha-numerical characters. The switching between character sets is performed using control binary sequences. While all Japanese characters can be encoded, many European accented character cannot be represented. There is no way to encode arbitrary Unicode character in ARIB STD-B24.

ISDB (ABNT):

There is no standard ABNT-defined representation of strings. Each country which adopted the ABNT-defined variant of ISDB uses its own representation. For instance, Brazil and other South American countries use ISO-8859-15 while the Philippines use UTF-8. To make things worse, although these character sets are included in the DVB standard, these countries do not use the DVB-defined leading binary sequences which indicate the character set and do not allow switching to other character sets.

ATSC:

Simple strings are encoded in 7-bit ASCII. But most strings are encoded using "multiple string structures" where all Unicode characters can be represented.

XML:

TSDuck-defined XML files use some predefined non-ambiguous character set as indicated in the first directive. This is usually UTF-8. All XML strings are encoded in the same character set. It is the responsibility of TSDuck to convert them in the appropriate character set when serializing tables and descriptors.

With ATSC multiple string structures, there is no ambiguity. They are part of the ATSC tables and descriptors definition and are always encoded using the same standard.

With DVB and ISDB, there are several types of ambiguities:

The ISDB signalization reuses some DVB-defined tables and descriptors, but texts are represented with a non-DVB character encoding. When analyzing or creating such structures, the context (DVB vs. ISDB) must be known to select the appropriate encoding method.
Invalid DVB encoding: According to [ETSI-300-468], the default DVB character set (without explicit character table code) is ISO-6937. However, some bogus signalization may assume that the default character set is different, typically the usual local character table for the region of the operator. The non-standard default character table must be specified using an option.

2.5.2. TSDuck options for character sets

TSDuck commands and plugins which manipulate tables and descriptors have specialized options to indicate the character set to use.

By default, the standard DVB text encoding is used in DVB and ISDB structures.

The following options can be used to alter the behavior of TSDuck. They are briefly repeated in the documentation of all commands to which they apply.

--brazil

A synonym for --default-charset RAW-ISO-8859-15.

All strings are interpreted and generated as ISO-8859-15 without explicit leading table code.

This is a handy shortcut when working on South American ISDB-Tb transport streams.

--default-charset name

When reading binary sections, this option specifies the default character set to use when interpreting strings from tables and descriptors, when there is no initial DVB sequence for character table selection. This overrides the DVB defaults and should be used with invalid streams which omit the initial DVB sequence for character table selection when using a non- default character set.

By default, standard DVB encoding is used.

When generating binary sections (from XML or JSON files for instance), this option specifies the preferred character encoding. The DVB rules are applied : when a non-default DVB character set is selected, the appropriate initial DVB sequence for character table selection is inserted.

By default, TSDuck tries several character sets until one is capable of encoding the string. The order of selection is ISO 6937 (DVB default character set), ISO 8859-15 (convenient with most European languages) and UTF-8. Since UTF-8 can encode everything, the string will always be successfully encoded.

See section 2.5.3 below for a list of available character set names.

--europe

A synonym for --default-charset ISO-8859-15.

Using this option, all DVB strings without explicit leading table code are assumed to use ISO-8859-15 instead of the standard ISO-6937 encoding.

This is a handy shortcut for commonly incorrect DVB signalization on some European satellites. In that signalization, the default character encoding (without leading table code) is ISO-8859-15, the most common encoding for Latin & Western Europe languages. When an explicit leading table code is present, then the corresponding character set is used.

--japan

A synonym for --default-charset ARIB-STD-B24.

This is a handy shortcut when working on Japanese transport streams.

Beyond character sets, in most applications, this option also declares ISDB as default standard, use Japan as default region name for UHF/VHF bands and activates some specificities for Japan such as the use of JST time instead of UTC or different semantics for component types.

--philippines

A synonym for --default-charset RAW-UTF-8.

All strings are interpreted and generated as UTF-8 without explicit leading table code.

This is a handy shortcut when working on Philippines transport streams.

2.5.3. Character set names

The available table names for option --default-charset are:

DVB character sets. The name specifies a standard DVB encoding with a different default character set. Without leading table code, the specified character set is used. But if a leading table code is present, the appropriate character set for that table code is used.
- ISO-6937
- DVB (synonym for ISO-6937)
- ISO-8859-1
- ISO-8859-2
- ISO-8859-3
- ISO-8859-4
- ISO-8859-5
- ISO-8859-6
- ISO-8859-7
- ISO-8859-8
- ISO-8859-9
- ISO-8859-10
- ISO-8859-11
- ISO-8859-13
- ISO-8859-14
- ISO-8859-15
- UTF-8
- UNICODE (in fact UTF-16)
ARIB character sets (Japan):
- ARIB-STD-B24
- ARIB (synonym for ARIB-STD-B24)
Raw character sets. They use the same encoding as their DVB-defined counterpart but without any leading table code. No leading code is interpreted, the specified case is unconditionally used. Using these character sets shall be reserved to specific situations.
- RAW-ISO-6937
- RAW-ISO-8859-1
- RAW-ISO-8859-2
- RAW-ISO-8859-3
- RAW-ISO-8859-4
- RAW-ISO-8859-5
- RAW-ISO-8859-6
- RAW-ISO-8859-7
- RAW-ISO-8859-8
- RAW-ISO-8859-9
- RAW-ISO-8859-10
- RAW-ISO-8859-11
- RAW-ISO-8859-13
- RAW-ISO-8859-14
- RAW-ISO-8859-15
- RAW-UTF-8
- RAW-UNICODE (in fact UTF-16)
Debug character set.
- DUMP

The DUMP character set can be used for debugging. This is not a real character set in the sense that it does not return a Unicode string from a binary representation.

With this character set, decoding binary data returns a string containing a hexadecimal dump of the binary data. It is typically used with tstables or tstabdump to display the exact binary content of strings in tables and descriptors.

Similarly, encoding a string means translating the hexadecimal characters which are contained in that string into binary data. The input string shall contain only hexadecimal digits and spaces. This character set is typically used in XML files to force specific binary contents in text areas of tables and descriptors.

2.6. XML files

2.6.1. Usage of XML files in TSDuck

XML files are used as configuration and data files. They are used as input and output by TSDuck.

All TSDuck XML files use <tsduck> as root node. They shall be encoded in UTF-8 format. The initial declaration line <?xml version="1.0" encoding="UTF-8"?> is optional but recommended.

For TSDuck users, XML files are mostly used to represent PSI/SI tables. This format can be used anywhere tables are used, either on input or output. See section 2.3.2 and appendix D.

XML files are also used as channel files containing lists of TV channels and the tuning characteristics of their respective transport streams. Channel files can be created and updated using the command tsscan. They can be used with the dvb input plugin as "tune to the transport stream of channel ABC, wherever it is". The format of channel files is documented in appendix B.

Finally, XML files are used as configuration files (read-only). They describe the characteristics of UHF and VHF frequency bands by region (tsduck.hfbands.xml, see appendix A, section A.4), the technical specifications of various models of LNB’s for satellite dishes (tsduck.lnbs.xml, see appendix A, section A.3) or resource monitoring configurations (tsduck.monitor.xml, see appendix C). These configuration files are augmented when new information is available. Do not hesitate to request enhancement of these files through the TSDuck issue tracker (see [TSDuck-Issues]).

2.6.2. Inline XML content

In most TSDuck commands, if the name of an input XML file starts with <?xml, it is considered as inline XML content, meaning that the string in the command line is directly the XML content and not a file name.

A similar mechanism exists for output XML files. When an application such as tsp runs for a long time, possibly forever, other applications may want to grab XML output files are soon as they are created. In that case, it is possible to output the whole content of an output XML file as one single line through the message logger (the standard error device by default). If another application filters the tsp standard error, it will get each XML file as one single text line. To facilitate the filtering of actual XML lines, it is possible to specify a marker prefix in the line, typically some easily recognizable pattern. See the description of the option --log-xml-line in the command tstables and the plugin tables.

The output of XML files as one single line is also extremely useful for third party applications which use TSDuck as a library. The C++, Java or Python class named TSProcessor is the equivalent of tsp inside an application. The log messages which are produced by this class can be processed by user-defined classes. These user-defined classes can then filter and process XML outputs as soon as they are produced. Java and Python examples of this features are provided with the TSDuck source code.

2.6.3. XML model files

For each type of XML file, TSDuck uses a model file which describes the expected XML structure of the corresponding data or configuration file. XML model files use the extension .model.xml.

This XML model mechanism can be considered as a minimalist equivalent of XML-Schema, with less features but much more lightweight.

In a model file, all allowed nodes and attributes are present as template. The contents of attributes in this template are comments describing the expected content of the corresponding attribute in real XML files. The values of these attributes in the template are descriptive only; they would be invalid if directly used in input XML files for TSDuck.

Notes on types and formats:

Tags and attributes are not case-sensitive.
Integer values can be represented in decimal or hexadecimal (0x prefix).
Booleans are true or false.
When an attribute or text node is described as hexadecimal content, it must contain an even number of hexadecimal digits. All forms of spaces, including line breaks, are ignored.
Attributes values for date, time and date/time are represented as "YYYY-MM-DD", "hh:mm:ss" and "YYYY-MM-DD hh:mm:ss" respectively. On output, these attributes values are exactly formatted as indicated. In input, to accommodate various conventions, all non-digit characters are considered as valid separators. Therefore, an ISO 8601 date such as "2020-12-01T15:10:21Z" is accepted and interpreted as "2020-12-01 15:10:21".
Some attributes accept symbols in addition to plain numerical values. The names of accepted symbols are listed in the attribute. Example: type="ATSC|DVB-C|DVB-S|DVB-T|ISDB-T"

The command tsxml can be used to test to conformance of XML files to a specific model.

All XML configuration and model files are located in the global TSDuck configuration directory:

Linux : /usr/share/tsduck
macOS : /usr/local/share/tsduck (Intel) or /opt/homebrew/share/tsduck (Arm)
Windows : %TSDUCK%\bin
BSD : /usr/local/share/tsduck or /usr/pkg/share/tsduck (NetBSD)

2.6.4. XML patch files

An XML patch file is a template for transformations to apply on XML files. It is typically used to apply on-the-fly transformations on various PSI/SI tables by plugins such as pat, pmt, bat, cat, sdt, nit when the requested transformations cannot be handled by other options.

This XML patching mechanism can be considered as a minimalist equivalent of XSLT, with less features but much more lightweight.

The command tsxml can be used to test XML patch files on any arbitrary XML file. This is the recommended way to test a patch file on existing XML tables before using it on real transport streams.

2.6.4.1. Structure matching

A patch file is also an XML file. Its structure mimics the structure of XML input files. This is a template which is compared with the input file.

More precisely, each XML element in the patch file (including its parent hierarchy) is compared with equivalent structures in the input file. To have a match, the node name and all parent node names must be identical and all attributes which are specified in the node in the patch file must be present and have the same value in the input file.

It is also possible to match a node according to an attribute having a value different from the specified one (see below).

Advanced structure matching is also possible using conditions, more details on this are provided later.

Consider the following input XML file:

<tsduck>
  <PAT transport_stream_id="1">
    <service service_id="10" program_map_PID="300"/>  <!-- [1] -->
  </PAT>
  <PAT transport_stream_id="2">
    <service service_id="10" program_map_PID="400"/>  <!-- [2] -->
    <service service_id="20" program_map_PID="500"/>  <!-- [3] -->
  </PAT>
</tsduck>

Using the following patch file, the <service> entry matches [1], [2] and [3].

<tsduck>
  <PAT>
    <service>
  </PAT>
</tsduck>

With the following patch file, the <service> entry matches [1] and [2] because of the service_id attribute:

<tsduck>
  <PAT>
    <service service_id="10"/>
  </PAT>
</tsduck>

The next patch file matches only [2] because of the combination of a <PAT> with transport_stream_id 2 and <service> with service_id 10.

<tsduck>
  <PAT transport_stream_id="2">
    <service service_id="10"/>
  </PAT>
</tsduck>

The next example illustrates how to match an attribute having any value except the specified one. In a patch file, when an attribute value starts with a !, the structure matches any node where the specified attribute has a different value (or the attribute is not present).

Thus, the following patch file matches [1] and [3].

<tsduck>
  <PAT transport_stream_id="1">
    <service program_map_PID="!400"/>
  </PAT>
</tsduck>

It could have been tempting to use the operator !=, the syntax program_map_PID!="400" instead of ="!400". However, !="400" is not a valid XML syntax.

2.6.4.2. Special attributes

In the XML structure, special attributes have a name starting with "x-". They have a special interpretation; they are not used for attribute matching.

The following table summarizes the special attributes. They are described in details in the subsequent sections.

Table 4. Special attributes in XML patch files
Attribute	Usage
`x-add-NAME="value"`	Add the attribute `NAME` with the specified value in the matching element.
`x-condition="EXPRESSION"`	The `EXPRESSION` is evaluated based on symbols. If the expression is true, the enclosing element is selected for patching.
`x-define="NAME"`	If the enclosing element is selected, the symbol `NAME` is defined in the global repository.
`x-delete-NAME=""`	Delete the attribute `NAME` in the matching element.
`x-node="add"`	The node with this attribute is added in the matching parent node.
`x-node="delete"`	The matching node is completely removed.
`x-node="delete(NAME)"`	The next parent with name `NAME` above the matching node is completely removed.
`x-undefine="NAME"`	If the enclosing element is selected, the symbol `NAME` is undefined from the global repository.
`x-update-NAME="value"`	Update the attribute `NAME` with the specified value in the matching element.

2.6.4.3. Attribute patching

Once a match is found for a given XML element, it is possible to alter the value of the attributes of this matching element using special attributes.

The name of these special attributes has the form x-command-name. The name part is the name of an attribute to alter in the element.

The possible special attributes are:

x-add-name="value"
Add the attribute name with the specified value in the matching element. If the attribute already existed, it is replaced.
x-update-name="value"
Update the attribute name with the specified value in the matching element, only if the attribute already existed.
x-delete-name=""
Delete the attribute name in the matching element.

2.6.4.4. Element patching

Similarly, the special attribute x-node is used to add or delete an entire XML element.

x-node="delete"
The matching node is completely removed.
x-node="delete(X)"
The next parent with name X above the matching node is completely removed.
x-node="add"
In this case, the matching node is the parent one. The inner node with attribute x-node="add" is added in the matching node (without the special attributes, of course).

2.6.4.5. Examples

Complete examples are available in section 5.1.8.

Smaller examples are shown in the patch file below:

<tsduck>

  <PAT>
    <service service_id="10" x-add-program_map_PID="1000"/>        <!-- [1] -->
    <service service_id="20" x-delete-program_map_PID=""/>         <!-- [2] -->
    <service service_id="30" x-node="delete"/>                     <!-- [3] -->
    <service>
  </PAT>

  <PAT transport_stream_id="100">
    <service service_id="80" program_map_PID="800" x-node="add"/>  <!-- [4] -->
  </PAT>

  <PAT transport_stream_id="200" x-node="delete"/>                 <!-- [5] -->

  <EIT>
    <event>
      <parental_rating_descriptor>
        <country rating="0x07" x-node="delete(EIT)"/>              <!-- [6] -->
      </parental_rating_descriptor>
    </event>
  </EIT>

</tsduck>

In [1], any service with id 10 in any PAT is updated with attribute program_map_PID="1000".

In [2], in any service with id 20 in any PAT, the attribute program_map_PID is deleted (this results in an invalid PAT but this is for the demonstation only).

In [3], any service with id 30 in any PAT is deleted.

In [4], in any PAT with transport_stream_id 100, a new service is added with service_id 80 and program_map_PID 800.

In [5], any PAT with transport_stream_id 200 is deleted.

In [6], an EIT is deleted when it contains an event which contains a parental_rating_descriptor with rating equals to 0x07.

2.6.4.6. Symbols and conditions

So far, we can modify, add or delete XML elements based on their name or the value of some of their attributes. Symbols and conditions allow to alter elements based on conditions which were found in previous other elements.

Symbols are words starting with a letter and made of alphanumerical characters and underscores. Symbol names are case sensitive. Symbols are defined in a global repository. This global repository it maintained all along the processing of a patch file.

Conditions are boolean expressions which are evaluated based on the definition of symbols. A symbol evaluates to true when it is defined and false when it is not. The unary operator ! is the negation. The binary operators && and || form logical expressions. Parentheses can be used to group sub-expressions.

The following special attributes define symbols and conditions.

x-define="NAME"
If the enclosing element is selected, the symbol NAME is defined in the global repository. The definition applies starting with the processing of the enclosing element.
x-undefine="NAME"
If the enclosing element is selected, the symbol NAME is undefined from the global repository. The removal of the symbol applies starting with the processing of the enclosing element.
x-condition="EXPRESSION"
The EXPRESSION is evaluated based on symbols. If the expression is true, the enclosing element is selected for patching. This is, in principle, similar to the attribute matching as described above. If the expression is false, the enclosing element is ignored.

Consider the following example. The idea is to transform any splice_insert command in a splice_information_table into a splice_null command when the splice is an "out of network" command.

<tsduck>
  <splice_information_table x-undefine="NULLIFY">                               <!-- [1] -->
    <splice_insert out_of_network="true" x-define="NULLIFY" x-node="delete"/>   <!-- [2] -->
    <splice_null x-condition="NULLIFY" x-node="add"/>                           <!-- [3] -->
    <splice_avail_descriptor x-condition="NULLIFY" x-node="delete"/>            <!-- [4] -->
  </splice_information_table>
</tsduck>

In [1], the symbol NULLIFY is undefined. This is a cleanup operation in the case it was defined during the processing of a previous table.

In [2], a <splice_insert> element is deleted when its attribute out_of_network= is true. This is a regular attribute matching, as defined earlier. Additionally, the symbol NULLIFY is defined when such an element is found.

In [3], a <splice_null> element is added when NULLIFY is defined. In practice, this means that a <splice_null> element is added only when a previous <splice_insert> was deleted.

In [4], using the same principle, we delete any <splice_avail_descriptor> node when a previous <splice_insert> was deleted. This type of descriptor is typically used with a <splice_insert> command but is useless with a <splice_null> command.

2.7. JSON and "normalized" report formats

TSDuck uses various text formats for report files. They are briefly described here.

2.7.1. "Normalized" reports

The name normalized report refers to a predictable text format which can be easily parsed using scripts to automate operations. This is an alternative output format for tools which otherwise produce reports in a human-friendly readable format which is harder to parse and may change in future versions.

Normalized reports are created by the commands tsanalyze, tscmp, tsdektec and the plugin analyze. Each command documents its own normalized format. A normalized report is usually requested using the option --normalized.

The original idea of normalized reports was a format which could be easily parsed using basic UNIX tools such as grep and sed. See sample usages in section 5.2.8, section 5.2.12, section 5.2.13, section 5.2.14.

2.7.2. JSON files

While the previous normalized reports are easy to parse in scripts, they were created in a time where no widely used standard parser-friendly format existed. Nowadays, most standard parsable files use the JSON format.

The open-source tool named jq (for JSON Query) is available on all operating systems as a standard package and makes the use of JSON files in scripts even easier than grep and sed with normalized report files.

All TSDuck tools and plugins which can produce normalized report can also produce JSON reports using the option --json.

With the option --json-line, the JSON text is output as one single line through the message logger (the standard error device by default). This feature is equivalent to the inline output XML format and can be useful for third party applications. See section 2.6.2 for details and usage examples.

2.7.3. Automated XML-to-JSON conversion

With TSDuck, JSON is used for analysis reports while XML is used to store more complex configuration or data structures such as PSI/SI tables.

An application which needs to analyze the PSI/SI tables which are extracted by some TSDuck command or plugin can simply parse the extracted XML text. Although many tools and libraries exist to parse XML, some developers may prefer to parse JSON rather than XML. In that case, TSDuck provides an automated XML-to-JSON conversion.

2.7.3.1. Conversion rules

There is no standard way to convert XML to JSON. Several tools exist and each of them has its own conversion rules. Because of the differences between XML and JSON, no conversion is perfect, and the result is sometimes not what would have been specified if JSON had been used from the beginning. However, the result is usually good enough for automatic parsing in an application.

The translation rules for the TSDuck automated XML-to-JSON conversion are described below. Note that the default rules can be fine-tuned using an XML model for the input document (see section 2.6.3) and specific command line options (see section 2.7.3.2).

Each XML element is converted to a JSON object {…}.
The name of the XML element is an attribute "#name" inside the object.
All attributes of the XML element are directly mapped into attributes in the JSON object.
- By default, attribute values are converted to JSON strings.
- If the XML model has a value for this attribute and if this model value starts with "int" or "uint" (not case sensitive) and the attribute value can be successfully converted to an integer, then the value becomes a JSON number.
- Similarly, if the XML model value for this attribute starts with "bool" and the value can be successfully converted to a boolean, then the value becomes a JSON literal True or False.
The children nodes inside an element are placed in a JSON array with name "#nodes".
Each XML text node is converted to a JSON string. If the XML model has a value for this text node and if this XML model value starts with "hexa" (not case sensitive), then all spaces are collapsed inside the string.
XML declarations, comments and unknown nodes are dropped.

The introduction of the two artificial attributes "#name" and "#nodes" was necessary because of the differences between XML and JSON. It could have been tempting to use the XML element name as JSON attribute name and the rest of the XML element (attributes and children nodes inside a JSON object) as JSON attribute value. However, while an XML element may contain several children elements with the same name, a JSON object cannot have several attributes with the same name. Thus, the XML element name had to be pushed inside the JSON element, not as its name, outside of the object.

Sample XML source:

<PAT version="12" current="true" transport_stream_id="0x0438" network_PID="0x0010">
  <service service_id="0x2261" program_map_PID="0x0064"/>
  <service service_id="0x2262" program_map_PID="0x00C8"/>
</PAT>

Converted JSON:

{
  "#name": "PAT",
  "current": true,
  "network_pid": 16,
  "transport_stream_id": 1080,
  "version": 12,
  "#nodes": [
    {
      "#name": "service",
      "program_map_pid": 100,
      "service_id": 8801
    },
    {
      "#name": "service",
      "program_map_pid": 200,
      "service_id": 8802
    }
  ]
}

The command tsxml can be used to test the JSON conversion of any arbitrary XML file.

2.7.3.2. TSDuck options for automated XML-to-JSON conversion

The following command line options are used in various TSDuck commands and plugins to fine-tune the automated XML-to-JSON conversion.

--x2j-collapse-text

When converting all XML text nodes into JSON strings, remove leading and trailing spaces. Also replace all other sequences of space characters (including line breaks) with one single space.

By default, text nodes are collapsed only when there is an XML model which identifies the text node as containing hexadecimal content.

--x2j-enforce-boolean

When an attribute in an element contains a boolean value (ie. the string "true" or "false") but there is no XML model file to tell if this is really a boolean, force the creation of a JSON literal True or False.

By default, when there is no XML model, all element attributes are converted as JSON strings.

--x2j-enforce-integer

When an attribute in an element contains an integer value but there is no XML model file to tell if this is really an integer, force the creation of a JSON number.

By default, when there is no XML model, all element attributes are converted as JSON strings.

--x2j-include-root

Keep the root of the XML document as a JSON object.

By default, the JSON document is made of a JSON array containing all JSON objects resulting from the conversion of all XML elements under the root.

Usually, in an XML file, there is one root element without attributes. The root of all TSDuck XML files is a simple <tsduck> element. This single root XML element is required by the XML syntax but usually carries no useful information. This is why it is removed by default in the XML-to-JSON conversion.

--x2j-trim-text

When converting all XML text nodes into JSON strings, remove leading and trailing spaces.

By default, text nodes are trimmed only when there is an XML model which identifies the text node as containing hexadecimal content.

3. Transport Stream Utilities

The TSDuck transport stream toolkit provides several command-line utilities. The main one is tsp, the transport stream processor. The other utilities are small tools which work on transport stream files.

With a few exceptions, the transport stream files are continuous streams of 188-byte TS packets. These files can also be pipes. With the help of tsp and its input and output plugins, the TS packets can be piped from and to various devices and protocols (files, DVB-ASI, DVB-S, DVB-C, DVB-T, multicast IP, etc.)

The following table lists all transport stream utilities:

Table 5. TSDuck utilities
Command	Description
`tsanalyze`	Analyze a TS file and display various information about the transport stream and each individual service and PID.
`tsbitrate`	Evaluate the original bitrate of a TS based on the analysis of the PCR’s and the number of packets between them.
`tscharset`	Test tool for DVB and ARIB character sets.
`tscmp`	Compare the binary content of two TS files.
`tsconfig`	Configuration options to build applications (developers only).
`tscrc32`	Compute MPEG-style CRC32 values.
`tsdate`	Display the date & time information (TDT & TOT) from a TS file.
`tsdektec`	Control a Dektec device.
`tsdump`	Dump the content of a TS file.
`tsecmg`	DVB SimulCrypt-compliant ECMG stub for system integration and debug.
`tseit`	Manipulate EIT’s using commands and scripts.
`tsemmg`	DVB SimulCrypt-compliant EMMG stub for system integration and debug.
`tsfclean`	Cleanup the structure and boundaries of a TS file.
`tsfixcc`	Fix continuity counters in a TS file.
`tsftrunc`	Truncate a TS file, removing extraneous bytes (last incomplete TS packet) or truncating after a specified TS packet.
`tsfuzz`	Introduce random errors in transport stream files.
`tsgenecm`	Generate one ECM using any DVB SimulCrypt compliant ECMG.
`tshides`	List HiDes modulator devices.
`tslatencymonitor`	Monitor latency between two TS input sources.
`tslsdvb`	List DVB receiver devices.
`tsp`	General-purpose TS processor: receive a TS from a user-specified input plugin, apply MPEG packet processing through several user-specified packet processor plugins and send the processed stream to a user-specified output plugin.
`tspacketize`	Packetize PSI/SI tables in a transport stream PID.
`tspcap`	Analyze pcap and pcap-ng files.
`tspcontrol`	Send control commands to a running `tsp`.
`tspsi`	Display the PSI (PAT, CAT, NIT, PMT, SDT) from a TS file.
`tsresync`	Resynchronize a captured TS file: locate start of first packet, resynchronize to next packet after holes, convert to 188-byte packets (if captured with 204-byte packets).
`tsscan`	Scan frequencies in a DVB network.
`tssmartcard`	List or reset smart-card reader devices.
`tsstuff`	Add stuffing to a TS file to reach a target bitrate.
`tsswitch`	Transport stream input source switch using remote control.
`tstabcomp`	PSI / SI table compiler from / to XML files.
`tstabdump`	Dump binary table files, as previously saved by `tstables`.
`tstables`	Collect specified PSI/SI tables from a TS file. Either display them or save them in binary files.
`tsterinfo`	Compute or retrieve various DVB-T (terrestrial) information.
`tstestecmg`	Test a DVB SimulCrypt compliant ECMG with an artificial load.
`tsvatek`	List VATek-based modulator devices.
`tsversion`	Check version, download and upgrade TSDuck.
`tsxml`	Test tool for TSDuck XML files manipulation.

3.1. Command line syntax

3.1.1. Command line options

All utilities are simple command-line tools. They accept options and parameters. The syntax of options follows the GNU getopt_long(3) conventions. See the corresponding Linux manual page for details.

In short, this means that all options have a long name preceded by a double dash and optionally a short name (one dash, one letter). Long options can be abbreviated if there is no ambiguity.

Although this syntax is inspired by Linux and the GNU utilities, the same syntax is used on TSDuck for Windows.

As an example, consider a utility which accepts the two options --verbose (short name -v) and --version (no short name). Then, the verbose mode can be equally triggered by -v, --verbose, --verb but not --ver since there is an ambiguity with --version.

3.1.2. Integer values in command line options

When an option or parameter is documented to require an integer value (PID, identifier, etc.), this value can be uniformly specified in decimal or hexadecimal format with the 0x prefix.

In decimal values, the commas which are used as separators for groups of thousands are ignored. Most commands display large values with separators in order to improve the readability. Therefore, these values can be simply copied / pasted in subsequent command lines.

Example: The following options are equivalent:

--count 3,100,456
--count 3100456
--count 0x002F4F28

When the same option is allowed to be specified several times in one command, it is possible to use ranges of integer values (two values, separated with a dash) instead of specifying all values individually.

Example: The following sets of options are equivalent:

--pid 0 --pid 0x20 --pid 0x21 --pid 0x22 --pid 0x23 --pid 0x24 --pid 0x25 --pid 0x40
--pid 0 --pid 0x20-0x25 --pid 0x40

3.1.3. Predefined common options

All commands accept the following common options:

--debug[=N]

Produce verbose debug output. Specify an optional debug level N. Do not use this option in normal operation.

Without this option, no debug output is produced. When the option is specified but not the level N, the default debug level is 1, that is to say a reasonable amount of information. The higher the debug level is, the more output is produced.

The amount of debug information depends on the command. Some commands do not generate any debug information.

--help

The option displays the syntax of the command and exits.

If either the standard output or the standard error is a terminal, the help text is "paged" through a system utility such as less or more, whichever is available. The environment variable PAGER can be used to specify an alternate pager command with its parameters (see section 3.1.4).

To redirect the help text to a file, you must redirect both the standard output and standard error. Otherwise, since at least one of the two is a terminal, the pager will be used. Example: tsp --help &>help.txt

All tsp plugins also accept the option --help which provides help on this specific plugin.

--verbose

Display verbose information.

--version[=name]

The option displays the TSDuck version and exits.

The optional name indicates which type or format of version to display. The default is long. Other values are described in the table below.

Table 6. Values for option `--version`
Name	Description
`acceleration`	Availability of accelerated instructions for CRC32, AES, etc.
`all`	All information.
`bitrate`	Representation of bitrate values in computations. Using compilation options, bitrates can be represented as fixed-point values, floating-point values, integer values or integer fractions. See section 2.2 for more details.
`compiler`	Compiler name and version.
`crypto`	Version of the cryptographic library.
`date`	Build date.
`dektec`	Version of the Dektec drivers and DTAPI library.
`http`	Version of the HTTP/HTTPS library.
`integer`	TSDuck version as one integer value which can be used in scripts to test against minimum required versions. Example: "32802466".
`long`	TSDuck version in long string format. This is the default.
`nsis`	TSDuck version in NSIS directive format (legacy, no longer used).
`rist`	Version of the RIST library.
`short`	TSDuck version is short format. Example: "3.28-2466".
`srt`	Version of the SRT library.
`system`	Description of the running system.
`vatek`	Version of the VATek library (for VATek-based modulators).

Example:

$ tsp --version=all
tsp: TSDuck - The MPEG Transport Stream Toolkit - version 3.28-2466
Built Aug 10 2021 - 23:09:27
Using GCC 10.3.0, C++ std 2011.03
System: Ubuntu (Ubuntu 21.04), on Intel x86-64, 64-bit, little-endian, page size:
4096 bytes
Bitrate: 64-bit fixed-point with 1 decimals
Web library: libcurl: 7.74.0, ssl: OpenSSL/1.1.1j, libz: 1.2.11
SRT library: libsrt version 1.4.2
Dektec: DTAPI: 5.45.0.172

Some commands which produce a very verbose output are automatically redirected to a pager command such as less or more, whichever is available. The redirection is performed only when the standard output is a terminal.

The environment variable PAGER can be used to specify an alternate pager command with its parameters.

The TSDuck commands which can send their output to a pager always define the --no-pager option to disable the redirection even when the standard output is a terminal.

3.1.5. Partial command line redirection from a file

In any TSDuck command, it is possible to read some or all options and parameter from a file. The syntax is @filename where filename is a text file containing options and parameters.

In the text file, each line must contain exactly one item (option name, option value or parameter).

Sample command:

$ tsp -v @dvb.txt -P until --seconds 20 -P analyze -o out.txt -O drop

The file dvb.txt contains a list of command line items, one per line. The content of the file dvb.txt exactly replaces the expression @dvb.txt.

Sample content of this file:

-I
dvb
--frequency
12,169,000,000
--symbol-rate
27,500,000
--fec-inner
3/4
--polarity
horizontal
--delivery-system
DVB-S2
--modulation
8-PSK

Note that each line contains exactly one command line item. Spaces or special characters are not filtered or interpreted. Using that kind of command can be useful in several situations:

When a custom application generates long and complicated TSDuck commands.
When the options or parameters contain special characters, spaces or any other sequence which must be properly escaped with some shells, possibly differently between shells or operating systems.

Command line parameter redirections can be nested. When one line of such a text file contains a pattern @filename, the second file is inserted here.

Finally, if a parameter really starts with a @ character (which can be possible in a service or device name for instance), use a double @@ to indicate that this is a literal @ character and not a redirection.

Consider the following command:

$ tsp -v @dvb.txt -P zap @@home -O drop

This command reads parameters from the file dvb.txt to find the tuning options and extracts the service named @home (with one @). The double @ has been used to indicate that this is a literal @.

And since redirections can be nested, the initial @@ escape sequence can also be used inside text files containing parameters.

3.1.6. Default options from the TSDuck configuration file

It is possible to specify default command line options or alternate options in a global configuration file. This configuration file is specific per user.

See appendix A for a complete reference of the TSDuck configuration file.

3.1.7. Bash command line completion

For bash users, when the bash-completion package is installed, specific completion scripts are added for TSDuck. Plugin names, command and plugin options, predefined enumeration values for options are automatically completed.

On Linux, the completions are automatically defined.

On macOS with Homebrew, there is no TSDuck-specific setup but the Homebrew-defined bash completions, as a whole, must have been previously enabled. Add the following line to your .bashrc file:

[[ -e $(brew --prefix)/etc/profile.d/bash_completion.sh ]] && \
    source $(brew --prefix)/etc/profile.d/bash_completion.sh

On Windows with Cygwin or Msys, add the following TSDuck-specific line to your .bashrc file:

source "$TSDUCK/setup/tsduck-completion.bash"

The rest of this chapter documents all TSDuck utilities, in alphabetical order.

3.2. tsanalyze

Transport stream analysis

This utility analyzes a transport stream. It reports either a full analysis of the transport stream, services and PID’s (either in human readable format or normalized format for automatic analysis) or selected individual information.

The output can include full synthetic analysis (options --*-analysis), full normalized output (options --normalized and --json) or a simple list of values on one line (options --*-list). The second and third type of options are useful to write automated scripts.

If output control options are specified, only the selected outputs are produced. If no such option is given, the default is:

$ tsanalyze --ts-analysis --service-analysis --pid-analysis --table-analysis

See also the plugin analyze for tsp for the equivalent tool in the context of tsp. This plugin analyzes the stream at a specific point in a TS processing pipeline.

Usage

$ tsanalyze [options] [input-file]

Input file

MPEG transport stream, either a capture file or a pipe from a live stream (see option --format for binary formats).

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

General purpose options

-b value
--bitrate value

Specifies the bitrate of the transport stream in bits/second (based on 188-byte packets). By default, the bitrate is evaluated using the PCR in the transport stream. If no bitrate can be determined (no user-specified value, no PCR), the analysis will not report the bitrates of the individual services and PID’s.

See section 2.2 for more details on the representation of bitrates.

--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

--no-pager

Do not send output through a pager process. By default, if the output device is a terminal, the output is paged. See section 3.1.4 for more details.

Analysis control options

These options are identical in the command tsanalyze and the tsp plugin analyze.

--suspect-max-consecutive value

Specifies the maximum number of consecutive suspect packets. The default value is one. If set to zero, the suspect packet detection is disabled.

Suspect packets are TS packets which are technically correct but which may be suspected of being incorrect, resulting in analysis errors. Typically, in the middle of a suite of packets with un-correctable binary errors, one packet may appear to have no such error while it has some errors in fact. To avoid adding this type of packets in the analysis, a packet is declared as suspect (and consequently ignored in the analysis) when:

its PID is unknown (no other packet was found in this PID)
it immediately follows a certain amount of packet containing errors (see option --suspect-min-error-count)
it immediately follows no more than the specified number consecutive suspect packets.

--suspect-min-error-count value

Specifies the minimum number of consecutive packets with errors before starting suspect packet detection. See also option --suspect-max-consecutive.

The default value is one. If set to zero, the suspect packet detection is disabled.

Output control options

These options are identical in the command tsanalyze and the tsp plugin analyze.

--deterministic

Enforce a deterministic and reproduceable output. Do not output non-reproduceable information such as system time (useful for automated tests).

--error-analysis

Report analysis about detected errors.

--global-pid-list

Report the list of all global PID’s, that is to say PID’s which are not referenced by a specific service but are standard DVB PSI/SI PID’s or are referenced by them. This include, for instance, PID’s of the PAT, EMM’s, EIT’s, stuffing, etc.

--normalized

Complete report about the transport stream, services, PID’s and tables in the old normalized output format. This type of output is useful for automatic analysis in scripts.

--pes-pid-list

Report the list of all PID’s which are declared as carrying PES packets (audio, video, subtitles, etc).

--pid-analysis

Report analysis for each PID.

--pid-list

Report the list of all PID’s.

--prefix 'string'

For one-line displays (options --*-list), prepend the specified string to all values. For instance, options --global --prefix -p outputs something like -p 0 -p 1 -p 16, which is an acceptable option list for the tsp plugin filter.

--service-analysis

Report analysis for each service.

--service-list

Report the list of all service ids.

--service-pid-list value

Report the list of all PID’s which are referenced by the specified service id.

--table-analysis

Report analysis for each table.

--title 'string'

Display the specified string as title header.

--ts-analysis

Report global transport stream analysis.

--unreferenced-pid-list

Report the list of all unreferenced PID’s, that is to say PID’s which are neither referenced by a service nor known as or referenced by the standard DVB PSI/SI.

-w
--wide-display

Use a wider grid display with more information on each line.

JSON output options

--json

Produce a report in JSON output format. Useful for automatic analysis.

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

By default, a new TCP connection is established each time a JSON message is produced (see also option --json-tcp-keep). Be aware that a complete TCP connection cycle may introduce some latency in the processing. If latency is an issue, consider using --json-udp.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

With --json-udp, specifies the TTL (Time-To-Live) socket option. The actual option is either "Unicast TTL" or "Multicast TTL", depending on the destination address. Remember that the default Multicast TTL is 1 on most systems.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

A synonym for --isdb --abnt --default-charset RAW-ISO-8859-15 --time-reference UTC-3 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--default-pds value

Default DVB-defined private data specifier (PDS). See section 2.4.2 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--isdb

Assume that the transport stream is an ISDB one. ISDB streams are normally automatically detected from their signalization. This option is only useful when ISDB-related stuff are found in the TS before the first ISDB-specific table. See section 2.4.2 for more details.

--japan

A synonym for --isdb --default-charset ARIB-STD-B24 --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --isdb --abnt --default-charset RAW-UTF-8 --time-reference UTC+8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

Normalized output format

In normalized output, each line describes one object (service, PID, table, etc). The format of each line is:

type:name[=value]:...

The type identifies the kind of object which is described by the line. The name identifies a characteristics for the object with an optional value. There is no space characters. All integer values are in decimal format.

The normalized syntax can be used to search for specific objects with specific characteristics. It is specially designed to extract values using standard UNIX tools such as sed and grep.

Example: The following sample command extracts the list of EMM PID’s for the SafeAccess CAS. The object type is pid (at the beginning of line) and the two selected characteristics are emm (no value) and cas with SafeAccess DVB-assigned CA_system_id value (0x4ADC, which is 19164 in decimal).

$ tsanalyze --normalize ... | \
    grep '^pid:' | grep ':emm:' | grep ':cas=19164:' | \
    sed -e 's/.*:pid=//' -e 's/:.*//'

Other more complex examples of automated scripts are available in chapter 5.

Obsolescence: Note that this format was designed in the early times of TSDuck. Nowadays, more modern formats such as JSON are more appropriate. The option --json can be used instead of --normalized to produce a JSON report. Such an output is easily manipulated and explored using the open source tool jq.

3.3. tsbitrate

Bitrate evaluation from PCR

This utility evaluates the original bitrate of a transport stream based on an analysis of the PCR’s (Program Clock Reference timestamps) and the interval between them. This is especially useful for captured files where the transmission bitrate information is lost.

Usage

$ tsbitrate [options] [input-file]

Input file

MPEG transport stream, either a capture file or a pipe from a live stream (see option --format for binary formats).

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Options

-a
--all

Analyze all packets in the input file. By default, stop analysis when enough PCR information has been collected.

-d
--dts

Use DTS (Decoding Time Stamps) from video PID’s instead of PCR (Program Clock Reference) from the transport layer.

--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

-f
--full

Full analysis. The file is entirely analyzed (as with --all) and the final report includes a complete per PID bitrate analysis.

-i
--ignore-errors

Ignore transport stream errors such as discontinuities. When errors are not ignored (the default), the bitrate of the original stream (before corruptions) is evaluated. When errors are ignored, the bitrate of the received stream is evaluated, missing packets being considered as non-existent.

--min-pcr value

Stop analysis when that number of PCR’s are read from the required minimum number of PID’s (default: stop after 64 PCR’s on 1 PID).

--min-pid value

Minimum number of PID to get PCR’s from (default: stop after 64 PCR’s on 1 PID).

-v
--value-only

Display only the bitrate value, in bits/seconds, based on 188-byte packets. Useful to reuse the value in command lines.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.4. tscharset

Test tool for DVB and ARIB character sets

This utility performs manual string encoding and decoding using various DVB and ARIB character sets. It can be used to evaluate the validity of conversions.

By default, the converted data is displayed on one line. With the --verbose option, more details are displayed such as the string in UTF-8 or UTF-16 format.

Usage

$ tscharset [options]

Options

-c
--c-style

Output binary data in C/C++ syntax, using 0x prefix. The result can be easily copied into C/C++ source code.

-d hexa-digits
--decode hexa-digits

Decode the specified binary data according to the default character set. The encoded data shall be represented as binary digits. Spaces are ignored.

-e "string"
--encode "string"

Encode the specified string according to the default character set. See also options --from-utf-8 and --from-utf-16.

-6 --from-utf-16

With --encode, specify that the parameter value is a suite of binary digits representing the string in UTF-16 format. There must be an even number of bytes.

-8 --from-utf-8

With --encode, specify that the parameter value is a suite of binary digits representing the string in UTF-8 format.

-l
--list-charsets

List all known character set names.

-o file-name
--output file-name

Output file name. By default, use standard output.

--to-utf-16

With --decode, display an hexadecimal representation of the decoded string in UTF-16 format.

With --verbose, this option is redundant because the string is already displayed in plain form and in UTF-16 representation.

--to-utf-8

With --decode, display an hexadecimal representation of the decoded string in UTF-8 format.

With --verbose, use UTF-8 instead of UTF-16 for the alternate representation of the string.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --default-charset RAW-ISO-8859-15 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--japan

A synonym for --default-charset ARIB-STD-B24 . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --default-charset RAW-UTF-8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.5. tscmp

Transport stream files comparison

This utility compares the binary content of two transport stream files. Selected fields may be omitted in the comparison to allow comparing files which went through different PID remapping or resynchronization process.

Usage

$ tscmp [options] filename-1 filename-2

Input files

MPEG transport stream files to be compared (see option --format for binary formats). If a file name is an empty string or a dash (-), the standard input is used.

Options

--buffered-packets value

Specifies the files input buffer size in TS packets. This is used with --search-reorder to look for reordered packets. Packets which are not found within that range in the other file are considered missing.

The default is 10,000 TS packets.

-b value
--byte-offset value

Start reading the files at the specified byte offset. The default is zero.

--cc-ignore

Ignore continuity counters when comparing packets. Useful if one file has been resynchronized.

-c
--continue

Continue the comparison up to the end of files. By default, stop after the first differing packet.

-d
--dump

Dump the content of all differing packets. Also separately dump the differing area within the packets.

--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

By default, the format of each input file is automatically detected and can be different from one file to another. When the option --format is specified, all input files must have the same format.

-m count
--min-reorder count

With --search-reorder, this is the minimum number of consecutive packets to consider in reordered sequences of packets. This is used to avoid random isolated packets or small sets of packet, such as null packets, to be considered as a reordered sequence.

The default is 7 TS packets.

-n
--normalized

Report in a normalized output format. Useful for automatic analysis.

-p value
--packet-offset value

Start reading the files at the specified TS packet. The default is zero.

--payload-only

Compare only the payload of the packets, ignore header and adaptation field.

--pcr-ignore

Ignore PCR and OPCR when comparing packets. Useful if one file has been resynchronized.

--pid-ignore

Ignore PID value when comparing packets. Useful if one file has gone through a remapping process.

-q
--quiet

Do not output any message. The process simply terminates with a success status if the files are identical and a failure status if they differ.

-s
--search-reorder

Search missing or reordered packets.

By default, packets are compared one by one without looking for equivalent packets somewhere else.

See also --threshold-diff and --buffered-packets.

-t value
--threshold-diff value

When used with --search-reorder, this value specifies the maximum number of differing bytes in packets to declare them equal. When two packets have more differing bytes than this threshold, the packets are reported as different and the first file is read ahead. The default is zero, which means that two packets must be strictly identical to declare them equal.

If you find this explanation unclear, try it with a second file which contains both missing and corrupted packets.

JSON output options

-j
--json

Produce a report in JSON output format. Useful for automatic analysis.

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.6. tsconfig

Configuration options to build applications (developers only)

This command is installed on UNIX systems (Linux, macOS, BSD) only.

For developers, it generates the various build options for the current operating system and is used by developers to build their applications.

Without any option, tsconfig displays all configuration options. With one or more specific options, it outputs command line options for the compiler, the linker or installation commands.

Usage

$ tsconfig [options]

Options

--bin

Display the directory for TSDuck executables.

--cflags

Display the pre-processor and compiler flags. In a makefile, this is used in CFLAGS and CXXFLAGS.

--config

Display the directory for TSDuck configuration files.

TSDuck extensions should store their .xml or .names files there.

--help

Display command help text.

--include

Display the include directory.

--install-dvb-firmware

Linux only: download and install additional DVB firmware.

Depending on the distro, some firmware files are installed with standard packages such as linux-firmware. Some USB tuners need additional firmware from non-standard sources. Using this option, tsconfig downloads and installs some known additional firmware files for DVB tuners.

Must be root to use that option.

--java

Display the jar file for TSDuck Java bindings, to be added in CLASSPATH.

--lib

Display the directory for TSDuck dynamic libraries (except plugins).

TSDuck extensions should store their tslibext_xxx.so libraries there (.dylib on macOS, .dll on Windows).

--libs

Display the library linking flags. In a makefile, this is used in LDLIBS.

--nostdcpp

When present before --cflags, no C++ standard level is imposed in the compilation flags.

By default, the command tsconfig --cflags forces C++17 as level of C++ language standard. If your application requires a more recent level, define the environment variable TS_NOSTDCPP to any non-empty value. This disables the C++ standard option in tsconfig. The application shall then define its own C++ standard in its command line. This user-specified C++ standard cannot be lower than C++17.

Alternatively, the command tsconfig --nostdcpp --cflags can be used to omit the C++ standard from the compilation options without defining the environment variable TS_NOSTDCPP.

--plugin

Display the directory for TSDuck plugins.

TSDuck extensions should store their tsplugin_xxx.so libraries there (.dylib on macOS, .dll on Windows).

--prefix

Display the installation prefix.

--python

Display the directory for TSDuck Python bindings, to be added in PYTHONPATH.

--so

Display the shared object files extension (.so, .dylib, .dll).

--static-libs

Display the static library linking flags. In a makefile, this is used in LDLIBS.

--vernum

Display the TSDuck version as a number.

--version

Display the TSDuck version as found in the development environment.

Sample usages

The following commands are used to build an application using the TSDuck library:

$ g++ $(tsconfig --cflags) -c app.cpp
$ g++ app.o $(tsconfig --libs) -o app

Replace g++ with clang++ if you use Clang/LLVM instead of GCC.

In a GNU makefile, the developer should use:

CXXFLAGS += $(shell tsconfig --cflags)
LDLIBS += $(shell tsconfig --libs)

If the application is a TSDuck extension providing one or more plugins, the installation commands in the makefile are like this:

$ install -m 644 tslibext_foo.so $(shell tsconfig --lib)
$ install -m 644 tsplugin_*.so $(shell tsconfig --plugin)

To use the Java and Python bindings:

$ export CLASSPATH="$(tsconfig --java):$CLASSPATH"
$ export PYTHONPATH="$(tsconfig --python):$PYTHONPATH"

3.7. tscrc32

Compute MPEG-style CRC32 values

This utility manually computes CRC32 values, as found in MPEG sections.

Usage

$ tscr32 [options] [input-file ...]

Input files

Any number of binary input files.

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Options

-a
--accelerated

Check if the computation of CRC32 is accelerated using specialized instructions (display yes or no).

-d hexa-data
--data hexa-data

Raw input data instead of input files. Use hexadecimal digits.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.8. tsdate

Date and time extraction

This utility extracts date and time information from a transport stream, namely the TDT (Time and Data Table) and the TOT (Time Offset Table).

Usage

$ tsdate [options] [input-file]

Input file

MPEG transport stream, either a capture file or a pipe from a live stream (see option --format for binary formats).

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Options

-a
--all

Report all TDT/TOT tables (default: report only the first table of each type).

-f name
--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

--notdt

Ignore Time & Date Table (TDT).

--notot

Ignore Time Offset Table (TOT).

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

A synonym for --isdb --abnt --time-reference UTC-3 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--isdb

--japan

A synonym for --isdb --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --isdb --abnt --time-reference UTC+8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.9. tsdektec

Dektec device control

This utility controls Dektec devices, which include input and/or output DVB-ASI devices or modulators (see [Dektec]).

Restrictions

This command is available on Linux and Windows only, Intel processors only. Dektec provides no software support on macOS and other processors. Moreover, this command may be unavailable on some Linux distributions since it integrates a closed-source library from Dektec, which is prohibited by the policy of some distributions.

Usage

$ tsdektec [options] [device]

Device

The optional parameter is a device index, from 0 to N-1 (with N being the number of Dektec devices in the system). The default is 0, the first device.

Use option --list-all (or -a) to have a complete list of devices in the system.

Options

-a
--list-all

List all Dektec devices available on the system.

-i port-number
--input port-number

Set the specified port in input mode. This applies to bidirectional ports which can be either set in input or output mode. The port number of each channel can be seen using the command tsdektec -av.

-l state
--led state

Set the state of the LED on the rear panel. Useful to identify a Dektec device when more than one is present. The state is one of off, green, red, yellow, blue, hardware. See also option --wait (the led state is automatically returned to hardware after exit).

-n
--normalized

With --all, list the Dektec devices in a normalized output format (useful for automatic analysis).

-o port-number
--output port-number

Set the specified port in output mode. This applies to bidirectional ports which can be either set in input or output mode. The port number of each channel can be seen using the command tsdektec -av.

-p value
--power-mode value

On DTU-315 USB modulators, set the power mode to the specified value.

Must be one of high-quality, low-power.

-r
--reset

Reset the device.

-w seconds
--wait seconds

Wait the specified number of seconds before exiting.

The default if 5 seconds if option --led is specified and 0 otherwise.

JSON output options

-j
--json

With --all, list the Dektec devices in JSON format. Useful for automatic analysis.

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

Normalized output format

In normalized output, each line describes one object (driver, device, channel, etc). The format of each line is:

type:name[=value]:...

The normalized syntax can be used to search for specific objects with specific characteristics. See also the description of the command tsanalyze for another example of normalized output.

3.10. tsdump

Dump TS packets

This utility dumps the contents of MPEG transport stream packets.

Usage

$ tsdump [options] [input-file ...]

Input files

Any number of MPEG transport stream files. If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Note that if the option --raw is used, the input files can be any type of file, not necessarily MPEG transport stream files.

Input file options

--byte-offset value

Start reading each file at the specified byte offset (default: 0).

This option is allowed only if all input files are regular files.

-c
--c-style

Same as --raw-dump (no interpretation of packets) but dump the bytes in C-language style, e.g. 0x01, 0x02, instead of 01 02. Useful to include tsdump output as data in a C or C++ source file.

-f name
--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

By default, the format of each input file is automatically detected and can be different from one file to another. When the option --format is specified, all input files must have the same format.

This option is ignored with --raw-file, the complete raw structure of the file is dumped.

-m value
--max-packets value

Maximum number of packets to dump per file.

--no-pager

Do not send output through a pager process. By default, if the output device is a terminal, the output is paged. See section 3.1.4 for more details.

--packet-offset value

Start reading each file at the specified TS packet (default: 0).

This option is allowed only if all input files are regular files.

-r
--raw-file

Raw dump of file, do not interpret as TS packets. With this option, tsdump simply acts as a hexa / ASCII file dumper.

Packet dump options

--adaptation-field

Include formatting of the adaptation field.

-a
--ascii

Include ASCII dump in addition to hexadecimal.

-b
--binary

Include binary dump in addition to hexadecimal.

-h
--headers-only

Dump packet headers only, not payload.

-l
--log

Display a short one-line log of each packet instead of full dump.

--log-size value

With option --log, specify how many bytes are displayed in each packet.

The default is 188 bytes (complete packet).

-n
--nibble

Same as --binary but add separator between 4-bit nibbles.

--no-headers

Do not display packet header information.

-o
--offset

Display offset from start of packet with hexadecimal dump.

--payload

Hexadecimal dump of TS payload only, skip TS header.

-p pid1[-pid2]
--pid pid1[-pid2]

Dump only packets with these PID values. Several --pid options may be specified.

By default, all packets are displayed.

--rs204

Dump the 16-byte trailer as found in RS204 files.

In the case of an ISDB-T stream with 204-byte packets, if you want to analyze the ISDB Information in the packet trailer, specify option --isdb. Without this option, the stream is considered as standard and the trailer is just a 16-byte Reed-Solomon FEC.

UDP reception options

The command tsdump can also be used to dump UDP datagrams. This behavior is triggered by the option --ip-udp. With this option, no input file shall be specified. The received UDP datagrams are not expected to contain TS packets and --raw-file is implicit.

This option is used to dump raw UDP datagrams. It is typically used for debug purpose on UDP networking. Do not use this option to dump TS packets from an IP-TV stream. Use tsp with input plugin ip and plugin dump.

The options which are described in this section apply only when --ip-udp is used.

--buffer-size value

Specify the UDP socket receive buffer size in bytes (socket option).

--default-interface

Let the system find the appropriate local interface on which to listen. By default, listen on all local interfaces.

--disable-multicast-loop

Disable multicast loopback.

By default, incoming multicast packets are looped back on local interfaces, if an application sends packets to the same group from the same system. This option disables this.

Warning: On input sockets, this option is effective only on Windows systems. On UNIX systems (Linux, macOS, BSD), this option applies only to output sockets.

--first-source

Filter UDP packets based on the source address. Use the sender address of the first received packet as only allowed source.

This option is useful when several sources send packets to the same destination address and port. Accepting all packets could result in a corrupted stream and only one sender shall be accepted.

To allow a more precise selection of the sender, use option --source. Options --first-source and --source are mutually exclusive.

--ip-udp [[source@]address:]port

Specify that tsdump shall dump raw UDP datagrams, not TS packets from transport stream files. The port part is mandatory and specifies the UDP port to listen on. The address part is optional. It specifies an IP multicast address to listen on. It can be also a host name that translates to a multicast address. If the address is not specified, the plugin simply listens on the specified local port and receives the packets which are sent to one of the local (unicast) IP addresses of the system.

An optional source address can be specified as source@address:port in the case of source-specific multicast (SSM).

--local-address address

Specify the IP address of the local interface on which to listen. It can be also a host name that translates to a local address. By default, listen on all local interfaces.

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

--receive-timeout value

Specify the UDP reception timeout in milliseconds. This timeout applies to each receive operation, individually. By default, receive operations wait for data, possibly forever.

--reuse-port

Set the reuse port socket option. This is now enabled by default, the option is present for legacy only.

--source address[:port]

Filter UDP packets based on the specified source address. This option is useful when several sources send packets to the same destination address and port. Accepting all packets could result in a corrupted stream and only one sender shall be accepted.

Options --first-source and --source are mutually exclusive.

--ssm

This option forces the usage of source-specific multicast (SSM) using the source address which is specified by the option --source. Without --ssm, standard ("any-source") multicast is used and the option --source is used to filter incoming packets.

The --ssm option is implicit when the classical SSM syntax source@address:port is used.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

A synonym for --isdb --abnt . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--isdb

--japan

A synonym for --isdb . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --isdb --abnt . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.11. tsecmg

Minimal generic DVB SimulCrypt-compliant ECMG

This utility behaves as a DVB SimulCrypt compliant ECMG. It can be used to debug system integration, replacing any standard ECM Generator. Most DVB SimulCrypt parameters can be adjusted from the command line to test the behaviour of an SCS.

This fake ECMG can be used with the tsp plugin named scrambler to build an end-to-end demo of a DVB SimulCrypt system.

This fake ECMG accepts all Super_CAS_Id values. All ECM requests are instantaneously responded. The returned ECM is a fake one. The fake ECM’s are TLV messages containing the access criteria and the control words as sent by the SCS in clear format.

Warning: It is obvious that this ECMG shall never be used on a production system since it returns ECM’s with clear control words.

Usage

$ tsecmg [options]

Network options

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

-o
--once

Accept only one client and exit at the end of the session.

-p value
--port value

TCP port number of the ECMG server. Default: 2222.

DVB SimulCrypt options

--ac-delay-start value

This option sets the DVB SimulCrypt option AC_delay_start, in milliseconds. By default, use the same value as --delay-start.

--ac-delay-stop value

This option sets the DVB SimulCrypt option AC_delay_stop, in milliseconds. By default, use the same value as --delay-stop.

--comp-time value

This option specifies the computation time of an ECM. The clear ECM’s which are generated by this ECMG take no time to generate. But, in order to emulate the behaviour of a real ECMG, this parameter forces a delay of the specified duration before returning an ECM.

-c value
--cw-per-ecm value

Specify the required number of control words per ECM. This option sets the DVB SimulCrypt option CW_per_msg. It also set lead_CW to CW_per_msg - 1. By default, use 2 control words per ECM, the current one and next one.

--delay-start value

This option sets the DVB SimulCrypt option delay_start, in milliseconds. Default: 200 ms.

--delay-stop value

This option sets the DVB SimulCrypt option delay_stop, in milliseconds. Default: 200 ms.

--ecmg-scs-version value

Specifies the version of the ECMG⇔SCS DVB SimulCrypt protocol. Valid values are 2 and 3. The default is 2.

--max-comp-time value

Specify the maximum ECM computation time in milliseconds. This option sets the DVB SimulCrypt option max_comp_time.

By default, use the value of --comp-time (which is zero by default) plus 100 milliseconds.

-r value
--repetition value

This option sets the DVB SimulCrypt option ECM_rep_period, the requested repetition period of ECM’s, in milliseconds.

The default is 100 milliseconds.

-s
--section-mode

Return ECM’s in section format. This option sets the DVB SimulCrypt parameter section_TSpkt_flag to zero.

By default, ECM’s are returned in TS packet format.

--transition-delay-start value

This option sets the DVB SimulCrypt option transition_delay_start, in milliseconds. Default: -500 milliseconds.

--transition-delay-stop value

This option sets the DVB SimulCrypt option transition_delay_stop, in milliseconds. Default: 0 ms.

DVB SimulCrypt logging options

--log-data[=level]

Same as --log-protocol but applies to CW_provision and ECM_response messages only.

To debug the session management without being flooded by data messages, use --log-protocol=info --log-data=debug.

--log-protocol[=level]

Log all ECMG⇔SCS protocol messages using the specified level. If the option is not present, the messages are logged at debug level only. If the option is present without value, the messages are logged at info level.

A level can be a numerical debug level or any of the following: fatal, severe, error, warning, info, verbose, debug.

Asynchronous logging options

This application is multi-threaded. Each thread may log messages at any time. To avoid delaying an application thread, the messages are displayed asynchronously in a low priority thread.

--log-message-count value

Specify the maximum number of buffered log messages. This value specifies the maximum number of buffered log messages in memory, before being displayed. When too many messages are logged in a short period of time, while plugins use all CPU power, the low-priority log thread has no resource. If it cannot display on time, the buffered messages and extra messages are dropped. Increase this value if you think that too many messages are dropped.

-s
--synchronous-log

With this option, each logged message is guaranteed to be displayed, synchronously, without any loss of message. The downside is that an application thread may be blocked for a short while when too many messages are logged.

-t
--timed-log

Each logged message contains a time stamp.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.12. tseit

Manipulate EIT’s using commands and scripts

This utility manipulates DVB Event Information Tables (EIT) using commands. Scripts can be used to reproduce specific test cases.

This utility is typically reserved to offline testing. To generate and inject EIT’s in actual transport streams, use the tsp plugin eitinject.

Usage

$ tseit [options]

Options

-c 'string'
--command 'string'

Specify an EIT manipulation command. See the list of available commands below.

Several --command options can be specified. All commands are executed in sequence.

The commands from --file options are executed first, then the --command options. If there is no --file and no --command, the commands are read from the standard input.

-e
--exit-on-error

Stop executing commands when an error is encountered. By default, continue execution on error.

-f file-name
--file file-name

Specify a text file containing EIT manipulation commands to execute (command script). If the file name is a dash (-), the standard input is used.

As usual in scripts, each text line is a command. Lines starting with # are considered as comments and ignored. Lines ending with a backslash (\) continue on the next line.

Several --file options can be specified. All scripts are executed in sequence. The commands from --file options are executed first, then the --command options. If there is no --file and no --command, the commands are read from the standard input.

-i path
--input-directory path

Default directory of input files in EIT manipulation commands.

In all commands and scripts, each time an input file is specified without directory or with a relative path, this default directory is used as base. It is consequently possible to write position-independent scripts and specify the actual directory or base path in the tseit command.

-o path
--output-directory path

Default directory of output files in EIT manipulation commands.

This is equivalent to option --input-directory, applied to output files.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

List of EIT manipulation commands

dump

Dump the content of the EIT database.

Usage:

dump

exit

Exit tseit. Useful in interactive sessions.

Usage:

exit

generate

Generate TS packets, injecting EIT’s from the event database according to the injection profile. Non-EIT packets are null packets. The TS id, TS bitrate and initial date/time must have been specified first (see command set).

Usage:

generate [options] filename

filename

Name of the output TS file to generate.

-b value --bytes value

Stop after generating the specified number of bytes.

-p value --packets value

Stop after generating the specified number of TS packets.

-s value --seconds value

Stop after generating the specified number of seconds of contents. The duration is based on the TS bitrate.

-u time --until time

Generate packets up to the specified date in the stream. The current date in the stream is based on the initial date and the bitrate. Use "year/month/day:hour:minute:second.millisecond" format.

help

List all internal commands. This command is useful in interactive session.

Usage:

help

load

Load events from a file.

Usage:

load filename

filename

A binary, XML or JSON file containing EIT sections. See the tsp plugin eitinject for more details on event database files.

process

Process a transport stream file with EIT generation. The input file is read, EIT’s are injected using the event database. The TS bitrate must have been specified first (see command set).

Usage:

process [options] infile outfile

infile

Name of the input TS file. Input EIT’s are used to populate the event database.

outfile

Name of the output TS file to generate, after EIT injection.

-b value --bytes value

Stop after generating the specified number of bytes.

-i --infinite

Repeat the input file infinitely.

-p value --packets value

Stop after generating the specified number of TS packets.

-r value --repeat value

Repeat the input file the specified number of times. By default, the input file is read once.

-s value --seconds value

Stop after generating the specified number of seconds of contents. The duration is based on the TS bitrate.

-o value --start-offset value

Start reading the input file at the specified offset in bytes.

-u time --until time

Generate packets up to the specified date in the stream. The current date in the stream is based on the initial date and the bitrate. Use "year/month/day:hour:minute:second.millisecond" format.

quit

Exit tseit. Useful in interactive sessions. Same as exit.

Usage:

quit

reset

Reset the content of the event database.

Usage:

reset

save

Save all current EIT sections in a file.

Usage:

save filename

filename

Name of the output file receiving EIT sections in binary format.

set

Set EIT generation options.

Usage:

set [options]

--actual

Enable the generation of all EIT actual.

--actual-pf

Enable the generation of EIT p/f actual.

--actual-schedule

Enable the generation of EIT schedule actual.

--eit-bitrate value

Set the EIT maximum bitrate in bits/second.

--no-actual

Disable the generation of all EIT actual.

--no-actual-pf

Disable the generation of EIT p/f actual.

--no-actual-schedule

Disable the generation of EIT schedule actual.

--no-other

Disable the generation of all EIT other.

--no-other-pf

Disable the generation of EIT p/f other.

--no-other-schedule

Disable the generation of EIT schedule other.

--no-pf

Disable the generation of all EIT p/f.

--no-schedule

Disable the generation of all EIT schedule.

--other

Enable the generation of all EIT other.

--other-pf

Enable the generation of EIT p/f other.

--other-schedule

Enable the generation of EIT schedule other.

--pf

Enable the generation of all EIT p/f.

--satellite

Use the EIT cycle profile for satellite and cable networks as specified in [ETSI-101-211].

--schedule

Enable the generation of all EIT schedule.

--terrestrial

Use the EIT cycle profile for terrestrial networks as specified in [ETSI-101-211].

--time time

Set the current date and time in the transport stream. Use "year/month/day:hour:minute:second.millisecond" format.

--ts-bitrate value

Set the transport stream bitrate in bits/second.

--ts-id value

Set the actual transport stream id.

3.13. tsemmg

Minimal generic DVB SimulCrypt-compliant EMMG

This utility behaves as a DVB SimulCrypt compliant EMMG. It can be used to debug system integration, replacing any standard EMM Generator. Most DVB SimulCrypt parameters can be adjusted from the command line to test the behaviour of a MUX.

This fake EMMG can be used with the tsp plugin named datainject to build an end-to-end demo of a DVB SimulCrypt system.

Usage

$ tsemmg [options] [section-file ...]

Parameters

The parameters are files containing sections in binary or XML format. Several files can be specified. All sections are loaded and injected in the MUX using the EMMG/PDG⇔MUX protocol. The list of all sections from all files is cycled as long as tsemmg is running. The sections can be of any type, not only EMM’s.

By default, when no input file is specified, this EMMG generates fake EMM sections of a fixed size and all payload bytes contain the same value. The value of the fake EMM table_id and the value of the payload bytes are incremented in each new section. See options --emm-size, --emm-min-table-id and --emm-max-table-id.

Options

-b value
--bandwidth value

Specify the bandwidth of the data which are sent to the MUX in kilobits per second. The default is 100 kb/s.

--bytes-per-send value

Specify the average size in bytes of each data provision. The exact value depends on sections and packets sizes. Default: 500 bytes.

--channel-id value

This option sets the DVB SimulCrypt parameter data_channel_id. The default is 1.

-c value
--client-id value

This option sets the DVB SimulCrypt parameter client_id. The default is 0.

For EMM injection, the most signification 16 bits shall be the CA_system_id of the corresponding CAS.

--cycles value

Inject the sections from the input files the specified number of times. By default, inject sections indefinitely.

-d value
--data-id value

This option sets the DVB SimulCrypt parameter data_id. The default is 0.

--emm-max-table-id value

Specify the maximum table id of the automatically generated fake EMM’s. The default is 0x8F.

When generating fake EMM’s, the table ids are cycled from the minimum to the maximum value.

--emm-min-table-id value

Specify the minimum table id of the automatically generated fake EMM’s. The default is 0x82.

--emm-size value

Specify the size in bytes of the automatically generated fake EMM’s. The default is 100 bytes.

--emmg-mux-version value

Specify the version of the EMMG/PDG⇔MUX DVB SimulCrypt protocol. Valid values are 1 to 5. The default is 2.

-i
--ignore-allocated

Ignore the allocated bandwidth as returned by the MUX. Continue to send data at the planned bandwidth, even if it is higher than the allocated bandwidth.

--max-bytes value

Stop after sending the specified number of bytes. By default, send data indefinitely.

-m address:port
--mux address:port

Specify the IP address (or host name) and TCP port of the MUX.

This is a required parameter, there is no default.

--requested-bandwidth value

This option sets the DVB SimulCrypt parameter bandwidth in the stream_BW_request message. The value is in kilobits per second.

The default is the value of the --bandwidth option. Specifying distinct values for --bandwidth and --requested-bandwidth can be used for testing the behavior of a MUX.

-s
--section-mode

Send EMM’s or data in section format. This option sets the DVB SimulCrypt parameter section_TSpkt_flag to zero. By default, EMM’s and data are sent in TS packet format.

--stream-id value

This option sets the DVB SimulCrypt parameter data_stream_id. The default is 1.

-t value
--type value

This option sets the DVB SimulCrypt parameter data_type. The default is 0 (EMM).

In addition to integer values, the following names can be used: emm (0), private-data (1) and ecm (2).

-u [address:]port
--udp [address:]port

Specify that the data_provision messages shall be sent using UDP.

By default, the data_provision messages are sent over TCP using the same TCP connection as the management commands.

If the IP address (or host name) is not specified, use the same IP address as the --mux option. The port number is required, even if it is the same as the TCP port.

-w milliseconds
--udp-end-wait milliseconds

With --udp, specify the number of milliseconds to wait after the last data_provision message (UDP) and before the stream_close_request message (TCP).

This can be necesssary to ensure that the stream_close_request is processed after the processing of the last data_provision. The default is 100 ms.

DVB SimulCrypt logging options

--log-data[=level]

Same as --log-protocol but applies to data_provision messages only.

To debug the session management without being flooded by data messages, use --log-protocol=info --log-data=debug.

--log-protocol[=level]

Log all EMMG/PDG⇔MUX protocol messages using the specified level. If the option is not present, the messages are logged at debug level only. If the option is present without value, the messages are logged at info level.

A level can be a numerical debug level or any of the following: fatal, severe, error, warning, info, verbose, debug.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.14. tsfclean

Cleanup the structure and boundaries of a transport stream file

In its most general form, an MPEG transport stream file is just a set of TS packets. It can be a capture of a live stream, in which case the file starts and ends at arbitrary points in an endless transmission.

However, when a media player manipulates stored contents, it expects the files to start with the actual beginning of an audio/video content. When the file format is an MPEG transport stream, the player expects some characteristics such as immediate identification of the services and PID’s, initial intra video frame, etc. Not matching these characteristics does not prevent the content from being rendered by the player but glitches are usually present at startup.

The tsfclean command cleans up a TS file to make it more consistent for media players and other similar tools. The following transformations are applied:

The output file starts with the PAT, the CAT (if present on input), the SDT (if present on input) and the PMT’s of all services. Thus, the player is aware of the exact structure of the TS before processing the first audio / video data.
EIT present/following for actual existing services are kept. All other EIT’s are removed.
All other PSI/SI (including NIT, BAT, TDT and other broadcast-related tables), all null packets and all orphan PID’s are deleted.
In each video PID, all packets preceding the first intra-frame are deleted. If no intra-frame can be found (unknown video codec), all packets preceding the first complete PES packet are deleted. Additionally, to allow early clock synchronization, all TS packets containing a PCR before the first intra-frame are passed but their payload is deleted.
In each audio, subtitles or data component of the services, all packets preceding the first complete PES packet or section are deleted. When PTS are present (audio for instance), the PES packets preceding (in PTS time) the first video intra-frame are deleted. When PTS are not present, all PES packets preceding (in the stream) the first video intra-frame are deleted.
In case of scrambled content, the PTS are not accessible. In that case, all audio and video packets preceding the first complete PES packet are deleted. However, no timing synchronization is possible.

If the input file contains several versions of a table (PAT, CAT, SDT or PMT’s), all successive versions are merged into one single version of the table. Some players are known to read the first table of each kind only and are not able to handle table updates as a TV receiver would do. Consequently, if a service or a component of a service appears and disappears several times, it becomes in fact declared from the start to the end of the output file. If incompatible non-cumulative changes are introduced in a table update, an error is reported.

Usage

$ tsfclean [options] file ...

File

MPEG transport stream input files to cleanup. All input files must be regular files (no pipe) since the processing is done on two passes.

If more than one file is specified, the output name shall specify a directory.

Options

-o path
--output path

Specify the output file or directory.

If the specified path is a directory, the output file is created in that directory, with the same base name as the input file.

This is a mandatory parameter, there is no default.

If more than one input file is specified, the output name shall specify a directory.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.15. tsfixcc

Fix continuity counters

This utility fixes errors in the continuity counters (CC) in a transport stream file. If packets are missing (non continuous CC), the CC in all subsequent packets in the affected PID’s are modified to remove the discontinuity.

If the file needs to be repeatedly played, tsfixcc can also add empty packets at the end of the file to fill the discontinuities between the end and the beginning of the file when the playback wraps to the beginning.

Warning: Make sure that tsfixcc is really the right tool for what you want to do. tsfixcc can only fix the continuity counters. If the input file is corrupted with missing packets, tsfxcc cannot restore the content of the missing packets. Non-contiguous continuity counters are here to inform the video player that TS packets are missing and the PES content is probably corrupted. If you use tsfixcc, the continuity counters will become continuous again but the PES content remains corrupted because some binary data are still missing. The difference is that the media player will not be informed that the PES content is corrupted. Make sure that this is what you want to do.

Usage

$ tsfixcc [options] file

File

MPEG transport stream. Must be a binary stream of 188-byte packets.

This file must be a regular file (cannot be a pipe). It is open in read/write mode and is directly updated.

Options

-c
--circular

Enforce continuity when the file is played repeatedly. Add empty packets, if necessary, on each PID so that the continuity is preserved between end and beginning of file.

Note, however, that this method is not compliant with the MPEG-2 Transport Stream standard as defined in [ISO-13818-1]. The standard specifies that the continuity counter shall not be incremented on packets without payload.

-n
--no-action

Display what should be performed but do not modify the file.

--no-replicate-duplicated

Two successive packets in the same PID are considered as duplicated if they have the same continuity counter and same content (except PCR, if any).

By default, duplicated input packets are replicated as duplicated on output (the corresponding output packets have the same continuity counters).

When this option is specified, the input packets are not considered as duplicated and the output packets receive individually incremented countinuity counters.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.16. tsftrunc

Transport stream file truncation

This utility truncates a captured transport stream file to remove trailing incomplete packets.

See also the utility tsresync for a more powerful way to recover corrupted transport stream files.

Usage

$ tsftrunc [options] file ...

Files

MPEG transport stream files. They must be binary streams of 188-byte packets.

The files must be regular files (cannot be pipes). They are open in read/write mode and are directly updated.

Options

-b value
--byte value

Truncate the file at the next packet boundary after the specified size in bytes. Mutually exclusive with --packet.

-n
--noaction

Do not perform truncation, check mode only.

-p value
--packet value

Index of first packet to truncate. If unspecified, all complete packets are kept in the file. Extraneous bytes at end of file (after last multiple of 188 bytes) are truncated.

-s value
--size-of-packet value

Specify the TS packet size in bytes. The default is 188 bytes.

Alternate packet sizes are useful for M2TS or other TS file formats.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.17. tsfuzz

Introduce random errors in transport stream files

This utility randomly corrupts transport stream files, typically to perform fuzzing attacks on media tools or receiver equipment.

The same effect can be obtained in transport stream processing pipeline using the tsp plugin fuzz.

Usage

$ tsfuzz [options] file ...

File

MPEG transport stream input files to corrupt.

If more than one file is specified, the output name shall specify a directory.

General options

-o path
--output path

Specify the output file or directory. If the specified path is a directory, the output file is created in that directory, with the same base name as the input file.

This is a mandatory parameter, there is no default.

If more than one input file is specified, the output name shall specify a directory.

Fuzzing options

These options are identical in the command tsfuzz and the tsp plugin fuzz.

-c value
--corrupt-probability value

Probability to corrupt a byte in the transport stream. The default is zero, meaning no corruption.

The value must be a fraction, e.g. 1/20, 1/1000, 3/20000, etc.

-p pid1[-pid2]
--pid pid1[-pid2]

PID filter: corrupt packets with these PID values only.

Several --pid options may be specified. By default, without --pid option, all PID’s are eligible for random corruption.

-s hexa-data
--seed hexa-data

Initial seed for the pseudo-random number generator.

Specify hexadecimal data. The size is not limited but at least 32 bytes are recommended.

Using the same seed on the same TS file will result in exactly the same corruptions. Without this parameter, a random seed is used, and the corruptions cannot be identically reproduced.

--sync-byte

May corrupt the 0x47 sync byte in TS packets. This may invalidate the synchronization of the transport stream.

By default, sync bytes are preserved.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.18. tsgenecm

Generate one ECM using any DVB SimulCrypt-compliant ECMG

This command connects to a DVB SimulCrypt compliant ECMG and requests the generation of one ECM.

Restriction

The target ECMG shall support current or current/next control words in ECM, meaning CW_per_msg = 1 or 2 and lead_CW = 0 or 1.

Usage

$ tsgenecm [options] output-file

Output file

Name of the binary output section file which receives the generated ECM. If the specified name is "-", the standard output is used.

ECM content options

--cp-number value

Crypto-period number (default: 0).

-c hexa-digits
--cw-current hexa-digits

Current control word (required). The value must be a suite of hexadecimal digits.

-n hexa-digits
--cw-next hexa-digits

Next control word (optional). The value must be a suite of hexadecimal digits.

ECMG client options

-a hexa-digits
--access-criteria hexa-digits

Specifies the access criteria for the service as sent to the ECMG. The value must be a suite of hexadecimal digits.

--channel-id value

Specifies the DVB SimulCrypt ECM_channel_id for the ECMG (default: 1).

-d seconds
--cp-duration seconds

Specifies the crypto-period duration in seconds (default: 10 seconds).

-i value
--ecm-id value

Specifies the DVB SimulCrypt ECM_id for the ECMG (default: 1).

-e host:port
--ecmg host:port

Specify an ECM Generator host name (or IP address) and TCP port.

-v value
--ecmg-scs-version value

Specifies the version of the ECMG⇔SCS DVB SimulCrypt protocol. Valid values are 2 and 3. The default is 2.

--stream-id value

Specifies the DVB SimulCrypt ECM_stream_id for the ECMG (default: 1).

-s value
--super-cas-id value

Specify the DVB SimulCrypt Super_CAS_Id. This is required when --ecmg is specified.

DVB SimulCrypt logging options

--log-data[=level]

Same as --log-protocol but applies to CW_provision and ECM_response messages only.

To debug the session management without being flooded by data messages, use --log-protocol=info --log-data=debug.

--log-protocol[=level]

A level can be a numerical debug level or any of the following: fatal, severe, error, warning, info, verbose, debug.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.19. tshides

List HiDes modulator devices

This utility lists HiDes modulator devices and their characteristics.

Restrictions

This command is available on Linux and Windows only. There is no HiDes device drivers on macOS or BSD systems.

Usage

$ tshides [options]

Options

-a value
--adapter value

Specify the HiDes adapter number to list. By default, list all HiDes devices.

Use --adapter or --device but not both.

-b value
--bandwidth value

Specify the bandwidth in Hz with --gain-range. The default is 8 MHz.

For compatibility with old versions, "low" values (below 1000) are interpreted in MHz. This means that values 8 and 8,000,000 are identical. Both mean 8 MHz.

-c
--count

Only display the number of devices, not their names or characteristics.

-d "name"
--device "name"

Specify the HiDes device name to list. By default, list all HiDes devices.

Use --adapter or --device but not both.

-f value
--frequency value

Frequency, in Hz, of the output carrier with --gain-range. The default is the first UHF channel.

-g
--gain-range

Display the allowed range of output gain for the specified device.

Usually, the allowed range of gain depends on the frequency and the bandwidth. This is why the gain range is not displayed with the other characteristics. Use the options --frequency and --bandwidth to display the corresponding gain range.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.20. tslatencymonitor

Monitor latency between two TS input sources

This utility uses the same input plugins as tsp or tsswitch to monitor the latency between these input sources.

Usage

$ tslatencymonitor [options] \
    -I input-name-1 [input-options] \
    -I input-name-2 [input-options]

Options

-b seconds
--buffer-time seconds

Specify the buffer time of timing data list in seconds. By default, the buffer time is 1 second.

-l
--list-plugins

List all available plugins.

-o filename
--output-file filename

Output file name for CSV reporting (standard error by default).

--output-interval seconds

Specify the time interval between each output in seconds. The default is 1 second.

Asynchronous logging options

This application is multi-threaded. Each thread may log messages at any time. To avoid delaying an application thread, the messages are displayed asynchronously in a low priority thread.

--log-message-count value

-s
--synchronous-log

-t
--timed-log

Each logged message contains a time stamp.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.21. tslsdvb

List DVB, ATSC, ISDB tuner receiver devices

This utility lists the physical tuner receiver devices in the system with their characteristics. Despite the legacy dvb name, all tuner devices are listed, DVB, ISDB or ATSC, terrestrial, satellite or cable.

This command lists physical devices only. It does not list tuner emulators (see section 7.1.4).

Usage

$ tslsdvb [options]

Options

-a N _
--adapter _N

Specify the Nth tuner device in the system, the first index being zero. This option can be used instead of device name.

On Linux systems, this means /dev/dvb/adapterN.

-d "name"
--device-name "name"

Specify the name of the DVB receiver device to use. The syntax of the device name depends on the operating system. See section 7.1.3 for more details on receiver devices naming.

By default, when no device name or adapter is specified, tslsdvb lists all available receiver devices.

-e
--extended-info

Display extended information.

This option comes in addition to --verbose to display extremely verbose information about a device such as the associated DirectShow graph on Windows.

Windows-specific options:

-l
--list-devices

Get a list of all tuner and receiver DirectShow filters, equivalent to --test list-devices.

--receiver-name "name"

Specify the name of the DirectShow receiver filter to use.

By default, first try a direct connection from the tuner filter to the rest of the graph. Then, try all receiver filters and concatenate them all.

This option is used only when a specific device name or adapter number is specified. It is ignored when all devices are listed since distinct tuner filters may need distinct receiver filters.

-t name
--test name

Run a specific DirectShow test. Produce a very verbose output, for debug only. The names of the available tests are listed below.

none

Do not run any test. This is the default.

list-devices

Get a short list of all tuner and receiver DirectShow filters.

enumerate-devices

Enumerate all DirectShow devices which are used with DVB tuners. This test is useful to detect all devices which may not be recognized as valid tuners by TSDuck.

tuning-spaces

List all DirectShow tuning spaces which are installed in the system and their compatibility with the various network providers.

bda-tuners

List all BDA tuners and their compatibility with the various predefined "network provider" filters.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.22. tsp

Transport stream processor

The transport stream processor is a general-purpose packet processing framework.

It receives an MPEG Transport Stream from a user-specified input plugin, applies MPEG packet processing through several user-specified packet processor plugins, and sends the processed stream to a user-specified output plugin.

All input, packet processing, and output plugins are shared libraries (.so files on Linux, .dylib on macOS, .dll on Windows).

The following figure illustrates the structure of a tsp process using three packet processing plugins.

Figure 2. Transport stream processor diagram

This section describes the general syntax and usage of the tsp command. All plugins are documented in detail, in alphabetical order, in chapter 4. The section 5.2 gives a few examples of tsp commands, both simple and complex examples.

Usage

The general syntax of the tsp command is the following:

$ tsp [tsp-options] \
      [-I input-name [input-options]] \
      [-P processor-name [processor-options]] ... \
      [-O output-name [output-options]]

All tsp-options must be placed on the command line before the input, packet processing and output plugin specifications. There must be at most one input and one output plugin. There may be any number of packet processing plugins.

On the command line, the order of the packet processing plugins is significant: the TS packets are passed from one processor to the other in this order. The input and output plugin, however, can be located anywhere on the command line. They are implicitly used as first and last plugin in the chain, respectively.

Offline and real-time defaults

There are two main classes of usage for tsp, offline and real-time processing. Offline processing works on static data such as transport stream files without specific timing constraints. Real-time processing applies to streaming devices such as tuners, Dektec devices or IP streams.

In the tsp command and in many plugins, some command line options affect tuning and performances. Roughly, we have to find a balance between throughput and latency.

To get a higher throughput, we must minimize the data copy and thread context switching operations. This is achieved using larger buffer sizes and letting plugins work on larger amounts of TS packets. This requires less CPU and provides better overall performances. But this also has the side effect of increasing the latency.
To get a lower latency, we must basically do the opposite: work on smaller data chunks, pass data faster (more frequently) from plugin to plugin. The drawback is an increase of CPU requirement.

There is no unique choice. When working on offline files, increasing the throughput and reducing the CPU load is the right choice. But for streaming and real-time processing, reducing the latency is the priority.

To optimize the offline or real-time processing, many tuning options can be adjusted. While fine tuning is sometimes useful, the user mainly needs two sets of default options: offline or real-time.

By default, tsp and all plugins use the offline defaults, the tuning options which give good performances at the expense of a higher latency.

The real-time defaults are used without having to specify all individual options in two cases:

The option -r or --realtime is specified in the tsp command line.
At least one plugin in the chain is designed to work in real-time.

In these two cases, tsp and all plugins use their real-time defaults (unless, of course, options are individually set).

The second condition, "designed to work in real-time", is an intrinsic property of a plugin. Examples of "real-time" plugins include dvb, dektec, ip, play or regulate. These plugins are somehow designed to work on real-time streams. Their simple presence in the tsp command is sufficient to trigger the use of real-time defaults for all plugins. It is still possible to force the use of offline defaults using the tsp option --realtime=off, even if a real-time plugin is present.

Rendering speed and transmission speed

With tsp, a stream has a rendering speed (the speed of the audio / video) and a transmission speed (the speed at which packets go through tsp).

As a general rule, the word bitrate refers to the rendering speed. So, when a plugin inserts data with a "bitrate of 100 kb/s" for instance, this means that the data will be received at this bitrate when the transport stream is played in real time (independently of the file processing speed, if the data insertion was previously performed on an offline file).

It is important to understand the differences between the two. Real-time streams, from broadcast or multicast, have identical transmission and rendering speeds because they are transmitted to watch TV. Files, on the other hand, have a very high transmission speed, typically the I/O speed of the disk, maybe 1 Gb/s or more on SSD.

Some plugins explicitly manipulate the rendering or transmission speed. The plugin pcrbitrate, for instance, is designed to evaluate the rendering speed based on embedded time stamps in the stream. The plugin regulate, on the other hand, is designed to alter the transmission speed.

Let’s review some examples of where these plugins should be used.

Consider that you have recorded a 6 Mb/s single program transport stream, and you want to send it through UDP/IP to a remote media player. Using tsp -I file, you read it and send it to -O ip. The effective reading speed of the file will be 500 M/b for instance. So, on a gigabit network, you send a 6 Mb/s video stream at 1 Gb/s, 166 times faster as it should be. Thus, a 15 minute video is received in 5 seconds and the player displays almost nothing. In this case, you must use the plugin regulate between -I file and -O ip. The plugin acts as a bottleneck and lets packets flow out at 6 Mb/s only.

But, when the source has the same transmission and rendering speeds (DVB tuner, IP source), the plugin regulate is useless. At best, it does nothing. At worst, it introduces undesirable artifacts. There are also cases where the transmission speed regulation is done automatically. If the media player is a local application such as VLC and is started using -O play, tsp communicates with the player through a pipe. A pipe is a self-regulated communication mechanism. So, even if the input is a disk file with a high reading speed, using regulate is not necessary because the same role is played here by the pipe. The difference with the previous example is that UDP/IP is not a regulated communication channel, unlike pipes and TCP/IP.

Bitrate propagation

At any point in the chain, all plugins have some knowledge of the transport stream bitrate or rendering speed. Some plugins use that bitrate information, some others don’t. The plugin regulate is a typical example. It uses the rendering speed as information to lower the transmission speed. As a general rule, tsp collects the input bitrate, either from the input plugin itself which extracts the bitrate from a hardware input device (this is the case for ASI cards for instance) or, if the input plugin is not able to report a bitrate, tsp automatically analyzes PCR’s at the output of the input plugin and computes the corresponding bitrate.

Then, the bitrate is transmitted from plugin to plugin.

Some plugins may inadvertently propagate incorrect bitrates while some plugins may force a (correct) recomputation of the bitrate. To illustrate the first case, consider -I file … -P zap … using sample bitrate values. You read a complete 36 Mb/s input file and tsp evaluates this bitrate. Then, -P zap extracts a 4 Mb/s service and removes everything else. But it does not recompute the transport stream bitrate. So, the propagated bitrate information is still 36 Mb/s. If this information is not used downstream in other plugins, we don’t care. But if we use the bitrate information in -P regulate -O ip for instance, we will regulate at 36 Mb/s a stream which should be played at 4 Mb/s. This is why, in specific situations like this, we need to recompute the bitrate using -P pcrbitrate before -P regulate.

Input timestamps

For each input packet, an input timestamp is collected. When the source can provide its own timestamps (RTP, SRT, M2TS file), this value is used. Otherwise, tsp uses the system time after the input plugin returns a bulk of packets. When an input plugin is able to generate its own input timestamps, its documentation describes how this is accomplished.

The input timestamps are propagated all along the chain of plugins. Some plugins may use them. For instance:

The plugin pcrverify can use them as time reference.
The output plugin file uses them to create files in M2TS format.

Modifying, inserting and deleting packets

In the complete chain of processing, between the input and the output plugin, each TS packet goes through all packet processing plugins, one after the other, in the order of the command line.

In fact, a TS packet never moves. It is loaded in a large circular buffer and stays there. Each plugin uses a sliding window over the circular buffer and inspects or modifies packets without moving them.

A packet processing plugin may read, modify or delete existing packets. But it cannot add new packets.

Roughly, each packet processing plugin has one of the following functions (or sometimes a combination of them):

Analysis (read packets).
Modification (modify existing packets).
Removal (delete packets from the stream).
Data injection (add new packets).

The last case cannot be directly implemented. To achieve data injection, a plugin usually steals stuffing. Each time a new TS packet needs to be injected, a plugin waits for the next null packet (i.e. a packet in PID 0x1FFF) and replaces this null packet with the new packet to insert.

Consequently, the original amount of stuffing and its distribution in a stream directly influences the insertion profile of new packets. Specifically, it is not possible to add more data than the stuffing bitrate. Moreover, precise timing cannot be always achieved. When data need to be inserted at a given bitrate, the plugin tries to reach this average bitrate (provided that there is enough stuffing) but cannot guarantee a precise constant inter-packet distance.

In broadcast streams, where the modulation parameters impose a fixed bitrate, there is always some stuffing. With variable bitrate, simple-program transport streams for IP, there can be no stuffing at all.

What are the options when the original amount of stuffing is not sufficient to insert the required data? It depends on the requirements on the stream.

If the stream is targeted for broadcast, with a given target bitrate which cannot be changed, there is no other solution than removing existing data to make room for the new data. Some plugins such as filter or svremove delete individual PID’s or complete services. By default, the deleted packets are simply removed from the stream. But these plugins also have a --stuffing option which replaces deleted packets by stuffing instead of removing them. Thus, you can increase the stuffing bitrate without altering the global transport stream bitrate.

If there is no requirement on the global bitrate, it is possible to insert artificial stuffing at input level using the global tsp option --add-input-stuffing. The option adds a given number of null packets after a given number of input packets (for instance, add 1 null packet every 15 input packets). The parameters influence the amount and distribution of the artificial stuffing. Do not be afraid of inserting too much stuffing. It is always possible to remove the stuffing in excess using -P filter -n -p 0x1FFF at the end of the chain, after all injection plugins.

Merging and forking

As indicated above, tsp processes one single transport stream. However, specific plugins such as merge and fork respectively combine and duplicate transport streams. They are designed to route transport streams from and to other applications. When the "other" application is another instance of tsp, we can create complex processing graphs.

This is illustrated in the diagram below.

Figure 3. Merging and forking transport streams

Joint termination

Some plugins have termination conditions.

For instance, the plugin until passes packets until some specified condition. The plugins mux and inject may terminate tsp after completing the data insertion, etc.

Therefore, a plugin can decide to terminate tsp on its own. The termination is unconditional, regardless of the state of the other plugins. Thus, if several plugins have termination conditions, tsp stops when the first plugin decides to terminate. In other words, there is an or operator between the various termination conditions.

The idea behind joint termination is to terminate tsp when several plugins have jointly terminated their processing.

If several plugins have a joint termination condition (usually using the option --joint-termination), tsp stops when the last plugin triggers the joint termination condition. In other words, there is an and operator between the various joint termination conditions.

Additionally, the tsp option --ignore-joint-termination disables this behavior. When this options is used, all plugins continue to pass packets as if some additional joint termination condition was still pending.

Packet labelling

Transport streams packets may receive one or more label from any packet processing plugin. A label is an integer value from 0 to 31, inclusive. A label remains attached to the packet all along the chain, from plugin to plugin. Later, it is possible to select packets with a label value or invoke a specific plugin only on packets having a given label.

The plugin filter has an option named --set-label to assign a label to the selected packets. Note that, with this option, the plugin filter does not drop unselected packets; it keeps all packets but assigns the specified label to the selected packets.

All packet processing plugins accept the option --only-label which selects only the packets with a given label. Thus, only the packets with that label pass through the plugin. All other packets, without that label, are directly passed to the next plugin in the chain.

The following example illustrates the usage of labels. The first three plugins select different kinds of packets and assign a label value depending on the kind of packet. These filter plugins do not drop any packet, they just assign labels to some of them. Later, three other plugins are applied only to one of these labels. In this example, we consequently count packets with unit start indicator and scrambling control value 2 and 3, respectively.

$ tsp -I ... \
      -P filter --unit-start --set-label 2 \
      -P filter --scrambling 2 --set-label 10 \
      -P filter --scrambling 3 --set-label 11 \
      -P count --only-label 2 --total --tag unit \
      -P count --only-label 10 --total --tag scr2 \
      -P count --only-label 11 --total --tag scr3 \
      -O ...

* count: unit: total: counted 5,311 packets out of 5,311
* count: scr2: total: counted 8,378 packets out of 8,378
* count: scr3: total: counted 7,439 packets out of 7,439

Global tsp options

These options apply to the execution of the tsp framework. They must be placed on the command line before any plugin specification.

-a nullpkt/inpkt
--add-input-stuffing nullpkt/inpkt

Specify that nullpkt null TS packets must be automatically inserted after every inpkt input TS packets. Both nullpkt and inpkt must be non-zero integer values. This option is useful to artificially increase the input bitrate by adding stuffing.

Example: the option -a 14/24 adds 14 null packets every 24 input packets, effectively turning a 24 Mb/s input stream (terrestrial) into a 38 Mb/s stream (satellite).

--add-start-stuffing count

Specify that count null TS packets must be automatically inserted at the start of the processing, before the first packet coming from the input plugin.

--add-stop-stuffing count

Specify that count null TS packets must be automatically inserted at the end of the processing, after the last packet coming from the input plugin.

-b value
--bitrate value

Specify the transport stream input bitrate, in bits/seconds. By default, the input bitrate is provided by the input plugin or by analysis of the PCR’s at the beginning of the input stream. If no or not enough PCR are found, the DTS from video PID’s are used.

See section 2.2 for more details on the representation of bitrates.

Use option --bitrate when you know precisely the input bitrate and you do not trust the input device, the PCR’s or the DTS.

See also the plugin pcrbitrate for permanent recomputation of the bitrate based on PCR’s or DTS.

--bitrate-adjust-interval value

Specify the interval in seconds between bitrate adjustments, ie. when the output bitrate is adjusted to the input one. The default is 5 seconds. Some output processors ignore this setting. Typically, ASI or modulator devices use it, while file devices ignore it. This option is ignored if --bitrate is specified.

--buffer-size-mb value

Specify the global buffer size in mega-bytes. This is the size of the buffer between the input and output devices. The default is 16 MB. Increasing the buffer size may improve the performance at the expense of increasing the overall latency (implicit time-shifting).

The value (in mega-bytes) can be decimal, for instance --buffer-size-mb 0.5, but note that there is no good reason to decrease the buffer size below 1 MB.

See also the options --max-input-packets and --max-flushed-packets to adjust the latency without modifying the global buffer size.

--final-wait milliseconds

Wait the specified number of milliseconds after the last input packet. Zero means wait forever.

-i
--ignore-joint-termination

Ignore all --joint-termination options in plugins. The plugins continue to pass packets as if some additional joint termination condition was still pending.

See the description of joint termination above for more details.

--initial-input-packets value

Specify the number of packets to initially read in the buffer before starting the processing.

The initial load is used to evaluate the bitrate so that all subsequent plugins can have a valid global bitrate value from the beginning. It is also used to make sure that the global buffer is optimally used.

The default initial load is half the size of the global buffer. For offline files and real-time devices with a sustained bitrate, it is a good idea to keep the default value.

The side effect of waiting for a significant amount of initial packets before starting the processing is that, with very low bitrates, tsp seems to do nothing until the global buffer is half full. The option --initial-input-packets is used to adjust this effect when necessary.

The downside of using a lower initial buffer load is that some plugins may not be able to use a valid bitrate for the initial part of the stream. Another downside is that the usage of the global buffer will probably be suboptimal and may even starve, creating output glitches, depending on the processing time of the intermediate plugins.

-l
--list-plugins

List all available plugins.

--log-plugin-index

In log messages, add the plugin index to the plugin name. This can be useful if the same plugin is used several times and all instances log many messages.

--max-flushed-packets value

Specify the maximum number of packets to be processed before flushing them to the next plugin or the output. When the processing time is high and some packets are lost, try decreasing this value.

The offline default is 10,000 packets. The real-time default is 1,000 packets.

--max-input-packets value

Specify the maximum number of packets to be received at a time from the input plugin.

By default, in offline mode, tsp reads as many packets as it can, depending on the free space in the buffer. The real-time default is 1,000 packets.

--max-output-packets value

Specify the maximum number of packets to be sent at a time by the output plugin.

By default, tsp sends as many packets as available. This option is useful only when an output plugin or a specific output device has problems with large output requests. This option forces multiple smaller send operations.

-r[keyword]
--realtime[=keyword]

Specifies if tsp and all plugins should use default values for real-time or offline processing.

By default, if any plugin prefers real-time, the real-time defaults are used. If no plugin prefers real-time, the offline default are used.

If -r or --realtime is used alone, the real-time defaults are enforced. The explicit values no, false, off are used to enforce the offline defaults and the explicit values yes, true, on are used to enforce the real-time defaults.

--receive-timeout milliseconds

Specify a timeout in milliseconds for all input operations.

Equivalent to the same --receive-timeout option in some input plugins. In practice, when an input plugin natively supports a receive timeout, this global parameter is passed to the plugin. Otherwise, tsp handles the receive timeout and tries to abort the stalled input operation in case of timeout.

By default, there is no input timeout.

Control commands options

It is possible to send commands to a running tsp process using the command tspcontrol. See the documentation of this command for more details on control commands. The following options control how these control commands are received.

--control-local address

With --control-port, specify the IP address of the local interface on which to listen for control commands. It can be also a host name that translates to a local address. By default, listen on all local interfaces.

--control-port value

Specify the TCP port on which tsp listens for control commands. If unspecified, no control commands are expected.

--control-reuse-port

With --control-port, set the reuse port socket option on the control TCP server port.

This option is not enabled by default to avoid accidentally running two identical tsp commands with the same control port.

--control-source address

With --control-port, specify a remote IP address which is allowed to send control commands.

By default, as a security precaution, only the local host is allowed to connect.

Several --control-source options are allowed.

--control-timeout milliseconds

With --control-port, specify the reception timeout in milliseconds for control commands. The default timeout is 5000 ms.

Monitoring options

-m[filename]
--monitor[=filename]

Continuously monitor the system resources which are used by the application process. This includes CPU load, virtual memory usage. Useful to verify the stability of the application or benchmarking the packet processing performance.

The optional file is an XML monitoring configuration file. See section C.2, for more details on resource monitoring configuration files.

Asynchronous logging options

This application is multi-threaded. Each thread may log messages at any time. To avoid delaying an application thread, the messages are displayed asynchronously in a low priority thread.

--log-message-count value

-s
--synchronous-log

-t
--timed-log

Each logged message contains a time stamp.

Default values for plugins options

The following options are commonly found in many different plugins. They typically influence the way the signalization is interpreted or generated.

These options can also be specified at tsp level, before specifying any plugin. They have have no effect on the tsp framework. They are only passed as initial default values for all plugins which accept the equivalent options. Explicit options at plugin level take precedence over these global defaults.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

A synonym for --isdb --abnt --default-charset RAW-ISO-8859-15 --hf-band-region brazil --time-reference UTC-3 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--conax

Interpret all EMM’s and ECM’s from unknown CAS as coming from Conax. Equivalent to --default-cas-id 0x0B00.

--default-cas-id value

Interpret all EMM’s and ECM’s from unknown CAS as coming from the specified CA_System_Id.

By default, EMM’s and ECM’s are interpreted according to the CA_descriptor which references their PID. This option is useful when analyzing partial transport streams without CAT or PMT to correctly identify the CA PID’s.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--default-pds value

Default DVB-defined private data specifier (PDS). See section 2.4.2 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--hf-band-region name

Specify the region for UHF/VHF band frequency layout. The default region is europe. Another default region may be specified per user in the TSDuck configuration file. See section A.4 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--irdeto

Interpret all EMM’s and ECM’s from unknown CAS as coming from Irdeto. Equivalent to --default-cas-id 0x0600.

--isdb

--japan

A synonym for --isdb --default-charset ARIB-STD-B24 --hf-band-region japan --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--mediaguard

Interpret all EMM’s and ECM’s from unknown CAS as coming from MediaGuard. Equivalent to --default-cas-id 0x0100.

--nagravision

Interpret all EMM’s and ECM’s from unknown CAS as coming from NagraVision. Equivalent to --default-cas-id 0x1800.

--nds

Interpret all EMM’s and ECM’s from unknown CAS as coming from Synamedia (formerly known as NDS). Equivalent to --default-cas-id 0x0900.

--philippines

A synonym for --isdb --abnt --default-charset RAW-UTF-8 --hf-band-region philippines --time-reference UTC+8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--safeaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from SafeAccess. Equivalent to --default-cas-id 0x4ADC.

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc --hf-band-region usa . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

--viaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from Viaccess. Equivalent to --default-cas-id 0x0500.

--widevine

Interpret all EMM’s and ECM’s from unknown CAS as coming from Widevine CAS. Equivalent to --default-cas-id 0x4AD4.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

Plugin activation options

-I name

Designate the shared library plugin for packet input. By default, read packets from standard input.

-O name

Designate the shared library plugin for packet output. By default, write packets to standard output.

-P name

Designate a shared library plugin for packet processing. Several packet processors are allowed. Each packet is successively processed by each processor, in the order of the command line. By default, there is no processor and the packets are directly passed from the input to the output.

The specified plugin name is used to locate a shared library for the plugin (.so file on Linux, .dylib on macOS, .dll on Windows). On Windows, usually, all plugins files are in the same directory as the tsp executable. More generally, a plugin can be designated in a number of ways, in the following order. When a method fails, the next one is attempted.

If the plugin name is a complete path name, with a directory, this path name is used.
Without directory in the plugin name, a list of directories is searched:
- If the environment TSPLUGINS_PATH is defined, a list of directories is parsed. Directories are separated by a semicolon ; on Windows and a colon : on UNIX systems (Linux, macOS, BSD).
- The same directory as the tsp executable file is used as last choice.
- In each of these directories, the file named tsplugin_name.so or .dylib or .dll is searched.
- If not found, the file name and then name.so or .dylib or .dll is searched.
If still not found, the standard algorithm of the operating system is applied to locate the shared library file, using the specified name (on Linux, see the man page of dlopen(3) for more details).

The input-options, processor-options and output-options, as specified in the general syntax of the tsp command, are specific to their corresponding plugin. All available plugins are documented in chapter 4.

Common plugin options

All plugins accept the following common options:

--help

The plugin displays its syntax and exits.

This means that the following type of command can be used to display the help text for a specific plugin:

$ tsp {-I|-O|-P} name --help

3.23. tspacketize

Packetize PSI/SI tables in a transport stream PID

This utility packetizes PSI/SI tables in a transport stream PID.

Usage

$ tspacketize [options] [input-file[=rate] ...]

Parameters

input-file[=rate]

Binary, XML or JSON files containing one or more sections or tables. By default, files with a name ending in .bin, .xml or .json are automatically recognized. For other file names, explicitly specify --binary or --xml or --json.

If the file name is omitted, the standard input is used (binary by default, specify --xml or --json otherwise).

The reference source format is XML. JSON files are first translated to XML using the "automated XML-to-JSON conversion" rules of TSDuck (see section 2.7.3) and then compiled to binary.

If different repetition rates are required for different files, a parameter can be filename=value where value is the repetition rate in milliseconds for all sections in that file. For repetition rates to be effective, the bitrate of the target PID must be specified, see option --bitrate.

If an input file name starts with <?xml, it is considered as inline XML content. Similarly, if an input file name starts with { or [, it is considered as inline JSON content. In these two cases, it is not possible to specify a specific repetition rate for this XML or JSON content.

Options

--binary

Specify that all input files are binary, regardless of their file name.

-b value
--bitrate value

Specifies the bitrate (in bits/second) of the target PID.

See section 2.2 for more details on the representation of bitrates.

This information is used to schedule sections in the output list of packets when specific bitrates are specified for sections. When no specific bitrate is specified for any input file, this option is ignored.

-c
--continuous

Continuous packetization. By default, generate one cycle of sections.

-f
--force-crc

Force recomputation of CRC32 in long sections. Ignore the CRC32 values in the input files. By default, the CRC32 of every section is verified and sections with wrong CRC32 are rejected.

-j
--json

Specify that all input files are JSON, regardless of their file name.

-o file-name
--output file-name

Output file name for TS packets. By default, use standard output.

-p value
--pid value

PID of the output TS packets. This is a required parameter, there is no default value.

-s
--stuffing

Insert stuffing at end of each section, up to the next TS packet boundary. By default, sections are packed and start in the middle of a TS packet, after the previous section. Note, however, that section headers are never scattered over a packet boundary.

-x
--xml

Specify that all input files are XML, regardless of their file name.

Sections files options

These options affect the way sections are loaded from binary, XML or JSON files. They are used in commands tspacketize, tstabcomp, and plugin inject.

--eit-actual

With --eit-normalization, generate all EIT Actual. Same as --eit-actual-pf --eit-actual-schedule.

--eit-actual-pf

With --eit-normalization, generate EIT p/f Actual. If no EIT selection option is specified, all EIT’s are generated.

--eit-actual-schedule

With --eit-normalization, generate EIT Schedule Actual. If no EIT selection option is specified, all EIT’s are generated.

--eit-base-date date

With --eit-normalization, use the specified date as reference for the allocation of the various EIT events in sections and segments.

The date must be in the format "YYYY/MM/DD [hh:mm:ss]". If only the date is present, it is used as base for the allocation of EIT schedule. If the time is also specified, it is the current time for the snapshot of EIT p/f. By default, use the oldest date in all EIT sections as base date.

--eit-normalization

Reorganize all EIT sections according to the rules from [ETSI-101-211].

EIT present/following: One single EIT p/f subtable is built per service. It is split in two sections, one for present and one for following events.
EIT schedule: All EIT schedule are kept but they are completely reorganized. All events are extracted and spread over new EIT sections according to ETSI TS 101 211 rules.

If several files are specified, the reorganization of EIT’s is performed inside each file independently. This is fine as long as all EIT’s for a given service are in the same input file.

3.24. tspcap

Analyze pcap and pcap-ng files

This simple utility provides a summary of the content of pcap and pcap-ng files. These files contain network packets, typically captured and saved by Wireshark.

The tspcap utility is not meant to replace Wireshark. It only computes global analysis data which are not otherwise available in Wireshark, for instance the data bitrate over a range of packets in the file.

Wireshark is typically used to investigate issues on a network capture. Then, if some specific global analysis is required, use tspcap.

See some usage examples in section 5.1.10.

Usage

$ tspcap [options] [input-file]

Parameters

input-file

Input file in pcap or pcap-ng format, typically as saved by Wireshark.

Use the standard input if no file name is specified.

Options

-d [address][:port]
--destination [address][:port]

Filter IP packets based on the specified destination socket address. The optional port number is used for TCP and UDP packets only. If the address part is omitted, all TCP or UDP packets with any destination address but with that destination port number are used.

--dvb-simulcrypt

Dump the content of a session as DVB SimulCrypt protocol.

Without --udp, the first TCP session matching the --source and --destination options is selected. The content of the session is interpreted as one of the TLV-based DVB SimulCrypt protocols and all messages are formatted.

With --udp, all packets matching the --source and --destination options are interpreted as EMMG/PDG⇔MUX protocol (this is the only DVB SimulCrypt protocol which is based on UDP).

-e
--extract-tcp-stream

Extract the content of a TCP session as hexadecimal dump.

The two directions of the TCP session are dumped.

The first TCP session matching the --source and --destination options is selected.

-i micro-seconds
--interval micro-seconds

Print a summary of exchanged data by intervals of times in micro-seconds.

By default, print a summary of the file content.

-l
--list-streams

List all data streams in the file. A data streams is made of all packets from one source to one destination using one protocol.

By default, print a summary of the file content.

--no-pager

Do not send output through a pager process. By default, if the output device is a terminal, the output is paged. See section 3.1.4 for more details.

--others

Filter packets from "other" protocols, i.e. neither TCP nor UDP.

-o file-name
--output-tcp-stream file-name

Extract the content of a TCP session and save it in the specified binary file.

The first TCP session matching the --source and --destination options is selected.

Unlike --extract-tcp-stream, only one side of the TCP session is saved, from --source to --destination.

If the file name is "-", the standard output is used.

-s [address][:port]
--source [address][:port]

Filter IP packets based on the specified source socket address.

The optional port number is used for TCP and UDP packets only. If the address part is omitted, all TCP or UDP packets with any source address but with that source port number are used.

-t
--tcp

Filter TCP packets.

-u
--udp

Filter UDP packets.

Packet filtering options

--first-date date-time

Filter packets starting at the specified date. Use format YYYY/MM/DD:hh:mm:ss.mmm.

--first-packet value

Filter packets starting at the specified number.

The packet numbering counts all captured packets from the beginning of the file, starting at 1. This is the same value as seen on Wireshark in the leftmost column.

--first-timestamp micro-seconds

Filter packets starting at the specified timestamp in micro-seconds from the beginning of the capture. This is the same value as seen on Wireshark in the "Time" column (in seconds).

--last-date date-time

Filter packets up to the specified date. Use format YYYY/MM/DD:hh:mm:ss.mmm.

--last-packet value

Filter packets up to the specified number.

The packet numbering counts all captured packets from the beginning of the file, starting at 1. This is the same value as seen on Wireshark in the leftmost column.

--last-timestamp micro-seconds

Filter packets up to the specified timestamp in micro-seconds from the beginning of the capture. This is the same value as seen on Wireshark in the "Time" column (in seconds).

--vlan-id value

Filter packets from the specified VLAN id.

This option can be specified multiple times. In that case, the values define the required nested VLAN ids, from the outer to inner VLAN. If the stream contains even more inner VLAN’s, they are all selected.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.25. tspcontrol

Send control commands to a running tsp process

This utility controls the execution of a running tsp process. The target tsp command shall listen to control commands using the option --control-port (see the documentation of tsp).

Usage

$ tspcontrol [options] command ...

Parameters

command …

The control command to send to the target tsp process. See the list of control commands below.

Note that everything after the control command name is considered as options and parameters of this control command. The options of tspcontrol must be placed before the control command name.

Options

-t [address:]port
--tsp [address:]port

Specify the IP address (or host name) and port where the target tsp process expects control commands (tsp option --control-port). If the IP address is omitted, the local host is used.

This is a required parameter, there is no default.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

List of control commands

exit

Terminate the tsp process.

Usage:

tspcontrol exit [options]

--abort

Specify to immediately abort the tsp process. By default, this command notifies each plugin to terminate and let the processing continue until the process naturally exits.

list

List all running plugins. The listed plugin indexes can be used with other control commands such as suspend, resume or restart.

Usage:

tspcontrol list [options]

-v --verbose

Produce verbose output.

restart

Restart a plugin with different parameters.

Usage:

tspcontrol restart [options] index [plugin-options …]

Parameters:

Index of the plugin to restart, followed by the new plugin parameters to use.

-s --same

Restart the plugin with the same options and parameters as the current ones. By default, when no plugin options are specified, restart with no option at all.

-v --verbose

Produce verbose output.

resume

Resume a suspended plugin.

Usage:

tspcontrol resume [options] index

Parameter:

Index of the plugin to resume.

-v --verbose

Produce verbose output.

set-log

Change the log level in the tsp process.

Usage:

tspcontrol set-log level

Parameter:

Specify a new logging level for the tsp process. It can be one of fatal, severe, error, warning, info, verbose, debug or a positive value for higher debug levels.

suspend

Suspend a plugin. When a packet processing plugin is suspended, the TS packets are directly passed from the previous to the next plugin, without going through the suspended one. When the output plugin is suspended, the output packets are dropped. The input plugin cannot be suspended.

Usage:

tspcontrol suspend [options] index

Parameters:

Index of the plugin to suspend.

-v --verbose

Produce verbose output.

3.26. tspsi

Dump all PSI tables

This utility extracts all PSI tables (PAT, CAT, PMT, NIT, BAT, SDT ) from a transport stream. The output is rather primitive, but it exactly exhibits the structure of tables, sections and descriptors.

Usage

$ tspsi [options] [input-file]

Input file

MPEG transport stream, either a capture file or a pipe from a live stream (see option --format for binary formats).

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

General options

--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

--no-pager

Do not send output through a pager process. By default, if the output device is a terminal, the output is paged. See section 3.1.4 for more details.

PSI selection and logging options

-a
--all-versions

Display all versions of PSI tables (need to read the complete transport stream). By default, display only the first version of each PSI table and stop when all expected PSI are extracted.

--cat-only

Display only the CAT, ignore other PSI tables.

--clear

Indicate that this is a clear transport stream, without conditional access information. Useful to avoid further reading the transport stream, waiting for a non-existent CAT.

-d
--dump

Dump all PSI sections.

--exclude-current

Exclude PSI tables with "current" indicator. This is rarely necessary. See also --include-next.

--include-next

Include PSI tables with "next" indicator. By default, they are excluded.

-j file-name
--json-output file-name

Save the tables in JSON format in the specified file. To output the JSON text on the standard output, explicitly specify this option with - as output file name.

The tables are initially formatted as XML and an automated XML-to-JSON conversion is applied. See section 2.7.3 for more details on XML-to-JSON conversion.

--log-json-line[='prefix']

Log each table as one single JSON line in the message logger instead of an output file.

Each table is initially formatted as XML and an automated XML-to-JSON conversion is applied. See section 2.7.3 for more details on XML-to-JSON conversion.

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.

--log-xml-line[='prefix']

Log each table as one single XML line in the message logger instead of an output file.

The optional string parameter specifies a prefix to prepend on the log line, before the XML text, to facilitate the filtering of the appropriate line in the logs.

-o file-name
--output-file file-name
--text-output file-name

Save the tables or sections in human-readable text format in the specified file name. By default, when no output option is specified, text is produced on the standard output.

If you need text formatting on the standard output in addition to other output such as XML, explicitly specify this option with - as output file name.

-x file-name
--xml-output file-name

Save the tables in XML format in the specified file. To output the XML text on the standard output, explicitly specify this option with - as output file name.

XML output options

The following options affect details in the generation of XML files.

--strict-xml

Save XML documents in strictly conformant XML format. By default, do not escape characters when this is not syntactically necessary to make the XML text more human-readable.

--x2j-collapse-text
--x2j-enforce-boolean
--x2j-enforce-integer
--x2j-include-root
--x2j-trim-text

Specific options for automated XML-to-JSON conversion. See section 2.7.3.2 for more details.

Sections display format options

These options affect the way individual sections are displayed.

-c
--c-style

Same as --raw-dump (no interpretation of section) but dump the bytes in C-language style, e.g. "0x01, 0x02," instead of "01 02". Useful to include this output as data in a C source file.

--nested-tlv[=min-size]

With option --tlv, try to interpret the value field of each TLV record as another TLV area. If the min-size value is specified, the nested TLV interpretation is performed only on value fields larger than this size. The syntax of the nested TLV is the same as the enclosing TLV.

-r
--raw-dump

Raw dump of section, no interpretation.

--tlv syntax

For sections of unknown types, this option specifies how to interpret some parts of the section payload as TLV records. Several --tlv options are allowed, each one describes a part of the section payload.

Each syntax string has the form start,size,tagSize,lengthSize,order. The start and size fields define the offset and size of the TLV area in the section payload. If the size field is auto, the TLV extends up to the end of the section. If the start field is auto, the longest TLV area in the section payload will be used. The fields tagSize and lengthSize indicate the size in bytes of the Tag and Length fields in the TLV structure. The field order must be either msb or lsb and indicates the byte order of the Tag and Length fields.

All fields are optional. The default values are auto,auto,1,1,msb.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

--conax

Interpret all EMM’s and ECM’s from unknown CAS as coming from Conax. Equivalent to --default-cas-id 0x0B00.

--default-cas-id value

Interpret all EMM’s and ECM’s from unknown CAS as coming from the specified CA_System_Id.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--default-pds value

Default DVB-defined private data specifier (PDS). See section 2.4.2 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--irdeto

Interpret all EMM’s and ECM’s from unknown CAS as coming from Irdeto. Equivalent to --default-cas-id 0x0600.

--isdb

--japan

A synonym for --isdb --default-charset ARIB-STD-B24 --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--mediaguard

Interpret all EMM’s and ECM’s from unknown CAS as coming from MediaGuard. Equivalent to --default-cas-id 0x0100.

--nagravision

Interpret all EMM’s and ECM’s from unknown CAS as coming from NagraVision. Equivalent to --default-cas-id 0x1800.

--nds

Interpret all EMM’s and ECM’s from unknown CAS as coming from Synamedia (formerly known as NDS). Equivalent to --default-cas-id 0x0900.

--philippines

--safeaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from SafeAccess. Equivalent to --default-cas-id 0x4ADC.

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

--viaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from Viaccess. Equivalent to --default-cas-id 0x0500.

--widevine

Interpret all EMM’s and ECM’s from unknown CAS as coming from Widevine CAS. Equivalent to --default-cas-id 0x4AD4.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.27. tsresync

Resynchronize corrupted transport stream files

This utility resynchronizes a corrupted transport stream file.

Usage

$ tsresync [options] [input-file]

Parameter

input-file

MPEG transport stream, either a capture file or a pipe from a live stream. Must be a binary stream of transport stream packets, with various encapsulation or possible corruptions.

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Options

-c
--continue

Continue re-resynchronizing after loss of synchronization. By default, stop after first packet not starting with 0x47.

-h value
--header-size value

When used with --packet-size, specifies the size of extra data preceeding each packet in the input file. The default is zero.

-k
--keep

Keep TS packet size from input to output file. By default, strip extra data and reduce packets to 188 bytes. See option --packet-size for a description of supported input packet sizes.

-m value
--min-contiguous value

Minimum size containing contiguous valid packets to consider a slice of input file as containing actual packets (default: 512 kB).

-o file-name
--output file-name

Output file name (standard output by default).

-p value
--packet-size value

Expected TS packet size in bytes. By default, try:

188-byte (standard)
204-byte (trailing 16-byte Reed-Solomon outer FEC)
192-byte (leading 4-byte timestamp in M2TS/Blu-ray disc files).

If the input file contains any other type of packet encapsulation, use options --packet-size and --header-size.

-s value
--sync-size value

Number of initial bytes to analyze to find start of packet synchronization (default: 1 MB).

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.28. tsscan

Digital TV network scanning of frequencies and services

This utility scans frequencies, transport streams and services in a DTV network.

There are two types of scanning:

NIT-based scanning: Modulation parameters must be given. In a first phase, the specified "reference" transport stream is acquired, its NIT is read and all transport stream descriptions (with their delivery system descriptors) are interpreted. In a second phase, all these transport streams are acquired to check their content.
Blind band scanning: This method applies to UHF and VHF bands only, for terrestrial DTV networks. All predefined channels in the selected band in the selected region or country are scanned one by one.

Usage

$ tsscan [options]

Scanning method selection

-n
--nit-scan

Perform a NIT-based scanning.

Tuning parameters for a reference transport stream must be present (frequency or channel reference). The NIT is read on the specified frequency and a full scan of the corresponding network is performed.

-u
--uhf-band

Perform a complete UHF-band scanning (DVB-T, ISDB-T or ATSC).

Use the predefined UHF frequency layout of the specified region (see option --hf-band-region).

By default, scan the center frequency of each channel only. Use option --use-offsets to scan all predefined offsets in each channel.

-v
--vhf-band

Perform a complete VHF-band scanning.

3.29. tssmartcard

Smartcard utility

This utility lists or resets the smart-card readers in the system.

Usage

$ tssmartcard [options] [reader-name]

Parameters

reader-name

The optional reader-name parameter indicates the smart-card reader device name to list or reset.

By default, without any option or parameter, the command lists all smart-card reader devices in the system.

Options

-a hexa-data
--apdu hexa-data

Send an APDU to the smartcard. The APDU shall be specified using an even number of hexadecimal digits. In verbose mode, the APDU, the status word and the response are displayed.

Several --apdu options can be specified. All APDU’s are sent in sequence.

-c
--cold-reset

Perform a cold reset on the smart-card.

--continue-on-error

With --apdu, continue sending next APDU’s after a PC/SC error.

By default, stop when an APDU triggered an error.

-e
--eject

Eject the smart-card (if supported by the reader device).

-t value
--timeout value

Timeout in milliseconds. The default is 1000 ms (1 second).

-w
--warm-reset

Perform a warm reset on the smart-card.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.30. tsstuff

Add stuffing to a TS file to reach a target bitrate

This utility adds stuffing packets to a TS file to reach a target bitrate. Time stamps (PCR or DTS) are extracted from one reference PID in the input file and stuffing packets are added so that the time stamps are approximately synchronized with the TS target bitrate.

Usage

$ tsstuff [options] [input-file]

Parameters

input-file

The input file is a TS file, typically with variable bitrate content.

If the parameter is omitted, is an empty string or a dash (-), the standard input is used.

Options

-b value
--bitrate value

Target constant bitrate of the output file.

See section 2.2 for more details on the representation of bitrates.

This is mandatory parameter, there is no default.

--buffer-size value

Input buffer size, in bytes. Must be large enough to always contain two time stamps in the reference PID. The default is 4,194,304 bytes (4 MB).

-d
--dts-based

Use Decoding Time Stamps (DTS) in the reference PID to evaluate the amount of stuffing to insert. The default is to use Program Clock References (PCR) instead of DTS.

-f value
--final-inter-packet value

Number of stuffing packets to add between input packets after the last time stamp (PCR or DTS). By default, use the same number as in the previous segment, between the last two time stamps.

-i value
--initial-inter-packet value

Number of stuffing packets to add between input packets before the first time stamp (PCR or DTS). By default, use the same number as in the first segment, between the first two time stamps.

--input-format name

Specify the format of the input transport stream file. See section 2.1.2 for more details.

-l value
--leading-packets value

Number of consecutive stuffing packets to add at the beginning of the output file, before the first input packet. The default is zero.

-m milliseconds
--min-interval milliseconds

Minimum interval, in milli-seconds, between two recomputations of the amount of stuffing to insert. This duration is based on timestamps, not real time. The default is 100 ms.

-o filename
--output-file filename

Output file name (standard output by default). The output file is a TS file with the same packets as the input file with interspersed stuffing packets and a constant bitrate.

--output-format name

Specify the format of the output file. See section 2.1.2 for more details. By default, the format is a standard TS file.

-r value
--reference-pid value

PID in which to collect time stamps (PCR or DTS) to use as reference for the insertion of stuffing packets. By default, use the first PID containing the specified type of time stamps (PCR or DTS).

-t value
--trailing-packets value

Number of consecutive stuffing packets to add at the end of the output file, after the last input packet. The default is zero.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.31. tsswitch

Transport stream input source switch using remote control

This utility uses several transport stream inputs and one single output. One input is selected and passed to the output. Using either predefined policies or remote control, it is possible to switch back and forth between inputs.

All inputs and output are performed using external plugins. These plugins are the same as the plugins which are used by tsp.

Using the input plugins file or fork, it is possible to connect applications to some tsswitch input. One of these applications can be tsp, in which case it is possible to insert specific processing between the input plugin and the switch.

See a sample usage with a system diagram in section 5.1.7.

Cycling through input plugins

The list of input plugins is ordered by index on the command line, from 0 to n-1. By default, the input plugin 0 is started when the command starts. When a plugin terminates (end of input or error), the next one is started. When the last plugin terminates, the tsswitch command terminates.

Running all input plugins in sequence, from 0 to n-1, is called a cycle. By default, only one cycle is executed before tsswitch terminates. Using the option --cycle, it is possible to execute a given number of cycles. With the option --infinite, tsswitch runs endlessly.

With the option --terminate, tsswitch terminates when the current plugin terminates. In this case, without remote control, tsswitch only executes the first plugin. If the remote control was used to switch to another input, tsswitch terminates when the current plugin terminates, whichever it is.

Input switching modes

There are three different modes when switching from an input plugin to another one.

By default, only one input plugin is active at a time. When tsswitch starts, the first plugin is started. When an input switch is requested, the current plugin is first stopped. When the stop operation is complete, the next plugin is started. This mode is required when two plugins use the same input device such as a tuner. Since the device cannot be shared, it must be completely stopped and closed before being reused by the next plugin. This is the safest mode. The downside is that there could be a transmission hole in the output during the switch.

With option --delayed-switch, the switching operation is slightly different. The next plugin is started first. In the meantime, output packets continue to be fetched from the previous input plugin. When the next plugin starts to receive packets, the switch is performed: output packets are now read from the next plugin. Finally, the previous input plugin is stopped. This mode guarantees a smooth transition. However, the actual output switch is delayed until the next plugin is fully operational.

With option --fast-switch, all input plugins are started in parallel from the beginning and are never stopped. All input plugins continuously read packets and fill their buffer. The current plugin performs normal flow control with the output plugin, without packet loss. All other input plugins continuously overwrite their circular input buffer. When an input switch is requested, the output plugin immediately jumps into the next plugin buffer where the latest packets are already available. This mode guarantees a smooth and immediate switch. It is appropriate for live streams only.

Remote control

Using the option --remote, tsswitch listens to UDP datagrams on a given port. Each datagram contains one switch command. A command is an ASCII string. Any trailing control characters such as CR or LF is ignored.

The command string can be one of:

An input index (e.g. 0, 1, 2, etc.) Upon reception, tsswitch immediately switches to the selected input plugin.
Strings next and previous (or prev) to switch to the next and previous input, respectively.
Strings exit or quit to properly terminate tsswitch.
Strings halt or abort to immediately abort the tsswitch process.

The bash shell provides an easy way to redirect output to a UDP message. The following sample commands send UDP messages on port 4444 to system 127.0.0.1 (the local host).

$ echo >/dev/udp/127.0.0.1/4444 2
$ echo >/dev/udp/127.0.0.1/4444 next
$ echo >/dev/udp/127.0.0.1/4444 prev
$ echo >/dev/udp/127.0.0.1/4444 exit

This is the easiest way to use the tsswitch remote control. Note that this is a feature of bash, not a Linux feature. It is available on all platforms, including macOS and Cygwin or Msys on Windows.

Event notification

It is possible to notify some external system of switching events, typically when a new input is selected. This can be done in two ways. First, it is possible to launch an external shell command each time a switching event occurs. Second, it is possible to send a JSON description of the event over UDP (possibly on a multicast address if necessary).

As an example, the following command demonstrates both methods at the same time:

$ tsswitch --infinite --event-command "echo ==== EVENT" --event-udp localhost:4444 \
    -I fork "tsp -I file $FILE1 -P regulate -P until --second 5" \
    -I fork "tsp -I file $FILE2 -P regulate -P until --second 5" \
    -O drop

The output of the command illustrates how the --event-command option works:

==== EVENT newinput 0 0
==== EVENT newinput 0 1
==== EVENT newinput 1 0
==== EVENT newinput 0 1
==== EVENT newinput 1 0
==== EVENT newinput 0 1
...

The first message refers to the command startup, using input #0 as initial input. All other messages refer to switching events from input #0 to input #1 or vice-versa.

To demonstrate the usage of the JSON UDP messages, we use the following command from another session running in parallel. It loops on reception of one UDP message using the command nc (netcat). The output of nc is piped into jq (JSON query) to display an indented and colored output of the JSON message.

$ while true; do nc -u -l -w 0 4444 | jq; done
{
  "command": "tsswitch",
  "event": "newinput",
  "new-input": 0,
  "origin": "tsduck",
  "previous-input": 1,
  "timestamp": "2021/03/13 19:33:42.595"
}
{
  "command": "tsswitch",
  "event": "newinput",
  "new-input": 1,
  "origin": "tsduck",
  "previous-input": 0,
  "timestamp": "2021/03/13 19:33:47.688"
}
{
  "command": "tsswitch",
  "event": "newinput",
  "new-input": 0,
  "origin": "tsduck",
  "previous-input": 1,
  "timestamp": "2021/03/13 19:33:52.780"
}
...

Usage

The general syntax of the tsswitch command is the following:

$ tsswitch [tsswitch-options] \
           -I input-name [input-options] ... \
           [-O output-name [output-options]]

All tsswitch-options must be placed on the command line before the input and output plugin specifications. There must be at least one input plugin and at most one output plugin. The default output plugin is file, sending all packets to the standard output.

On the command line, the order of the input plugins is significant. They are indexed from 0 to n-1. This index value is used in the remote control protocol to select an input stream.

Plugin activation options

-I name

Designate a shared library plugin for packet input. There is no default. At least one input plugin shall be specified.

-O name

Designate the shared library plugin for packet output. By default, write packets to standard output.

All input and output plugins which are available for tsp can be used by tsswitch. See the description of the command tsp for the method to locate the plugin files.

General options

-b value
--buffer-packets value

Specify the size in TS packets of each input plugin buffer. The default is 512 packets.

-l
--list-plugins

List all available plugins.

--max-input-packets value

Specify the maximum number of TS packets to read at a time. This value may impact the switch response time. The default is 128 packets. The actual value is never more than half the - -buffer-packets value.

--max-output-packets value

Specify the maximum number of TS packets to write at a time. The default is 128 packets.

Input cycles options

-c value
--cycle value

Specify how many times to repeat the cycle through all input plugins in sequence. By default, all input plugins are executed in sequence only once (--cycle 1). The options --cycle, --infinite and --terminate are mutually exclusive.

--first-input value

Specify the index of the first input plugin to start. By default, the first plugin (index 0) is used.

-i
--infinite

Infinitely repeat the cycle through all input plugins in sequence.

-t
--terminate

Terminate execution when the current input plugin terminates.

Input modes options

-d
--delayed-switch

Perform delayed input switching. When switching from one input plugin to another one, the second plugin is started first. Packets from the first plugin continue to be output while the second plugin is starting. Then, after the second plugin starts to receive packets, the switch occurs: packets are now fetched from the second plugin. Finally, after the switch, the first plugin is stopped.

By default, the current input is first stopped and then the next one is started. Options --delayed-switch and --fast-switch are mutually exclusive.

-f
--fast-switch

Perform fast input switching. All input plugins are started at once and they continuously receive packets in parallel. Packets are dropped, except for the current input plugin. This option is typically used when all inputs are live streams on distinct devices (not the same DVB tuner for instance).

By default, only one input plugin is started at a time. When switching, the current input is first stopped and then the next one is started. Options --delayed-switch and --fast-switch are mutually exclusive.

-p value
--primary-input value

Specify the index of the input plugin which is considered as primary or preferred.

This input plugin is always started, never stopped, even without --fast-switch. When no packet is received on this plugin, the normal switching rules apply. However, as soon as packets are back on the primary input, the reception is immediately switched back to it.

By default, there is no primary input, all input plugins are equal.

--receive-timeout value

Specify a receive timeout in milliseconds (independently of any equivalent feature the input plugins).

When the current input plugin has received no packet within this timeout, automatically switch to the next plugin.

By default, without --primary-input, there is no automatic switch when the current input plugin is waiting for packets. With --primary-input, the default is 2,000 ms.

Remote control options

-a address
--allow address

Specify an IP address or host name which is allowed to send remote commands. Several --allow options can be used to specify several allowed remote control systems.

By default, all received commands are accepted. If at least one --allow option is specified, any remote command which is not sent by an allowed host is rejected.

This is a security feature, but not a perfect one since IP address spoofing is trivial with UDP.

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

-r [address:]port
--remote [address:]port

Specify the local UDP port which is used to receive remote commands. If an optional address is specified, it must be a local IP address of the system. By default, there is no remote control.

--udp-buffer-size value

Specifies the UDP socket receive buffer size in bytes (socket option).

Event notification options

The following options are used to notify external systems of events occurring in tsswitch. Currently, only one type of event is defined: its name is newinput and is signalled when input switching occurs (including the first input when tsswitch starts).

--event-command "command"

When a switch event occurs, run the specified external shell command. This can be used to notify some external system of the event.

The command receives additional parameters:

Event name, currently only newinput is defined.
The input index before the event.
The input index after the event.
Optional: the user data string from --event-user-data option.

These parameters can be used or ignored by the alarm command.

--event-local-address address

With --event-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--event-ttl value

With --event-udp, specifies the TTL (Time-To-Live) socket option. The actual option is either "Unicast TTL" or "Multicast TTL", depending on the destination address. Remember that the default Multicast TTL is 1 on most systems.

--event-udp address:port

When a switch event occurs, send a short JSON description over UDP/IP to the specified destination. This can be used to notify some external system of the event.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

--event-user-data 'string '

A user-defined string which is passed to the event processing.

With --event-command, this string is passed as last parameter of the user-specified command.

With --event-udp, this string is passed as user-data JSON value.

Monitoring options

-m[filename]
--monitor[=filename]

The optional file is an XML monitoring configuration file. See section C.2, for more details on resource monitoring configuration files.

Asynchronous logging options

This application is multi-threaded. Each thread may log messages at any time. To avoid delaying an application thread, the messages are displayed asynchronously in a low priority thread.

--log-message-count value

-s
--synchronous-log

--timed-log

Each logged message contains a time stamp.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.32. tstabcomp

Compile or decompile MPEG tables from XML files

This utility is an MPEG table compiler which takes MPEG tables in source form as XML files and produces binary section files.

The tstabcomp utility is also an MPEG table decompiler. From a binary file containing sections, it recreates an XML file. This XML file can be edited by hand and recompiled for instance.

See section 2.3 for a description of the format of PSI/SI files which can be manipulated by TSDuck and more specifically section 2.3.2 for a complete description of XML files.

Additionally, TSDuck defines automated XML-to-JSON translation rules (see section section 2.7.3). The command tstabcomp can use these translation rules to read input source files in JSON format and write output decompiled tables in JSON format. However, in all cases, XML is used as intermediate format. Input JSON files are translated to XML first and then compiled in binary format. On output, the tables are first decompiled in XML format and then translated to JSON.

Usage

$ tstabcomp [options] input-file ...

Parameters

input-file

XML or JSON source files to compile or binary table files to decompile.

By default, files ending in .xml or .json are compiled and files ending in .bin are decompiled. For other files, explicitly specify --compile or --decompile.

If an input file name is a dash (-), the standard input is used. In that case, --compile or --decompile must be specified since the input file type cannot be deduced from its name.

If an input file name starts with <?xml, it is considered as inline XML content. Similarly, if an input file name starts with { or [, it is considered as inline JSON content.

Options

-c
--compile

Compile all files as XML or JSON source files into binary files. This is the default for .xml or .json files.

-d
--decompile

Decompile all files as binary files into XML files. This is the default for .bin files.

-e
--extensions

With --xml-model, include the content of the available extensions.

-f
--from-json

Each input file must be a JSON file, typically from a previous automated XML-to-JSON conversion or in a similar format.

This is automatically detected for file names ending in .json. This option is only required when the input file name has a non-standard extension or is the standard input.

By default, in decompilation mode, in the absence of .json extension, input files are read as XML.

-j
--json

When decompiling, perform an automated XML-to-JSON conversion. The output file is in JSON format instead of XML. See section 2.7.3 for more details on XML-to-JSON conversion.

-o file-name --output file-name

Specify the output file name.

If the specified path is a directory, the output file is built from this directory and default file name.

If the specified name is a dash (-), the standard output is used.

By default, the output file has the same name as the input and extension .bin (compile), .xml or .json (decompile). The default output file for the standard input (-) is the standard output (-).

If more than one input file is specified, the output path, if present, must be either a directory name or the standard output (-).

-x
--xml-model

Display the XML model of the table files. This model is not a full XML-Schema, this is an informal template file which describes the expected syntax of TSDuck XML files. See section 2.6.3 for a description of XML model files.

If --output is specified, the model is saved here. Do not specify input files.

XML output options

The following options affect details in the generation of XML files.

--strict-xml

Save XML documents in strictly conformant XML format. By default, do not escape characters when this is not syntactically necessary to make the XML text more human-readable.

--x2j-collapse-text
--x2j-enforce-boolean
--x2j-enforce-integer
--x2j-include-root
--x2j-trim-text

Specific options for automated XML-to-JSON conversion. See section 2.7.3.2 for more details.

Sections files options

These options affect the way sections are loaded from binary, XML or JSON files. They are used in commands tspacketize, tstabcomp, and plugin inject.

--eit-actual

With --eit-normalization, generate all EIT Actual. Same as --eit-actual-pf --eit-actual-schedule.

--eit-actual-pf

With --eit-normalization, generate EIT p/f Actual. If no EIT selection option is specified, all EIT’s are generated.

--eit-actual-schedule

With --eit-normalization, generate EIT Schedule Actual. If no EIT selection option is specified, all EIT’s are generated.

--eit-base-date date

With --eit-normalization, use the specified date as reference for the allocation of the various EIT events in sections and segments.

--eit-normalization

Reorganize all EIT sections according to the rules from [ETSI-101-211].

EIT present/following: One single EIT p/f subtable is built per service. It is split in two sections, one for present and one for following events.
EIT schedule: All EIT schedule are kept but they are completely reorganized. All events are extracted and spread over new EIT sections according to ETSI TS 101 211 rules.

If several files are specified, the reorganization of EIT’s is performed inside each file independently. This is fine as long as all EIT’s for a given service are in the same input file.

3.33. tstabdump

Dump MPEG tables and sections

This utility dumps in human readable format MPEG tables, as saved in binary files by the tstables utility for instance.

Usage

$ tstabdump [options] [input-file ...]

Parameters

input-file

Binary section file. Several files can be specified. By default, without file and without --ip-udp, the binary tables are read from the standard input.

With --ip-udp, no file shall be specified. Binary sections and tables are received over UDP/IP as sent by the utility tstables or the plugin tables.

Options

-x value
--max-tables value

Maximum number of tables or sections to dump. Stop logging tables when this limit is reached. This option is useful with --ip-udp which never ends otherwise.

Tables and sections interpretation and formatting options

--ignore-crc32

Do not check CRC32 of input sections. This can be used to analyze sections with incorrect CRC32 but which are otherwise correct.

--no-pager

Do not send output through a pager process. By default, if the output device is a terminal, the output is paged. See section 3.1.4 for more details.

Sections display format options

These options affect the way individual sections are displayed.

-c
--c-style

Same as --raw-dump (no interpretation of section) but dump the bytes in C-language style, e.g. "0x01, 0x02," instead of "01 02". Useful to include this output as data in a C source file.

--nested-tlv[=min-size]

-r
--raw-dump

Raw dump of section, no interpretation.

--tlv syntax

All fields are optional. The default values are auto,auto,1,1,msb.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

--conax

Interpret all EMM’s and ECM’s from unknown CAS as coming from Conax. Equivalent to --default-cas-id 0x0B00.

--default-cas-id value

Interpret all EMM’s and ECM’s from unknown CAS as coming from the specified CA_System_Id.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--default-pds value

Default DVB-defined private data specifier (PDS). See section 2.4.2 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--irdeto

Interpret all EMM’s and ECM’s from unknown CAS as coming from Irdeto. Equivalent to --default-cas-id 0x0600.

--isdb

--japan

A synonym for --isdb --default-charset ARIB-STD-B24 --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--mediaguard

Interpret all EMM’s and ECM’s from unknown CAS as coming from MediaGuard. Equivalent to --default-cas-id 0x0100.

--nagravision

Interpret all EMM’s and ECM’s from unknown CAS as coming from NagraVision. Equivalent to --default-cas-id 0x1800.

--nds

Interpret all EMM’s and ECM’s from unknown CAS as coming from Synamedia (formerly known as NDS). Equivalent to --default-cas-id 0x0900.

--philippines

--safeaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from SafeAccess. Equivalent to --default-cas-id 0x4ADC.

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

--viaccess

Interpret all EMM’s and ECM’s from unknown CAS as coming from Viaccess. Equivalent to --default-cas-id 0x0500.

--widevine

Interpret all EMM’s and ECM’s from unknown CAS as coming from Widevine CAS. Equivalent to --default-cas-id 0x4AD4.

UDP reception options

These options apply only when --ip-udp is used. In this case, the binary sections are received using UDP/IP. No input file is used.

--buffer-size value

Specify the UDP socket receive buffer size in bytes (socket option).

--default-interface

Let the system find the appropriate local interface on which to listen. By default, listen on all local interfaces.

--disable-multicast-loop

Disable multicast loopback.

By default, incoming multicast packets are looped back on local interfaces, if an application sends packets to the same group from the same system. This option disables this.

Warning: On input sockets, this option is effective only on Windows systems. On UNIX systems (Linux, macOS, BSD), this option applies only to output sockets.

--first-source

Filter UDP packets based on the source address. Use the sender address of the first received packet as only allowed source.

This option is useful when several sources send packets to the same destination address and port. Accepting all packets could result in a corrupted stream and only one sender shall be accepted.

To allow a more precise selection of the sender, use option --source. Options --first-source and --source are mutually exclusive.

--ip-udp [[source@]address:]port

Specify that the sections and tables are received from UDP/IP, as sent by tstables or the plugin tables.

The port part is mandatory and specifies the UDP port to listen on. The address part is optional. It specifies an IP multicast address to listen on. It can be also a host name that translates to a multicast address. If the address is not specified, the plugin simply listens on the specified local port and receives the packets which are sent to one of the local (unicast) IP addresses of the system.

An optional source address can be specified as source@address:port in the case of source-specific multicast (SSM).

--local-address address

Specify the IP address of the local interface on which to listen. It can be also a host name that translates to a local address. By default, listen on all local interfaces.

--no-encapsulation

With --ip-udp, receive the tables as raw binary messages in UDP packets. By default, the tables are formatted into TLV messages.

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

--receive-timeout value

Specify the UDP reception timeout in milliseconds. This timeout applies to each receive operation, individually. By default, receive operations wait for data, possibly forever.

--reuse-port

Set the reuse port socket option. This is now enabled by default, the option is present for legacy only.

--source address[:port]

Options --first-source and --source are mutually exclusive.

--ssm

The --ssm option is implicit when the classical SSM syntax source@address:port is used.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.34. tstables

Collect MPEG tables and sections

This utility collects MPEG tables or individual sections from a transport stream. The tables can be saved in a human readable format, in binary or XML files or sent over UDP/IP to some collecting server. It is possible to save the tables in several formats at the same time. By default, the tables are displayed in human-readable format on the standard output.

Usage

$ tstables [options] [input-file]

Parameters

input-file

MPEG transport stream, either a capture file or a pipe from a live stream (see option --format for binary formats). If the parameter is omitted, is an empty string or a dash (-), the standard input is used. Tables and sections selection options

Input options

--format name

Specify the format of the input transport stream. See section 2.1.2 for more details.

Tables selection and manipulation options

--all-once

Same as --all-sections but collect each section only once per combination of PID, table id, table id extension, section number and version.

-a
--all-sections

Display/save all sections, as they appear in the stream. By default, collect complete tables, with all sections of the tables grouped and ordered and collect each version of a table only once. Note that this mode is incompatible with all forms of XML and JSON output since valid XML and JSON structures may contain complete tables only.

-d
--diversified-payload

Select only sections with diversified payload. This means that section payloads containing the same byte value (all 0x00 or all 0xFF for instance) are ignored. Typically, such sections are stuffing and can be ignored that way.

--exclude-current

Exclude short sections and long sections with "current" indicator. This is rarely necessary.

3.35. tsterinfo

DVB-Terrestrial Information

This utility performs various operations and conversions on DVB-T transmission and modulation parameters:

Compute the carrier frequency from a UHF or VHF channel number and optional offset count.
Triggered when option --uhf-channel, --vhf-channel, and optionally --offset-count, are specified.
Retrieve the UHF or VHF channel number and offset count from a carrier frequency.
Triggered when option --frequency is specified.
Compute the nominal transport stream bitrate from OFDM modulation parameters (bandwidth, high-priority stream error correction rate, constellation and guard interval). Supported for non-hierarchical transmission only.
Triggered when options --guard-interval and --high-priority-fec, and optionally --bandwidth and --constellation, are specified.
Given a transport stream bitrate, retrieve the OFDM modulation parameters (bandwidth, high-priority stream error correction rate, constellation and guard interval). Sometimes, several combinations of parameters are possible; they are all reported (see also option --max-guess). This could be useful on Windows systems where the tuners are not able to report their current parameters. In that case, you can use tsanalyze, tsbitrate, or tsp -v to evaluate the transport stream bitrate based on PCR analysis. Then, tsterinfo will retrieve the most probable modulation parameters. Note that only the four mentioned parameters can be retrieved. All other DVB-T transmission parameters are independent from the transport stream bitrate.
Triggered when option --bitrate is specified.

See some examples in section 5.1.5.

Usage

$ tsterinfo [options]

Options

-w value
--bandwidth value

Specify the OFMD bandwith in Hz, used to compute the resulting bitrate.

For compatibility with old versions, "low" values (below 1000) are interpreted in MHz. This means that values 8 and 8,000,000 are identical. Both mean 8 MHz.

The default is 8 MHz.

-b value
--bitrate value

Transport stream bitrate in bits/second, based on 188-byte packets.

See section 2.2 for more details on the representation of bitrates.

Given this bitrate, tsterinfo will try to guess the OFDM modulation parameters: bandwidth, high-priority stream error correction rate, constellation and guard interval.

-c value
--constellation value

Specify the OFMD constellation, used to compute the resulting bitrate. Must be one of QPSK, 16-QAM, 64-QAM (default: 64-QAM).

-d
--default-region

Display the default region for UHF/VHF band frequency layout. See also option --hf-band-region.

-f value
--frequency value

Carrier frequency in Hz. UHF or VHF channel and offset will be displayed.

-g value
--guard-interval value

Specify the OFMD guard interval, used to compute the resulting bitrate. Must be one of 1/32, 1/16, 1/8, 1/4 (no default).

-h value
--high-priority-fec value

Specify the OFMD error correction for high priority streams, used to compute the resulting bitrate. Must be one of 1/2, 2/3, 3/4, 5/6, 7/8 (no default).

-m value
--max-guess value

When used with --bitrate, specify the maximum number of sets of modulation parameters to display. By default, display only one set of parameters, the one giving the closest bitrate. When the given bitrate is not exact and the transmission parameters are uncertain, it may be useful to display more than one possible set of values. The difference between the specified bitrate and nominal bitrate is displayed for each set of parameters. The various sets of parameters are displayed in increasing order of bitrate difference (ie. most probable parameters first). When more than one set of parameters give the same bitrate, they are all displayed, regardless of --max-guess.

-o value
--offset-count value

Specify the number of offsets from the UHF or VHF channel. The default is zero. See options --uhf-channel and --vhf-channel.

-n
--region-names

List all known regions with UHF/VHF band frequency layout.

-s
--simple

Produce simple output: only numbers, no comment, no formatting. Typically useful to write scripts and reuse tsterinfo output.

-u value
--uhf-channel value

Specify the UHF channel number of the carrier. Can be combined with an --offset-count option. The resulting frequency will be displayed.

-v value
--vhf-channel value

Specify the VHF channel number of the carrier. Can be combined with an --offset-count option. The resulting frequency will be displayed.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --hf-band-region brazil . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

-r name
--hf-band-region name

--japan

A synonym for --hf-band-region japan . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --hf-band-region philippines . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--usa

A synonym for --hf-band-region usa . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.36. tstestecmg

Test a DVB SimulCrypt compliant ECMG with an artificial load

This utility is designed to test the resistance of an ECMG. It behaves as a DVB SimulCrypt SCS and connects to one ECMG. It creates several "ECM channels" and several "ECM streams" per channel.

In each ECM stream, tstestecm emulates crypto-periods. At the beginning of each crypto-period, it requests one ECM. The returned ECM is not used, no scrambling is performed, this is just a stress test on the ECMG.

It is possible to run tstestecmg from multiple systems in parallel, connecting to the same ECMG, to emulate very hight loads. Each instance creates multiple channels (be sure to correctly distribute the channel numbers between instances, see option --first-channel-id).

Usage

$ tstestecmg [options] host:port

Test options

--max-ecm count

Stop the test after generating the specified number of ECM’s. By default, the test endlessly runs.

--max-seconds seconds

Stop the test after the specified number of seconds. By default, the test endlessly runs.

--statistics-interval seconds

Specify the interval in seconds between the display of two statistics lines. When set to zero, disable periodic statistics, only display final statistics. The default is 10 seconds.

DVB SimulCrypt options

-a hexa-digits
--access-criteria hexa-digits

Specifies the access criteria as sent to the ECMG. The value must be a suite of hexadecimal digits. All ECM’s are generated using these access criteria. Empty by default.

-c value
--channels value

Specify the number of ECM channels to open. There is one TCP connection to the ECMG per channel. The default is 10 channels.

--cp-duration seconds

Specify the crypto-period duration in seconds. The default is 10 seconds.

--cw-size bytes

Specify the size in bytes of control words. The default is 8 bytes.

--ecmg-scs-version value

Specify the version of the ECMG⇔SCS DVB SimulCrypt protocol. Valid values are 2 and 3. The default is 2.

--first-channel-id value

Specify the first ECM_channel_id value for the ECMG. Subsequent connections use sequential values. The default is 0.

--first-ecm-id value

Specify the first ECM_id value to use in the first stream. Subsequent streams use sequential values. The default is the value of --first-channel-id times the value of --streams-per-channel.

--first-stream-id value

Specify the first ECM_stream_id to use in each channel. Subsequent streams use sequential values. The default is 0.

-s value
--streams-per-channel value

Specify the number of streams to open in each channel. The default is 10.

--super-cas-id value

Specify the DVB SimulCrypt Super_CAS_Id. This is a required parameter.

DVB SimulCrypt logging options

--log-data[=level]

Same as --log-protocol but applies to CW_provision and ECM_response messages only.

To debug the session management without being flooded by data messages, use --log-protocol=info --log-data=debug.

--log-protocol[=level]

A level can be a numerical debug level or any of the following: fatal, severe, error, warning, info, verbose, debug.

Asynchronous logging options

This application is multi-threaded. Each thread may log messages at any time. To avoid delaying an application thread, the messages are displayed asynchronously in a low priority thread.

--log-message-count value

-s
--synchronous-log

-t
--timed-log

Each logged message contains a time stamp.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.37. tsvatek

List VATek-based modulator devices

This utility lists modulator devices which are based on chips from Vision Advance Technology Inc. (VATek). The final modulator device products can be from different manufacturers.

System support

Unlike Dektec and HiDes devices which are available on Linux and Windows only, VATek-based devices are available on all operating systems, including macOS, because VATek chips do not need a dedicated device driver. They are accessed through the portable libusb library which is available on all operating systems.

Usage

$ tshides [options] [device]

Parameters

The optional device index, from 0 to N-1 (with N being the number of VATek-based devices in the system) indicates which device to display.

The default is 0. Use option --all to have a complete list of devices in the system.

Options

-a
--all

List all VATek-based devices available on the system.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

3.38. tsversion

Check version, download and upgrade TSDuck

By default, this utility simply displays the TSDuck version.

Additionally, in prebuilt binary packages of TSDuck as available from tsduck.io or github.com, the tsversion command can also connect to GitHub to list all available releases of TSDuck, check for a new version, download it or upgrade TSDuck to the latest version.

These capabilities are usually disabled in TSDuck packages which are available through a package manager on Linux or through Homebrew on macOS. In these cases, the package manager handles the installation and upgrades of all packages, including TSDuck.

As an example, the following command checks for a new version online and, if one is available, downloads it and upgrades TSDuck:

$ tsversion --upgrade

Detecting the availability of a new release always works. However, to perform an upgrade, the binary packages for the current operating system and architecture must be available online. Not all combinations of binary packages are available. It is only guaranteed that TSDuck can be upgraded by tsversion for Windows 64 bits, the latest version of most 64-bit Linux distros (Fedora, Red Hat & clones, Debian, Ubuntu) and macOS (through Homebrew). For other platforms, you must recompile TSDuck from sources.

Usage

$ tsversion [options]

Common options

-e
--extensions

List all installed TSDuck extensions.

-i
--integer

Display the current version of TSDuck in integer format, suitable for comparison in a script.

Example: 31000669 for 3.10-669 (5 digits are used for the last commit number).

--support name

Check support for a specific feature.

By default, TSDuck is built with all features. However, it may be compiled with specific make options such as NODEKTEC=1 or NOPCSC=1 to remove dependencies on some libraries. The option --support can be used to test if a feature is available.

The feature name must be one of all, dektec, hides, http, pcsc, rist, srt, vatek.

Using all displays all features.

With any other option, tsversion simply exits with a success or failure status, depending if the corresponding feature is implemented or not.

Upgrade options

The following options are available in prebuilt binary packages of TSDuck from tsduck.io or github.com. They may be disabled in TSDuck packages which are available through a package manager on Linux or through Homebrew on macOS.

--all

List all available versions of TSDuck from GitHub.

-b
--binary

With --download, fetch the binary installers of the latest version.

This is the default. When --source is specified, you have to explicitly specify --binary if you also need the binary installers.

-c
--check

Check if a new version of TSDuck is available from GitHub.

-d
--download

Download the latest version (or the version specified by --name) from GitHub. By default, download the binary installers for the current operating system and architecture. Specify --source to download the source code.

If a local file with the same name and size already exists, the local file is reused and the download operation is skipped.

-f
--force

Force downloads even if a file with same name and size already exists.

-l
--latest

Display the latest version of TSDuck from GitHub.

-n version-name
--name version-name

Get information or download from GitHub the specified version, not the latest one.

-o dir-name
--output-directory dir-name

Specify the output directory for downloaded files (current directory by default).

-s
--source

With --download, download the source code archive instead of the binary installers.

-t
--this

Display the current version of TSDuck (this executable).

-u
--upgrade

Upgrade TSDuck to the latest version.

Internet access proxy options

The following options are used to specify how this system accesses Internet.

--proxy-host name

Optional proxy host name for Internet access.

--proxy-password string

Optional proxy password for Internet access (for use with --proxy-user).

--proxy-port value

Optional proxy port for Internet access (for use with --proxy-host).

--proxy-user name

Optional proxy user name for Internet access.

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

Environment variables

Listing versions and information about versions accesses the GitHub site. Remote information is requested from the GitHub API. GitHub limits the anonymous access to its API to a certain number of requests per hour per source IP address. If you get an error such as "API rate limit exceeded", you may have to wait for the next hour and retry. Alternatively, if you are a registered GitHub user and you have a registered authentication token, this rate limit is removed.

Set the value of your authentication token into the environment variable TSDUCK_GITHUB_API_TOKEN before using tsversion. For macOS users, if the environment variable HOMEBREW_GITHUB_API_TOKEN is already defined, it will be used.

3.39. tsxml

Test tool for TSDuck XML manipulation

This simple utility can be used to test some XML files which are manipulated by TSDuck.

Usage

$ tsxml [options] [input-file ...]

Parameters

input-files

Any number of XML files. Input files are processed in sequence.

If an input file is specified as a dash (-), the standard input is used.

General options

--attributes-merge name

With --merge, specify how attributes coming from the XML nodes to merge are processed.

Must be one of:

add: New attributes, not present in the base node, are added. Attributes already existing in the base node are ignored. This is the default.
none: No attribute is copied from the node to merge.
replace: All attributes from the nodes to merge are copied in the base node, replacing existing ones.

-c
--channel

A shortcut for --model tsduck.channels.model.xml.

This option verifies that the input files are valid channel configuration files.

-f
--from-json

Each input file must be a JSON file, typically from a previous automated XML-to-JSON conversion or in a similar format. A reverse automated JSON-to-XML conversion is performed first and the resulting XML document is processed as input.

See section 2.7.3 for more details on XML-to-JSON conversion.

-h
--hf-band

A shortcut for --model tsduck.hfbands.model.xml.

This option verifies that the input files are valid HF bands definition files.

-i value
--indent value

Specify the indentation size of output files. The default is 2 spaces.

-j
--json

Perform an automated XML-to-JSON conversion. The output file is in JSON format instead of XML.

See section 2.7.3 for more details on XML-to-JSON conversion.

-l
--lnb

A shortcut for --model tsduck.lnbs.model.xml.

This option verifies that the input files are valid satellite LNB definition files.

--merge

Merge all input files into one single XML document, instead of processing all input files one by one.

With this option, all input XML files must have the same root tag.

-m filename
--model filename

Specify an XML model file which is used to validate all input files.

The file is automatically searched in the directories for TSDuck configuration files.

--monitor

A shortcut for --model tsduck.monitor.model.xml.

This option verifies that the input files are valid resource monitoring configuration files.

-o filename
--output filename

Specify the name of the output file (standard output by default).

An output file is produced only if --patch, --reformat or --json are specified.

-p filename
--patch filename

Specify an XML patch file. See section 2.6.4 for more details on XML patch files.

All operations which are specified in this file are applied on each input XML file. Several --patch options can be specified. Patch files are sequentially applied on each input file.

This option is useful to test the XML patch files which are applied on the signalisation in various plugins using option --patch-xml.

-r
--reformat

Reformat the input XML files according to the default XML layout for TSDuck XML files. This option is useful to generate an expected output file format.

If more than one input file is specified, they are all reformatted in the same output file.

-s name
--sort name

Specify that the sub-elements of all XML structures with the specified tag name will be sorted in alphanumerical order.

Several --sort options can be specified.

-t
--tables

A shortcut for --model tsduck.tables.model.xml. Table definitions for installed TSDuck extensions are also merged in the main model.

This option verifies that the input files are valid PSI/SI table files.

--uncomment

Remove comments from the XML documents.

--xml-line[='prefix']

Output each transformed input XML file as one single XML line in the message logger instead of an output file.

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

XML output options

The following options affect details in the generation of XML files.

--strict-xml

Save XML documents in strictly conformant XML format. By default, do not escape characters when this is not syntactically necessary to make the XML text more human-readable.

--x2j-collapse-text
--x2j-enforce-boolean
--x2j-enforce-integer
--x2j-include-root
--x2j-trim-text

Specific options for automated XML-to-JSON conversion. See section 2.7.3.2 for more details.

JSON output options

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

Generic common command options

The following options are implicitly defined in all commands.

--debug[=N]

Produce verbose debug output. Specify an optional debug level N (1 by default).

--help

Display the command help text.

--verbose

Produce verbose messages.

--version

Display the version number.

4. TSP Plugins

This chapter contains the reference documentation of all plugins for tsp, the transport stream processor. The input and output plugins can also be used by the command tsswitch.

The following table lists all available plugins.

Table 8. tsp plugins
Plugin	Type	Description
`aes`	packet	Experimental AES scrambling
`analyze`	packet	Analyze the structure of the transport stream
`bat`	packet	Perform various transformations on the BAT
`bitrate_monitor`	packet	Monitor the bitrate of the TS or a given set of PID’s
`boostpid`	packet	Boost the bitrate of a PID, stealing stuffing packets
`cat`	packet	Perform various transformations on the CAT
`clear`	packet	Extract clear (non-scrambled) sequences
`continuity`	packet	Check TS continuity counters
`count`	packet	Count TS packets per PID
`craft`	input, packet	Build or modify specifically crafted packets
`cutoff`	packet	Set labels on TS packets upon reception of UDP messages
`datainject`	packet	DVB SimulCrypt-compliant EMM and private data injector
`decap`	packet	Decapsulate TS packets from a PID produced by `encap` plugin
`dektec`	input, output	Dektec DTA-1xx DVB-ASI and modulator devices I/O
`descrambler`	packet	Generic DVB descrambler
`drop`	output	Drop output packets
`dump`	packet	Dump transport stream packets
`duplicate`	packet	Duplicate PID’s, reusing null packets
`dvb`	input	DVB receiver devices (DVB-S, DVB-C, DVB-T) input
`eit`	packet	Analyze EIT sections
`eitinject`	packet	Generate and inject EIT’s in a transport stream
`encap`	packet	Encapsulate packets from several PID’s into one single PID
`feed`	packet	Extract an inner TS from an outer feed TS (experimental)
`file`	input, output, packet	Transport stream files input / output. As packet processor plugin, save packets to a file and pass to next plugin
`filter`	packet	Filter TS packets according to various criteria
`fork`	input, output, packet	Exchange packets with a created process, either input or output
`fuzz`	packet	Introduce random errors in the transport stream
`hides`	output	Send the transport stream to a HiDes modulator device
`history`	packet	Report a history of major events on the transport stream
`hls`	input, output	Receive or generate HTTP Live Streaming (HLS) media
`http`	input, output	Send / receive a transport stream as / from an HTTP server
`inject`	packet	Inject a table into a transport stream
`ip`	input, output, packet	Send / receive UDP/IP datagrams, including multicast IP and RTP
`isdbinfo`	packet	Extract ISDB-T information from the stream
`limit`	packet	Limit the global bitrate by dropping packets
`memory`	input, output	Direct memory input / output with an application
`merge`	packet	Merge TS packets coming from the output of a created process
`mpe`	packet	Extract MPE (Multi-Protocol Encapsulation) datagrams
`mpeinject`	packet	Encapsulate and inject an incoming UDP stream into MPE
`mux`	packet	Inject TS packets from a file into the transport
`nit`	packet	Perform various transformations on the NIT
`nitscan`	packet	Scan the NIT for tuning information
`null`	input	Null packets generator
`pat`	packet	Perform various transformations on the PAT
`pattern`	packet	Replace packet payload with a binary pattern
`pcap`	input	Read TS packets from a pcap or pcap-ng file
`pcradjust`	packet	Adjust PCR’s according to a constant bitrate
`pcrbitrate`	packet	Permanently recompute bitrate based on PCR’s
`pcrcopy`	packet	Copy and synchronize PCR’s from one PID to another
`pcredit`	packet	Edit PCR, PTS and DTS values in various ways
`pcrextract`	packet	Extract PCR’s from TS packets
`pcrverify`	packet	Verify PCR values
`pes`	packet	Analyze PES packets
`pidshift`	packet	Shift one or more PID’s forward in the transport stream
`play`	output	Play output TS on a media player
`pmt`	packet	Perform various transformations on the PMT
`psi`	packet	Extract all PSI tables (PAT, CAT, PMT, NIT, BAT, SDT)
`psimerge`	packet	Merge PSI/SI from mixed streams
`reduce`	packet	Reduce the bitrate by removing stuffing packets
`regulate`	packet	Regulate TS packets flow according to a bitrate or PCR
`remap`	packet	Generic PID remapper
`rist`	input, output	Send / receive using Reliable Internet Stream Transport (RIST)
`rmorphan`	packet	Remove unreferenced ("orphan") PID’s
`rmsplice`	packet	Remove ads insertions using SCTE 35 splicing information
`scrambler`	packet	DVB scrambler
`sdt`	packet	Perform various transformations on the SDT
`sections`	packet	Remove or merge sections from various PID’s
`sifilter`	packet	Extract PSI/SI PID’s
`skip`	packet	Skip leading packets in a TS
`slice`	packet	Pass or drop packets based on packet numbers or relative time
`spliceinject`	packet	Inject SCTE 35 splice commands in a transport stream
`splicemonitor`	packet	Monitor SCTE 35 splice information
`srt`	input, output	Send / receive packets using Secure Reliable Transport (SRT)
`stats`	packet	Report various statistics on PID’s and labels
`stuffanalyze`	packet	Analyze the level of stuffing in sections
`svremove`	packet	Remove a service
`svrename`	packet	Rename a service (modify service id, name, type, etc.)
`svresync`	packet	Resynchronize the clock of a service based on another service
`t2mi`	packet	Extract T2-MI (DVB-T2 Modulator Interface) packets
`tables`	packet	Collect MPEG tables
`teletext`	packet	Extract Teletext subtitles in SRT format
`time`	packet	Schedule packets pass or drop
`timeref`	packet	Update TDT and TOT with a new time reference
`timeshift`	packet	Delay transmission by a fixed amount of packets
`trace`	packet	Trace packets with a custom message
`trigger`	packet	Trigger actions on selected labeled TS packets
`tsrename`	packet	Rename a transport stream (modify ts id, etc.)
`until`	packet	Pass TS packets until specified conditions
`vatek`	output	Send the transport stream to a VATek-based modulator device
`zap`	packet	Zap on one or more services, remove all other services

Some plugins are related to the scrambling of TS packets and Conditional Access Systems. Please note the following:

The DVB-CSA scrambling algorithm is inherently and purposely very slow with a software implementation. A 3.4 GHz Pentium 4 CPU, for instance, cannot (de)scramble more than 20 Mb/s. Be cautious not to ask for impossible tasks, like real time (de)scrambling of a complete TS on a regular PC.
These tsp plugins are implemented for testing Conditional Access Systems, either on the head-end or set-top box side. TSDuck does not provide any support to hack or circumvent Conditional Access Systems and will never do so. The CAS-related plugins require and use external CAS-provided systems (ECMG, EMMG and smartcards). All secrecy and proprietary CAS information remain isolated inside these external systems and TSDuck does not attempt to access this type of secret and private information. TSDuck only interacts with these systems using their external communication protocols.

4.1. aes

Experimental AES scrambling

This plugin scrambles or descrambles the payload of packets from a specified service using AES and a fixed key. Various chaining modes are allowed. All video, audio and subtitles components of the service are scrambled.

By default, the plugin scrambles the packets. Use the option --descramble to descramble the packets.

Usage

$ tsp -P aes [options] [service]

Parameter

service

Specifies the service to scramble or descramble.

If the parameter is an integer value (either decimal or hexadecimal), it is interpreted as a service id. If its format is integer.integer, it is interpreted as major and minor ids on ATSC streams. Otherwise, the parameter is interpreted as a service name, as specified in the SDT (DVB, ISDB) or VCT (ATSC). Service names are not case sensitive and blanks are ignored. If the input TS does not contain an SDT (DVB, ISDB) or VCT (ATSC), use a service id.

If the service is unspecified, individual PID’s are scrambled (see option --pid).

Options

--cbc

Use Cipher Block Chaining (CBC) mode without padding. The residue (last part of the packet payload, shorter than 16 bytes) is left clear.

--cts1

Use Cipher Text Stealing (CTS) mode. TS packets with a payload shorter than 17 bytes are left clear.

Several incompatible designs of CTS exist. This one implements the description in:

Bruce Schneier, Applied Cryptography (2nd, Ed.), pp 191, 195
RFC 2040, The RC5, RC5-CBC, RC5-CBC-Pad, and RC5-CTS Algorithms
"CBC ciphertext stealing" in http://en.wikipedia.org/wiki/Ciphertext_stealing

--cts2

Use Cipher Text Stealing (CTS) mode. TS packets with a payload shorter than 16 bytes are left clear.

Several incompatible designs of CTS exist. This one implements the description in http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/ciphertext%20stealing%20proposal.pdf

--cts3

Use ECB Cipher Text Stealing (CTS) mode. TS packets with a payload shorter than 17 bytes are left clear.

Several incompatible designs of CTS exist. This one implements the description of "ECB ciphertext stealing" in http://en.wikipedia.org/wiki/Ciphertext_stealing

--cts4

Use ECB Cipher Text Stealing (CTS) mode. TS packets with a payload shorter than 17 bytes are left clear.

Several incompatible designs of CTS exist. This one implements the ECB ciphertext stealing which is used in ST 71xx chips.

-d
--descramble

Descramble instead of scramble.

--dvs042

Use DVS 042 (now ANSI/SCTE 52 2003) cipher block chaining mode. See [SCTE-52].

TS packets with a payload shorter than 16 bytes are left clear. Note that the DVS 042 standard allows the scrambling of short messages (shorter than the cipher block size, ie. 16 bytes with AES) but the two versions of the standard (ANSI/SCTE 52 2003 and ANSI/SCTE 52 2008) have incompatible descriptions of the processing of short messages. To avoid conflicts, this plugin does not scramble these short messages.

--ecb

Use Electronic Code Book (ECB) mode without padding. The residue (last part of the packet payload, shorter than 16 bytes) is left clear.

This is the default mode.

-i hexa-digits
--iv hexa-digits

Specifies the initialization vector. Must be a string of 32 hexadecimal digits. Must not be used in ECB mode and the various ECB-CTS modes (CTS3, CTS4).

The default IV is all zeroes.

-k hexa-digits
--key hexa-digits

Specifies a fixed and constant AES key for all TS packets. The value must be a string of 32 or 64 hexadecimal digits. This is a mandatory parameter.

-p pid1[-pid2]
--pid pid1[-pid2]

Specifies PID’s to scramble. Can be used instead of specifying a service.

Several --pid options may be specified.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --default-charset RAW-ISO-8859-15 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--japan

A synonym for --default-charset ARIB-STD-B24 . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --default-charset RAW-UTF-8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

The options --only-label and --except-label are complementary. When the two are specified, the plugin is invoked for all transport stream packets with any label from --only-label and no label from --except-label.

4.2. analyze

Global transport stream analysis

This plugin performs various types of global analysis on the transport stream.

It is equivalent to the tsanalyze utility. The following two commands produce the same result:

$ tsanalyze options ... filename
$ tsp -I file filename -P analyze options ... -O drop

Usage

$ tsp -P analyze [options]

General purpose options

-c
--cumulative

With --interval, accumulate analysis data of all intervals. With this option, each new report is an analysis from the beginning of the stream.

By default, the analyzed data are reset after each report.

-i seconds
--interval seconds

Produce a new output file at regular intervals. After outputting a file, the analysis context is reset, i.e. each output file contains a fully independent analysis.

-m
--multiple-files

When used with --interval and --output-file, create a new file for each analysis instead of rewriting the previous file. Assuming that the specified output file name has the form base.ext, each file is created with a time stamp in its name as base-YYYYMMDD-hhmmss.ext.

-o filename
--output-file filename

Specify the output text file for the analysis result. By default, use the standard output.

If you do not specify this option, be sure to use a tsp output plugin which redirects the output TS to something different from the default. Otherwise, the text output of the analysis will be mixed with the binary output of the TS packets!

Analysis control options

These options are identical in the command tsanalyze and the tsp plugin analyze.

--suspect-max-consecutive value

Specifies the maximum number of consecutive suspect packets. The default value is one. If set to zero, the suspect packet detection is disabled.

its PID is unknown (no other packet was found in this PID)
it immediately follows a certain amount of packet containing errors (see option --suspect-min-error-count)
it immediately follows no more than the specified number consecutive suspect packets.

--suspect-min-error-count value

Specifies the minimum number of consecutive packets with errors before starting suspect packet detection. See also option --suspect-max-consecutive.

The default value is one. If set to zero, the suspect packet detection is disabled.

Output control options

These options are identical in the command tsanalyze and the tsp plugin analyze.

--deterministic

Enforce a deterministic and reproduceable output. Do not output non-reproduceable information such as system time (useful for automated tests).

--error-analysis

Report analysis about detected errors.

--global-pid-list

--normalized

Complete report about the transport stream, services, PID’s and tables in the old normalized output format. This type of output is useful for automatic analysis in scripts.

--pes-pid-list

Report the list of all PID’s which are declared as carrying PES packets (audio, video, subtitles, etc).

--pid-analysis

Report analysis for each PID.

--pid-list

Report the list of all PID’s.

--prefix 'string'

--service-analysis

Report analysis for each service.

--service-list

Report the list of all service ids.

--service-pid-list value

Report the list of all PID’s which are referenced by the specified service id.

--table-analysis

Report analysis for each table.

--title 'string'

Display the specified string as title header.

--ts-analysis

Report global transport stream analysis.

--unreferenced-pid-list

Report the list of all unreferenced PID’s, that is to say PID’s which are neither referenced by a service nor known as or referenced by the standard DVB PSI/SI.

-w
--wide-display

Use a wider grid display with more information on each line.

JSON output options

--json

Produce a report in JSON output format. Useful for automatic analysis.

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--default-pds value

Default DVB-defined private data specifier (PDS). See section 2.4.2 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--isdb

--japan

A synonym for --isdb --default-charset ARIB-STD-B24 --time-reference JST . See section 2.4.2 and section 2.5.2 for more details.

--philippines

--time-reference name

Use a non-standard time reference in DVB or ISDB-defined SI. See section 2.4.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

Normalized output format

See the corresponding description in the documentation of the tsanalyze command.

4.3. bat

Perform various transformations on a BAT

This plugin performs various transformations on the BAT, either all BAT’s of the transport stream or one specific BAT for one specific bouquet.

Usage

$ tsp -P bat [options]

Options

-b value
--bouquet-id value

Specify the bouquet id of the BAT to modify and leave other BAT’s unmodified. By default, all BAT’s are modified.

--cleanup-private-descriptors

Remove all private descriptors without preceding private_data_specifier_descriptor.

--pds value

With option --remove-descriptor, specify the private data specifier which applies to the descriptor tag values above 0x80.

--remove-descriptor value

Remove from the BAT all descriptors with the specified tag. Several --remove-descriptor options may be specified to remove several types of descriptors. See also option --pds.

-r value
--remove-service value

Remove the specified service_id from the following descriptors: service_list_descriptor, logical_channel_number_descriptor.

Several --remove-service options may be specified to remove several services.

--remove-ts value

Remove from the BAT all references to the transport stream with the specified ts_id value.

Several --remove-ts options may be specified to remove several TS.

Generic options for table manipulation

-b value
--bitrate value

Specifies the bitrate in bits / second of the PID containing the BAT if a new one is created.

See section 2.2 for more details on the representation of bitrates.

The default is 3000 b/s.

-c
--create

Create a new empty BAT if none was received after one second.

This is equivalent to --create-after 1000.

--create-after milliseconds

Create a new empty BAT if none was received after the specified number of milliseconds. If an actual BAT is received later, it will be used as the base for transformations instead of the empty one.

This can be useful to force the creation of a BAT in a TS which has none (the BAT is an optional table).

-i
--increment-version

Increment the version number of the BAT.

--inter-packet value

When a new BAT is created and --bitrate is not present, this option specifies the packet interval for the BAT PID, that is to say the number of TS packets in the transport between two packets of the PID.

Use instead of --bitrate if the global bitrate of the TS cannot be determined.

--patch-xml filename

Specify an XML patch file which is applied to each BAT on the fly. The XML patches are applied first. The other options of this plugin are applied on the patched table.

If the specified name starts with <?xml, it is considered as inline XML content, meaning that the string in the command line is directly the XML content and not a file name.

Several --patch-xml options can be specified. Patch files are sequentially applied on each table.

See section 2.6.4 for more details on XML patch files.

-v value
--new-version value

Specify a new value for the version of the BAT.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.4. bitrate_monitor

Monitor the bitrate of the transport stream or a given set of PID’s

This plugin is used to monitor the bitrate of the complete transport stream or a given set of PID’s. Note that the bitrate is the instantaneous bitrate, meaning that it is computed from the packets received during the last n seconds (n is a plugin parameter, the default value is 5 seconds).

If the bitrate value is outside of the specified range, an alarm is reported.

An alarm command can be specified to report anomalies in a custom way. If such a command is present, it will be called with the problem description as parameters. See an example in section 5.2.30.

Usage

$ tsp -P bitrate_monitor [options]

Options

-a "command"
--alarm-command "command"

Command to run when the bitrate goes either out of range or back to normal.

The command receives the following additional parameters:

A human-readable alarm message.
Either ts or the decimal integer value of the first PID to monitor.
Bitrate alarm state string, one of lower, greater, normal.
Current bitrate in b/s (decimal integer) of TS or set of PID’s.
Minimum bitrate in b/s (decimal integer).
Maximum bitrate in b/s (decimal integer).
Net bitrate, without null packets, in b/s (decimal integer).

These parameters can be used or ignored by the alarm command.

--json-line[='prefix']

Report the bitrate information as one single line in JSON format.

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.

--min value

Set minimum allowed value for bitrate in bits/s.

See section 2.2 for more details on the representation of bitrates.

The default is 10 bits/s.

--max value

Set maximum allowed value for bitrate bits/s.

See section 2.2 for more details on the representation of bitrates.

The default is 2³² bits/s. Note that default values for minimum and maximum bitrate are only useful to detect if the given PID is present or not.

-p value
--periodic-bitrate value

Always report the bitrate and net bitrate (without null packets) at the specific intervals in seconds, even if the bitrate is in range.

--periodic-command value

Run the --alarm-command at the specific intervals in seconds, even if the bitrate is in range.

With this option, the alarm command is run on state change and at periodic intervals.

--pid pid1[-pid2]

Specifies the PID or set of PID’s to monitor.

By default, when no --pid is specified, monitor the bitrate of the full TS. Several --pid options may be specified. When several PID’s are specified, the tested bitrate is the global bitrate of all the selected PID’s.

Compatibility: Previously, the PID to monitor could be specified as a command line parameter, without explicit --pid option. This is still accepted for compatibility for old scripts.

--set-label-above label1[-label2]

Set the specified labels on all packets while the bitrate is above normal.

Several --set-label-above options may be specified.

--set-label-below label1[-label2]

Set the specified labels on all packets while the bitrate is below normal.

Several --set-label-below options may be specified.

--set-label-go-above label1[-label2]

Set the specified labels on one packet when the bitrate goes above normal.

Several --set-label-go-above options may be specified.

--set-label-go-below label1[-label2]

Set the specified labels on one packet when the bitrate goes below normal.

Several --set-label-go-below options may be specified.

--set-label-go-normal label1[-label2]

Set the specified labels on one packet when the bitrate goes back to normal (within range).

Several --set-label-go-normal options may be specified.

--set-label-normal label1[-label2]

Set the specified labels on all packets while the bitrate is normal (within range).

Several --set-label-normal options may be specified.

--tag 'string'

Message tag to be displayed in alarms. Useful when the plugin is used several times in the same process.

-s
--summary

Display a final summary of bitrate statistics.

-t value
--time-interval value

Time interval in seconds used to compute the bitrate. The default is 5 seconds.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.5. boostpid

Boost the bitrate of a PID

This plugin artificially increases the bitrate of a selected PID by adding empty packets (ie. without payload). The plugin does not really insert new packets in the TS, it "steals" stuffing packets.

Usage

$ tsp -P boostpid [options] pid addpkt inpkt

Parameters

pid

The first parameter specifies the PID to boost.

addpkt inpkt

The second and third parameters specify that addpkt TS packets must be automatically added after every inpkt input TS packets in the PID. Both addpkt and inpkt must be non-zero integer values.

As an example, the parameters 3 1 indicate to add 3 new empty packets in the PID for every existing packet. The resulting bitrate of the PID is multiplied by 4.

Take care to limit the added packet ratio to something realistic. The value 1000 1, for instance, is unrealistic since it is impossible, in most cases, to find 1000 stuffing packets to replace between all existing packets of the PID.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.6. cat

Perform various transformations on the CAT

This plugin performs various transformations on the CAT.

Usage

$ tsp -P cat [options]

Options

-a casid/pid[/private-data]
--add-ca-descriptor casid/pid[/private-data]

Add a CA_descriptor in the CAT with the specified CA_System_Id and EMM PID. The optional private data must be a suite of hexadecimal digits.

Several --add-ca-descriptor options may be specified to add several descriptors.

--cleanup-private-descriptors

Remove all private descriptors without preceding private_data_specifier_descriptor.

-r id1[-id2]
--remove-casid id1[-id2]

Remove all CA_descriptor with any of the specified CA_System_Id.

Several --remove-casid options may be specified.

--remove-pid pid1[-pid2]

Remove all CA_descriptor with the specified EMM PID values.

Several --remove-pid options may be specified.

Generic options for table manipulation

-b value
--bitrate value

Specifies the bitrate in bits / second of the PID containing the CAT if a new one is created.

See section 2.2 for more details on the representation of bitrates.

The default is 3000 b/s.

-c
--create

Create a new empty CAT if none was received after one second.

This is equivalent to --create-after 1000.

--create-after milliseconds

Create a new empty CAT if none was received after the specified number of milliseconds. If an actual CAT is received later, it will be used as the base for transformations instead of the empty one.

This can be useful to force the creation of a CAT in a TS which has none (the CAT is an optional table).

-i
--increment-version

Increment the version number of the CAT.

--inter-packet value

When a new CAT is created and --bitrate is not present, this option specifies the packet interval for the CAT PID, that is to say the number of TS packets in the transport between two packets of the PID.

Use instead of --bitrate if the global bitrate of the TS cannot be determined.

--patch-xml filename

Specify an XML patch file which is applied to each CAT on the fly. The XML patches are applied first. The other options of this plugin are applied on the patched table.

If the specified name starts with <?xml, it is considered as inline XML content, meaning that the string in the command line is directly the XML content and not a file name.

Several --patch-xml options can be specified. Patch files are sequentially applied on each table.

See section 2.6.4 for more details on XML patch files.

-v value
--new-version value

Specify a new value for the version of the CAT.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.7. clear

Extract clear (non scrambled) sequences

This plugin extracts clear (non scrambled) sequences of a transport stream.

The extraction is based on one "reference" service (see option --service). When a clear packet is found on any audio or video stream of the reference service, all subsequent packets in the TS are transmitted. When no clear packet has been found in the last second, all subsequent packets in the TS are dropped.

This plugin is typically used after the plugin zap. It let the service pass when it is clear and drops it when it is scrambled.

Usage

$ tsp -P clear [options]

Options

-a
--audio

Check only audio PIDs for clear packets. By default, audio and video PIDs are checked.

-d value
--drop-after-packets value

Specifies the number of packets after the last clear packet to wait before stopping the packet transmission. By default, stop 1 second after the last clear packet (based on current bitrate).

-s name-or-id
--service name-or-id

Specify the reference service.

If this option is not specified, the first service in the PAT is used.

--stuffing

Replace excluded packets with stuffing (null packets) instead of removing them. Useful to preserve bitrate.

-v
--video

Check only video PIDs for clear packets. By default, audio and video PIDs are checked.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --default-charset RAW-ISO-8859-15 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--japan

A synonym for --default-charset ARIB-STD-B24 . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --default-charset RAW-UTF-8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.8. continuity

Check continuity counters

This plugin checks the continuity counters on TS packets, PID per PID.

Usage

$ tsp -P continuity [options]

Options

-f
--fix

Fix incorrect continuity counters. By default, only display discontinuities.

Warning: Make sure that "fixing" the continuity counters is really what you want to do. If the input file is corrupted with missing packets, this plugin cannot restore the content of the missing packets. Non-contiguous continuity counters are here to inform the video player that TS packets are missing and the PES content is probably corrupted. If you use --fix, the continuity counters will become continuous again but the PES content remains corrupted because some binary data are still missing. The difference is that the media player will not be informed that the PES content is corrupted. Make sure that this is what you want to do.

--json-line[='prefix']

Report the continuity information as one single line in JSON format.

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.

--no-replicate-duplicated

Two successive packets in the same PID are considered as duplicated if they have the same continuity counter and same content (except PCR, if any).

By default, with --fix, duplicated input packets are replicated as duplicated on output (the corresponding output packets have the same continuity counters).

When this option is specified, the input packets are not considered as duplicated and the output packets receive individually incremented countinuity counters.

-p pid1[-pid2]
--pid pid1[-pid2]

Check or fix continuity counters only in packets with these PID values.

Several --pid options may be specified. By default, all PID’s are checked or fixed.

-t "string"
--tag "string"

Message tag to be displayed when packets are missing. Useful when the plugin is used several times in the same command line.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.9. count

Count TS packets per PID

This plugin counts packets per PID and provides either a summary of packet counts or a detailed list of packet per PID.

Usage

$ tsp -P count [options]

Options

-a
--all

Report packet index and PID for all packets from the selected PID’s. By default, only a final summary is reported.

-b
--brief

Brief display. Report only the numerical values, not comment on their usage. This option is useful for automatic processing of the resulting output.

-i value
--interval value

Report a timestamp and global packet counts at regular intervals. The specified value is a number of packets.

-n
--negate

Negate the filter: specified PID’s are excluded.

-o filename
--output-file filename

Specify the output file for reporting packet counters. By default, report on standard error using the tsp logging mechanism.

-p pid1[-pid2]
--pid pid1[-pid2]

PID filter: select packets with these PID values. Several --pid options may be specified. By default, if --pid is not specified, all PID’s are selected.

-s
--summary

Display a final summary of packet counts per PID. This is the default, unless --all or --total is specified, in which case the final summary is reported only if --summary is specified.

--tag "string"

Message tag to be displayed with count report lines. Useful when the plugin is used several times in the same command line.

-t
--total

Display the total packet counts in all PID’s.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.10. craft (input)

Build specifically crafted input packets

This plugin generates fake transport stream packets from scratch. The various fields in the packets are specified using command line options.

Usage

$ tsp -I craft [options]

Options

--cc value

Specify the initial value of the continuity counter field (0 by default).

--constant-cc

Do not increment the continuity counter.

By default, the continuity counter in incremented when the packet has a payload.

-c value
--count value

Specify the number of crafted packets to generate. After the last packet, an end-of-file condition is generated.

By default, if --count is not specified, crafted packets are generated endlessly.

--discontinuity

Set the discontinuity_indicator in the packets. An adaptation field is created.

--error

Set the transport_error_indicator in the packets.

--es-priority

Set the elementary_stream_priority_indicator in the packets. An adaptation field is created.

-j
--joint-termination

When --count is specified, perform a joint termination when completed instead of unconditional termination. See the tsp reference documentation for more details on joint termination.

--no-payload

Do not use a payload.

--opcr value

Set this OPCR value in the packets. An adaptation field is created.

--payload-pattern hexa-digits

Specify the binary pattern to apply on packets payload.

The value must be a string of hexadecimal digits specifying any number of bytes. The pattern is repeated to fill the payload. The last repetition of the pattern is truncated if necessary.

The default is FF.

--payload-size value

Specify the size of the packet payload in bytes. When necessary, an adaptation field is created.

Note that --payload-size 0 specifies that a payload exists with a zero size. This is different from --no-payload which also specifies that the payload does not exist.

By default, the payload uses all free space in the packet.

--pcr value

Set this PCR value in the packets. An adaptation field is created.

-p value
--pid value

Specify the PID for the packets (0 by default).

--priority

Set the transport_priority flag in the packets.

--private-data hexa-digits

Specify the complete binary content of the transport_private_data in the adaptation field. The value must be a string of hexadecimal digits specifying any number of bytes.

--pusi

Set the payload_unit_start_indicator in the packets.

--random-access

Set the random_access_indicator in the packets. An adaptation field is created.

--rs204 hexa-digits

Generate a 204-byte packet and specify the binary content to store in the 16-byte trailer. The value must be a string of hexadecimal digits specifying up to 16 bytes. If the data are shorter than 16 bytes, they are padded with 0xFF.

--scrambling value

Specify the value of the transport_scrambling_control field (0 by default).

--splice-countdown value

Create a splicing point and set this splice countdown value in the packets. An adaptation field is created.

Generic input plugins options

The following options are implicitly defined in all input plugins.

--help

Display the plugin help text.

4.11. craft (packet processing)

Craft specific low-level transformations on packets

This plugin modifies precise fields in all TS packets.

Some operations may need space in the adaptation field. By default, the payload is left unmodified and a transformation is rejected if it needs to enlarge the adaptation field since this would destroy part of the existing payload. Enlarging the adaptation field is possible only when --payload-pattern is specified, in which case the payload is overwritten anyway.

Usage

$ tsp -P craft [options]

Options

--clear-discontinuity

Clear the discontinuity_indicator in the packets.

--clear-error

Clear the transport_error_indicator in the packets.

--clear-es-priority

Clear the elementary_stream_priority_indicator in the packets.

--clear-priority

Clear the transport_priority flag in the packets.

--clear-pusi

Clear the payload_unit_start_indicator in the packets.

--clear-random-access

Clear the random_access_indicator in the packets.

--continuity-counter value

Specify the value of the continuity_counter field.

--delete-rs204

Delete the 16-byte trailer of a 204-byte packet, if there is one.

--discontinuity

Set the discontinuity_indicator in the packets. Space is required in the adaptation field.

--error

Set the transport_error_indicator in the packets.

--es-priority

Set the elementary_stream_priority_indicator in the packets. Space is required in the adaptation field.

--no-opcr

Remove the OPCR from the packets.

--no-payload

Remove the payload.

--no-pcr

Remove the PCR from the packets.

--no-private-data

Remove the private data from adaptation field.

--no-repeat

Do not repeat payload pattern operations as specified by options --payload-pattern, --payload-and, --payload-or, --payload-xor. The operation is performed once only.

--no-splice-countdown

Remove the splicing point from the packets.

--offset-pattern value

Specify starting offset in payload when using --payload-pattern. By default, the pattern replacement starts at the beginning of the packet payload.

--opcr value

Set this OPCR value in the packets. Space is required in the adaptation field.

--pack-pes-header

When a TS packet contains the start of a PES packet and the header of this PES packet contains stuffing, shift the TS payload to remove all possible stuffing from the PES header. Create TS stuffing in the adaptation field to compensate.

With PES data streams such as subtitles, the PES header sometimes contains stuffing to make sure that the PES packet uses an integral number of full TS packets. This option is a way to create space in the adaptation field of TS packets without destroying data. Then, PCR or other data can be added in the adaptation fields.

--payload-and hexa-digits

Apply a binary "and" operation on the payload using the specified hexvalue binary pattern.

The value must be a string of hexadecimal digits specifying any number of bytes.

The "and" operation is repeated up to the end of the payload (unless --no-repeat is specified).

--payload-or hexa-digits

Apply a binary "or" operation on the payload using the specified hexvalue binary pattern.

The value must be a string of hexadecimal digits specifying any number of bytes.

The "or" operation is repeated up to the end of the payload (unless --no-repeat is specified).

--payload-pattern hexa-digits

Overwrite the payload with the specified hexvalue binary pattern.

The value must be a string of hexadecimal digits specifying any number of bytes.

The pattern is repeated to fill the payload (unless --no-repeat is specified).

--payload-size size

Resize the packet payload to the specified value in bytes.

When necessary, an adaptation field is created or enlarged. Without --payload-pattern, the existing payload is either shrunk or enlarged.

When an existing payload is shrunk, the end of the payload is truncated. When an existing payload is enlarged, its end is padded with 0xFF bytes.

Note that --payload-size 0 specifies that a payload exists with a zero size. This is different from --no-payload which also specifies that the payload does not exist.

--payload-xor hexa-digits

Apply a binary "exclusive or" operation on the payload using the specified binary pattern.

The value must be a string of hexadecimal digits specifying any number of bytes.

The "exclusive or" operation is repeated up to the end of the payload (unless --no-repeat is specified).

--pcr value

Set this PCR value in the packets. Space is required in the adaptation field.

--pes-payload

With this option, the modified payload is the PES payload, not the TS payload. When the TS packet does not contain the start of a PES packet, the TS payload is not modified.

With --payload-size, the TS payload is resized so that the part of the PES payload which is in the TS packet gets the specified size.

With --payload-pattern and --offset-pattern, the pattern is applied inside the PES payload at the specified offset.

-p value
--pid value

Modify the PID to the specified value.

--priority

Set the transport_priority flag in the packets.

--private-data hexa-digits

Specify the binary content of the transport_private_data in the adaptation field. The value must be a string of hexadecimal digits specifying any number of bytes. Space is required in the adaptation field.

--pusi

Set the payload_unit_start_indicator in the packets.

--random-access

Set the random_access_indicator in the packets. Space is required in the adaptation field.

--rs204 hexa-digits

Specify the binary content to store in the 16-byte trailer of a 204-byte packet. If the packets have no trailer, one is created. The value must be a string of hexadecimal digits specifying up to 16 bytes. If the data are shorter than 16 bytes, they are padded with 0xFF.

--scrambling value

Specify the value of the transport_scrambling_control field.

--splice-countdown value

Create a splicing point and set this splice countdown value in the packets. Space is required in the adaptation field.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.12. cutoff

Set labels on TS packets upon reception of UDP messages

This plugin sets or clears labels on the TS packets upon reception of text commands from UDP.

This plugin is typically used as a remote command reception. Depending on the remote commands, packets are marked and can be processed differently in subsequent plugins in the chain.

Remote commands

The plugin cutoff listens to UDP datagrams on a given port. Each datagram contains exactly one command. A command is an ASCII string. Any trailing control characters such as CR or LF is ignored.

The command string can be one of:

pulse-label n

Set the label n on the next TS packet (only once).

start-label n

Set the label n on all TS packets (until the next stop-label command).

stop-label n

Stop setting the label n on all TS packets.

exit

Exit the tsp execution, simulate an end of stream at the next TS packet.

The bash shell provides an easy way to redirect output to a UDP message. The following sample commands send UDP messages on port 4444 to system 127.0.0.1 (the local host).

$ echo >/dev/udp/127.0.0.1/4444 pulse-label 1
$ echo >/dev/udp/127.0.0.1/4444 start-label 2
$ echo >/dev/udp/127.0.0.1/4444 stop-label 2
$ echo >/dev/udp/127.0.0.1/4444 exit

This is the easiest way to control the plugin cutoff. Note that this is a feature of bash, not a Linux feature. It is available on all platforms, including macOS and Cygwin or Msys on Windows.

Usage

$ tsp -P cutoff [options] [[source@]address:]port

Parameter

The parameter [address:]port describes the destination of incoming UDP datagrams. All datagrams which are received on this stream are text commands.

The port part is mandatory and specifies the UDP port to listen on. The address part is optional. It specifies an IP multicast address to listen on. It can be also a host name that translates to a multicast address.

An optional source address can be specified as source@address:port in the case of source-specific multicast (SSM).

If the address is not specified, the plugin simply listens on the specified local port and receives the packets which are sent to one of the local (unicast) IP addresses of the system.

Options

-a address
--allow address

Specify an IP address or host name which is allowed to send remote commands. Several --allow options can be used to specify several allowed remote control systems.

By default, all received commands are accepted. If at least one --allow option is specified, any remote command which is not sent by an allowed host is rejected.

This is a security feature, but not a perfect one since IP address spoofing is trivial with UDP.

-b value
--buffer-size value

Specify the UDP socket receive buffer size in bytes (socket option).

--default-interface

Let the system find the appropriate local interface on which to listen. By default, listen on all local interfaces.

--disable-multicast-loop

Disable multicast loopback.

By default, incoming multicast packets are looped back on local interfaces, if an application sends packets to the same group from the same system. This option disables this.

Warning: On input sockets, this option is effective only on Windows systems. On UNIX systems (Linux, macOS, BSD), this option applies only to output sockets.

-f
--first-source

Filter UDP packets based on the source address. Use the sender address of the first received packet as only allowed source.

This option is useful when several sources send packets to the same destination address and port. Accepting all commands could result in inconsistent processing and only one sender shall be accepted.

To allow a more precise selection of the sender, use option --source. Options --first-source and --source are mutually exclusive.

-l address
--local-address address

Specify the IP address of the local interface on which to listen. It can be also a host name that translates to a local address. By default, listen on all local interfaces.

--max-queue value

Specify the maximum number of queued UDP commands before their execution into the stream. The default is 128.

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

--receive-timeout value

Specify the UDP reception timeout in milliseconds. This timeout applies to each receive operation, individually.

By default, receive operations wait for commands, possibly forever.

-r
--reuse-port

Set the reuse port socket option. This is now enabled by default, the option is present for legacy only.

-s address[:port]
--source address[:port]

Filter UDP packets based on the specified source address.

This option is useful when several sources send packets to the same destination address and port. Accepting all commands could result in inconsistent processing and only one sender shall be accepted.

Options --first-source and --source are mutually exclusive.

--ssm

The --ssm option is implicit when the classical SSM syntax source@address:port is used.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.13. datainject

DVB-SimulCrypt EMM and private data injector

This plugin receives EMM’s and/or private data using the DVB SimulCrypt EMMG/PDG⇔MUX protocol and injects them into the transport stream in a specific PID.

This plugin is a TCP server (MUX side of the protocol). It accepts only one EMMG/PDG connection at a time.

If the injected data are EMM’s, make sure to update the CAT accordingly (see the plugin cat).

Usage

$ tsp -P datainject [options]

Options

-b value
--bitrate-max value

Specifies the maximum bitrate for the data PID in bits / second.

See section 2.2 for more details on the representation of bitrates.

By default, the data PID bitrate is limited by the stuffing bitrate (data insertion is performed by replacing stuffing packets).

--buffer-size value

Specify the TCP and UDP socket receive buffer size in bytes (socket option).

-v value
--emmg-mux-version value

Specifies the version of the EMMG/PDG⇔MUX DVB SimulCrypt protocol. Valid values are 1 to 5. The default is 2.

--no-reuse-port

Disable the reuse port socket option. Do not use unless completely necessary.

-p value
--pid value

Specifies the PID for the data insertion.

This option is mandatory, there is no default.

-q value
--queue-size value

Specifies the maximum number of data sections or TS packets in the internal queue, i.e. messages which are received from the EMMG/PDG client but not yet inserted into the transport stream.

The default is 1000.

-r
--reuse-port

Set the reuse port socket option. This is now enabled by default, the option is present for legacy only.

-s [address:]port
--server [address:]port

Specifies the local TCP port on which the plugin listens for an incoming EMMG/PDG connection. This option is mandatory.

When present, the optional address shall specify a local IP address or host name (by default, the plugin accepts connections on any local IP interface).

This plugin behaves as a MUX, ie. a TCP server, and accepts only one EMMG/PDG connection at a time.

-u [address:]port
--udp [address:]port

Specifies the local UDP port on which the plugin listens for data provision messages (these messages can be sent using TCP or UDP).

By default, the UDP reception uses the same port and optional local address as specified for TCP using option --server.

--unregulated

Insert data packets immediately. Do not regulate the insertion of data packets, do not limit the data bitrate.

This is useful to test invalid EMMG’s which do not comply with the allocated bitrate policy.

DVB SimulCrypt logging options

--log-data[=level]

Same as --log-protocol but applies to data_provision messages only.

To debug the session management without being flooded by data messages, use --log-protocol=info --log-data=debug.

--log-protocol[=level]

A level can be a numerical debug level or any of the following: fatal, severe, error, warning, info, verbose, debug.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.14. decap

Decapsulate TS packets from a PID produced by the encap plugin

This plugin is the counterpart of the encap plugin. It decapsulates the original TS packets from a "tunnel PID" which was created by encap. See the documentation of the encap plugin for more details.

The decapsulated packets replace the tunnel PID. Because of the encapsulation overhead, the total volume of decapsulated packets is slightly smaller (approximately 2%) than the encapsulation PID. The packets in excess are replaced by null packets after decapsulation.

Usage

$ tsp -P decap [options]

Options

-i
--ignore-errors

Ignore errors such as malformed encapsulated stream.

-p value
--pid value

Specify the input PID containing all encapsulated PID’s.

This is a mandatory parameter, there is no default.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.15. dektec (input)

Dektec DTA-1xx and DTU-2xx ASI, GigE and demodulator devices

This input plugin receives packets from a Dektec DTA-1xx or DTU-2xx DVB-ASI or demodulator device.

Using this plugin forces tsp and all plugins to use their real-time defaults (see the reference documentation for tsp).

Restrictions

This plugin is available on Linux and Windows only, Intel processors only. Dektec provides no software support on macOS and other processors. Moreover, this plugin may be unavailable on some Linux distributions since it integrates a closed-source library from Dektec, which is prohibited by the policy of some distributions.

TSDuck manipulates transport stream packets only. Consequently, this plugin only supports input/output modes which process MPEG-TS packets. Some Dektec devices support other modes such as SDI, HDMI, ATSC-3.0 which handle other formats. These modes cannot be used with TSDuck.

Usage

$ tsp -I dektec [options]

General options

-c value
--channel value

Channel index on the input Dektec device. By default, use the first input channel on the device.

-d value
--device value

Device index, from 0 to N-1 (with N being the number of Dektec devices in the system). Use the command tsdektec -a to have a complete list of devices in the system.

By default, use the first input Dektec device.

--fifo-size value

Set the reception FIFO size in bytes of the input channel in the Dektec device.

The default value depends on the device type.

--io-standard name

Specify the I/O standard to use on the device port. This option applies to multi-standard ports such as ASI/SDI ports. The list possible values for this option is given in the table below.

Which modes are supported in practice depend on the device model. See the Dektec documentation for more details.

Table 9. Values for option `--io-standard` (`dektec` plugins)
Value	Description
`ASI`	DVB-ASI transport stream
`SPI`	DVB-SPI transport stream
`IF-AD-converter`	IF A/D converter
`IP`	Transport stream over IP
`dektec-streaming`	DekTec Streaming-data Interface
`demodulator`	Demodulator input
`modulator`	Modulator output

--preload-fifo

Wait for the reception FIFO (hardware buffer) to be half-full before starting reception.

-t value
--receive-timeout value

Specify the data reception timeout in milliseconds. This timeout applies to each receive operation, individually. By default, receive operations wait for data, possibly forever.

Demodulators options

The following options are used with Dektec demodulator devices.

--c2-bandwidth value

DVB-C2 demodulators: indicate the DVB-C2 bandwidth.

Must be one of 6-MHz, 8-MHz. The default is 8-MHz.

--code-rate value

For demodulator devices only: specify the code rate. The specified value depends on the modulation type.

DVB-S:

1/2, 2/3, 3/4, 4/5, 5/6, 6/7, 7/8.

DVB-S2:

1/2, 1/3, 1/4, 2/3, 2/5, 3/4, 3/5, 4/5, 5/6, 6/7, 7/8, 8/9, 9/10.

DVB-T:

1/2, 2/3, 3/4, 5/6, 7/8.

The value auto can be used to automatically detect the code rate. This is the default.

--constellation value

DVB-T demodulators: indicate the constellation type.

Must be one of 16-QAM, 64-QAM, QPSK, auto.

The value auto can be used to automatically detect the constellation. This is the default.

--dvbt-bandwidth value

DVB-T/T2 demodulators: indicate the bandwidth in MHz. The default is 8 MHz.

Must be one of 1.7, 10, 5, 6, 7, 8. The bandwidth values 1.7, 5 and 10 MHz are valid for DVB-T2 only.

-f value
--frequency value

For demodulator devices only: specify the frequency, in Hz, of the input carrier. There is no default.

For DVB-S/S2 receivers, the specified frequency is the intermediate frequency. For convenience, the option --satellite-frequency can be used instead of --frequency when the intermediate frequency is unknown. When --frequency is used with DVB-S/S2, the original satellite frequency is unknown, it is impossible to determine if a high band is used and no "high band 22 kHz tone" is send to the LNB.

For DTA-2137 receivers, the valid range is 950 MHz to 2150 MHz (L Band).

--guard-interval value

DVB-T demodulators: indicate the guard interval.

Must be one of 1/16, 1/32, 1/4, 1/8, auto. The default is auto.

--isdbt-bandwidth value

ISDB-T demodulators: indicate the bandwidth in MHz.

Must be one of 5, 6, 7, 8. The default is 8 MHz.

--isdbt-segments value

ISDB-T demodulators: indicate the number of segments.

Must be one of 1, 3 or 13. The default is 1.

--isdbt-subchannel value

ISDB-T demodulators: indicate the sub-channel number (0 to 41) of the centre segment of the spectrum. The default is 22.

--j83 value

QAM demodulators: indicate the ITU-T J.83 annex to use. Must be one of A, B, C. A is DVB-C, B is "American QAM", C is "Japanese QAM". The default is A.

--lnb string

DVB-S/S2 receivers: description of the LNB which is used to convert the --satellite-frequency into an intermediate frequency. This option is useless when --satellite-frequency is not specified.

See section A.3 for more details.

-m value
--modulation value

For demodulators, indicate the modulation type. The supported modulation types depend on the device model. The default modulation type is DVB-S.

Must be one of ATSC-VSB, DAB, DVB-C2, DVB-S, DVB-S-QPSK (same as DVB-S), DVB-S2, DVB-S2-QPSK (same as DVB-S2), DVB-S2-8PSK, DVB-S2-16APSK, DVB-S2-32APSK, DVB-T, DVB-T2, ISDB-T, QAM (auto-detection of QAM type), 16-QAM, 32-QAM, 64-QAM, 128-QAM, 256-QAM.

--polarity value

DVB-S/S2 receivers: indicate the polarity.

Must be one of horizontal, vertical. The default is vertical.

--qam-b value

QAM demodulators: with --j83 B, indicate the QAM-B interleaver mode.

Must be one of I8-J16, I16-J8, I32-J4, I64-J2, I128-J1, I128-J1D, I128-J2, I128-J3, I128-J4, I128-J5, I128-J6, I128-J7, I128-J8, auto. The default is auto.

--satellite-frequency value

DVB-S/S2 receivers: indicate the target satellite frequency, in Hz, of the input carrier. The actual frequency at the input of the receiver is the intermediate frequency which is computed based on the characteristics of the LNB (see option --lnb). This option is useful when the satellite frequency is better known than the intermediate frequency.

The options --frequency and --satellite-frequency are mutually exclusive.

--satellite-number value

DVB-S/S2 receivers: indicate the satellite/dish number.

Must be 0 to 3 with DiSEqC switches and 0 to 1 for non-DiSEqC switches. The default is 0.

--symbol-rate value

DVB-C/S/S2 demodulators: Specify the symbol rate in symbols/second.

By default, automatically detect the symbol rate.

--t2-profile value

DVB-T2 demodulators: indicate the DVB-T2 profile.

Must be one of base, lite. The default is base.

--transmission-mode value

DVB-T demodulators: indicate the transmission mode.

Must be one of 2K, 8K, auto. The default is auto.

--vsb value

ATSC demodulators: indicate the VSB constellation.

Must be one of 8, 16. The default is 8.

TS-over-IP options

The following options are used with Dektec Ethernet devices.

--ip4 ipv4-address:port

TS-over-IP: Destination IPv4 address and port.

Either --ip4 or --ip6 must be specified with Dektec Ethernet devices. The address part is mandatory for multicast, optional for unicast.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--ip6 [ipv6-address]:port

TS-over-IP: Destination IPv6 address and port.

Important: The square brackets are literal, as in any IPv6 URL, not an indication of an optional field.

Either --ip4 or --ip6 must be specified with Dektec Ethernet devices. The address part is mandatory for multicast, optional for unicast.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--smpte-2022-fec

TS-over-IP: Use SMPTE-2022 error correction.

--ssm4-filter ipv4-address:port

TS-over-IP: Specify optional IPv4 source-specific multicast (SSM) filter.

The port number is optional. This option may be repeated to filter on multiple sources.

With SMPTE 2022-7 network redundancy, the same list of filters is used in both links.

--ssm6-filter [ipv6-address]:port

TS-over-IP: Specify optional IPv6 source-specific multicast (SSM) filter.

Important: The square brackets are literal, as in any IPv6 URL, not an indication of an optional field.

The port number is optional. This option may be repeated to filter on multiple sources.

With SMPTE 2022-7 network redundancy, the same list of filters is used in both links.

--vlan-id value

TS-over-IP: Optional VLAN identifier as specified in IEEE 802.1Q.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

Generic input plugins options

The following options are implicitly defined in all input plugins.

--help

Display the plugin help text.

4.16. dektec (output)

Dektec DTA-1xx and DTU-2xx ASI, GigE and modulator devices

This output plugin sends packets to a DVB-ASI Dektec DTA-1xx or DTU-2xx device or a Dektec DTA-1xx modulator.

Using this plugin forces tsp and all plugins to use their real-time defaults (see the reference documentation for tsp).

Restrictions

Usage

$ tsp -O dektec [options]

Overview of options

For multi-standard modulators such as the DTA-115, the type of required modulation must be specified if it is different from the default modulation. See the table below for the default modulation type by device model.

Table 10. Dektec modulators default modulation types
Device model	Default modulation
DTA-107	DVB-S (QPSK)
DTA-107.S2	DVB-S2 (QPSK)
DTA-110	DVB-C (64-QAM)
DTA-110T	DVB-T
DTA-115	DVB-T

Depending on the type of output, the combination of required and optional options is different. See the next table for the applicability of options by modulation type. The modulation type is specified using option --modulation.

Table 11. Command line options for Dektec modulators
Modulation	Applicable options
All (common options)	`--bitrate --channel --device --stuffing --fifo-size`
DVB-ASI	`--204`
All except DVB-ASI	`--frequency --instant-detach --inversion --level --modulation --offset-count --uhf-channel --vhf-channel`
x-QAM	`--j83 --qam-b`
ADBT-T, DMB-T/H	`--bandwidth --dmb-constellation --dmb-fec --dmb-frame-numbering --dmb-header --dmb-interleaver --pilots`
ATSC	`--vsb --vsb-taps`
DVB-S	`--convolutional-rate --lnb --satellite-frequency --symbol-rate`
DVB-S2	`--convolutional-rate --lnb --pilots --roll-off --s2-gold-code --s2-short-fec-frame --satellite-frequency --symbol-rate`
DVB-T	`--bandwidth --cell-id --constellation --convolutional-rate --guard-interval --indepth-interleave --mpe-fec --time-slice --transmission-mode`
DVB-T2	`--bandwidth --bandwidth-extension --cell-id --fef --fef-interval --fef-length --fef-s1 --fef-s2 --fef-signal --fef-type --fft-mode --miso --papr --pilot-pattern --plp0-code-rate --plp0-fec-type --plp0-group-id --plp0-high-efficiency --plp0-id --plp0-il-length --plp0-il-type --plp0-in-band --plp0-issy --plp0-modulation --plp0-null-packet-deletion --plp0-rotation --plp0-tsrate --plp0-type --t2-fpsf --t2-guard-interval --t2-l1-modulation --t2-network-id --t2-system-id`

General options

--204

For DVB-ASI devices only: Send 204-byte packets (188 meaningful bytes plus 16 stuffing bytes for Reed-Solomon coding). By default, send 188-byte packets.

-b value
--bitrate value

Specify the output bitrate in bits/second.

This option is not mandatory but highly recommende to get a precise output. By default, use the input device bitrate or, if the input device cannot report bitrate, analyze some PCR’s at the beginning of the input stream to evaluate the original bitrate of the transport stream.

See section 2.2 for more details on the representation of bitrates.

-c value
--channel value

Channel index on the output Dektec device. By default, use the first output channel on the device.

-d value
--device value

Device index, from 0 to N-1 (with N being the number of Dektec devices in the system). Use the command tsdektec -a to have a complete list of devices in the system. By default, use the first output Dektec device.

--drop-to-maintain-preload

If the FIFO were preloaded, and maintaining the preload via option --maintain-preload, drop any packets that would exceed the preload FIFO size plus a small threshold.

--fifo-size value

Set the FIFO size in bytes of the output channel in the Dektec device. The default value depends on the device type.

--instant-detach

At end of stream, perform an instant detach of the output channel. The transmit FIFO is immediately cleared without waiting for all data to be transmitted. With some Dektec devices, the default mode may hang at end of stream and --instant-detach avoids this.

The options --instant-detach and --wait-detach are mutually exclusive.

--io-standard name

Specify the I/O standard to use on the device port. This option applies to multi-standard ports such as ASI/SDI ports. The list possible values for this option is given in the table below.

Which modes are supported in practice depend on the device model. See the Dektec documentation for more details.

Table 12. Values for option `--io-standard` (`dektec` plugins)
Value	Description
`ASI`	DVB-ASI transport stream
`SPI`	DVB-SPI transport stream
`IF-AD-converter`	IF A/D converter
`IP`	Transport stream over IP
`dektec-streaming`	DekTec Streaming-data Interface
`demodulator`	Demodulator input
`modulator`	Modulator output

--maintain-preload

If the FIFO were preloaded (see options --preload-fifo and --drop-to-maintain-preload), roughly maintain the FIFO buffer size in order to maintain the delay from real-time. If the FIFO size drops to zero bytes, pause transmission till it gets back to the preload FIFO size.

--power-mode value

DTU-315 modulators: set the power mode to the specified value.

Must be one of high-quality, low-power.

--preload-fifo

Preload FIFO (hardware buffer) before starting transmission.

Preloading the FIFO will introduce a variable delay to the start of transmission, if the delivery of packets to the plug-in is pre-regulated, based on the size of the FIFO, the TS bit rate, and the size of the FIFO to preload, as controlled by the --preload-fifo-percentage or --preload-fifo-delay options.

If the delivery of packets to the plug-in is not self-regulated (i.e. they are delivered faster than real-time, as might occur when loading from file), there is no benefit to preloading the FIFO, because in that case, the FIFO will fill up quickly anyway.

This option is implicitly set when using a modulator for output.

--preload-fifo-delay value

The use of this option indicates that the size of the FIFO to preload prior to starting transmission should be calculated based on the specified delay, in milliseconds, and the configured bit rate. That is, transmission will start after the specified delay worth of media has been preloaded.

This option takes precedence over the --preload-fifo-percentage option.

There is no default value, and the valid range is 100-100000.

--preload-fifo-percentage value

Percentage of size of FIFO to preload prior to starting transmission (default: 80%).

-s
*--stuffing

Automatically generate stuffing packets if tsp fails to provide packets fast enough.

This option applies only to ASI, SDI and hardware-based modulators (DVB-C, DVB-S). This option is ineffective on modulators which are partially software-based (DVB-T on DTA-110T or DTA-115).

--wait-detach

At end of stream, the plugin waits until all bytes in the transmit FIFO are sent. Some Dektec devices may hang on detach in that case. You should try first.

The options --instant-detach and --wait-detach are mutually exclusive.

Modulators options

The following options are used with Dektec modulator devices.

--bandwidth value

DVB-T/H, DVB-T2, ADTB-T and DMB-T/H modulators: indicate bandwidth in MHz.

Must be one of 1.7, 5, 6, 7, 8 or 10. The default is 8 MHz. The bandwidth values 1.7 and 10 MHz are valid for DVB-T2 only.

--bandwidth-extension

DVB-T2 modulators: indicate that the extended carrier mode is used.

By default, use normal carrier mode.

--carrier-only

Output the carrier frequency only, without modulated transport stream. All output packets are dropped.

Sample usage: To generate an empty carrier and wait forever, use the following command:

$ tsp --final-wait 0 -I null 1 -O dektec --carrier-only --frequency ...

This is a minimal command which generates only one input packet and then wait forever. Using the null input plugin alone would also work. However, it would saturate the CPU, looping on null packet generation, dropping them later. The above command just generates one packet (this is the required minimum to start the output plugin) and then does nothing except maintaining the output carrier frequency.

--cell-id value

DVB-T and DVB-T2 modulators: indicate the cell identifier to set in the transmission parameters signaling (TPS). Disabled by default with DVB-T. Default value is 0 with DVB-T2.

--constellation value

DVB-T modulators: indicate the constellation type. Must be one of QPSK, 16-QAM, 64-QAM. The default is 64-QAM.

-r rate
--convolutional-rate rate

For modulators devices only: specify the convolutional rate. The specified value depends on the modulation type. The default is 3/4.

DVB-S:

1/2, 2/3, 3/4, 4/5, 5/6, 6/7, 7/8.

DVB-S2:

1/2, 1/3, 1/4, 2/3, 2/5, 3/4, 3/5, 4/5, 5/6, 6/7, 7/8, 8/9, 9/10.

DVB-T:

1/2, 2/3, 3/4, 5/6, 7/8.

--dmb-constellation value

DMB-T/H, ADTB-T modulators: indicate the constellation type. Must be one of: 4-QAM-NR, 4-QAM, 16-QAM, 32-QAM, 64-QAM. The default is 64-QAM. 4-QAM-NR and 32-QAM can be used only with --dmb-fec 0.8.

--dmb-fec value

DMB-T/H, ADTB-T modulators: indicate the FEC code rate. Must be one of 0.4, 0.6, 0.8. The default is 0.8.

--dmb-frame-numbering

DMB-T/H, ADTB-T modulators: indicate to use frame numbering. The default is to use no frame numbering.

--dmb-header value

DMB-T/H, ADTB-T modulators: indicate the FEC frame header mode. Must be one of PN420, PN595 (ADTB-T only) or PN945. The default is PN945.

--dmb-interleaver value

DMB-T/H, ADTB-T modulators: indicate the interleaver mode. Must be one of 1 (B=54, M=240) or 2 (B=54, M=720). The default is 1.

--fef

DVB-T2 modulators: enable insertion of FEF (Future Extension Frames). Not enabled by default.

--fef-interval value

DVB-T2 modulators: indicate the number of T2 frames between two FEF parts. The valid range is 1 to 255 and --t2-fpsf shall be divisible by --fef-interval. The default is 1.

--fef-length value

DVB-T2 modulators: indicate the length of a FEF-part in number of T-units (= samples). The valid range is 0 to 0x3FFFFF. The default is 1.

--fef-s1 value

DVB-T2 modulators: indicate the S1-field value in the P1 signalling data. Valid values: 2, 3, 4, 5, 6 and 7. The default is 2.

--fef-s2 value

DVB-T2 modulators: indicate the S2-field value in the P1 signalling data. Valid values: 1, 3, 5, 7, 9, 11, 13 and 15. The default is 1.

--fef-signal value

DVB-T2 modulators: indicate the type of signal generated during the FEF period. Must be one of 0 (zero I/Q samples during FEF), 1K (1K OFDM symbols with 852 active carriers containing BPSK symbols, same PRBS as the T2 dummy cells, not reset between symbols) or 1K-384 (1K OFDM symbols with 384 active carriers containing BPSK symbols). The default is 0.

--fef-type value

DVB-T2 modulators: indicate the FEF type. The valid range is 0 … 15. The default is 0.

--fft-mode value

DVB-T2 modulators: indicate the FFT mode. Must be one of 1K, 2K, 4K, 8K, 16K or 32K. The default is 32K.

-f value
--frequency value

For modulator devices only: specify the frequency, in Hz, of the output carrier. There is no default.

For OFDM modulators, the options --uhf-channel or --vhf-channel and --offset-count (optional) may be used instead.

For DVB-S/S2 modulators, the specified frequency is the intermediate frequency. For convenience, the option --satellite-frequency can be used instead of --frequency when the intermediate frequency is unknown.

For DTA-107 (DVB-S) modulators, the valid range is 950 MHz to 2150 MHz.

For DTA-110 (DVB-C) and 110T (DVB-T/H) modulators, the valid range is 400 MHz to 862 MHz.

For DTA-115 (DVB-C/T/H) modulators, the valid range is 47 MHz to 862 MHz.

-g value
--guard-interval value

DVB-T modulators: indicate the guard interval. Must be one of: 1/32, 1/16, 1/8, 1/4. The default is 1/32.

--hf-band-region name

Specify the region for UHF/VHF band frequency layout.

The default region is europe. Another default region may be specified per user in the TSDuck configuration file. See section A.4 for more details.

--indepth-interleave

DVB-T modulators: use in-depth interleave. The default is native interleave.

-i
--input-modulation

All modulators devices: try to guess default modulation parameters from input stream. All explicitely specified parameters override these defaults.

If the input plugin is dvb, use the modulation parameters of the input signal as default values for their counterparts in the Dektec modulator. On Linux systems, the actual modulation parameters of the input signal are used. On Windows systems, the DirectShow/BDA drivers cannot return the actual modulation parameters and only the user-specified parameters in the input plugin are used (they can be different from the actual parameters of the input signal).

With other input plugins, if the specified output modulation is DVB-T or DVB-T2, try to guess the following modulation parameters from the input bitrate: --bandwidth --constellation --convolutional-rate --guard-interval. When a specific bitrate can be produced by distinct combinations of modulation parameters, a deterministic order is applied to select the prefered combination.

--inversion

For modulators devices only: enable spectral inversion.

--j83 value

QAM modulators: indicate the ITU-T J.83 annex to use. Must be one of A (DVB-C), B (American QAM) or C (Japanese QAM). The default is A.

-l value
--level value

Modulators: indicate the output level in units of 0.1 dBm (e.g. --level -30 means -3 dBm). Not supported by all devices.

For DTA-107 modulators, the valid range is -47.0 to -27.0 dBm.

For DTA-115, QAM, the valid range is -35.0 to 0.0 dBm.

For DTA-115, OFDM, ISDB-T, the valid range is -38.0 to -3.0 dBm.

--lnb string

DVB-S/S2 modulators: description of the LNB which is used to convert the --satellite-frequency into an intermediate frequency. This option is useless when --satellite-frequency is not specified.

See xref:[xrefstyle=short] A.3 page 492 for more details.

--miso value

DVB-T2 modulators: indicate the MISO mode. Must be one of OFF, 1, 2 or BOTH. The default is OFF. This mode can be used to simulate antenna 1, antenna 2, or the average of antenna 1 and antenna 2 to simulate reception halfway between the antennas.

-m value
--modulation value

For modulators, indicate the modulation type. Must be one of: 4-QAM, 16-QAM, 32-QAM, 64-QAM, 128-QAM, 256-QAM, ADTB-T, ATSC-VSB, DMB-T, DVB-S, DVB-S-QPSK (same as DVB-S), DVB-S-BPSK, DVB-S2, DVB-S2-QPSK (same as DVB-S2), DVB-S2-8PSK, DVB-S2-16APSK, DVB-S2-32APSK, DVB-T, DVB-T2, ISDB-T. For DVB-H, specify DVB-T. For DMB-H, specify DMB-T.

The supported modulation types depend on the device model. See the table above for the default modulation type by device model.

--mpe-fec

DVB-T/H modulators: indicate that at least one elementary stream uses MPE-FEC (DVB-H signalling).

-o value
--offset-count value

UHF and VHF modulators: specify the number of offsets from the UHF or VHF channel. Can be positive or negative. The default is zero. See options --uhf-channel and --vhf-channel.

--papr value

DVB-T2 modulators: indicate the Peak to Average Power Reduction method. Must be one of NONE, ACE (Active Constellation Extension), TR (power reduction with reserved carriers) or BOTH (both ACE and TS). The default is NONE.

--pilots

DVB-S2 and ADTB-T modulators: enable pilots (default: no pilot).

-p value
--pilot-pattern value

DVB-T2 modulators: indicate the pilot pattern to use, a value in the range 1 to 8. The default is 7.

--plp0-code-rate value

DVB-T2 modulators: indicate the convolutional coding rate used by the PLP #0. Must be one of 1/2, 3/5, 2/3, 3/4, 4/5, 5/6. The default is 2/3.

--plp0-fec-type value

DVB-T2 modulators: indicate the FEC type used by the PLP #0. Must be one of 16K, 64K. The default is 64K LPDC.

--plp0-group-id value

DVB-T2 modulators: indicate the PLP group with which the PLP #0 is associated. The valid range is 0 to 255. The default is 0.

--plp0-high-efficiency

DVB-T2 modulators: indicate that the PLP #0 uses High Efficiency Mode (HEM). Otherwise Normal Mode (NM) is used.

--plp0-id value

DVB-T2 modulators: indicate the unique identification of the PLP #0 within the T2 system. The valid range is 0 to 255. The default is 0.

--plp0-il-length value

DVB-T2 modulators: indicate the time interleaving length for PLP #0. The valid range is 0 to 255. The default is 3.

If --plp0-il-type is set to ONE-TO-ONE (the default), this parameter specifies the number of TI-blocks per interleaving frame.

If --plp0-il-type is set to MULTI, this parameter specifies the number of T2 frames to which each interleaving frame is mapped.

--plp0-il-type value

DVB-T2 modulators: indicate the type of interleaving used by the PLP #0. Must be one of ONE-TO-ONE (one interleaving frame corresponds to one T2 frame) or MULTI (one interleaving frame is carried in multiple T2 frames). The default is ONE-TO-ONE.

--plp0-in-band

DVB-T2 modulators: indicate that the in-band flag is set and in-band signalling information is inserted in PLP #0.

--plp0-issy value

DVB-T2 modulators: type of ISSY field to compute and insert in PLP #0. Must be one of NONE, SHORT, LONG. The default is NONE.

--plp0-modulation value

DVB-T2 modulators: indicate the modulation used by PLP #0. Must be one of BPSK, QPSK, 16-QAM, 64-QAM, 256-QAM. The default is 256-QAM.

--plp0-null-packet-deletion

DVB-T2 modulators: indicate that null-packet deletion is active in PLP #0. Otherwise it is not active.

--plp0-rotation

DVB-T2 modulators: indicate that constellation rotation is used for PLP #0. Otherwise not.

--plp0-tsrate value

DVB-T2 modulators: PLP #0 bitrate. The default is 0 (use all available).

--plp0-type value

DVB-T2 modulators: indicate the PLP type for PLP #0. Must be one of COMMON, 1, 2. The default is COMMON.

-q value
--qam-b value

QAM modulators: with --j83 B, indicate the QAM-B interleaver mode. Must be one of: I128-J1D, I64-J2, I32-J4, I16-J8, I8-J16, I128-J1, I128-J2, I128-J3, I128-J4, I128-J5, I128-J6, I128-J7, I128-J8. The default is I128-J1D.

--roll-off value

DVB-S2/S2X modulators: indicate the roll-off factor. Must be one of 0.03, 0.05, 0.10, 0.15, 0.20, 0.25, 0.35, auto, none. The default is auto.

--s2-gold-code value

DVB-S2 modulators: indicate the physical layer scrambling initialization sequence, aka gold code.

--s2-short-fec-frame

DVB-S2 modulators: use short FEC frames, 12 000 bits (default: long FEC frames, 64 800 bits).

--satellite-frequency value

DVB-S/S2 modulators: indicate the target satellite frequency, in Hz, of the output carrier. The actual frequency at the output of the modulator is the intermediate frequency which is computed based on the characteristics of the LNB (see option --lnb). This option is useful when the satellite frequency is better known than the intermediate frequency.

The options --frequency and --satellite-frequency are mutually exclusive.

--symbol-rate value

DVB-C/S/S2 modulators: Specify the symbol rate in symbols/second.

By default, the symbol rate is implicitly computed from the convolutional rate, the modulation type and the bitrate. But when --symbol-rate is specified, the input bitrate is ignored and the output bitrate is forced to the value resulting from the combination of the specified symbol rate, convolutional rate and modulation type.

The options --symbol-rate and --bitrate are mutually exclusive.

--t2-fpsf value

DVB-T2 modulators: indicate the number of T2 frames per super-frame. Must be in the range 1 to 255. The default is 2.

--t2-guard-interval value

DVB-T2 modulators: indicates the guard interval. Must be one of: 1/128, 1/32, 1/16, 19/256, 1/8, 19/128, 1/4. The default is 1/128.

--t2-l1-modulation value

DVB-T2 modulators: indicate the modulation type used for the L1-post signalling block. Must be one of BPSK, QPSK, 16-QAM, 64-QAM. The default is 16-QAM.

--t2-network-id value

DVB-T2 modulators: indicate the DVB-T2 network identification. The default is 0.

--t2-system-id value

DVB-T2 modulators: indicate the DVB-T2 system identification. The default is 0.

--time-slice

DVB-T/H modulators: indicate that at least one elementary stream uses time slicing (DVB-H signalling).

-t value
--transmission-mode value

DVB-T modulators: indicates the transmission mode. Must be one of 2K, 4K or 8K. The default is 8K.

-u value
--uhf-channel value

UHF modulators: specify the UHF channel number of the output carrier. Can be used in replacement to --frequency. Can be combined with an --offset-count option. The UHF frequency layout depends on the region, see --hf-band-region option.

-v value
--vhf-channel value

VHF modulators: specify the VHF channel number of the output carrier. Can be used in replacement to --frequency. Can be combined with an --offset-count option. The VHF frequency layout depends on the region, see --hf-band-region option.

--vsb value

ATSC modulators: indicate the VSB constellation. Must be one of 8 (19,392,658 Mb/s) or 16 (38,785,317 Mb/s). The default is 8.

--vsb-taps value

ATSC modulators: indicate the number of taps of each phase of the root-raised cosine filter that is used to shape the spectrum of the output signal. The number of taps can have any value between 2 and 256 (the implementation is optimized for powers of 2). Specifying more taps improves the spectrum, but increases processor overhead. The recommend (and default) number of taps is 64 taps. If insufficient CPU power is available, 32 taps produces acceptable results, too.

TS-over-IP options

The following options are used with Dektec Ethernet devices.

--gw4 ipv4-address

TS-over-IP: Specify a non-default IPv4 gateway address.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--gw6 ipv6-address

TS-over-IP: Specify a non-default IPv6 gateway address.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--ip4 ipv4-address:port

TS-over-IP: Destination IPv4 address and port.

Either --ip4 or --ip6 must be specified with Dektec Ethernet devices. The address part is mandatory for multicast, optional for unicast.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--ip6 [ipv6-address]:port

TS-over-IP: Destination IPv6 address and port.

Important: The square brackets are literal, as in any IPv6 URL, not an indication of an optional field.

Either --ip4 or --ip6 must be specified with Dektec Ethernet devices. The address part is mandatory for multicast, optional for unicast.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--rtp

TS-over-IP: Use RTP protocol. By default, TS packets are sent in UDP datagrams without RTP or other protocol header.

--smpte-2022-fec type

TS-over-IP: Specify type of SMPTE-2022 error correction mode to use. Must be one of 2d-m1, 2d-m1-b, 2d-m2, 2d-m2-b or none. The default is none.

--smpte-2022-d value

TS-over-IP with SMPTE-2022 error correction: Specify the number of rows in the FEC matrix, aka 'D' parameter.

--smpte-2022-l value

TS-over-IP with SMPTE-2022 error correction: Specify the number of columns in the FEC matrix, aka 'L' parameter.

--source-port value

TS-over-IP: Optional UDP source port for outgoing packets. By default, use a random port.

With SMPTE 2022-7 network redundancy, this parameter must be specified twice, main and redundant link.

--tos value

TS-over-IP: Type-of-service (TOS) or differentiated services value of outgoing IP datagrams.

--ts-per-ip value

TS-over-IP: Number of TS packets per IP datagram. The default is 7.

--ttl value

TS-over-IP: Time-to-live (TTL) value of outgoing IP datagrams.

--vlan-id value

TS-over-IP: Optional VLAN identifier as specified in IEEE 802.1Q.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

--vlan-priority value

TS-over-IP: Optional VLAN priority code point as specified in IEEE 802.1Q.

With SMPTE 2022-7 network redundancy, this parameter can be specified twice, main and redundant link.

Generic output plugins options

The following options are implicitly defined in all output plugins.

--help

Display the plugin help text.

4.17. descrambler

Generic DVB descrambler

This plugin descrambles fixed PID’s with fixed control words.

As a demo, it can also descramble services for which clear ECM’s were generated using the utility named tsecmg, a DVB SimulCrypt-compliant ECMG for test and demo.

Usage

$ tsp -P descrambler [options] [service]

Parameter

service

The optional parameter specifies the service to descramble.

If no fixed control word is specified, ECM’s from the service are used to extract control words.

In the absence of explicit option such as --atis-idsa, --dvb-cissa, --aes-cbc or --dvb-csa2, the descrambling type is based on the scrambling_descriptor in the PMT of the service (if there is one).

Options

--cas-id value

Specify the CA_system_id to filter when searching for ECM streams. Since this descrambler is a demo tool using clear ECM’s, it is unlikely that other real ECM streams exist. So, by default, any ECM stream is used to get the clear ECM’s.

-p pid1[-pid2]
--pid pid1[-pid2]

Descramble packets with these PID values. Several --pid options may be specified. By default, descramble the specified service.

--swap-cw

Swap even and odd control words from the ECM. Useful when a crazy ECMG inadvertently swapped the CW before generating the ECM.

--synchronous

Specify to synchronously decipher the ECM’s.

In real-time mode, the processing of packets continues in parallel while ECM’s are deciphered. Use this option to force the stream processing to wait for ECM’s at the point where the each ECM is received.

In offline mode, this option is always on. This is usually the right thing to do. Otherwise, if an ECM takes too long to be deciphered, the stream processing may reach the next crypto-period before the control word is available.

This plugin only processes clear ECM’s as generated by tsecmg. These ECM’s are not ciphered and their processing is immediate. So, this option is useless in practice. However, this plugin is based on a generic descrambler implementation. For other conditional access systems, processing an ECM may be delegated to a smartcard and take a relatively long time. So, this option can be useful in that case.

Transport stream scrambling options

--aes-cbc

Use AES-CBC scrambling instead of DVB-CSA2 (the default).

The control words are 16-byte long instead of 8-byte. The residue is left clear. Specify a fixed initialization vector using the --iv option.

Note that this is a non-standard TS scrambling mode. The only standard AES-based scrambling modes are ATIS-IDSA and DVB-CISSA (DVB-CISSA is the same as AES-CBC with a DVB-defined IV).

With the plugin scrambler, a scrambling_descriptor is automatically added to the PMT of the service to indicate the use of AES-CBC scrambling. Since there is no standard value for AES-CBC, the user-defined scrambling_mode value 0xF0 is used.

--aes-ctr

Use AES-CTR scrambling instead of DVB-CSA2 (the default).

The control words are 16-byte long instead of 8-byte. The residue is included in the scrambling. Specify a fixed initialization vector using the --iv option. See the option --ctr-counter-bits for the size of the counter part in the IV.

Note that this is a non-standard TS scrambling mode. The only standard AES-based scrambling modes are ATIS-IDSA and DVB-CISSA.

With the plugin scrambler, a scrambling_descriptor is automatically added to the PMT of the service to indicate the use of AES-CTR scrambling. Since there is no standard value for AES-CTR, the user-defined scrambling_mode value 0xF1 is used.

--atis-idsa

Use ATIS-IDSA descrambling (ATIS-0800006) instead of DVB-CSA2 (the default).

The control words are 16-byte long instead of 8-byte.

--ctr-counter-bits value

With --aes-ctr, specifies the size in bits of the counter part.

In the initialization vector, the fixed nonce part uses the first 128-N bits and the counter part uses the last N bits.

By default, the counter part uses the second half of the IV (64 bits).

-c hexa-digits
--cw hexa-digits

Specifies a fixed and constant control word for all TS packets (no crypto-period scheduling, no ECM).

The value must be a string of 16 hexadecimal digits (32 digits with --atis-idsa, --dvb-cissa, --aes-cbc, --aes-ctr).

--dvb-cissa

Use DVB-CISSA descrambling (see [ETSI-103-127]) instead of DVB-CSA2 (the default).

The control words are 16-byte long instead of 8-byte.

--dvb-csa2

Use DVB-CSA2 descrambling. This is the default.

-f name
--cw-file name

Specifies a text file containing the list of control words to apply. Each line of the file must contain exactly 16 hexadecimal digits (32 digits with --atis-idsa, --dvb-cissa, --aes-cbc, --aes-ctr).

During descrambling, the next control word is used each time a new transport_scrambling_control value is found in the header of a TS packet. At the end of the list of control words, restart with the first one.

--iv hexa-digits

With --aes-cbc or --aes-ctr, specifies a fixed initialization vector for all TS packets.

The value must be a string of 32 hexadecimal digits. The default IV is all zeroes.

-n
--no-entropy-reduction

Do not perform DVB-CSA2 control word entropy reduction to 48 bits, keep full 64-bit control words. This option is ignored with other encryption algorithms.

--output-cw-file name

Specifies a text file to create with all control words. Each line of the file will contain a control word with 16 or 32 hexadecimal digits, depending on the scrambling algorithm. Each time a new control word is used to descramble packets, it is logged in the file.

This option is specifically useful when the control words are dynamically extracted from ECM’s. The created file can be used later using --cw-file to perform a direct descrambling test.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --default-charset RAW-ISO-8859-15 . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--default-charset name

Default character set to use when interpreting strings from tables and descriptors. By default, the standard DVB encoding is used. See section 2.5 for more details.

--europe

A synonym for --default-charset ISO-8859-15. See section 2.5 for more details.

--japan

A synonym for --default-charset ARIB-STD-B24 . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --default-charset RAW-UTF-8 . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.18. drop (output)

Drop output packets

This output plugin simply drops all packets. This plugin is useful when the interesting work is done by the various packet processing plugins and the actual output packets are useless.

Usage

$ tsp -O drop [options]

Generic output plugins options

The following options are implicitly defined in all output plugins.

--help

Display the plugin help text.

4.19. dump

Dump transport stream packets

This plugin is equivalent to the command tsdump.

Usage

$ tsp -P dump [options]

General options

-o file-name
--output-file file-name

Output file for dumped packets. By default, use the standard output.

The options --log and --output-file are mutually exclusive.

Packet dump options

--adaptation-field

Include formatting of the adaptation field.

-a
--ascii

Include ASCII dump in addition to hexadecimal.

-b
--binary

Include binary dump in addition to hexadecimal.

-h
--headers-only

Dump packet headers only, not payload.

-l
--log

Display a short one-line log of each packet instead of full dump.

--log-size value

With option --log, specify how many bytes are displayed in each packet.

The default is 188 bytes (complete packet).

-n
--nibble

Same as --binary but add separator between 4-bit nibbles.

--no-headers

Do not display packet header information.

-o
--offset

Display offset from start of packet with hexadecimal dump.

--payload

Hexadecimal dump of TS payload only, skip TS header.

-p pid1[-pid2]
--pid pid1[-pid2]

Dump only packets with these PID values. Several --pid options may be specified.

By default, all packets are displayed.

--rs204

Dump the 16-byte trailer as found in RS204 files.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--abnt

Assume that the transport stream is an ISDB one with ABNT-defined variants. See section 2.4.2 for more details.

--atsc

Assume that the transport stream is an ATSC one. See section 2.4.2 for more details.

--brazil

A synonym for --isdb --abnt . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--ignore-leap-seconds

Do not explicitly include leap seconds in some UTC computations. See section 2.4.2 for more details.

--isdb

--japan

A synonym for --isdb . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --isdb --abnt . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--usa

A synonym for --atsc . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.20. duplicate

Duplicate PID’s, reusing null packets

This plugin duplicates the content of several PID’s into new PID’s. The duplicated packets are created by replacing existing null packets. The input stream shall consequently contain at least as many null packets as packets to duplicate.

Usage

$ tsp -P duplicate [options] [pid[-pid]=newpid ...]

Parameters

pid[-pid]=newpid

Each PID duplication is specified as pid=newpid or pid1-pid2=newpid. All PID’s can be specified as decimal or hexadecimal values. More than one PID duplication can be specified.

In the first form, the PID pid is duplicated as newpid.

In the second form, all PID’s within the range pid1 to pid2 (inclusive) are respectively duplicated as newpid, newpid+1, etc. (this behaviour is changed using option --single).

The null PID 0x1FFF cannot be duplicated.

Options

-d
--drop-overflow

Silently drop overflow packets. By default, overflow packets trigger warnings.

See also option --max-buffered-packets.

-m value
--max-buffered-packets value

Specify the maximum number of buffered packets. The input packets to duplicate are internally buffered until a null packet is found and replaced by the buffered packet. An overflow is usually caused by insufficient null packets in the input stream.

The default is 1,024 packets.

--reset-label label1[-label2]

Clear the specified labels on the duplicated packets.

Several --reset-label options may be specified.

--set-label label1[-label2]

Set the specified labels on the duplicated packets.

Several --set-label options may be specified.

-s
--single

When a duplication is in the form pid1-pid2=newpid, duplicate all input PID’s within the range pid1 to pid2 to the same newpid value, not newpid, newpid+1, etc.

This option forces --unchecked since distinct PID’s are duplicated to the same one.

-u
--unchecked

Do not perform any consistency checking while duplicating PID’s. Duplicating two PID’s to the same PID or to a PID which is already present in the input is accepted.

Note that this option should be used with care since the resulting stream can be illegal or inconsistent.

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.21. dvb (input)

DVB, ATSC, ISDB tuner receivers input

This input plugin receives TS packets from a tuner receiver device. These devices include a wide range of satellite, cable and terrestrial adapters. Most of them are simple tuners. See section 7.1 for more details on tuner receiver devices.

Using this plugin forces tsp and all plugins to use their real-time defaults (see the reference documentation for tsp).

This plugin originally supported DVB receivers only. Later, support was added for ATSC and ISDB receivers, but the plugin retained its original name dvb.

Usage

$ tsp -I dvb [options]

Reception options

-a N
--adapter N

Specify the N^th tuner device in the system, the first index being zero. This option can be used instead of device name.

On Linux systems, this means /dev/dvb/adapterN.

-d "name"
--device-name "name"

Specify the name of the receiver device to use. Use the tslsdvb utility to list all available devices.

By default, the first receiver device is used. The syntax of the device name depends on the operating system. See section 7.1.3 for more details on receiver devices naming.

The specified name can also be the path of an XML file (a file name ending in .xml) which is used as tuner emulator. See section 7.1.4 for more details on tuner emulators.

--lnb string

For satellite reception, specifies the description of the LNB (Low-Noise Block in the dish). See section A.3 for more details.

--receive-timeout milliseconds

Specify the timeout, in milliseconds, for each receive operation. To disable the timeout and wait indefinitely for packets, specify zero. This is the default.

--signal-timeout seconds

Specify the timeout, in seconds, for the DVB frontend signal locking. If no signal is detected within this timeout, the command aborts. To disable the timeout and wait indefinitely for the signal, specify zero. The default is 5 seconds.

Linux-specific options

--demux-buffer-size value

Default buffer size, in bytes, of the demux device. The default is 1 MB.

Windows-specific options

--demux-queue-size value

Specify the maximum number of media samples in the queue between the DirectShow capture thread and the input plugin thread. The default is 1000 media samples.

--receiver-name "name"

Specify the name of the DirectShow receiver filter to use.

By default, first try a direct connection from the tuner filter to the rest of the graph. Then, try all receiver filters and concatenate them all.

Status reporting options

Using these options, it is possible to send a status report of the reception at regular interval. The status report is in JSON format and can be displayed or sent over UDP or TCP.

--json-interval seconds

With --json-line, --json-tcp, --json-udp, specify the interval between two status reports.

The default is 60 seconds.

--json-buffer-size value

With --json-tcp or --json-udp, specify the network socket send buffer size.

--json-line[='prefix']

Same as --json but report the JSON text as one single line in the message logger instead of fully formatted output file.

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.

--json-tcp address:port

Same as --json but report the JSON text as one single line in a TCP connection instead of the output file.

The address specifies an IP address or a host name that translates to an IP address. The port specifies the destination TCP port.

--json-tcp-keep

With --json-tcp, keep the TCP connection open for all JSON messages. By default, a new TCP connection is established each time a JSON message is produced.

--json-udp address:port

Same as --json but report the JSON text as one single line in a UDP datagram instead of the output file.

The address specifies an IP address which can be either unicast or multicast. It can be also a host name that translates to an IP address. The port specifies the destination UDP port.

Be aware that the size of UDP datagrams is limited by design to 64 kB. If larger JSON contents are expected, consider using --json-tcp.

--json-udp-local address

With --json-udp, when the destination is a multicast address, specify the IP address of the outgoing local interface. It can be also a host name that translates to a local address.

--json-udp-ttl value

Tuning options

By default, no tuning is performed on the DVB frontend. The transponder on which the frontend is currently tuned is used.

There are two ways to specify a new transponder:

Specifying individual tuning options, one for each tuning parameters. Common values are provided as default.
The name of a channel contained in the transponder, using a channels configuration file. See appendix B for more details on channels configuration files.

Tuning method 1: Individual tuning options

--bandwidth value

Used for terrestrial tuners only. Specify the bandwidth in Hz.

For compatibility with old versions, low values (below 1000) are interpreted in MHz. This means that values 8 and 8,000,000 are identical. Both mean 8 MHz.

The default is 8 MHz for DVB-T/T2 and 6 MHz for ISDB-T.

--delivery-system value

Specify which delivery system to use. Must be one of the following values:

Table 13. Values for option `--delivery-system` (tuner reception)
Value	Description	Supported options
`ATSC`	ATSC	`--frequency --modulation --spectral-inversion`
`ATSC-MH`	ATSC -M/H (handheld)	Unsupported
`CMMB`	CMMB Terrestrial	Unsupported
`DAB`	DAB (digital audio)	Unsupported
`DSS`	DSS Satellite	Unsupported
`DTMB`	DTMB Terrestrial	Unsupported
`DVB-C`	DVB-C (same as `DVB-C/A`)	Same as `DVB-C/A`
`DVB-C/A`	DVB-C ITU-T J.83 Annex A	`--fec-inner --frequency --modulation --spectral-inversion --symbol-rate`
`DVB-C/B`	DVB-C ITU-T J.83 Annex B	Unsupported
`DVB-C/C`	DVB-C ITU-T J.83 Annex C	Same as DVB-C/A
`DVB-C2`	DVB-C2	Unsupported
`DVB-H`	DVB-H (deprecated)	Unsupported
`DVB-S`	DVB-S	`--fec-inner --frequency --polarity --satellite-number --spectral-inversion --symbol-rate`
`DVB-S-Turbo`	DVB-S Turbo	Unsupported
`DVB-S2`	DVB-S2	`--fec-inner --frequency --isi --modulation --pilots --pls-code --pls-mode --polarity --roll-off --satellite-number --spectral-inversion --symbol-rate`
`DVB-T`	DVB-T	`--bandwidth --frequency --guard-interval --hierarchy --high-priority-fec --low-priority-fec --modulation --spectral-inversion --transmission-mode`
`DVB-T2`	DVB-T2	`--bandwidth --frequency --guard-interval --hierarchy --high-priority-fec --low-priority-fec --modulation --plp --spectral-inversion --transmission-mode`
`ISDB-C`	ISDB-C	Unsupported
`ISDB-S`	ISDB-S	`--fec-inner --frequency --polarity --satellite-number --spectral-inversion --stream-id --symbol-rate`
`ISDB-T`	ISDB-T	`--bandwidth --frequency --guard-interval --isdbt-layer-a-fec --isdbt-layer-a-modulation --isdbt-layer-a-segment-count --isdbt-layer-a-time-interleaving --isdbt-layer-b-fec --isdbt-layer-b-modulation --isdbt-layer-b-segment-count --isdbt-layer-b-time-interleaving --isdbt-layer-c-fec --isdbt-layer-c-modulation --isdbt-layer-c-segment-count --isdbt-layer-c-time-interleaving --sb-segment-count --sb-segment-index --sb-subchannel-id --sound-broadcasting --spectral-inversion --transmission-mode`
`undefined`	Undefined	Unsupported

Note that some delivery systems are not available on some operating systems.

By default, use the default system for the tuner.

--fec-inner value

Used for satellite and cable tuners only.

Specify the Inner Forward Error Correction. Must be one of none, auto, 1/2, 1/3, 1/4, 2/3, 2/5, 3/4, 3/5, 4/5, 4/15, 5/6, 5/9, 5/11, 6/7, 7/8, 7/9, 7/15, 8/9, 8/15, 9/10, 9/20, 11/15, 11/20, 11/45, 13/18, 13/45, 14/45, 23/36, 25/36, 26/45, 28/45, 32/45, 77/90.

The default is auto.

-f value
--frequency value

Specify the carrier frequency in Hz (all tuners).

For DVB-T tuners, the options --uhf-channel or --vhf-channel (and associated optional --offset-count) can be used instead of --frequency.

--guard-interval value

Used for terrestrial tuners only.

Must be one of auto, 1/4, 1/8, 1/16, 1/32, 1/64, 1/128, 19/128, 19/256, PN-420, PN-595, PN-945.

The default is 1/32.

--hierarchy value

Used for DVB-T tuners only.

Must be one of auto, none, 1, 2, 4. The default is none.

--high-priority-fec value

Used for DVB-T tuners only.

Error correction for high priority streams. See option --fec-inner for the list of possible values. The default is auto.

--isdbt-layer-a-fec value

Used for ISDB-T tuners only.

Error correction for layer A. See option --fec-inner for the list of possible values. The default is auto.

--isdbt-layer-a-modulation value

Used for ISDB-T tuners only.

Modulation for layer A. The default is automatically detected. See option --modulation for the list of possible values.

--isdbt-layer-a-segment-count value

Used for ISDB-T tuners only.

Number of segments for layer A. Possible values: 0 to 13. The default is automatically detected.

--isdbt-layer-a-time-interleaving value

Used for ISDB-T tuners only.

Time interleaving for layer A. Possible values: 0 to 3. The default is automatically detected.

--isdbt-layer-b-fec value

Used for ISDB-T tuners only.

Error correction for layer B. The default is automatically detected. See option --fec-inner for the list of possible values.

--isdbt-layer-b-modulation value

Used for ISDB-T tuners only.

Modulation for layer B. The default is automatically detected. See option --modulation for the list of possible values.

--isdbt-layer-b-segment-count value

Used for ISDB-T tuners only.

Number of segments for layer B. Possible values: 0 to 13. The default is automatically detected.

--isdbt-layer-b-time-interleaving value

Used for ISDB-T tuners only.

Time interleaving for layer B. Possible values: 0 to 3. The default is automatically detected.

--isdbt-layer-c-fec value

Used for ISDB-T tuners only.

Error correction for layer C. The default is automatically detected. See option --fec-inner for the list of possible values.

--isdbt-layer-c-modulation value

Used for ISDB-T tuners only.

Modulation for layer C. The default is automatically detected. See option --modulation for the list of possible values.

--isdbt-layer-c-segment-count value

Used for ISDB-T tuners only.

Number of segments for layer C. Possible values: 0 to 13. The default is automatically detected.

--isdbt-layer-c-time-interleaving value

Used for ISDB-T tuners only.

Time interleaving for layer C. Possible values: 0 to 3. The default is automatically detected.

--isdbt-layers 'string'

Used for ISDB-T tuners only.

Hierarchical reception in ISDB-T is achieved by enabling or disabling layers in the decoding process. The specified string contains a combination of characters A, B, C, indicating which layers shall be used. The default is ABC (all layers).

--isdbt-partial-reception

Used for ISDB-T tuners only.

Specify that the reception of the ISDB-T channel is in partial reception mode. The default is automatically detected.

--isi value

Used for DVB-S2 tuners only.

Specify the Input Stream Id (ISI) number to select, from 0 to 255. Used with multi-stream, see also options --pls-code and --pls-mode.

The default is to keep the entire stream, without multi-stream selection.

Warning: this option is supported on Linux only. Currently, Windows provides no support for multi-stream.

--low-priority-fec value

Used for DVB-T tuners only.

Error correction for low priority streams. See option --fec-inner for the list of possible values. The default is auto.

-m value
--modulation value

Used for DVB-C, DVB-T, DVB-S2 and ATSC tuners.

Modulation type (a.k.a. constellation for DVB-T).

Must be one of 4-QAM-NR, 8-APSK-L, 8-PSK, 8-VSB, 16-APSK, 16-APSK-L, 16-QAM, 16-VSB, 32-APSK, 32-APSK-L, 32-QAM, 64-APSK, 64-APSK-L, 64-QAM, 128-QAM, 256-QAM, 1024-QAM, 4096-QAM, DQPSK, QAM (auto-detected QAM), QPSK.

The default is 64-QAM for DVB-T and DVB-C, QPSK for DVB-S2, 8-VSB for ATSC.

--offset-count value

Used for terrestrial tuners only.

Specify the number of offsets from the UHF or VHF channel. The default is zero. See options --uhf-channel and --vhf-channel.

--pilots value

Used for DVB-S2 tuners only.

Presence of pilots frames. Must be one of auto, on or off. The default is off.

--plp value

Used for DVB-T2 tuners only.

Specify the Physical Layer Pipe (PLP) number to select, from 0 to 255. The default is to keep the entire stream, without PLP selection.

--pls-code value

Used for DVB-S2 tuners only.

Specify the Physical Layer Scrambling (PLS) code value, from 0 to 262143 (0x3FFFF). Used with multi-stream, see also option --isi.

With GOLD mode (the default), the default PLS code is zero. With ROOT mode, there is no default, the PLS code must be specified.

Warning: this option is supported on Linux only. Currently, Windows provides no support for multi-stream.

--pls-mode mode

Used for DVB-S2 tuners only.

Specify the Physical Layer Scrambling (PLS) mode. Used with multi-stream, see also option --isi. Must be one of GOLD, ROOT. The default is GOLD.

Warning: this option is supported on Linux only. Currently, Windows provides no support for multi-stream.

--polarity value

Used for satellite tuners only.

Must be one of horizontal or vertical for linear polarization, left or right for circular polarization. The default is vertical.

--roll-off value

Used for DVB-S2 tuners only.

Roll-off factor. Must be one of auto, 0.05, 0.10, 0.15, 0.20, 0.25, 0.35. The default is 0.35 (implicit for DVB-S, default for DVB-S2).

--satellite-number value

Used for satellite tuners only.

Satellite/dish number. Must be 0 to 3 with DiSEqC switches and 0 to 1 for non-DiSEqC switches. The default is zero.

--sb-segment-count value

Used for ISDB-T tuners only.

With --sound-broadcasting, specify the total count of connected ISDB-Tsb channels. Possible values: 1 to 13. The default is 13.

--sb-segment-index value

Used for ISDB-T tuners only.

With --sound-broadcasting, specify the index of the segment to be demodulated for an ISDB-Tsb channel where several of them are transmitted in the connected manner. Possible values: 0 to value of --sb-segment-count minus 1. The default is 0.

--sb-subchannel-id value

Used for ISDB-T tuners only.

With --sound-broadcasting, specify the sub-channel id of the segment to be demodulated in the ISDB-Tsb channel. Possible values: 0 to 41. The default is 0.

--sound-broadcasting

Used for ISDB-T tuners only.

Specify that the reception is an ISDB-Tsb (sound broadcasting) channel instead of an ISDB-T one.

--spectral-inversion value

Spectral inversion. Must be one of on, off, auto. The default is auto.

--stream-id value

Used for ISDB-S tuners only.

In the case of multi-stream broadcasting, specify the inner transport stream id. By default, use the first inner transport stream, if any is found.

Warning: this option is supported on Linux only. Currently, Windows provides no support for multi-stream.

-s value
--symbol-rate value

Used for satellite and cable tuners only.

Symbol rate in symbols/second. The default is 27.5 mega-symbols/second for DVB-S, 6.9 mega-symbols/second for DVB-C, 28.86 mega-symbols/second for ISDB-S.

--transmission-mode value

Used for terrestrial tuners only.

Must be one of auto, 2K, 4K, 8K. For DVB-T2, also accept 1K, 2K-interleaved, 4K-interleaved, 16K, 32K. The default is 8K.

--uhf-channel value

Used for terrestrial tuners only.

Specify the UHF channel number of the carrier. Can be used in replacement to --frequency. Can be combined with an --offset-count option. The UHF frequency layout depends on the region, see --hf-band-region option.

--vhf-channel value

Used for terrestrial tuners only.

Specify the VHF channel number of the carrier. Can be used in replacement to --frequency. Can be combined with an --offset-count option. The VHF frequency layout depends on the region, see --hf-band-region option.

Tuning method 2: Locating the transponder by channel name

-c name
--channel-transponder name

Tune to the transponder containing the specified channel. The channel name is not case-sensitive and blanks are ignored. It is either an "HF band channel" or a "TV channel".

A "HF band channel" has the format band-number such as UHF-22 (terrestrial) or BS-12 (Japanese satellite). See also option --offset-count.

A "TV channel" name is searched in a channels configuration file and the corresponding tuning information in this file is used. See also option --tuning-file.

For ATSC networks, the channel name can be replaced by the channel id using the format major-id.minor-id (e.g. 1.2 or 12.8).

--tuning-file file-name

Specify the channels configuration file to use for option --channel-transponder.

Channel configuration files can be created manually or using the utility tsscan or the plugin nitscan. The location of the default configuration file depends on the system.

See appendix B for more details on channels configuration files.

Interpretation of the transport stream content

These options controls the peculiarities of local Digital TV standards and how they are used.

--brazil

A synonym for --hf-band-region brazil . This is a handy shortcut when working on South American ISDB-Tb transport streams. See section 2.4.2 and section 2.5.2 for more details.

--hf-band-region name

--japan

A synonym for --hf-band-region japan . See section 2.4.2 and section 2.5.2 for more details.

--philippines

A synonym for --hf-band-region philippines . This is a handy shortcut when working on Philippines transport streams. See section 2.4.2 and section 2.5.2 for more details.

--usa

A synonym for --hf-band-region usa . This is a handy shortcut when working on North American transport streams. See section 2.4.2 and section 2.5.2 for more details.

Generic input plugins options

The following options are implicitly defined in all input plugins.

--help

Display the plugin help text.

4.22. eit

Analyze EIT sections

This plugin analyzes EIT sections and produces a report of EIT present/following and EIT schedule by transport stream and by service. The EPG depth in days is also reported by service (number of days in advance an event is signaled by an EIT schedule). See section 5.2.16 for an example of report.

Usage

$ tsp -P eit [options]

Options

-o file-name
--output-file file-name

Specify the output file for the report (default: standard output).

Generic packet processing plugin options

The following options are implicitly defined in all packet processing plugins.

--help

Display the plugin help text.

--only-label label1[-label2]

Invoke this plugin only for packets with any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --only-label options may be specified.

--except-label label1[-label2]

Invoke this plugin only for packets without any of the specified labels. Other packets are transparently passed to the next plugin, without going through this one.

Several --except-label options may be specified.

4.23. eitinject

Generate and inject EIT’s in a transport stream

This plugin generates EIT’s from a database of events and injects those EIT’s on time in the transport stream. The plugin can selectively generate "EIT actual" and/or "EIT other" and "EIT present/following" (or "p/f") and/or "EIT schedule".

EIT’s are "injected" in the transport stream by replacing null packets or pre-existing EIT packets. All EIT’s are injected by default in the DVB-defined PID for EIT’s, the PID number 18 (see also option --pid). There must be enough null or EIT packets to replace, otherwise EIT’s won’t be correctly injected or not injected at all.

The events can be loaded at any time but the actual EIT injection can start only when the actual transport stream id and the current time reference are known. The actual transport stream id is required to determine if events for a given service shall be included in EIT actual or EIT other. The current time is required to generate EIT p/f on time and drop obsolete events from EIT schedule. The organization of EIT schedule table ids also depends on the current date.

By default, the actual transport stream id is extracted from the first PAT. The current time is permanently resynchronized on TDT and TOT. See also options --ts-id and --time.

Note that the concept of "current time" is always relative to the transport stream. It is possible to inject EIT’s in a transport stream file at the speed of file read/write. The "current time" of a packet (for EIT generation and insertion) is based on the last reference (typically from a TDT or TOT), the transport stream bitrate and the number of packets since the last reference.

Electronic Program Guide (EPG) database

The events are loaded in an EPG database in memory. There are several sources for events: files and incoming EIT’s (from the TS upstream).

Event files shall contain EIT tables or sections in binary, XML or JSON format. The organization of events in the EIT’s and the type of EIT’s are ignored. Only the events descriptions and the DVB triplets (service id, transport stream id and original network id) are important, all the rest is ignored.

When event files are loaded or when incoming EIT’s are received, all events are individually extracted and stored in the EPG database in memory. The EIT encapsulation is just a convenient pre-existing format to store events, nothing more.

Events are reorganized by the plugin eitinject and new EIT’s are recreated when necessary with the stored events.

The event input files can be specified using wildcards (be sure to use quotes in order to avoid the interpretation of the wildcards by the shell). The plugin eitinject polls the corresponding files at regular intervals. Whenever a file matching the wildcards is created or updated, the file is loaded. Existing events with unmodified content are ignored.

Let’s take an example. Consider the following command:

$ tsp ... -P eitinject --file '/home/epg/input/*.xml' --delete-files ...

Each time XML files are copied into the directory /home/epg/input, they are loaded and all events from all EIT’s in those files are processed. Most of the time, "processed" means loaded and added in the EPG database (see an exception in the next section on event deletion).

Each XML files is then deleted after being loaded (option --delete-files).

Note the quotes in '/home/epg/input/*.xml'. Without them, the shell would expand the wildcard with all existing XML files in directory /home/epg/input. The plugin eitinject would then only consider these files, those which existed at the time the command was started. With the quotes, the shell does not expand the wildcard and the raw string with *.xml is passed to the plugin and all present and future XML files in that directory will be loaded.

Consider the following XML file:

<?xml version="1.0" encoding="UTF-8"?>
<tsduck>
  <EIT service_id="1" transport_stream_id="4" original_network_id="1">

    <event event_id="1000" start_time="2020-07-01 00:10:00" duration="00:20:00">
      <short_event_descriptor language_code="foo">
        <event_name>Event 1000</event_name>
      </short_event_descriptor>
    </event>

    <event event_id="1001" start_time="2020-07-01 00:30:00" duration="00:30:00">
      <short_event_descriptor language_code="foo">
        <event_name>Event 1001</event_name>
      </short_event_descriptor>
    </event>

    <event event_id="1002" start_time="2020-07-01 01:00:00" duration="00:30:00">
      <short_event_descriptor language_code="foo">
        <event_name>Event 1002</event_name>
      </short_event_descriptor>
    </event>

  </EIT>
</tsduck>

When we copy this file into the directory /home/epg/input, three consecutive events are loaded into the EPG database. They are included in further EIT schedule for the service id 1 in transport stream with id 4. If some of th

TSDuck User’s Guide

Preface

1. Transport Stream Toolkit Overview

1.1. Operating system selection guidelines

1.2. Developing applications using the TSDuck library

1.3. Installing TSDuck

1.3.1. Windows

1.3.2. Linux

1.3.3. macOS

1.3.4. BSD systems

2. Data Formats

2.1. Transport stream

2.1.1. Live transport streams

2.1.2. Stored transport streams

2.1.3. Support for 204-byte packets

2.2. Bit rates

2.2.1. Interpretation

2.2.2. Representation

2.2.3. Specifying bitrate in command lines

2.2.4. Rebuilding with a different bitrate representation

2.3. PSI/SI signalization

2.3.1. PSI/SI binary format

2.3.1.1. Creating PSI/SI binary files

2.3.1.2. Using PSI/SI binary files

2.3.2. PSI/SI XML format

2.4. Compatibility and conflicts between standards

2.4.1. Supported standards

2.4.2. TSDuck options for default standard selection

2.5. Character sets

2.5.1. Standards and character sets

2.5.2. TSDuck options for character sets

2.5.3. Character set names

2.6. XML files

2.6.1. Usage of XML files in TSDuck

2.6.2. Inline XML content

2.6.3. XML model files

2.6.4. XML patch files

2.6.4.1. Structure matching

2.6.4.2. Special attributes

2.6.4.3. Attribute patching

2.6.4.4. Element patching

2.6.4.5. Examples

2.6.4.6. Symbols and conditions

2.7. JSON and "normalized" report formats

2.7.1. "Normalized" reports

2.7.2. JSON files

2.7.3. Automated XML-to-JSON conversion

2.7.3.1. Conversion rules

2.7.3.2. TSDuck options for automated XML-to-JSON conversion

3. Transport Stream Utilities

3.1. Command line syntax

3.1.1. Command line options

3.1.2. Integer values in command line options

3.1.3. Predefined common options

3.1.4. Using a pager command

3.1.5. Partial command line redirection from a file

3.1.6. Default options from the TSDuck configuration file

3.1.7. Bash command line completion

3.2. tsanalyze

3.3. tsbitrate

3.4. tscharset

3.5. tscmp

3.6. tsconfig

3.7. tscrc32

3.8. tsdate

3.9. tsdektec

3.10. tsdump

3.11. tsecmg

3.12. tseit

3.13. tsemmg

3.14. tsfclean

3.15. tsfixcc

3.16. tsftrunc

3.17. tsfuzz

3.18. tsgenecm

3.19. tshides

3.20. tslatencymonitor

3.21. tslsdvb

3.22. tsp

3.23. tspacketize