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)
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.
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
.
Name | Description |
---|---|
|
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. |
|
Standard transport stream file containing contiguous 188-byte TS packets without any encapsulation. This is the default for output files. |
|
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 |
|
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. |
|
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 |
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.
Plugin | Type | Default | Enforced |
---|---|---|---|
|
input |
None. |
Option |
|
packet |
Unmodified. |
Options |
|
packet |
Not displayed. |
Options |
|
input |
Automatically detected and extracted. |
Option |
|
output |
Dropped. |
Option |
|
packet |
Dropped. |
Option |
|
input |
Automatically detected and extracted. |
Option |
|
output |
Dropped. |
Option |
|
packet |
Dropped. |
Option |
|
input |
Automatically detected and extracted. |
Option |
|
output |
Dropped. |
Option |
|
packet |
Dropped. |
Option |
|
packet |
Automatically detected and extracted. |
Option |
|
input |
Automatically detected and extracted. |
Option |
|
input |
Automatically detected and extracted. |
Option |
|
output |
Dropped. |
Option |
|
input |
Automatically detected and extracted. |
Option |
|
output |
Dropped. |
Option |
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.
Name | Value | Description |
---|---|---|
|
|
Alliance for Open Media |
|
|
Free TV Australia |
|
|
AVS Audio Working Group of China |
|
|
AVS Video Working Group of China |
|
|
BskyB British TV operator |
|
|
Canal+ French TV operator |
|
|
UHD World Association (UWA) |
|
|
European Association of Consumer Electronics Manufacturers, now renamed as DigitalEurope |
|
|
European Information, Communications and Consumer Electronics Technology Industry Associations. Merged with EACEM. |
|
|
Eutelsat European satellite provider |
|
|
Former CAS vendor |
|
|
Kudelski, Nagravision, CAS vendor |
|
|
NorDig standard committee (Northern Europe and Ireland) |
|
|
British regulator, formerly ITC |
|
|
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 forISO-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 factUTF-16
)
-
-
ARIB character sets (Japan):
-
ARIB-STD-B24
-
ARIB
(synonym forARIB-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 factUTF-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
orfalse
. -
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.
Attribute | Usage |
---|---|
|
Add the attribute |
|
The |
|
If the enclosing element is selected, the symbol |
|
Delete the attribute |
|
The node with this attribute is added in the matching parent node. |
|
The matching node is completely removed. |
|
The next parent with name |
|
If the enclosing element is selected, the symbol |
|
Update the attribute |
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 attributename
with the specified value in the matching element. If the attribute already existed, it is replaced. -
x-update-name="value"
Update the attributename
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 nameX
above the matching node is completely removed. -
x-node="add"
In this case, the matching node is the parent one. The inner node with attributex-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 symbolNAME
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 symbolNAME
is undefined from the global repository. The removal of the symbol applies starting with the processing of the enclosing element. -
x-condition="EXPRESSION"
TheEXPRESSION
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 literalTrue
orFalse
.
-
-
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:
Command | Description |
---|---|
|
Analyze a TS file and display various information about the transport stream and each individual service and PID. |
|
Evaluate the original bitrate of a TS based on the analysis of the PCR’s and the number of packets between them. |
|
Test tool for DVB and ARIB character sets. |
|
Compare the binary content of two TS files. |
|
Configuration options to build applications (developers only). |
|
Compute MPEG-style CRC32 values. |
|
Display the date & time information (TDT & TOT) from a TS file. |
|
Control a Dektec device. |
|
Dump the content of a TS file. |
|
DVB SimulCrypt-compliant ECMG stub for system integration and debug. |
|
Manipulate EIT’s using commands and scripts. |
|
DVB SimulCrypt-compliant EMMG stub for system integration and debug. |
|
Cleanup the structure and boundaries of a TS file. |
|
Fix continuity counters in a TS file. |
|
Truncate a TS file, removing extraneous bytes (last incomplete TS packet) or truncating after a specified TS packet. |
|
Introduce random errors in transport stream files. |
|
Generate one ECM using any DVB SimulCrypt compliant ECMG. |
|
List HiDes modulator devices. |
|
Monitor latency between two TS input sources. |
|
List DVB receiver devices. |
|
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. |
|
Packetize PSI/SI tables in a transport stream PID. |
|
Analyze pcap and pcap-ng files. |
|
Send control commands to a running |
|
Display the PSI (PAT, CAT, NIT, PMT, SDT) from a TS file. |
|
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). |
|
Scan frequencies in a DVB network. |
|
List or reset smart-card reader devices. |
|
Add stuffing to a TS file to reach a target bitrate. |
|
Transport stream input source switch using remote control. |
|
PSI / SI table compiler from / to XML files. |
|
Dump binary table files, as previously saved by |
|
Collect specified PSI/SI tables from a TS file. Either display them or save them in binary files. |
|
Compute or retrieve various DVB-T (terrestrial) information. |
|
Test a DVB SimulCrypt compliant ECMG with an artificial load. |
|
List VATek-based modulator devices. |
|
Check version, download and upgrade TSDuck. |
|
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.
Name | Description |
---|---|
|
Availability of accelerated instructions for CRC32, AES, etc. |
|
All information. |
|
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 name and version. |
|
Version of the cryptographic library. |
|
Build date. |
|
Version of the Dektec drivers and DTAPI library. |
|
Version of the HTTP/HTTPS library. |
|
TSDuck version as one integer value which can be used in scripts to test against minimum required versions. Example: "32802466". |
|
TSDuck version in long string format. This is the default. |
|
TSDuck version in NSIS directive format (legacy, no longer used). |
|
Version of the RIST library. |
|
TSDuck version is short format. Example: "3.28-2466". |
|
Version of the SRT library. |
|
Description of the running system. |
|
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
3.1.4. Using a pager command
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.
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.
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
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
--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.
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.
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 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.
See also the description of the command tsanalyze
for another example of normalized output.
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.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
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
.
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 the content of the EIT database. |
|
Usage: |
|
|
|
Exit |
|
Usage: |
|
|
|
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 |
|
Usage: |
|
|
|
Name of the output TS file to generate. |
|
|
Stop after generating the specified number of bytes. |
|
|
Stop after generating the specified number of TS packets. |
|
|
Stop after generating the specified number of seconds of contents. The duration is based on the TS bitrate. |
|
|
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. |
|
|
List all internal commands. This command is useful in interactive session. |
|
Usage: |
|
|
|
Load events from a file. |
|
Usage: |
|
|
|
A binary, XML or JSON file containing EIT sections.
See the |
|
|
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 |
|
Usage: |
|
|
|
Name of the input TS file. Input EIT’s are used to populate the event database. |
|
|
Name of the output TS file to generate, after EIT injection. |
|
|
Stop after generating the specified number of bytes. |
|
|
Repeat the input file infinitely. |
|
|
Stop after generating the specified number of TS packets. |
|
|
Repeat the input file the specified number of times. By default, the input file is read once. |
|
|
Stop after generating the specified number of seconds of contents. The duration is based on the TS bitrate. |
|
|
Start reading the input file at the specified offset in bytes. |
|
|
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. |
|
|
Exit |
|
Usage: |
|
|
|
Reset the content of the event database. |
|
Usage: |
|
|
|
Save all current EIT sections in a file. |
|
Usage: |
|
|
|
Name of the output file receiving EIT sections in binary format. |
|
|
Set EIT generation options. |
|
Usage: |
|
|
|
Enable the generation of all EIT actual. |
|
|
Enable the generation of EIT p/f actual. |
|
|
Enable the generation of EIT schedule actual. |
|
|
Set the EIT maximum bitrate in bits/second. |
|
|
Disable the generation of all EIT actual. |
|
|
Disable the generation of EIT p/f actual. |
|
|
Disable the generation of EIT schedule actual. |
|
|
Disable the generation of all EIT other. |
|
|
Disable the generation of EIT p/f other. |
|
|
Disable the generation of EIT schedule other. |
|
|
Disable the generation of all EIT p/f. |
|
|
Disable the generation of all EIT schedule. |
|
|
Enable the generation of all EIT other. |
|
|
Enable the generation of EIT p/f other. |
|
|
Enable the generation of EIT schedule other. |
|
|
Enable the generation of all EIT p/f. |
|
|
Use the EIT cycle profile for satellite and cable networks as specified in [ETSI-101-211]. |
|
|
Enable the generation of all EIT schedule. |
|
|
Use the EIT cycle profile for terrestrial networks as specified in [ETSI-101-211]. |
|
|
Set the current date and time in the transport stream. Use "year/month/day:hour:minute:second.millisecond" format. |
|
|
Set the transport stream bitrate in bits/second. |
|
|
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]
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
.
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
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.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.
|
Do not run any test. This is the default. |
|
Get a short list of all tuner and receiver DirectShow filters. |
|
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. |
|
List all DirectShow tuning spaces which are installed in the system and their compatibility with the various network providers. |
|
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.
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 thetsp
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.
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
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.
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
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
--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 thenname.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.
See also option --eit-base-date
.
--eit-other
With --eit-normalization
, generate all EIT Other.
Same as --eit-other-pf --eit-other-schedule
.
--eit-other-pf
With --eit-normalization
, generate EIT p/f Other.
If no EIT selection option is specified, all EIT’s are generated.
--eit-other-schedule
With --eit-normalization
, generate EIT Schedule Other.
If no EIT selection option is specified, all EIT’s are generated.
--eit-pf
With --eit-normalization
, generate all EIT p/f.
Same as --eit-actual-pf --eit-other-pf
.
--eit-schedule
With --eit-normalization
, generate all EIT Schedule.
Same as --eit-actual-schedule --eit-other-schedule
.
--pack-and-flush
When loading a binary section file, pack incomplete tables, ignoring missing sections, and flush them. Sections are renumbered to remove any hole between sections.
Use with care because this may create inconsistent tables.
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.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
|
Terminate the tsp process. |
|
Usage: |
|
|
|
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 all running plugins. The listed plugin indexes can be used with other control commands
such as |
|
Usage: |
|
|
|
Produce verbose output. |
|
|
Restart a plugin with different parameters. |
|
Usage: |
|
|
Parameters: |
Index of the plugin to restart, followed by the new plugin parameters to use. |
|
|
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. |
|
|
Produce verbose output. |
|
|
Resume a suspended plugin. |
|
Usage: |
|
|
Parameter: |
Index of the plugin to resume. |
|
|
Produce verbose output. |
|
|
Change the log level in the |
|
Usage: |
|
|
Parameter: |
Specify a new logging level for the |
|
|
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: |
|
|
Parameters: |
Index of the plugin to suspend. |
|
|
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
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.
--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.
--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
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.
--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
--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
.
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.
See also option --uhf-band
.
Tuner device options and tuning parameters
All options from the dvb
input plugin are also available to tsscan
.
As an exception, the option --delivery-system
can be specified several times with tsscan
(see below).
See section 4.21 for the list of tuning options.
In the dvb
input plugin documentation, the "reception options" specify which tuner to use and basic reception timeouts.
These options are used by tsscan
in all types of scanning.
--delivery-system value
Specify which delivery system to use.
With --nit-scan
, this is the delivery system for the stream which contains the NIT to scan.
With --uhf-band
and --vhf-band
, the option can be specified several times.
In that case, the multiple delivery systems are tested in the specified order on each channel.
This is typically used to scan terrestrial networks using DVB-T and DVT-T2.
Be aware that the scan time is multiplied by the number of specified systems on channels without signal.
With UHF and VHF scanning, the only allowed modulations are DVB-T (the default) and DVB-T2.
Other specific tuning parameters are used with --nit-scan
only.
They are used to receive the initial reference transport stream from which the NIT is analyzed.
When the delivery system is not specified, the default system for the tuner is used. When it is specified, the delivery system must be one of the following values:
Value | Description | Supported options |
---|---|---|
|
ATSC |
|
|
ATSC -M/H (handheld) |
Unsupported |
|
CMMB Terrestrial |
Unsupported |
|
DAB (digital audio) |
Unsupported |
|
DSS Satellite |
Unsupported |
|
DTMB Terrestrial |
Unsupported |
|
DVB-C (same as |
Same as |
|
DVB-C ITU-T J.83 Annex A |
|
|
DVB-C ITU-T J.83 Annex B |
Unsupported |
|
DVB-C ITU-T J.83 Annex C |
Same as DVB-C/A |
|
DVB-C2 |
Unsupported |
|
DVB-H (deprecated) |
Unsupported |
|
DVB-S |
|
|
DVB-S Turbo |
Unsupported |
|
DVB-S2 |
|
|
DVB-T |
|
|
DVB-T2 |
|
|
ISDB-C |
Unsupported |
|
ISDB-S |
|
|
ISDB-T |
|
|
Undefined |
Unsupported |
Scanning options
--best-strength
With UHF/VHF-band scanning, for each channel, use the offset with the best signal strength. By default, use the average of lowest and highest offsets with required minimum strength.
Note that some tuners cannot report a correct signal strength, making this option useless.
--first-channel value
For UHF/VHF-band scanning, specify the first channel to scan (default: lowest channel in band).
--first-offset value
For UHF/VHF-band scanning, specify the first offset to scan on each channel.
Note that tsscan
may scan lower offsets.
As long as some signal is found at a specified offset, tsscan
continues to check up to 3 lower offsets below the "first" one.
This means that if a signal is found at offset -2, offset -3 will be checked anyway, etc. up to offset -5.
-g
--global-service-list
Same as --service-list
but display a global list of services at the end of scanning instead of per transport stream.
--last-channel value
For UHF/VHF-band scanning, specify the last channel to scan (default: highest channel in band).
--last-offset value
For UHF/VHF-band scanning, specify the last offset to scan on each channel.
Note that tsscan
may scan higher offsets.
As long as some signal is found at a specified offset, tsscan
continues to check up to 3 higher offsets above the "last" one.
This means that if a signal is found at offset +2, offset +3 will be checked anyway, etc. up to offset +5.
--min-strength value
Minimum signal strength. Frequencies with lower signal strength are ignored.
The value can be in milli-dB or percentage. It depends on the tuner and its driver. Check the displayed unit. The default is 10, whatever unit it is.
--no-offset
For UHF/VHF-band scanning, scan only the central frequency of each channel.
This is now the default.
Specify option --use-offsets
to scan all offsets.
--psi-timeout milliseconds
Specifies the timeout, in milliseconds, for PSI/SI table collection.
Useful with --service-list
or NIT-based scan.
The default is 10,000 milli-seconds.
--save-channels filename
Save the description of all channels in the specified XML file. See appendix B, for more details on channels configuration files.
If the file name is -
, use the default tuning configuration file.
See also option --update-channels
.
-l
--service-list
Read the SDT of each channel and display the list of services.
--show-modulation
Display modulation parameters.
On Windows, with UHF band scanning, the actual modulation parameters of a transponder may not be available. This depends on the driver of the tuner. Most Windows drivers do not report the correct values. |
--update-channels filename
Update the description of all channels in the specified XML file. The content of each scanned transport stream is replaced in the file. If the file does not exist, it is created. See appendix B, for more details on channels configuration files.
If the file name is -
, use the default tuning configuration file.
See also option --save-channels
.
--use-offsets
For UHF/VHF-band scanning, do not scan only the central frequency of each channel. Also scan frequencies with offsets.
As an example, if a signal is transmitted at offset +1, the reception may be successful at offsets -1 to +3 (but not -2 and +4).
With this option, tsscan
checks all offsets and reports that the signal is at offset +1 (central point between offsets -1 and +3).
By default, tsscan
reports that the signal is found at the central frequency of the channel (offset zero).
This significantly speeds up the scanning process but does not provide any offset information.
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
--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.
--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.
--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
--hf-band-region japan
.
See section 2.4.2 and section 2.5.2 for more details.
--philippines
A synonym for
--isdb
--abnt
--default-charset RAW-UTF-8
--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
--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.
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.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
andprevious
(orprev
) to switch to the next and previous input, respectively. -
Strings
exit
orquit
to properly terminatetsswitch
. -
Strings
halt
orabort
to immediately abort thetsswitch
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]
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
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.
--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.
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.
See also option --eit-base-date
.
--eit-other
With --eit-normalization
, generate all EIT Other.
Same as --eit-other-pf --eit-other-schedule
.
--eit-other-pf
With --eit-normalization
, generate EIT p/f Other.
If no EIT selection option is specified, all EIT’s are generated.
--eit-other-schedule
With --eit-normalization
, generate EIT Schedule Other.
If no EIT selection option is specified, all EIT’s are generated.
--eit-pf
With --eit-normalization
, generate all EIT p/f.
Same as --eit-actual-pf --eit-other-pf
.
--eit-schedule
With --eit-normalization
, generate all EIT Schedule.
Same as --eit-actual-schedule --eit-other-schedule
.
--pack-and-flush
When loading a binary section file, pack incomplete tables, ignoring missing sections, and flush them. Sections are renumbered to remove any hole between sections.
Use with care because this may create inconsistent tables.
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.
--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.
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]
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
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.
--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.
--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
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.
--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
--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
.
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]
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.
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.
See also --include-next
.
--fill-eit
Before exiting, add missing empty sections in EIT’s and flush them. This can be useful with segmented EIT schedule where empty sections at end of segments are usually not transmitted.
--include-next
Include long sections with "next" indicator. By default, they are excluded.
--invalid-sections
Display and dump invalid sections. These sections are normally dropped because they are truncated, incomplete, corrupted, have an invalid CRC32, etc. Because these sections are invalid, they cannot be formatted as normal sections. Instead, a binary and text dump is displayed.
--invalid-versions
Track invalid version numbers in sections.
Per MPEG rules, the version number of a section with long header shall be updated each time the content of the section is updated. With this option, the content of the sections is tracked to detect modified sections without version updates.
These events are considered as errors.
-x value
--max-tables value
Maximum number of tables to dump. Stop execution when this limit is reached.
--negate-pid
Negate the PID filter: specified PID’s are excluded.
Warning: this can be a dangerous option on complete transport streams since PID’s not containing sections can be accidentally selected.
--negate-section-number
Negate the section number filter: specified sections are excluded.
-n
--negate-tid
Negate the TID filter: specified TID’s are excluded.
--negate-tid-ext
Negate the TID extension filter: specified TID extensions are excluded.
--no-deep-duplicate
Do not report identical sections in the same PID, even when non-consecutive. A hash of each section is kept for each PID and later identical sections are not reported.
Warning: This option accumulates memory for hash values of all sections since the beginning. Do not use that option for commands running too long or the process may crash with insufficient memory.
--no-duplicate
Do not report consecutive identical tables with a short section in the same PID.
This can be useful for ECM’s. This is the way to display new ECM’s only.
By default, tables with long sections are reported only when a new version is detected but tables with a short section are all reported.
--only-invalid-sections
Same as --invalid-sections
but do not display valid tables and sections, only invalid sections.
--pack-all-sections
Same as --all-sections
but also modify each long section so that it becomes a valid complete table.
Its section_number and last_section_number are forced to zero.
Use with care because this may create inconsistent tables.
This option can be useful with tables with sparse sections such as EIT’s to save them in XML format
(as an alternative, see also --fill-eit
).
--pack-and-flush
Before exiting, pack incomplete tables, ignoring missing sections, and flush them.
Use with care because this may create inconsistent tables.
Unlike option --pack-all-sections
, --pack-and-flush
does not force --all-sections
because it only applies to the last incomplete tables before exiting.
-p pid1[-pid2]
--pid pid1[-pid2]
PID filter: select packets with these PID values.
Several --pid
options may be specified.
By default, without --pid
option, all PID’s are used.
PID’s containing PES data are automatically ignored.
--psi-si
Add all PID’s containing PSI/SI tables, ie. PAT, CAT, PMT, NIT, SDT and BAT. The PMT PID’s are dynamically collected each time a new PAT is encountered.
Note that EIT, TDT and TOT are not included.
Use --pid 18
to get EIT and --pid 20
to get TDT and TOT.
--section-content hexa-data
Binary content filter: Specify binary data that must match the beginning of the section.
The value must be a string of hexadecimal digits specifying any number of bytes.
See also option --section-mask
to specify selected bits or bytes only.
--section-mask hexa-data
With --section-content
, specify a mask of meaningful bits in the binary data that must match the beginning of the section.
The value must be a string of hexadecimal digits specifying any number of bytes.
If omitted or shorter than the --section-content
parameter, the mask is implicitely padded with FF bytes.
--section-number num1[-num2]
Section number filter: when sections are filtered individually instead of complete tables (--all-sections
),
select sections with this section number or range of section numbers.
Several --section-number
options may be specified.
-t id1[-id2]
--tid id1[-id2]
TID filter: select sections with these TID (table id) values.
Several --tid
options may be specified.
Without --tid
option, all tables are saved.
-e id1[-id2]
--tid-ext id1[-id2]
TID extension filter: select sections with these table id extension values (apply to long sections only).
Several --tid-ext
options may be specified.
Without --tid-ext
option, all tables are saved.
Output options
-b file-name
--binary-output file-name
Save the sections in raw binary format in the specified output file name.
If the file name is empty or a dash (-
), the binary sections are written to the standard output.
See also option --multiple-files
.
-f
--flush
Flush standard output after each display. Useful to monitor the content if the output has been redirected to a disk file.
--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
Display a short one-line log of each table instead of full table display.
--log-hexa-line[='prefix']
Log each binary table (or section with --all-sections
)
as one single hexadecimal line in the message logger instead of an output binary file.
The optional string parameter specifies a prefix to prepend on the log line before the hexadecimal text to facilitate the filtering of the appropriate line in the logs.
--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-size value
With option --log
, specify how many bytes are displayed at the beginning of the table payload
(the header is not displayed).
The default is 8 bytes.
--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.
--meta-sections
Add an hexadecimal dump of each section in the XML and JSON metadata.
-m
--multiple-files
Create multiple binary output files, one per section.
A binary output file name must be specified (option --binary-output
).
Assuming that the specified file name has the form base.ext
,
each file is created with the name base_pXXXX_tXX.ext
for short sections and
base_pXXXX_tXX_eXXXX_vXX_sXX.ext
for long sections, where the XX
respectively specify
the hexadecimal values of the PID, TID (table id), TIDext (table id extension), version and section index.
--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.
-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 like binary files (--binary-output
)
or UPD/IP (--ip-udp
), explicitly specify this option with -
as output file name.
--packet-index
Display the index of the first and last TS packet of each displayed section or table.
--rewrite-binary
With --binary-output
, rewrite the same file with each table.
The specified file always contains one single table, the latest one.
--rewrite-json
With --json-output
, rewrite the same file with each table.
The specified file always contains one single table, the latest one.
--rewrite-xml
With --xml-output
, rewrite the same file with each table.
The specified file always contains one single table, the latest one.
--time-stamp
Display a time stamp (current local time) with each table.
--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.
UDP/IP logging options
-i address:port
--ip-udp address:port
Send binary tables over UDP/IP to the specified destination. 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.
See also option --udp-format
.
--local-udp address
With --ip-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.
--no-encapsulation
With --ip-udp
, send the tables as raw binary messages in UDP packets.
By default, the binary tables are formatted into TLV messages.
Ignored if --udp-format
is not binary
(the default).
--ttl value
With --ip-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.
--udp-format value
With --ip-udp
, specify the format of sections in the UDP datagrams.
The value must be one of binary
, JSON
, XML
.
The default is binary
.
With --all-sections
or --all-once
, the only allowed format is binary
.
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
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.
--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.
--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
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.
--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
--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
.
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.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
, ortsp -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
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.
--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]
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.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.
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.
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.
Plugin | Type | Description |
---|---|---|
|
packet |
Experimental AES scrambling |
|
packet |
Analyze the structure of the transport stream |
|
packet |
Perform various transformations on the BAT |
|
packet |
Monitor the bitrate of the TS or a given set of PID’s |
|
packet |
Boost the bitrate of a PID, stealing stuffing packets |
|
packet |
Perform various transformations on the CAT |
|
packet |
Extract clear (non-scrambled) sequences |
|
packet |
Check TS continuity counters |
|
packet |
Count TS packets per PID |
|
input, packet |
Build or modify specifically crafted packets |
|
packet |
Set labels on TS packets upon reception of UDP messages |
|
packet |
DVB SimulCrypt-compliant EMM and private data injector |
|
packet |
Decapsulate TS packets from a PID produced by |
|
input, output |
Dektec DTA-1xx DVB-ASI and modulator devices I/O |
|
packet |
Generic DVB descrambler |
|
output |
Drop output packets |
|
packet |
Dump transport stream packets |
|
packet |
Duplicate PID’s, reusing null packets |
|
input |
DVB receiver devices (DVB-S, DVB-C, DVB-T) input |
|
packet |
Analyze EIT sections |
|
packet |
Generate and inject EIT’s in a transport stream |
|
packet |
Encapsulate packets from several PID’s into one single PID |
|
packet |
Extract an inner TS from an outer feed TS (experimental) |
|
input, output, packet |
Transport stream files input / output. As packet processor plugin, save packets to a file and pass to next plugin |
|
packet |
Filter TS packets according to various criteria |
|
input, output, packet |
Exchange packets with a created process, either input or output |
|
packet |
Introduce random errors in the transport stream |
|
output |
Send the transport stream to a HiDes modulator device |
|
packet |
Report a history of major events on the transport stream |
|
input, output |
Receive or generate HTTP Live Streaming (HLS) media |
|
input, output |
Send / receive a transport stream as / from an HTTP server |
|
packet |
Inject a table into a transport stream |
|
input, output, packet |
Send / receive UDP/IP datagrams, including multicast IP and RTP |
|
packet |
Extract ISDB-T information from the stream |
|
packet |
Limit the global bitrate by dropping packets |
|
input, output |
Direct memory input / output with an application |
|
packet |
Merge TS packets coming from the output of a created process |
|
packet |
Extract MPE (Multi-Protocol Encapsulation) datagrams |
|
packet |
Encapsulate and inject an incoming UDP stream into MPE |
|
packet |
Inject TS packets from a file into the transport |
|
packet |
Perform various transformations on the NIT |
|
packet |
Scan the NIT for tuning information |
|
input |
Null packets generator |
|
packet |
Perform various transformations on the PAT |
|
packet |
Replace packet payload with a binary pattern |
|
input |
Read TS packets from a pcap or pcap-ng file |
|
packet |
Adjust PCR’s according to a constant bitrate |
|
packet |
Permanently recompute bitrate based on PCR’s |
|
packet |
Copy and synchronize PCR’s from one PID to another |
|
packet |
Edit PCR, PTS and DTS values in various ways |
|
packet |
Extract PCR’s from TS packets |
|
packet |
Verify PCR values |
|
packet |
Analyze PES packets |
|
packet |
Shift one or more PID’s forward in the transport stream |
|
output |
Play output TS on a media player |
|
packet |
Perform various transformations on the PMT |
|
packet |
Extract all PSI tables (PAT, CAT, PMT, NIT, BAT, SDT) |
|
packet |
Merge PSI/SI from mixed streams |
|
packet |
Reduce the bitrate by removing stuffing packets |
|
packet |
Regulate TS packets flow according to a bitrate or PCR |
|
packet |
Generic PID remapper |
|
input, output |
Send / receive using Reliable Internet Stream Transport (RIST) |
|
packet |
Remove unreferenced ("orphan") PID’s |
|
packet |
Remove ads insertions using SCTE 35 splicing information |
|
packet |
DVB scrambler |
|
packet |
Perform various transformations on the SDT |
|
packet |
Remove or merge sections from various PID’s |
|
packet |
Extract PSI/SI PID’s |
|
packet |
Skip leading packets in a TS |
|
packet |
Pass or drop packets based on packet numbers or relative time |
|
packet |
Inject SCTE 35 splice commands in a transport stream |
|
packet |
Monitor SCTE 35 splice information |
|
input, output |
Send / receive packets using Secure Reliable Transport (SRT) |
|
packet |
Report various statistics on PID’s and labels |
|
packet |
Analyze the level of stuffing in sections |
|
packet |
Remove a service |
|
packet |
Rename a service (modify service id, name, type, etc.) |
|
packet |
Resynchronize the clock of a service based on another service |
|
packet |
Extract T2-MI (DVB-T2 Modulator Interface) packets |
|
packet |
Collect MPEG tables |
|
packet |
Extract Teletext subtitles in SRT format |
|
packet |
Schedule packets pass or drop |
|
packet |
Update TDT and TOT with a new time reference |
|
packet |
Delay transmission by a fixed amount of packets |
|
packet |
Trace packets with a custom message |
|
packet |
Trigger actions on selected labeled TS packets |
|
packet |
Rename a transport stream (modify ts id, etc.) |
|
packet |
Pass TS packets until specified conditions |
|
output |
Send the transport stream to a VATek-based modulator device |
|
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.
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 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
.
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.
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.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 232 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.
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.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.
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.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.
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.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 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 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.
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.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.
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.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.
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.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.
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.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:
|
Set the label n on the next TS packet (only once). |
|
Set the label n on all TS packets (until the next |
|
Stop setting the label n on all TS packets. |
|
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
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.
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.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]
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 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.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.
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.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.
Value | Description |
---|---|
|
DVB-ASI transport stream |
|
DVB-SPI transport stream |
|
IF A/D converter |
|
Transport stream over IP |
|
DekTec Streaming-data Interface |
|
Demodulator input |
|
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: |
|
DVB-S2: |
|
DVB-T: |
|
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
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 -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.
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
.
Modulation | Applicable options |
---|---|
All (common options) |
|
DVB-ASI |
|
All except DVB-ASI |
|
x-QAM |
|
ADBT-T, DMB-T/H |
|
ATSC |
|
DVB-S |
|
DVB-S2 |
|
DVB-T |
|
DVB-T2 |
|
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.
Value | Description |
---|---|
|
DVB-ASI transport stream |
|
DVB-SPI transport stream |
|
IF A/D converter |
|
Transport stream over IP |
|
DekTec Streaming-data Interface |
|
Demodulator input |
|
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: |
|
DVB-S2: |
|
DVB-T: |
|
--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).
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 it is an empty string or a dash (-
), the first service in the PAT is descrambled.
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.
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.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.
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.
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
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
.
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.
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.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.
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.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 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 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.
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.
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:
Value | Description | Supported options |
---|---|---|
|
ATSC |
|
|
ATSC -M/H (handheld) |
Unsupported |
|
CMMB Terrestrial |
Unsupported |
|
DAB (digital audio) |
Unsupported |
|
DSS Satellite |
Unsupported |
|
DTMB Terrestrial |
Unsupported |
|
DVB-C (same as |
Same as |
|
DVB-C ITU-T J.83 Annex A |
|
|
DVB-C ITU-T J.83 Annex B |
Unsupported |
|
DVB-C ITU-T J.83 Annex C |
Same as DVB-C/A |
|
DVB-C2 |
Unsupported |
|
DVB-H (deprecated) |
Unsupported |
|
DVB-S |
|
|
DVB-S Turbo |
Unsupported |
|
DVB-S2 |
|
|
DVB-T |
|
|
DVB-T2 |
|
|
ISDB-C |
Unsupported |
|
ISDB-S |
|
|
ISDB-T |
|
|
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
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.
--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.
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.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