# Device metadata administrator guide

Available in 4.2.19 (metadata introduced in 4.2.18). Open **Config → System Details → Device identity and screen
capabilities**. All administrator changes require config.write; monitor/operator/
manager accounts cannot save declarations. Read-only API users can inspect them.

Enter only a confirmed publisher/manufacturer and real product/hardware model.
The issued product serial is read-only and supplied by licence registration.
Leave unknown editable fields blank (stored as JSON null).
An installation UUID, Host ID and recipient-certificate serial are separate
identifiers and do not establish an equipment serial. Text limits are 50 Unicode
characters. The installation UUID is shown read-only and cannot be changed through
the configuration endpoint.

For **Installed screen audio formats**, select Unconfigured when the screen has
not been commissioned, None installed for an explicit empty declaration, or toggle
5.1, 7.1 and IAB as applicable to the complete screen. These buttons do not route
audio, choose CPLs or claim decoder/IAB support. A mismatch with the currently
available decoder is reported while retaining your declaration.

Digital 3D and Closed captions each have Unconfigured/Unsupported/Supported
choices. These are operator declarations, not hardware certification. Save the
panel explicitly. Changes survive restart and upgrade; current playback/output
layout never changes them. The audio declaration timestamp changes only when the
saved formats change.

SOAP identity defaults to **Legacy Barco compatibility**. Keep it for existing
unqualified SOAP clients. Select **Real product identity** only after confirming
that the site's TMS handles the actual product/model and an absent issued serial.
The native device-info endpoint always reports real identity and identifies the
selected compatibility mode separately.

Additional known component versions may be declared with the documented API's
components array. Use source operator, a stable unique lowercase component ID,
an explicit description (maximum 256 characters), actual version (maximum 512),
nullable manufacturer (maximum 50), and kind Software/Firmware/Hardware or null.
Describe a security manager explicitly if one actually exists; its kind follows
its implementation rather than being assumed Firmware. IDs player-service and
playback-engine are reserved for actual running builds.

## Offline clone provisioning

Never start two installations cloned with the same portable device ID. Stop the
cloned player's service and back up its database. On the **offline clone only**,
run:

```sh
python3 scripts/provision-player-device-id.py /path/to/player.sqlite --new-installation
```

An installed Debian package also provides this helper as
`/usr/libexec/dcp-cine-player/provision-player-device-id`.

The command creates a fresh UUID and clears copied equipment identity, operator
components, SOAP mode and screen declarations. `--retain-screen-declarations`
retains only audio/3D/caption declarations when intentionally reusing those screen
settings; it still clears copied equipment identity and components. Restart the
clone and inspect device-info to confirm a different UUID. Normal upgrades and
recipient certificate rotation must never invoke this command.

Provision fresh installation credentials/certificates separately using the
existing commissioning workflow. Do not distribute a copied private key or audit
history as the new installation's identity. This tool changes portable device
metadata only, not the recipient certificate or audit journal.

Persistence uses the existing SQLite settings record device_metadata_v1. Include
that record in normal backups/upgrades. A malformed optional metadata record
returns METADATA_UNAVAILABLE without preventing operational startup. Diagnose
storage/configuration before provisioning; a new ID is not a repair for an existing
installation.

## Licence-managed serial in 4.2.19

The serial field is read-only. Activate the intended licence through the existing
licence workflow; the authority supplies its issued product serial. Reactivating
that code preserves its serial even when certificates rotate or the licence is
transferred. Changing to another licence changes the issued product serial.
Unregistered/deactivated demos have no serial; existing manual metadata is not
used as a fallback. Expiry or a temporary network failure does not erase an
otherwise registered licence identity. No certificate is rotated by this update.