# 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
Constant Value Meaning 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
Function Returns Does 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
Function Returns Does 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
Function Returns Does 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
Function Returns Does 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
Field Meaning 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
Field Meaning username as stringthe user; anonymous on port 5000 role as stringadmin, viewer or a custom rolecameras as list of stringthe cameras the user may see
# HttpError
Field Meaning 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
Field Meaning 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
Field Meaning id as stringthe item's id camera as stringthe camera severity as stringalert or detectionstartTime 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
Field Meaning 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
Field Meaning day as stringYYYY-MM-DD, UTChour 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
Field Meaning 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
Field Meaning 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
Field Meaning 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