VClarity Protocol (VCP)

An open HTTP + JSON protocol that lets video players like VClarity import and browse video collection libraries hosted by your website.

VCP connects three parties: the client (the VClarity app on a phone), the VC service (the player's backend gateway), and your website — the provider. Once your site is registered as a publisher, any VClarity user can type your URL into the app and import your video collections into their on-device library, complete with artwork, metadata, and structure.

The protocol is deliberately small: four required read-only routes make a complete, conforming provider. Everything else — search, delta sync, watch progress, reactions, playlists — is an optional capability you advertise in your manifest when you're ready.

How it works

A user types your website's URL into VClarity (optionally with a personal access token from your site). The VC service looks your origin up in the publisher registry, reads your registered manifest, runs the authentication handshake your manifest asks for, and imports your collections. Media itself — video segments, subtitles, artwork — always streams directly from your CDN to the device.

VClarity Protocol architecture showing API traffic between the VClarity client, VC service, and provider, with media delivered directly from the provider CDN to the client.

Two data planes, two very different rules:

API plane — every VCP request to your server comes from the VC service, identified by your service token. Devices and third parties never call your VCP API directly, and you must reject any request without a valid token.
Media plane — devices fetch video, subtitles, and artwork directly from the URLs in your API responses. The gateway never proxies media.

Who's who

Term	Meaning
Client	The video player app on the user's device (iOS/Android).
VC service	The player's backend gateway. All VCP API traffic to providers originates here, never from devices.
Provider	The website/server implementing the VCP endpoints — that's you.
Publisher	A provider that has completed registration with the VC platform and holds a service secret.
Manifest	The discovery document you submit at registration, stored in and served from the publisher registry.
Collection	An ordered set of videos — a playlist, series, shelf, or folder.
Source	One playable rendition of a video: an HLS/DASH/MP4 URL plus its technical attributes.

Your first request

Every VCP call is plain HTTPS + JSON. Here's what listing collections looks like — the VCP-Service-Token header is how the gateway identifies itself to you:

curl "https://api.example.com/vcp/v1/collections?limit=50" \
  -H "VCP-Service-Token: vcps_a81f42..."

import requests

resp = requests.get(
    "https://api.example.com/vcp/v1/collections",
    params={"limit": 50},
    headers={"VCP-Service-Token": "vcps_a81f42..."},
)
resp.raise_for_status()

for collection in resp.json()["collections"]:
    print(collection["id"], collection["title"])

require "rest-client"
require "json"

resp = RestClient.get(
  "https://api.example.com/vcp/v1/collections",
  { params: { limit: 50 }, "VCP-Service-Token" => "vcps_a81f42..." }
)

JSON.parse(resp.body)["collections"].each do |collection|
  puts "#{collection["id"]}  #{collection["title"]}"
end

const resp = await fetch('https://api.example.com/vcp/v1/collections?limit=50', {
  headers: { 'VCP-Service-Token': 'vcps_a81f42...' },
})
if (!resp.ok) throw new Error('VCP request failed: ' + resp.status)

const { collections } = await resp.json()
for (const collection of collections) console.log(collection.id, collection.title)

Topics

Getting StartedBuild the four required routes, write a manifest, and register as a publisher.

Publisher RegistrationRegister your origin, prove domain ownership over DNS, and handle the service token.

Discovery & the ManifestThe discovery document that tells the VC platform what your integration can do.

AuthenticationPublic libraries, pasted API keys, device pairing, and privileged user tokens.

API ReferenceCollections, videos, sources, search, delta sync, progress, reactions, and playlists.

Security GuideTransport rules, hardening requirements, and per-role security checklists.

Reading these docs

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used as described in RFC 2119: MUST is a hard protocol requirement, SHOULD is a strong recommendation you can deviate from with good reason, and MAY is genuinely optional. This documentation covers VCP version 1 — see theRelease Notes for every version, what changed in each, and where older documentation lives.