Pipeline notes & player reference

These are the working notes we keep for the Frameyard encoding pipeline and the embeddable player. They are written for the people who integrate us — course platforms, internal training portals and a few broadcasters — not as marketing material. If something here is wrong or stale, it is because the pipeline moved faster than the page.

A source file arrives, gets probed, then transcoded into the ladder that matches its shape (talking head, screencast, or full-motion). Renditions land on this host, and the player pulls them back through whichever edge is closest to the viewer. Nothing else happens in between — there is no session server, no per-view database write, no callback into your app.

Embedding the player

One script tag and a container. The script reads the data-asset attribute, resolves the manifest and picks a rendition from the ladder. It does not register anything globally except window.Frameyard.

<!-- put this once, before </body> -->
<script src="/videos/api.js" defer></script>

<div class="fy-player"
     data-asset="as_7k2md91f"
     data-poster="auto"
     data-start="0"></div>

// same thing, if you build the DOM yourself
const player = Frameyard.mount(node, {
  asset:   'as_7k2md91f',
  ladder:  'auto',        // or 'screencast' / 'motion'
  preload: 'metadata',
  onReady: () => console.log(player.duration)
});

player.on('stall', e => report(e.rendition, e.ms));

# manifest for one asset (studio token required)
curl -sS "https://$HOST/videos/as_7k2md91f/manifest.json" \
     -H "authorization: Bearer $FY_TOKEN"

# upload ticket; the PUT goes straight to the ingest host
curl -sS -X POST "https://$HOST/videos/tickets" \
     -H "authorization: Bearer $FY_TOKEN" \
     -d '{"ladder":"screencast","retain":"90d"}'

The player is a little under 40 KB after compression and has no dependencies. If data-poster is left on auto, the first keyframe past the two second mark is used, which is usually the least awkward frame of a talking head.

Delivery & ranges

Renditions are stored as progressive files, not segments. Players ask for byte ranges, edges cache those ranges, and a seek is a new range request rather than a playlist reload. It keeps the origin boring, which is the point.

Behaviour	What we do
Range requests	accept-ranges: bytes, 1 MiB windows
Cache lifetime at edge	30 days, immutable renditions
Manifest lifetime	60 s, revalidated
Origin fetch	HTTPS only, SNI pinned to the delivery host
Retention default	90 days after last playback

A one hour screencast at the 1080p rung is roughly 1.1 GB, so a course platform with a few thousand active learners moves several terabytes a week without anything unusual happening. That is the shape of traffic this host is built for.

Encoding ladders

Three ladders. The prober picks one from motion vectors and text density; you can force it per asset if it guesses wrong on you.

Ladder	Rungs	Codec	Typical source
talking	360 / 540 / 720 / 1080	h264 high	lectures, interviews
screencast	720 / 1080 / 1440	h264 + av1	software demos, IDE capture
motion	360 / 720 / 1080 / 2160	av1	events, b-roll

The screencast ladder keeps a higher rung at a lower bitrate on purpose — small text stays readable, and nobody watches a code screencast for the grain.

Pipeline numbers

Counters below come from the delivery meters and refresh on their own. They describe this host only, not the whole fleet.

Delivered this month

—

Egress now

—

rolling 5 min

Encode queue

—

Startup p95

—

first frame

egress, last 24 h—

Changes

2026-07-24av1 rung on the screencast ladder

The 1440 rung now ships av1 alongside h264. Players that report av1 support get it; everything else keeps the old file. Storage per asset went up about 18 %, egress down roughly a third on that rung.

2026-07-11poster picking moved past the slate

Auto posters used to grab frame zero, which for half our lecture uploads is a black slate. It now takes the first keyframe after two seconds.

2026-06-29range window widened to 1 MiB

Edges were asking for 256 KiB windows and doing four times the work on long seeks. Wider windows cut origin requests noticeably without hurting startup.

2026-06-08tickets replace direct upload URLs

Upload now goes through a short lived ticket. Old signed URLs keep working until the end of the quarter, then they stop.

Studio console

Uploads, retention and per-asset numbers live in the studio console. It is a separate sign-in from the player — the player never needs an account, the console always does.

No account yet? Console access is opened by the team that owns your library — ask them to add your address, and the invite lands in your inbox.