playerHeartbeat

POST

/api/v1/player/heartbeat

const url = 'https://example.com/api/v1/player/heartbeat';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"playerFamily":"example","playerArchitecture":"example","noiseMeter":{"status":"active","currentLevel":1,"pendingHistory":[{"startedAt":"2026-04-15T12:00:00Z","averageLevel":1,"peakLevel":1,"monitoredMs":1,"warningMs":1,"loudMs":1,"triggerCount":1}]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/api/v1/player/heartbeat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "playerFamily": "example", "playerArchitecture": "example", "noiseMeter": { "status": "active", "currentLevel": 1, "pendingHistory": [ { "startedAt": "2026-04-15T12:00:00Z", "averageLevel": 1, "peakLevel": 1, "monitoredMs": 1, "warningMs": 1, "loudMs": 1, "triggerCount": 1 } ] } }'

Accepts the authenticated Player heartbeat. Optional Linux Display Control fields report detected providers, independent capabilities, display power observations, and policy state. They do not determine Player online status; command acknowledgement and display state confirmation remain separate.

The optional noiseMeter object carries the Noise Meter plugin’s live state and its completed ten-second history buckets. It is derived numbers only — no audio, waveform, or sample is exchanged in either direction. The screen is taken from the authenticated device credential, never from the body, and a batch is bounded to 120 records. Storage is idempotent on screen plus bucket start, so a retried heartbeat cannot duplicate history.

Authorizations

deviceBearer

Request Body

application/json

The Player status document. Only the optional Noise Meter section and the release family fields are described here; the remaining fields are the existing heartbeat contract and are additive.

object

playerFamily

android, electron-linux or edge. The server keeps only these values; another value is recorded as absent.

string

playerArchitecture

x86_64 or aarch64, kept only with playerFamily: edge. An Edge screen without a known architecture is incompatible for Edge deployments.

string

noiseMeter

Noise Meter plugin state. Contains no audio, waveform, or sample, and levels are the relative 0-100 Tilecast scale rather than dB, dBA, or SPL.

object

status

Allowed values: active normal loud unavailable inactive

currentLevel

The live relative level when the heartbeat was built.

number

<= 100

pendingHistory

The oldest unacknowledged ten-second buckets. Bounded per heartbeat; the rest stay queued on the Player for later heartbeats rather than accelerating the cadence.

Array<object>

<= 120 items

object

startedAt

required

Start of the fixed ten-second grid slot.

string format: date-time

averageLevel

required

number

<= 100

peakLevel

required

number

<= 100

monitoredMs

required

How much of the bucket the microphone actually covered, so a partly monitored slot is not read as ten seconds of quiet.

integer

<= 10000

warningMs

required

integer

<= 10000

loudMs

required

integer

<= 10000

triggerCount

Times the Player’s state machine entered its loud state in this bucket, counted where it happened.

integer

<= 1000

Responses

200

Heartbeat accepted. data.ignoredFields names optional playback identifiers that were malformed and therefore dropped. data.noiseHistory.accepted is how many submitted Noise Meter records the server has taken responsibility for; a Player keeps its batch until it sees that count.

400

Heartbeat body rejected

401

Credential invalid or revoked

403

Screen disabled