Skip to content
@deckyard/frigate

frigate cheatsheet

Every export of @deckyard/frigate. Guides are listed in the introduction.

jennifer
import "@deckyard/frigate/" as frigate;

A request the server refused throws HttpError (kind frigate.http) with the HTTP status and, for a 422, the validation errors as fields (query.limit -> message); a response over a cap (or nested past the JSON decoder's caps) is kind "limit", a deadline that passed kind "timeout", a connection the server closed mid-answer kind "closed", a network failure (refused, reset, unreachable, DNS, TLS) kind "net", the net.NetError that http threw; every other failure is Error{kind: "frigate"} (a cancelled task stays kind "cancelled"). A c argument is a Client; a query is a list of string of name=value parameters with Frigate's snake_case names. Times are float Unix seconds. "Admin" calls need the admin role.

Constants

ConstantValueMeaning
VERSION"0.1.0"this deck's version
DEFAULT_TIMEOUT_MS30000how long one request may take
DEFAULT_MAX_BYTES16777216the largest JSON response read
DEFAULT_MAX_MEDIA_BYTES268435456the largest image or video read
MAX_SUB_LABEL100the longest sub label
MAX_SPAN_SECONDS86400the longest range of a clip or an export
MAX_RECORDINGS_SPAN_SECONDS21600the longest range of one recordings call (a day is four)

The client

FunctionReturnsDoes
client(baseUrl)Clienta client for the server's root URL, not signed in; requests refuse plain http to another machine
login(c, username, password)Clientsign in; the client carries the JWT (Client.token)
withToken(c, token)Clientsign in with a JWT kept from an earlier login
withPlainHttp(c)Clientallow plain http to another machine (port 5000 on the LAN)
withTls(c, tls)Clientcertificate options (caCert, skipVerify)
withTimeout(c, ms)Clientthe deadline of one request, 1000 to 86400000 ms
withMaxBytes(c, most)Clientthe largest JSON response, 65536 to 268435456 bytes
withMaxMediaBytes(c, most)Clientthe largest image or video, 65536 to 2147483647 bytes
version(c)stringthe Frigate version, such as 0.18.2-cfa08c5
profile(c)Profilewho the client is signed in as
call(c, method, path, query, body)json.Valueany other API request below /api
fetch(c, path, query)bytesany other image or video below /api

Events and review items

FunctionReturnsDoes
events(c, query)list of Eventevents, newest first, filtered by the server; thumbnails left out
event(c, id)Eventone event
deleteEvent(c, id)nulladmin; delete an event with its media
retainEvent(c, id, keep)nulladmin; keep an event regardless of retention, or stop keeping it
setSubLabel(c, id, subLabel, score)nulladmin; set or clear ("") the sub label; score 0 for none
createEvent(c, camera, label, subLabel, seconds)stringadmin; a manual event, the new id; 0 seconds keeps it open; a label may have single inner spaces (traffic light)
endEvent(c, id)nulladmin; end a manual event left open
eventSnapshot(c, id)bytesthe event's snapshot, a JPEG
eventThumbnail(c, id, format)bytesits thumbnail, jpg, png or webp
eventClip(c, id, padding)bytesits clip, an MP4, with padding seconds either side
reviews(c, query)list of Reviewreview items, newest first, filtered by the server
review(c, id)Reviewone review item
markReviewed(c, ids, reviewed)nullmark items reviewed or not, for the signed-in user

Changes to events go through the server's event queue: event shows them after a moment. Every other read sees a change at once: each GET carries X-Cache-Bypass: 1, past the 5-second cache in front of port 8971.

Recordings and exports

FunctionReturnsDoes
recordings(c, camera, after, before)list of Recordingthe recorded segments in a range of at most 6 hours
recordingHours(c, camera)list of RecordingHourthe hours recorded, in UTC, newest day first
storage(c)list of Storageadmin; the disk space each camera's recordings take
recordingClip(c, camera, start, end)bytesan MP4 cut from the recordings
recordingFrame(c, camera, at, format, height)bytesone recorded frame, jpg or png; height 0 for the recorded size
startExport(c, camera, start, end, name)stringqueue an export; its id
exports(c, query)list of Exportexports, newest first, filtered by the server (cameras, start_date, end_date, export_case_id; [] for all)
exportInfo(c, id)Exportone export
waitExport(c, id, ms)Exportwait until it is written; kind "timeout" after ms
exportFile(c, e)bytesa finished export's MP4
deleteExports(c, ids)nulladmin; delete exports, all or none

Cameras and the server

FunctionReturnsDoes
config(c)json.Valuethe configuration in use, defaults filled in
cameras(c)list of stringthe camera names, sorted
stats(c)json.Valuethe live numbers: cameras, detectors, processes, storage
cameraStats(c)list of CameraStatseach camera's frame rates and stream state
latestFrame(c, camera, format, height)bytesthe camera's latest frame; height 0 for the detect size
labels(c, camera)list of stringthe labels events were recorded with, of one camera or all ("")
switchCamera(c, camera, feature, on)nulladmin; a feature on or off until restart, * for every camera
switchPart(c, camera, part, name, on)nulladmin; a zone, motion_mask or object_mask on or off
restart(c)nulladmin; restart Frigate

switchCamera features: enabled, detect, motion, recordings, snapshots, audio, audio_transcription, notifications, review_alerts, review_detections, object_descriptions, review_descriptions, improve_contrast, ptz_autotracker, birdseye.

Types

Client

FieldMeaning
baseUrl as stringthe server's root URL without a trailing slash
token as stringthe JWT, "" when not signed in
tls as http.TlsOptionscertificate checks for https
allowPlainHttp as boolplain http to another machine allowed
timeoutMs as intthe deadline of one request
maxBytes as intthe largest JSON response
maxMediaBytes as intthe largest image or video

Profile

FieldMeaning
username as stringthe user; anonymous on port 5000
role as stringadmin, viewer or a custom role
cameras as list of stringthe cameras the user may see

HttpError

FieldMeaning
kind as stringalways "frigate.http"
message as stringfrigate: <request>: <why> (HTTP nnn)
status as intthe HTTP status, such as 401, 404 or 422
fields as map of string to stringa 422's validation errors, query.limit -> message; empty otherwise

Event

FieldMeaning
id as stringthe event's id, such as 1794646971.714268-8qyqhn
camera as stringthe camera
label as stringperson, car, ...
subLabel as stringa recognised name or a set sub label, "" if none
score as floatthe best score, 0 to 1
startTime as floatfirst seen, Unix seconds
endTime as floatlast seen, 0 while tracked
inProgress as boolstill tracked
zones as list of stringthe zones entered
hasClip as boola clip exists
hasSnapshot as boola snapshot exists
retained as boolkept regardless of retention
raw as json.Valuethe event as the server sent it

Review

FieldMeaning
id as stringthe item's id
camera as stringthe camera
severity as stringalert or detection
startTime as floatits start, Unix seconds
endTime as floatits end, 0 while going on
inProgress as boolstill going on
reviewed as boolreviewed by the signed-in user; false from review
events as list of stringthe ids of its events
objects as list of stringwhat was seen, such as person: alice
zones as list of stringthe zones entered
raw as json.Valuethe item as the server sent it

Recording

FieldMeaning
id as stringthe segment's id
startTime as floatits start, Unix seconds
endTime as floatits end, Unix seconds
duration as floatits length in seconds
motion as intthe motion in it
objects as intthe object detections in it
sizeMb as floatits size in MB

RecordingHour

FieldMeaning
day as stringYYYY-MM-DD, UTC
hour as int0 to 23, UTC
events as intthe events in it
motion as intthe motion in it
objects as intthe object detections in it
duration as floatthe seconds recorded

Storage

FieldMeaning
camera as stringthe camera
usageMb as floatthe space taken, MB
bandwidthMb as floatMB recorded per hour
usagePercent as floatits share of the disk, 0 to 100

Export

FieldMeaning
id as stringthe export's id
camera as stringthe camera
name as stringits name
date as floatthe start of the stretch, Unix seconds
videoPath as stringthe file on the server
inProgress as boolstill being written

CameraStats

FieldMeaning
name as stringthe camera
cameraFps as floatframes per second from the camera
processFps as floatframes per second processed
detectionFps as floatdetections per second
detectionEnabled as booldetection is on
connection as stringthe stream's state, such as excellent
reconnects as intreconnects in the last hour