---
title: "common.sync-clock@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/common.sync-clock"
updated: null
---

# common.sync-clock@1 · OpenVibe.Services

HTML: [common.sync-clock@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/common.sync-clock)

# SyncClock `common.sync-clock@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/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`](/docs/contracts/common.sync-clock.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

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `room` | string | yes | The authority's room id (Chat: the room's slug). | - `pattern ^[a-z0-9][a-z0-9-]*$`<br>- `minLength 1`<br>- `maxLength 64` |
| `media` | one of | yes | What is playing: an OpenVibe media ref or an https URL. A ref names a Media object; a URL is the media file itself. |  |
| `position_ms` | integer | yes | The media position at at\_ms, in milliseconds. At most 30 days. | - `minimum 0`<br>- `maximum 2592000000` |
| `rate` | number | yes | The playback rate the room is playing at (1 is normal speed). | - `maximum 16` |
| `paused` | boolean | yes | When true the timeline stands still at position\_ms; when false it advances at rate. |  |
| `at_ms` | integer | yes | The 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_by` | string | yes | The subject that made the change (the lease holder's subject as the authority knows it). | - `minLength 1`<br>- `maxLength 200` |
| `seq` | integer | yes | The 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 }] }
~~~~