Archiver Rules (Integrators)

This guide is for program-states integrators running their own integration service. It describes how that service tells the media pipeline what to archive, by returning archiverRules in its response to the bulk ping.

If you just want to record streams to S3 from the dashboard or the API, use Recording instead — you don't need this page. Archiver rules are the lower-level mechanism that the recording config sits on top of.

The bulk ping

Your integration service is pinged periodically for every active stream, to confirm the stream should keep running and to refresh per-stream policy:

PUT /ping/bulk
Content-Type: application/json

{ "privateKeys": ["<key>", "..."] }

You respond with a JSON object keyed by the same identifier (the private/auth key), each value a BulkPingEntry:

{
  "<streamId>": {
    "statusCode": 200,
    "status": "OK",
    "message": "",
    "needsAuth": false,
    "missing": false,
    "archiverRules": { },
    "appData": { },
    "rtmpPush": []
  }
}

Only entries with statusCode == 200 keep archiving. A non-200 tears the stream down; missing: true means the stream is unknown and is stopped. The archiverRules you return are applied to the stream and evaluated on the next ping cycle.

`archiverRules`

archiverRules is a map of rule name → rule object. The rule name is a label you choose; it is not a reserved value. Reusing the same name on a later ping updates that rule (see Starting and stopping).

"archiverRules": {
  "my-recording-rule": {
    "name": "my-recording-rule",
    "type": "all",
    "driver": "hlss3",
    "formats": ["all"],
    "minDurSec": 10,
    "maxDurSec": -1,
    "continuousUploadIndex": true,
    "archiveLabel": "<sessionId-or-your-label>",
    "tempFilePathTemplate": "/tmp/{{{ClientReferrer}}}/{{{PublicKey}}}/{{{Height}}}",
    "tempFileNameTemplate": "{{{PublicKey}}}_{{{FileSeqNum}}}_{{{FileDuration}}}.ts",
    "postProcessCmds": [
      {
        "cmd": "S3upload",
        "s3Bucket": "my-bucket",
        "s3Region": "us-east-1",
        "cmdArgsTemplate": ["<localPath>", "my-bucket", "<remoteKey>"]
      },
      { "cmd": "rm", "cmdArgsTemplate": ["<localPath>"] }
    ]
  }
}

Rule fields

Field	Type	Notes
`name`	string	Optional; matches the rule name.
`type`	string	What to record: `all`, `paid`, `unpaid`, `snapshot`. `paid`/`unpaid` are gated by `needsAuth`.
`driver`	string	Output writer: `hlss3`, `flvFile`, `flvSnapshot`.
`formats`	string[]	Which variants to archive (see `formats` values). Required — empty means no tasks.
`minDurSec` / `maxDurSec`	int	Min/max archive duration (sec). `-1` = unbounded.
`warmup`	int	Seconds after broadcast start before archiving begins.
`backfill`	int	Seconds of pre-roll to include.
`segmentDur`	int	Segment length (ms).
`interval`	int	Snapshot interval (ms), `snapshot` drivers only.
`tempFilePathTemplate` / `tempFileNameTemplate`	string	Local working path/name (templated).
`pathTemplate` / `fileTemplate`	string	Final output path/name (templated).
`continuousUploadIndex`	bool	Upload/refresh the index (e.g. `index.m3u8`) after each segment.
`strictPostProcess`	bool	Abort the chain if any post-process command fails.
`includeMetadata`	string[]	Field names written as object metadata on upload.
`archiveLabel`	string	Arbitrary label, available to templates as `{{{ArchiveLabel}}}`.
`postProcessCmds`	PostProcessCmd[]	Run per finished segment/file.
`trailerPostProcessCmds`	PostProcessCmd[]	Run once at the end of the archive.
`liveDvr`	bool	Build a live-DVR manifest from the archived segments.
`publicOnly`	bool	Restrict to public (unauthenticated) streams.

`formats` values

"all" — every FLV variant.
"source" — the source variant only.
"source-aac" — the source (or highest-bitrate FLV) variant with AAC audio.
"<kbps>" — a number; picks the variant with the closest total bitrate.

Non-FLV variants are skipped.

`PostProcessCmd` fields

Field	Notes
`cmd`	Command to run, e.g. `S3upload`, `ffmpeg`, `rm`.
`cmdArgsTemplate`	`string[]` of args; templated. For `S3upload` the convention is `[localPath, bucket, remoteKey]`.
`s3AccessKeyId`, `s3SecretKey`, `s3Region`, `s3Url`, `s3Bucket`, `s3BaseUrl`	S3 credentials/target for upload commands.
`s3VaultConfig`	Name of a server-side vault credential set, instead of inline keys.
`s3DisablePathCleaning`	bool, optional.
`httpTimeoutMillisec`	int, optional.

Template variables

The template fields (pathTemplate, fileTemplate, tempFilePathTemplate, tempFileNameTemplate) and cmdArgsTemplate entries are rendered with mustache. Use the triple-brace form {{{Var}}} (unescaped) so path separators and special characters pass through untouched. A variable with no value for a given stream renders empty.

Stream identity: {{{PublicKey}}} (excluding any variant postfix), {{{StreamName}}} (full public name incl. variant postfix), {{{PrivateKey}}}, {{{ClientReferrer}}} (project ID), {{{UserSlug}}}, {{{CallId}}}, {{{ArchiveLabel}}}.

Media properties: {{{Width}}}, {{{Height}}}, {{{VideoKbps}}}, {{{AudioKbps}}}, {{{FrameRate}}}, {{{SegmentDur}}}, {{{SequenceNumber}}}, {{{FileSeqNum}}}, {{{FileDuration}}}.

Timestamps: {{{StreamStartTime}}}, {{{ArchiveStartTime}}}, {{{ArchiveFileStartTime}}} / {{{ArchiveFileEndTime}}}, {{{FirstVideoPTS}}} / {{{LastVideoPTS}}}, plus the zero-padded start-time components SYYYY/SMM/SDD/SHH/SMm/SSS (year, month, day, hour, minute, second) and the EYYYY/EMM/… end-time equivalents — each wrapped in the same triple-brace mustache form as the variables above.

includeMetadata is a list of these variable names whose resolved values are written as object metadata on upload.

Starting and stopping archiving

How the archiverRules field is interpreted depends on whether it is absent, empty, or populated:

What you send	Effect
No `archiverRules` field at all (omitted)	Current rules left unchanged — archiving continues as-is.
`archiverRules: {}` (present but empty)	Clears the stream's rules — archiving stops.
`archiverRules` with one or more rules	Replaces the stream's rules wholesale (not a per-rule merge).

All-or-nothing

Sending archiverRules replaces the entire set — include every rule you want to keep recording. Dropping a rule that was recording stops that archive. Omitting the field and sending {} are different: leave the field out to keep current rules running; send {} only to stop archiving entirely.

For a given rule name, fields you set override the defaults, fields you omit fall back to defaults, and reusing the name on a later ping updates that rule.

Minimal example

Archive all variants of one stream; unspecified fields use defaults:

{
  "<streamId>": {
    "statusCode": 200,
    "status": "OK",
    "needsAuth": false,
    "archiverRules": {
      "my-recording-rule": { "type": "all", "formats": ["all"] }
    }
  }
}

Recording — the dashboard/API way to archive to S3 (most users want this).
Clipping & VOD — produce on-demand assets from archived sessions.
Webhooks Overview — the program-states webhook flow this builds on.

The bulk ping​

archiverRules​

Rule fields​

formats values​

PostProcessCmd fields​

Template variables​

Starting and stopping archiving​

Minimal example​