Docs for game servers

Clips On Highlight API

Game servers and mods can ask Clips On to save a highlight clip on the player's PC at the exact moment something happens, for example a kill. Clips On keeps a replay buffer, so the clip includes the seconds before the event. Nothing is sent over the internet. Events travel from the game client to Clips On on the same PC.

Channels

Use whichever channel your game's client scripting supports. Both carry the same JSON messages.

ChannelHowNotes
Local HTTPPOST http://127.0.0.1:47710/v1/eventRequests from regular web pages are rejected. In-game browsers of MTA, FiveM, alt:V and RAGE MP are accepted.
Event fileAppend one JSON object per line to a file named clipon_events.jsonlClips On watches the MTA mods/deathmatch/resources and mods/deathmatch/priv folders. Latency is about 100 ms.

GET http://127.0.0.1:47710/v1/status returns {"app":"Clips On","version":"...","api":1} and can be used to check that Clips On is running.

Messages

hello

Sent once when the player joins. It tells Clips On who you are and which events you can send. The player sees this list in the approval dialog.

json
{
  "type": "hello",
  "server": { "id": "owl-rp", "name": "Owl Roleplay", "game": "mta", "address": "51.38.1.2:22003" },
  "events": [
    { "id": "kill", "label": "Kill" },
    { "id": "headshot", "label": "Headshot", "before": 8, "after": 3 }
  ],
  "t": 1794690000
}

event

json
{
  "type": "event",
  "server": { "id": "owl-rp" },
  "event": "kill",
  "label": "Kill Steve",
  "before": 10,
  "after": 4,
  "uid": "8812-3",
  "t": 1794690012
}
FieldRequiredMeaning
server.idyesStable id of your server. Keep it the same forever.
eventyesEvent id from your hello list. Unknown ids are added automatically.
labelnoText shown to the player and used as the clip title.
before, afternoSeconds to keep before and after the event. Clips On limits them to 2 to 60 and 0 to 30.
uidnoUnique id. Duplicates are ignored, so it is safe to send through both channels.
tnoUnix time in seconds. Events older than 15 seconds are ignored.

Registering your server

Any server that runs the Clips On resource or sends the messages above works right away. Players do not have to approve anything. Registering is optional: a server registered by the Clips On team at clipson.ir is shown as verified, and its name, event list and timings come from the registry.

To register, send the Clips On team:

  • your server.id (it must stay the same forever),
  • the address or addresses your server reports in server.address,
  • the list of events with labels and, optionally, seconds before and after.

Once registered, players do not have to approve anything. The event list, labels and timings come from the registry, so you can change them without updating your scripts. Players can still turn a server or single events off on the Servers page.

  • Events are only clipped while the game's recording mode is Highlight or Full.
  • Events that arrive close together are merged into one clip, and each game session has a clip limit.

MTA: San Andreas

Download the ready resource clipon.zip, or start from the minimal clipon_template.zip that only exports saveTheClip(label, before, after).

  1. Copy the clipon folder into your server's resources folder and add <resource src="clipon" startup="1" /> to mtaserver.conf.
  2. Optional settings in meta.xml: serverId, serverName, address, autoKills, multiKillSeconds, port.
  3. With autoKills on, kills, headshots and multi kills are sent automatically.
  4. From your own scripts:
lua
exports.clipon:register({
    { id = "heist", label = "Heist complete", before = 20, after = 5 },
})

exports.clipon:highlight(player, "heist", { label = "Bank heist" })

The client tries the local HTTP channel first and switches to the event file if MTA refuses the request.

Other games

GameHow it works
Counter-Strike 2Built in. Clips On installs a Game State Integration file. Kills, headshots, triple, quad, ace and round wins.
Dota 2Built in, Game State Integration. Kills, multi kills and victory.
MinecraftBuilt in. Reads latest.log of the official launcher and Prism, MultiMC, PolyMC and ATLauncher instances. Kills and advancements on any server.
League of LegendsBuilt in. Uses Riot's Live Client Data API during a match.
Rocket LeagueBuilt in. Clips On turns on the official Stats API (TAGame/Config/DefaultStatsAPI.ini) for Steam and Epic installs. Goals, assists, saves, epic saves, demolitions, hat tricks and victory. Restart the game once after installing Clips On.
FiveM, alt:V, RAGE MP, VMP, Garry's Mod and othersUse the local HTTP channel from a client script or an in-game browser page.