# Playback Desk

> The file is not broken. It is illegal on that decoder. A level is three separate
> ceilings - frame size, pixel rate, bitrate - so the same pixels can be legal at one
> frame rate and refused at another: 1080p30 needs level 4.0 and 1080p60 needs 4.2.

https://playback-desk.skillsafe.ai/

## What it is

Five lanes over one rendered video file and the list of places it has to play, plus a
**free browser-side engine** that checks every ceiling. The engine costs nothing, needs no
account, and makes no network calls. Writing the report costs credits.

## The arithmetic

    macroblocks       ceil(w/16) * ceil(h/16)          <- the frame, padded to whole ones
    pixel rate        macroblocks * fps
    bits per pixel    bitrate / (w * h * fps)
    keyframe share    ratio / (ratio + n - 1)          <- n = frames per keyframe interval
    buffer refill     bitrate / fps                    <- kbit per frame period
    largest frame     bufsize                          <- from a full buffer, exactly
    preroll           bytes * 8 / link                 <- with the index at the end

## Figures that are exact, and surprising

- **A level is three ceilings and they fail differently.** Over the frame size, only a
  smaller frame reaches it. Over the pixel rate, a lower frame rate does. Over the bitrate,
  a re-encode does without touching the picture at all.
- **1080p30 needs level 4.0 and 1080p60 needs 4.2.** 4K30 needs 5.1 and 4K60 needs 5.2. A
  device one level short plays one and shows a black screen with working audio for the other.
- **1080 is encoded as 1088.** Macroblocks are 16 pixels square and a frame rounds up, so
  1080p is **8,160 macroblocks against level 4.0's ceiling of 8,192** - a margin of 0.39
  percent, which is the ledge most delivery advice is balanced on.
- **Level 4.2's rate ceiling is exactly its frame ceiling at 60 fps**: 8,704 x 60 = 522,240.
  The level was cut for 1080p60 and the numbers say so.
- **A bitrate is not a quality setting.** 10,000 kbit/s is **0.1608 bits per pixel at
  1080p30 and 0.0201 at 2160p60** - exactly eight times less, four times the pixels twice a
  second. Nothing in the render settings shows it.
- **The lever people reach for is usually capped.** Raising 4K60 from 12,000 to 15,000
  kbit/s moves it from 0.0241 to 0.0301 bits per pixel: out of starved, and still nowhere
  near the 0.0965 the same 12,000 buys at 1080p60.
- **A keyframe larger than the buffer stalls playback however fast the link is** - once per
  keyframe, at a regular interval, which is what makes it read as a broken file rather than
  a slow connection. From a full buffer, the largest frame a decoder can take is exactly the
  buffer size.
- **A longer keyframe interval needs a LARGER buffer, not a smaller one.** Its share of the
  bits falls while its absolute size rises: at 8,000 kbit/s and 30 fps a keyframe needs 0.17
  seconds of buffer at 12-frame intervals and 0.26 at 300.
- **Keyframes are 25 percent of the budget at a 25-frame interval** and 42.11 percent at 12,
  on a cost ratio of 8. Shortening the interval to help seeking is paid for by every frame
  in between.
- **The index is written last.** Unless it is moved to the front, a streaming player shows
  nothing until the final byte lands: **67.5 MB over a 20 Mbit/s link is 27 seconds** of
  blank page. Invisible on a local file, which is where it gets tested.
- **8-bit 4:2:0 is the only pixel format that is safe.** Ten-bit and 4:2:2 decode in software
  on the editing machine and fail completely on the phone the MP4 was made for.

## The sheet

    FILE
    name      | the launch cut for the site hero
    width     | 3840
    height    | 2160
    fps       | 60
    bitrate   | 12000
    codec     | h264
    profile   | high
    pixfmt    | yuv420p
    gop       | 240
    bufsize   | 12000
    duration  | 45
    faststart | no

    TARGETS
    t1 | the marketing site on a laptop  | level 5.2 | link 50
    t2 | the lobby screen's media player | level 4.2 | link 0
    t3 | the sales deck on an iPad       | level 5.1 | link 20

`width`, `height`, `fps` and `bitrate` are required. `bitrate` is kbit/s, `bufsize` kbit,
`link` Mbit/s, and **`link 0` means a local file**. Anything omitted is filled from the
values a file has when nobody chose one - h264, high, yuv420p, a keyframe every 250 frames,
and faststart off - and every one of those is reported as an assumption rather than a
reading.

## The lanes

- `plan` - decide what the file has to survive, before anything is rendered
- `check` - what this file will do elsewhere (the primary lane)
- `level` - which of the three ceilings is refusing it, and what each fix does not reach
- `budget` - what the bitrate actually buys, and what the keyframes take off the top
- `deliver` - what ships as it is, what one flag fixes, and what has to be rendered again

## What it cannot do

It is arithmetic on declared settings and **has not seen a frame**. Bits per pixel says how
much budget the encoder had, not what it did with it, and the bands it is scored against are
working conventions rather than a standard. The keyframe size is a model assuming a fixed
cost ratio and an evenly spent budget; real rate control does neither. **A level is a
ceiling, not a promise** - a file inside a device's level can still fail on it for want of a
profile, a container feature or memory, and clearing the level only means the level is not
the reason. File sizes are video only.

## Source

Lanes derived from the `video-report` skill in
[remotion-dev/remotion](https://github.com/remotion-dev/remotion), which exists for one
moment: somebody reports that a video is not working, and the skill's whole method is to
fetch it and render it again with a verbose log. Not affiliated with or endorsed by the
authors of that repository.

## API

https://playback-desk.skillsafe.ai/api.html