MediaViewedPayload media.viewed@1

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

Version
1.0.0
Owner
media
Visibility
internal
Status
active
Compatibility
backward
Decision
ADR-004
Schema
https://openvibe.network/contracts/events/payloads/media.viewed.v1.json

media.viewed v1 (OpenVibe.Media server/views/service.js, POST /api/v1/views). A view counted for an item: one per person (or anonymous session) per item per 30 minutes; a preview counts from 1 second and a watch or live view when playback started. ref names the item in its owner's id space (service, kind, id). how is preview, watch or live. site is the site the view happened on when it differs from the owner, creator the creator's canonical subject or channel username when known, both for Report and never required. seconds is the cumulative watch time the event carried; of_seconds the item's length when known; concurrent is the number of live watchers Media saw at that moment for a live view, null otherwise. No IP address, user agent or raw anonymous session id is in the payload or stored with the view. Events are outbox rows written with the count in the same transaction and relayed to OpenVibe.Events; subject { type: <kind>, id: <id> }, visibility internal, actor service:media.

Fields

FieldTypeRequiredDescriptionConstraints
refobjectyes
  • no other fields
ref.servicestringyes
  • pattern ^[a-z][a-z0-9-]{1,39}$
ref.kindstringyes
  • pattern ^[a-z][a-z0-9_]{1,39}$
ref.idstringyes
  • minLength 1
  • maxLength 200
ref.sitestring | nullThe site the view happened on, or null when it is the owning service.
  • maxLength 40
ref.creatorstring | nullThe creator's canonical subject or channel username, or null when unknown.
  • maxLength 200
howenumyes
  • one of "preview", "watch", "live"
occurred_atstringyesWhen Media counted the view.
  • pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,3})?Z$
  • format date-time
secondsnumber | nullThe cumulative watch time this view carried.
  • minimum 0
  • maximum 86400
of_secondsnumber | nullThe item's length when the client knew it.
  • maximum 86400
concurrentinteger | nullLive watchers Media saw at that moment (how = live), null otherwise.
  • minimum 1

Examples

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

Valid: live
{
  "ref": {
    "service": "live",
    "kind": "stream",
    "id": "311",
    "site": "network",
    "creator": "maticus"
  },
  "how": "live",
  "occurred_at": "2026-11-12T10:04:05.123Z",
  "seconds": 61,
  "of_seconds": null,
  "concurrent": 12
}
Rejected: no-time
{
  "ref": {
    "service": "media",
    "kind": "vod",
    "id": "42"
  },
  "how": "watch"
}

Validate

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