# DCP-Cine Player device metadata handoff for Cinema Catcher 13 October 2026. Current implementation: **4.2.20 beta** (initial metadata release 4.2.18). Contract: `d-cine.player-api.device-info.v1`. Read the [OpenAPI contract](player-api.openapi.json), [administrator guide](device-metadata-administration.md) and [qualification results](device-info-qualification.md). The required identity/component/audio/screen contract is implemented. **Connected-equipment inventory is deferred**, negotiated as false and returned as `{"state":"unsupported","items":[]}`. Existing Catcher assignments remain its authoritative equipment inventory. ## Negotiation and authentication Authenticate with the existing login session, bearer token, or `X-DCP-Player-API-Key`, then read `/api/player/v1/capabilities`. `device_metadata` advertises schema, endpoint, identity, components and audio; these flags promise the contract, not that every value is known. `GET /api/player/v1/device-info` requires `status.read`. No playback/ingest licence or recipient certificate is needed. Responses are JSON with `Cache-Control: no-store`. Reads use a single saved metadata record, cached native-engine handshake, and cached licence state; there is no network device query, scan, certificate access or control command. A 1.5-second read deadline bounds storage access. Optional unavailable values produce warnings; unusable snapshot storage returns structured 503 `METADATA_UNAVAILABLE`. Status/playback/ingest remain independent of this optional metadata record. ## Identity and running versions `player.device_id` is a persisted installation UUID (`urn:uuid:...`), allocated once on database startup independently of IP, host name, certificate and audit journal identities. Restart, upgrade and certificate rotation preserve it. An offline clone must be explicitly provisioned with a new ID before first use; see the administrator guide. Never rotate the production recipient certificate as a qualification shortcut. Product is `dcp-cine-player`. Manufacturer/model default to null until confirmed by the maintainer or explicitly configured by an administrator. The issued product serial comes from the licence registration; an unregistered demo reports null. No Git vendor, current certificate serial, Host ID, monitor EDID or Barco label supplies these identity fields. Configured manufacturer/model have source `operator`; otherwise identity source is `installation`. See the licence-owned serial rules below. There is no automatic hardware identity discovery. Components always include the **actual running service build** (`player-service`, Software, source build). A connected upgraded native engine contributes its separate **compiled engine version** (`playback-engine`, Software, source build). Mixed service/engine versions are reported separately, not collapsed. A legacy engine without this handshake contributes an ENGINE_VERSION_UNREPORTED warning. No standalone firmware/security-manager component is claimed by this software installation. Explicit administrator components may describe an actually known security manager and its actual classification/version; unclassified kind is null. Manually entered versions use source operator. Reserved running-component IDs cannot be overridden. Legacy `/identity.serial` is **certificate serial** and is unchanged; new `certificate_serial_number` is its equal alias. The public leaf PEM download and missing-certificate 503 behaviour remain unchanged. No private key or certificate chain was added. Neither certificate serial nor Host ID becomes equipment serial. Native and SOAP reads share the same internal identity/component snapshot. The SOAP **default remains legacy_barco**: `Barco ICMP`, `D-Cine Player compatibility`, and the legacy Host ID serial field. Native `protocol_compatibility.barco` explicitly identifies this emulation. Only an administrator selecting `soap_identity_mode:"real"` switches GetProductInformation to the real product/model/issued serial and service version. Unknown model/serial becomes empty SOAP text, while native JSON remains null. Qualify a legacy TMS before changing this setting; no real legacy client's identity parsing was qualified by the isolated SOAP fixtures. ## Audio and screen declarations `audio.decode_formats` is null until a connected native engine explicitly advertises implementation support; its source is then runtime_capability. The DCP/PCM build advertises 5.1 and 7.1; it does **not** advertise IAB. Disabled native audio or a build without DCP audio advertises []. A valid licence omitting playback changes the available formats to []; demo evaluation retains the implementation's allowed playback. No catalogue, cue name, channel count or processor branding is used to infer formats. This describes decoding/routing implementation availability, not verified auditorium loudspeaker playability. `installed_formats` is an independent operator declaration: null is unconfigured, [] is an explicit declaration of none, and the initial accepted labels are 5.1, 7.1, IAB. It is not changed by current CPL, audio route/layout, or licence changes. Source is operator only when declared. The UTC timestamp records the declaration change and is cleared when returned to unconfigured; repeated identical saves retain it. An unavailable declared format remains declared and produces AUDIO_CONFIGURATION_MISMATCH. Neither this warning nor a declaration certifies actual playout capability. Digital 3D and closed-caption support are independently nullable booleans. Null is unknown; false/true are explicit operator declarations. No subtitles, filenames, licences, connected equipment or 3D cues infer these flags. Identity fields are limited to 50 Unicode characters, component description 256, version 512. Oversized/invalid administrator input is rejected. Unusable cached fields become null (or the affected unusable entry is omitted) with INVALID_METADATA_VALUE; valid fields remain available. No silent truncation. ## Administrator configuration contract `GET /api/player/v1/device-info/configuration` returns the portable saved fields, installation ID and audio declaration timestamp. Authenticated read-status users can inspect these fields. `PUT` requires **config.write (administrator)** and is a complete replacement of declaration fields only. `device_id` and declaration timestamp are server-owned and must not be sent in a PUT. Config is saved atomically without sending a device control command, applying audio routing, or interrupting playback. ```json { "manufacturer": null, "model": null, "serial_number": null, "components": [], "installed_formats": ["5.1"], "digital_3d": null, "closed_captions": false, "soap_identity_mode": "legacy_barco" } ``` The GUI is **Config → System Details → Device identity and screen capabilities**. Its audio toggle buttons explicitly distinguish Unconfigured and None installed. These changes do not update Catcher's operator values automatically. ## Catcher adapter ownership and FLM Cache metadata for approximately 60 seconds. Metadata failure must leave player monitoring and existing saved Catcher/operator data usable. Preserve facility, screen, receiver and facility-scoped SourceId values. Do not equate a new device UUID or certificate rotation with permission to create/reassign equipment. Use real manufacturer/model/issued serial and structured components for FLM. Never import the SOAP compatibility label or `/identity.serial` as equipment truth. Suggested installed soundfield and screen declarations apply only to an unset Catcher configuration or explicit operator acceptance. Decode formats are TMS compatibility information, not the FLM audio declaration. Accept agreed future additive audio tokens without crashing. Catcher maps 5.1/7.1 to scoped 51/71 and IAB to its existing application scope, validates its SMPTE ST 430-16:2017 XML and publishes only after operator review. The player does not generate FLM, store an OpenTDL account, or contact dcnServices/tools.d-cine.net. Qualification on Catcher `10.30.1.246`, XML preview, publication to the existing linked office record and repeated-publication/receiver-ID checks belong to the Catcher adapter developer. No FLM publication or Catcher record change is performed by this implementation. ## Initial 4.2.18 delivery evidence Implementation commit: `138812326e90ebe406dc3c652488f7acdd55b5bf` (4.2.18). The player is installed and qualified; see `device-info-qualification.md`, `device-info-installation.json`, and `device-info-fixtures/player-device-info.json`. The response is from the real installation and includes no credentials, private keys or connection addresses. The maintainer has confirmed D-Cine as publisher and dcp-cine-player as the software-product model; these are saved administrator declarations on the real installation. The maintainer explicitly confirmed 260014 as the issued product serial; it is stored independently with source operator and is retained through certificate rotation. It was not automatically imported from a certificate. The current installed audio and screen declarations remain unconfigured. Connected-device inventory is **deferred**, not implemented. Catcher can qualify its adapter against this endpoint now; its existing receiver/facility IDs and operator overrides must be preserved. No Catcher configuration, XML publication or production certificate rotation is performed by this player release. ## Licence-owned serial update — 4.2.19 The product serial is now assigned to the licence registration by the authority, returned with license_id/serial_number on activation and heartbeat, and cached in the existing licence state file. The same licence retains its serial across reactivation, transfer and recipient certificate rotation. Another licence supplies its own serial. An unregistered/deactivated demo reports null in device-info, even if old certificates or 4.2.18 manual serial metadata remain. An expired but still registered licence retains its issued identity; temporary network errors also retain it. Rejected activation credentials or a confirmed machine mismatch clear the active registration identity. The native configuration shape remains compatible: serial_number is read-only; PUT may echo the current serial or supply null, but cannot set a different serial. The administrator panel displays the assigned value without an editable input. Manufacturer/model declarations and the installation UUID remain independent. Legacy /identity.serial and certificate_serial_number still describe the current certificate and may differ from the licence serial. SOAP real identity uses the same licence-owned serial; default legacy compatibility remains unchanged. Authority migration 0017 records the existing published serial of bound licence registrations once. Future certificate changes cannot rewrite that value. Existing unbound legacy registrations without recoverable identity require commissioning/review; new registrations receive their issued serial on activation. Qualification and live evidence: license-serial-qualification.md. ## Anonymous discovery addition — 4.2.20 GET /api/player/v1/discovery and /.well-known/dcp-cine-player now provide minimal product/version, installation UUID, licence-issued serial and public leaf PEM without login. Their /recipient-certificate children return the public leaf only. This addition does not change the authenticated device-info/status/configuration/ control contract. Read [the discovery API guide](player-discovery-api.md) for fields, error/partial-response semantics, scanner examples and public-key limits.