//----------------------------------------------------------------------------
//
// TSDuck - The MPEG Transport Stream Toolkit
// Copyright (c) 2005-2025, Thierry Lelegard
// BSD-2-Clause license, see LICENSE.txt file or https://tsduck.io/license
//
//----------------------------------------------------------------------------

<<<
=== descrambler

[.cmd-header]
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]
Usage

[source,shell]
----
$ tsp -P descrambler [options] [service]
----

[.usage]
Parameter

[.opt]
_service_

[.optdoc]
The optional parameter specifies the service to descramble.

[.optdoc]
If no fixed control word is specified, ECM's from the service are used to extract control words.

[.optdoc]
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).
include::{docdir}/opt/optdoc-service.adoc[tags=!*]
If it is an empty string or a dash (`-`), the first service in the PAT is descrambled.

[.usage]
Options

[.opt]
*--cas-id* _value_

[.optdoc]
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.

[.opt]
*-p* _pid1[-pid2]_ +
*--pid* _pid1[-pid2]_

[.optdoc]
Descramble packets with these PID values.
Several `--pid` options may be specified.
By default, descramble the specified service.

[.opt]
*--swap-cw*

[.optdoc]
Swap even and odd control words from the ECM.
Useful when a crazy ECMG inadvertently swapped the CW before generating the ECM.

[.opt]
*--synchronous*

[.optdoc]
Specify to synchronously decipher the ECM's.

[.optdoc]
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.

[.optdoc]
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.

[.optdoc]
NOTE: 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.

include::{docdir}/opt/group-scrambling.adoc[tags=!*]
include::{docdir}/opt/group-duck-context.adoc[tags=!*;charset]
include::{docdir}/opt/group-common-plugins.adoc[tags=!*]
