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

[#chap-sixmlref]
[appendix]
== PSI/SI XML Reference Model

This appendix describes the XML reference format for all tables and descriptors.

=== PSI/SI file format

The format which is used here is informal.
See xref:xml-models[xrefstyle=short] about XML model files.

Additionally:

* Hexadecimal content is a suite of hexadecimal digits.
  Spaces are ignored.
  Note that the name _hexadecimal content_ is used for data blocks, usually private ones, of arbitrary length.
  This is different from integer values in attributes which can be represented as hexadecimal using the prefix `0x`.
  In _hexadecimal content_ blocks, there is no `0x` prefix, everything is hexadecimal.
* The pseudo-node `<DESCRIPTOR_LIST>` is a place-holder for a sequence a descriptor nodes.
* Unsupported tables and descriptors can still be used.
  Their payloads must be specified as hexadecimal content.
  See tags `<generic_short_table>`, `<generic_long_table>` and `<generic_descriptor>` in xref:xml-generic[xrefstyle=short].

==== XML file structure

The `<tsduck>` root node contains any number of tables:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<tsduck>
  <!-- any number of table structures -->
</tsduck>
----

The table structures are documented in the following sections.
Descriptors are documented right after.
Tables and descriptors are grouped by standard bodies or private parties which defined them.

When a table or structure is not supported by TSDuck, it is still possible to represent it using
the generic structures `<generic_short_table>`, `<generic_long_table>` and `<generic_descriptor>`
(see xref:xml-generic[xrefstyle=short]).

[#table-metadata]
==== Table metadata

Although not documented in the following reference sections and not actually part of the binary table,
each table structure accepts the following metadata information.

This information is optional and typically generated by tools and plugins which extract tables from a stream.
They are informational only.

[source,xml]
----
<metadata PID="uint13, optional"
          time="YYYY-MM-DD hh:mm:ss, optional"
          first_ts_packet="uint64, optional"
          last_ts_packet="uint64, optional"
          attribute="string, optional">
  <section>
    Hexadecimal content.
  </section>
</metadata>
----

The `attribute` attribute contains a generic string which can be used by applications.
This is an application-specific attribute.
This string is not part of the table, it is not included in binary tables which are
injected in transport streams.

Each time an application reads an XML file, the binary tables have the corresponding
attribute string attached. The application is free to use it or ignore it.
Similarly, when an application sets an attribute string on a binary table and saves
the table in XML format, that string can be found in the `metadata` structure.

The `<section>` structures are used to propagate a copy of the entire binary sections of the original table.
There is one `<section>` structure per binary section.
These structures are generated by the command `tstables` and the plugin `tables` only when the
option `--meta-sections` is supplied.

=== MPEG-defined tables

include::.all.mpeg.tables.adoc[]

=== DVB-defined tables

include::.all.dvb.tables.adoc[]

=== Astra-defined tables

The European satellite operator SES Astra defines a few private tables.
They are used in the context of the DVB standard.

include::.all.astra.tables.adoc[]

=== SCTE-defined tables

include::.all.scte.tables.adoc[]

=== ATSC-defined tables

include::.all.atsc.tables.adoc[]

=== ISDB-defined tables

include::.all.isdb.tables.adoc[]

=== MPEG-defined descriptors

include::.all.mpeg.descriptors.adoc[]

=== SMPTE-defined descriptors (MPEG private descriptors)

include::.all.smpte.descriptors.adoc[]

=== DVB-defined descriptors

Note that a few descriptors are allowed in specific tables only since they reuse tag values which are
otherwise MPEG-reserved <<ISO-13818-1>>.
They cannot be used elsewhere.
These restrictions, when applicable, are documented in XML comments for the table-specific descriptor.
Such descriptors exist for the AIT <<ETSI-102-809>>, the UNT <<ETSI-102-006>> and the INT <<ETSI-301-192>>.

include::.all.dvb.descriptors.adoc[]

=== DTG/OFCOM-defined descriptors (DVB private descriptors)

include::.all.dtg.descriptors.adoc[]

=== EACEM-defined descriptors (DVB private descriptors)

include::.all.eacem.descriptors.adoc[]

=== Astra-defined descriptors (DVB private descriptors)

include::.all.astra.descriptors.adoc[]

=== Eutelsat-defined descriptors (DVB private descriptors)

include::.all.eutelsat.descriptors.adoc[]

=== NorDig-defined descriptors (DVB private descriptors)

include::.all.nordig.descriptors.adoc[]

=== BSkyB-defined descriptors (DVB private descriptors)

No public reference is available for BskyB private descriptors.

include::.all.sky.descriptors.adoc[]

=== Free TV Australia-defined descriptors (DVB private descriptors)

include::.all.australia.descriptors.adoc[]

=== AVS-defined descriptors (DVB private descriptors)

include::.all.avs.descriptors.adoc[]

=== AOM-defined descriptors (DVB private descriptors)

include::.all.aom.descriptors.adoc[]

=== UWA-defined descriptors (DVB private descriptors)

include::.all.uwa.descriptors.adoc[]

=== SCTE-defined descriptors

include::.all.scte.descriptors.adoc[]

=== ATSC-defined descriptors

include::.all.atsc.descriptors.adoc[]

=== ISDB-defined descriptors

include::.all.isdb.descriptors.adoc[]

[#xml-generic]
=== Generic format for unsupported tables and descriptors

Unsupported tables and descriptors can be represented using generic XML tags.

==== Generic short table

[source,xml]
----
<generic_short_table table_id="uint8, required" private="bool, default=true">

  Generic table with binary payload of one short section, to be used when a
  specific table is not yet implemented. The body of this element shall contain
  an even number of hexadecimal digits, the payload of the short section.

  The private indicator shall be false on MPEG-defined sections and preferably
  true on DVB-defined and user-defined sections.

</generic_short_table>
----

==== Generic long table

[source,xml]
----
<generic_long_table
    table_id="uint8, required"
    table_id_ext="uint16, default=0xFFFF"
    version="uint5, default=0"
    current="bool, default=true"
    private="bool, default=true">

  Generic table with binary payload of long sections, to be used when a specific
  table is not yet implemented.

  The private indicator shall be false on MPEG-defined sections and preferably
  true on DVB-defined and user-defined sections.

  <!-- One per section -->
  <section>
    The body of the section elements shall contain an even number of hexadecimal
    digits, the payload of the long section. The CRC32 field is not part of this
    payload, it will be recomputed.
  </section>

</generic_long_table>
----

==== Generic descriptor

[source,xml]
----
<generic_descriptor tag="uint8, required">

  Generic descriptor with binary payload, to be used when a specific descriptor
  is not yet implemented. The body of this element shall contain an even number
  of hexadecimal digits.

</generic_descriptor>
----
