SyncClock common.sync-clock@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
contracts
Visibility
public
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/common/sync-clock.v1.json

common.sync-clock@1: one timeline for many players (seven domains plan B4). The authority stamps at_ms and seq when it accepts a change and fans the state out; a player computes where it should be as position_ms + (authority time now - at_ms) * rate when paused is false, and exactly position_ms when paused is true. Chat hosts a room's clock on its room socket, keeps the latest state in memory and in the room_sync_clocks table, refuses a set from anyone but the current common.control-lease@1 holder, and sends the state to a member when they join the room. Clock offset is measured over the same socket with time ping/pong pairs, best of five samples, refreshed every 60 s.

Fields

FieldTypeRequiredDescriptionConstraints
roomstringyesThe authority's room id (Chat: the room's slug).
  • pattern ^[a-z0-9][a-z0-9-]*$
  • minLength 1
  • maxLength 64
mediaone ofyesWhat is playing: an OpenVibe media ref or an https URL. A ref names a Media object; a URL is the media file itself.
position_msintegeryesThe media position at at_ms, in milliseconds. At most 30 days.
  • minimum 0
  • maximum 2592000000
ratenumberyesThe playback rate the room is playing at (1 is normal speed).
  • maximum 16
pausedbooleanyesWhen true the timeline stands still at position_ms; when false it advances at rate.
at_msintegeryesThe authority's epoch milliseconds when it accepted this state. A player subtracts this from the authority's clock now, so the value is never the player's own clock.
  • minimum 0
set_bystringyesThe subject that made the change (the lease holder's subject as the authority knows it).
  • minLength 1
  • maxLength 200
seqintegeryesThe timeline version: starts at 1 and increments on every accepted change. A client ignores a state with a seq it has already seen.
  • minimum 1

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: ref-paused
{
  "room": "friday-film",
  "media": {
    "media_id": "legacy:media:vod:4242",
    "role": "main"
  },
  "position_ms": 12000,
  "rate": 1.25,
  "paused": true,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 8
}
Valid: url-playing
{
  "room": "friday-film",
  "media": "https://media.openvibe.network/vod/friday-film.webm",
  "position_ms": 61234,
  "rate": 1,
  "paused": false,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 7
}
Rejected: bad-media
{
  "room": "friday-film",
  "media": {
    "url": "https://media.openvibe.network/vod/friday-film.webm"
  },
  "position_ms": 0,
  "rate": 1,
  "paused": false,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 1
}
Rejected: bad-position-and-rate
{
  "room": "friday-film",
  "media": "https://media.openvibe.network/vod/friday-film.webm",
  "position_ms": -1,
  "rate": 0,
  "paused": false,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 1
}
Rejected: bad-room
{
  "room": "Friday Film",
  "media": "https://media.openvibe.network/vod/friday-film.webm",
  "position_ms": 0,
  "rate": 1,
  "paused": false,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 1
}
Rejected: http-media
{
  "room": "friday-film",
  "media": "http://media.openvibe.network/vod/friday-film.webm",
  "position_ms": 0,
  "rate": 1,
  "paused": false,
  "at_ms": 1794067200123,
  "set_by": "usr_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "seq": 1
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('common.sync-clock@1', value);   // { valid, errors: [{ path, message }] }