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

<<<
=== identify

[.cmd-header]
Identify PID's based on various criteria

This plugin explores the signalization of the transport stream to identify all PID's which satisfy some selection criteria.

By default, a log message is issued for each newly idenfied PID.
It is also possible to set one or more labels on all packets of the identified PID's.
Using labels, it is possible to identify these packets in other plugins, downstream the chain of processing.

When several selection criteria are specified, all criteria must be satisfied to identify the PID
(there is an "and" operator on all criteria).
To identify PID's which satisfy any of the selection criteria ("or" operator), simply use successive `identify` plugins,
one per criteria.

[.usage]
Usage

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

[.usage]
Options

[.opt]
*--all-set-label* _label1[-label2]_

[.optdoc]
Set the specified labels on all packets of all PID's in the TS after identifying the first PID.

[.optdoc]
This option is typically useful with `--set-environment-variable`.
If another plugin, downstream the chain, uses this environment variable,
using `--only-label NN` on that plugin ensures that the plugin only starts after the PID is identified
and therefore after the environment variable is defined.
As another more radical example, using `-P filter --negate --label NN` deletes all TS packets until the PID is idenfified.

[.optdoc]
See also the option `--set-label`.

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

[.optdoc]
Identify all PID's carrying audio.

[.opt]
*-l* _language-code_ +
*--language* _language-code_

With `--audio` or `--subtitles`, identify PID's carrying the specified language.
The specified name must be a 3-character ISO-639 language code.

[.opt]
*--log*

[.optdoc]
Log a message on each newly identified PID.

[.optdoc]
This is the default when nothing else is specified
(none of `--set-label`, `--all-set-label`, `--set-environment-variable`).

[.opt]
*-p* +
*--pmt*

[.optdoc]
Identify all PID's carrying PMT's.

[.opt]
*--registration* _value1[-value2]_

[.optdoc]
Identify all PID's with a registration descriptor in the PMT containing the specified value
(or in the specified range of values).

[.optdoc]
Several options --registration are allowed.

[.opt]
*--scte-35*

[.optdoc]
Identify all PID's carrying SCTE-35 splice commands.

[.opt]
*-s* _name-or-id_ +
*--service* _name-or-id_

[.optdoc]
Identify all PID's belonging to the specified service.
include::{docdir}/opt/optdoc-service.adoc[tags=!*]

[.opt]
*--set-environment-variable* _name_

[.optdoc]
When a PID is identified, define the specific environment variable with this PID value.
This environment variable can be reused in a XML patch file in another plugin, downstream the chain, for instance.

[.optdoc]
It is recommended to use this option only when one PID will be identified.
When several PID's are identified, the environment variable is redefined for each new identified PID
and using the environment variable later produces different results.

[.opt]
*--set-label* _label1[-label2]_

[.optdoc]
Set the specified labels on all packets of the identified PID's.

[.optdoc]
Several `--set-label` options may be specified, all labels are set on all identified PID's.

[.opt]
*--stream-type* _value1[-value2]_

[.optdoc]
Identify all PID's with any of the specified stream types in the PMT.

[.optdoc]
Several options --stream-type are allowed.

[.opt]
*--subtitles*

[.optdoc]
Identify all PID's carrying subtitles.

[.opt]
*-v* +
*--video*

[.optdoc]
Identify all PID's carrying video.

[.optdoc]
Several `--set-label` options may be specified.

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