CaptureStudio 1.0.0
Still frames and moment finding for terminal recordings
Techlosoft - Remote Ops Workspace


WHAT IT IS
==========

You have a recording. You need pictures of it.

CaptureStudio reads a SessionForge cast, replays it into an in-memory terminal
screen, and writes real PNG images of what that screen looked like. It also
tells you WHICH moments are worth a picture, so you do not have to scrub
through a seven minute deploy looking for the frame where the error appeared.

There are no settings to learn. Point it at a cast:

    capturestudio moments deploy.jsonl
    capturestudio shots deploy.jsonl --auto --count 6 --out-dir frames/

The first command lists the interesting timestamps. The second writes six PNGs
of them. That is the whole tool.

Sibling tools cover the other angles. SessionForge records the cast in the
first place. ScreenFlow renders a whole cast to an animated GIF. RecordDeck
edits the timeline. CaptureStudio is the one that does STILL FRAMES and
MOMENT FINDING - and unlike ScreenFlow it renders in COLOUR: 16-colour,
256-colour and 24-bit truecolour all land in the image.


INSTALL
=======

Pre-built binaries are in dist/. There is nothing to install - copy the one for
your platform anywhere on your PATH and run it.

    dist/capturestudio-linux-amd64        Linux, x86-64
    dist/capturestudio-darwin-arm64       macOS, Apple Silicon
    dist/capturestudio-darwin-amd64       macOS, Intel
    dist/capturestudio-windows-amd64.exe  Windows, x86-64

On macOS and Linux you may need to mark it executable:

    chmod +x capturestudio-linux-amd64

To build from source you need Go 1.24 or newer. There are no dependencies of
any kind - no third-party modules, no cgo, no font files - so no network
access is required:

    go build -o capturestudio .

The bitmap font is generated, not vendored. font.go is produced from the glyph
artwork in fontgen.go and is checked in, so a plain `go build` needs nothing
extra. To regenerate it after editing a glyph:

    go run fontgen.go > font.go && gofmt -w font.go


COMMANDS
========

    capturestudio moments       <cast.jsonl> [--count N] [--quiet S] [--json]

    capturestudio shot          <cast.jsonl> --at T --out frame.png
                                [--scale N] [--theme dark|light] [--pad N]
                                [--cols N] [--rows N] [--force] [--json]

    capturestudio shots         <cast.jsonl> --auto [--count N] --out-dir DIR
    capturestudio shots         <cast.jsonl> --at T [--at T ...] --out-dir DIR

    capturestudio contact-sheet <cast.jsonl> --out sheet.png [--count N]
                                [--across N] [--thumb-width N]

    capturestudio info          <cast.jsonl> [--json]

    capturestudio help | -h | --help | version

moments
    Replays the cast, scores every burst of screen change, and lists the settle
    points - the frames at the end of a burst, once the screen has stopped
    moving. Prints the timestamp, the score, how many grid cells changed, how
    long the screen then stayed still, and a one-line preview of what changed.
    Writes no files and touches nothing.

shot
    Reconstructs the screen at ONE timestamp and writes it as a PNG.

shots
    Writes several PNGs in one go. With --auto the timestamps come from moment
    finding; otherwise give explicit --at times. Frames are numbered in
    chronological order: frame-01.png, frame-02.png, and so on.

contact-sheet
    One PNG holding a numbered grid of thumbnails that summarises the whole
    recording, with a header line and a caption under each number giving the
    timestamp and score. This is the "what happened in this session" picture.

info
    Cast header, grid size, event count, duration, byte totals split by stream,
    how many settle points were found, the recorded exit code, and a tally of
    any input sequences the emulator could not render.

FLAGS

    --at <time>        Timestamp to capture. See TIMESTAMPS below.
    --out <file>       Output PNG (shot, contact-sheet). Short form -o.
    --out-dir <dir>    Output directory (shots). Created if missing.
    --prefix <name>    Filename prefix for shots. Default "frame".
    --auto             Pick the timestamps with moment finding (shots).
    --count N          Moments to list, or frames to write. Short form -n.
    --quiet S          Seconds of stillness that end a burst of change.
                       Default 0.25.
    --scale N          Integer magnification, 1 to 32. Default 2 for shot and
                       shots, 1 elsewhere. Nearest neighbour, so the pixels
                       stay crisp instead of going blurry.
    --theme NAME       dark (default) or light.
    --pad N            Border around the grid, in unscaled pixels. Default 8.
    --cols N           Override the grid width from the cast header.
    --rows N           Override the grid height from the cast header.
    --across N         Thumbnails per row on a contact sheet. Default 3.
    --thumb-width N    Thumbnail width in pixels on a contact sheet.
                       Default 320.
    --force            Overwrite an output file that already exists.
    --strict           Report every input sequence the emulator did not render,
                       with counts, on stderr.
    --json             Machine-readable output.

Flags may appear before or after positional arguments; either order works.


TIMESTAMPS
==========

--at accepts any of:

    12.5        seconds
    12.5s       seconds, with a suffix
    50%         a percentage of the recording's duration
    start       0 seconds (begin is a synonym)
    end         the timestamp of the last event (final, last are synonyms)

Commas separate several times in one flag, and --at may be repeated:

    capturestudio shots deploy.jsonl --at 0,25%,50%,end --out-dir frames/

A timestamp past the end of the recording gives you the final frame. A cast is
replayed by feeding it every event whose timestamp is at or before the one you
asked for, in file order, so the answer is exact and deterministic.


QUICK START
===========

    # record something with SessionForge
    sessionforge record deploy.jsonl --title "prod deploy" -- ./deploy.sh

    # what is in it, and where are the interesting bits
    capturestudio info deploy.jsonl
    capturestudio moments deploy.jsonl

    # one frame, at the moment the tests failed
    capturestudio shot deploy.jsonl --at 4.834 --out failure.png

    # six frames chosen automatically
    capturestudio shots deploy.jsonl --auto --count 6 --out-dir frames/

    # one picture summarising the whole session, for the ticket
    capturestudio contact-sheet deploy.jsonl --out sheet.png

    # the final screen, big, on a light background for printing
    capturestudio shot deploy.jsonl --at end --out final.png --scale 4 --theme light


EXAMPLE OUTPUT
==============

    $ capturestudio moments build.jsonl --count 6
    CaptureStudio moments
    cast     : build.jsonl
    grid     : 80x24   duration: 6.941s   quiet threshold: 0.250s
    found    : 14 settle point(s), showing 6

    RANK  AT         SCORE    CHANGED     QUIET    WHAT CHANGED
    1     6.941s     107.8    425/1920    0.25s    artifact techlosoft-nightly...
    2     0.002s     95.5     87/1920     0.60s    host : build-07.techlosoft.internal
    3     6.237s     85.9     48/1920     0.70s    artifact: techlosoft-nightly-4412...
    4     1.105s     81.9     40/1920     0.70s    git fetch --all --tags
    5     4.834s     71.0     20/1920     0.90s    FAIL flaky-net 1 test
    6     4.031s     70.1     35/1920     0.40s    PASS unit 214 tests

    $ capturestudio shots build.jsonl --auto --count 6 --out-dir frames/
    wrote 6 frame(s) to frames/ using automatic moment finding
    each frame is 992x560 px (grid 80x24, theme dark, scale 2)

      frames/frame-01.png          t=0.002s     4.0 KiB  score 95.5   host : bui...
      frames/frame-02.png          t=1.105s     4.9 KiB  score 81.9   git fetch ...
      frames/frame-03.png          t=4.031s     6.1 KiB  score 70.1   PASS unit ...
      frames/frame-04.png          t=4.834s     6.7 KiB  score 71.0   FAIL flaky...
      frames/frame-05.png          t=6.237s     7.5 KiB  score 85.9   artifact: ...
      frames/frame-06.png          t=6.941s     4.7 KiB  score 107.8  artifact t...


HOW MOMENT FINDING WORKS
========================

A recording is mostly nothing happening, punctuated by bursts of output. The
frame worth capturing is the one at the END of a burst, once the screen has
settled - not somewhere in the middle of a repaint.

1.  The cast is replayed one event at a time. After each event, CaptureStudio
    counts how many grid cells differ from the state before it. A cell counts
    as changed if its character, colours or attributes changed.

2.  Consecutive events are grouped into BURSTS. A burst ends when the gap to
    the next event is at least the quiet threshold (--quiet, default 0.25s),
    or at the end of the file. The burst's SETTLE POINT is the timestamp of its
    last event: that is the frame the viewer actually saw.

3.  Each burst is scored:

        change = 100 * log1p(cellsChanged) / log1p(totalCells)
        settle = 1 + 0.5 * log1p(quietAfter / quietThreshold)
        score  = change * settle

4.  Bursts are ranked by score, highest first, ties broken by earlier
    timestamp. Bursts that changed nothing on screen are dropped entirely.

WHY THE LOGARITHM
Linear cell counting would make a single full-screen clear-and-redraw outrank
every other frame in the recording by an order of magnitude, and every
automatic selection would be "the screen got wiped, six times". Log compression
means a full repaint of an 80x24 screen scores about 100 while one changed line
of 60 characters still scores about 55 - so an interesting small update can beat
a boring big one, and --auto returns a spread of frames instead of six
near-identical repaints. A full repaint still outranks a single line; it just
does not outrank it by 32x.

WHY THE SETTLE WEIGHT
A frame that stayed on screen for four seconds was being PRESENTED. A frame
that was overwritten 30ms later was a transient. The settle weight is a mild
logarithmic bonus for the length of the pause that follows, so of two equally
large changes the one the recording lingered on wins.

TUNING
Raise --quiet to merge chatty output into fewer, larger moments; lower it to
split a burst into its individual writes. At --quiet 0.005 on a typical cast
every event becomes its own moment.


THE TERMINAL EMULATOR
=====================

CaptureStudio contains a real, small terminal emulator: a character grid of
rows x cols cells, each holding a character, a foreground colour, a background
colour and attribute bits. This is the documented, complete list of what it
understands. Everything else is skipped WITHOUT corrupting the grid, and
--strict reports what was skipped and how often.

TEXT AND CONTROL CHARACTERS

    printable ASCII   written at the cursor, one cell each
    non-ASCII runes   decoded from UTF-8, stored faithfully, one cell each,
                      drawn as a missing-glyph box (see SCOPE)
    CR   \r  (0x0D)   carriage return, column 0, cancels a pending wrap
    LF   \n  (0x0A)   newline: down one row AND back to column 0 (see below)
    VT   \v  (0x0B)   treated as LF
    FF   \f  (0x0C)   treated as LF
    BS   \b  (0x08)   cursor left one column, does not erase, stops at column 0
    HT   \t  (0x09)   advance to the next multiple-of-8 column, clamped to the
                      last column. Tab stops are fixed; HTS and TBC are not
                      implemented
    BEL  \a  (0x07)   ignored, nothing to draw
    other C0, DEL     ignored and counted

WRAPPING
Deferred wrap, as xterm does it. A character written into the LAST column parks
the cursor there and sets a pending-wrap flag; the wrap happens only when the
NEXT printable character arrives. So printing exactly `cols` characters fills
one row and does not open a blank one, and a newline or carriage return after a
full row cancels the pending wrap. Running off the bottom row scrolls the grid
up by one line.

WHY LF ALSO RETURNS THE CARRIAGE
This is the one place CaptureStudio deliberately differs from a bare VT100, and
it is deliberate. SessionForge captures PIPES, not a PTY, so a cast contains
exactly the bytes the program wrote: a lone "\n". On a real terminal that "\n"
would have gone through the kernel line discipline with ONLCR set, which turns
it into CR+LF before the terminal ever sees it. Replaying pipe-captured output
with strict LF-means-down-only semantics produces the famous descending
staircase instead of a screen. CaptureStudio therefore applies the translation
the tty driver would have applied. Casts that already contain explicit CRLF are
unaffected: the CR simply lands on column 0 twice.

CSI SEQUENCES (ESC [ ... final)

    A   CUU   cursor up N rows, default 1, clamped to the top
    B   CUD   cursor down N rows, default 1, clamped to the bottom
    C   CUF   cursor forward N columns, default 1, clamped to the last column
    D   CUB   cursor back N columns, default 1, clamped to column 0
    E   CNL   cursor down N rows and to column 0
    F   CPL   cursor up N rows and to column 0
    G   CHA   cursor to absolute column N (1-based)
    `   HPA   same as CHA
    d   VPA   cursor to absolute row N (1-based)
    H   CUP   cursor to row;column, BOTH 1-BASED, defaults 1;1, clamped
    f   HVP   same as CUP
    J   ED    0 = cursor to end of screen, 1 = start of screen to cursor,
              2 = whole screen, 3 = same as 2 (there is no scrollback to clear)
    K   EL    0 = cursor to end of line, 1 = start of line to cursor,
              2 = whole line
    m   SGR   see below

Erasing writes blank cells carrying the CURRENT background colour, which is
what a real terminal does, so `ESC[41m ESC[2J` really does give you a red
screen. Every cursor movement clears the pending-wrap flag.

SGR (COLOUR AND ATTRIBUTES)

    0            reset everything
    1  / 22      bold on / off
    2  / 22      dim on / off
    4  / 24      underline on / off
    7  / 27      reverse video on / off
    21           treated as "bold off"
    30-37        foreground, ANSI colours 0-7
    90-97        foreground, bright ANSI colours 8-15
    39           foreground back to the theme default
    40-47        background, ANSI colours 0-7
    100-107      background, bright ANSI colours 8-15
    49           background back to the theme default
    38;5;N       foreground, 256-colour palette index N
    48;5;N       background, 256-colour palette index N
    38;2;R;G;B   foreground, 24-bit truecolour
    48;2;R;G;B   background, 24-bit truecolour

The colon sub-parameter forms are accepted too, because real programs emit
them: 38:5:196 and 38:2::12:34:56 both work, and the empty colour-space field
of ITU T.416 is skipped as the standard requires. An SGR parameter that is not
in the list above is counted and ignored WITHOUT disturbing the parameters
around it, so `ESC[31;53;42m` still gives you red on green.

HOW THE ATTRIBUTES ARE PAINTED

    bold      an ANSI colour 0-7 becomes its bright 8-15 twin; any other
              colour is pushed 25% toward white
    dim       the foreground is blended halfway into the background
    reverse   foreground and background are swapped, AFTER bold and dim
    underline a one-pixel rule across the bottom of the cell

THE 256-COLOUR PALETTE
Indices 0-15 are the standard xterm ANSI colours. 16-231 are the 6x6x6 cube
with the usual levels 0, 95, 135, 175, 215, 255. 232-255 are the 24 greys,
8 + 10*n. Truecolour is written into the PNG verbatim, no quantisation.

STRING SEQUENCES
OSC (ESC ] ... BEL, or ESC ] ... ESC \) is parsed and swallowed whole, so a
window-title escape never leaks onto the screen as text. DCS, SOS, PM and APC
are swallowed the same way and counted. ESC ( B and the other charset
designations are swallowed; US-ASCII is always assumed. ESC c resets the
terminal. A CSI longer than 64 bytes is abandoned, but its remaining bytes are
still swallowed up to its final byte so its parameters cannot spill onto the
grid as visible text.


IMAGE OUTPUT
============

Frames are drawn with an embedded 5x8 bitmap font covering all 95 printable
ASCII characters. The glyph artwork lives in fontgen.go as plain ASCII art and
is packed into font.go as one byte per scan line. There is no font file, no
font library and no system font lookup, which is why a single static binary
produces identical images on every platform.

Each character occupies a 6x11 pixel cell: the 5x8 glyph, one pixel of leading
above, and room below for descenders and the underline rule. Rows 0-6 are cap
height with the baseline on row 6; row 7 is the descender row used by g j p q y
, ; and _ .

    frame width  = cols * 6 * scale + 2 * pad * scale
    frame height = rows * 11 * scale + 2 * pad * scale

An 80x24 grid at the default --scale 2 --pad 8 is therefore 992x560 pixels.
Magnification is integer nearest-neighbour, so the result stays crisp.

Contact-sheet thumbnails are rendered at scale 1 and then box-averaged down to
--thumb-width. Averaging rather than point-sampling matters: a one-pixel glyph
stroke would vanish entirely under nearest-neighbour and the thumbnails would
look blank.

Output is written through a temporary file in the destination directory and
renamed into place, so an encoding failure cannot leave a truncated PNG behind.
An existing output file is NEVER overwritten without --force, and `shots`
checks every target path before writing any of them, so a collision halfway
through cannot leave you with a half-replaced frame set.

SIZE GUARDS
Absurd dimensions fail with a message instead of trying to allocate. The grid
is capped at 1000x1000 cells, --scale at 32, --pad at 400, each image side at
20000 pixels, and the total at 64 million pixels (a 256 MiB RGBA buffer). The
error names the flag to turn down:

    $ capturestudio shot build.jsonl --at 1 --out huge.png \
          --cols 900 --rows 900 --scale 32
    capturestudio: the frame would be 173312x317312 pixels; the per-side limit
    is 20000 - reduce --scale, --cols or --rows


CAST FORMAT
===========

CaptureStudio reads the SessionForge cast format, exactly as SessionForge
writes it. JSON Lines: one header object, then one array per event, then an
optional footer object.

    {"version":1,"command":["./deploy.sh"],"started_at":"2026-08-11T07:05:16Z",
     "shell":"/bin/bash","width":80,"height":24,"title":"prod deploy"}
    [0.001510, "o", "== build agent ==\n"]
    [1.105118, "e", "warning: retrying\n"]
    [3.004161, "o", "AAECAwQF", "b64"]
    {"exit_code":0,"duration":7.846948897}

    version     must be 1
    width       grid columns; used unless --cols overrides it
    height      grid rows; used unless --rows overrides it
    events      [elapsed_seconds, "o"|"e", "chunk"] with an optional fourth
                "b64" field when the chunk was not valid UTF-8
    footer      carries the exit code; a cast cut short has none

Both streams are replayed into the same grid, in file order, because that is
what the person watching the terminal saw. The "o"/"e" tag is preserved in the
cast but does not change how a frame is drawn - a terminal has one screen.

Base64 events are decoded and fed to the emulator as raw bytes. Bytes that are
not valid UTF-8 are counted and drawn as the Unicode replacement character
rather than being allowed to desynchronise the parser.

The cast file is opened READ-ONLY (O_RDONLY) and is never written, truncated,
moved or locked. Running CaptureStudio against a recording that SessionForge is
still appending to is safe; you will simply see the events that had been
flushed when you started.


SCOPE / WHAT THIS DOES NOT DO
=============================

Read this part. It is the honest boundary of the tool.

IT DOES NOT CAPTURE YOUR SCREEN.
CaptureStudio is not a screenshot utility and not a screen recorder. It takes
no picture of your monitor, your terminal window, or any window at all. It
reads a cast file that SessionForge already recorded and draws its own picture
of what that byte stream means. If you have no cast, CaptureStudio has nothing
to do. It never reads the framebuffer, never talks to X11, Wayland, Quartz or
the Windows desktop, and never asks for screen-recording permission - because
it has no use for any of it.

NO VIDEO, NO AUDIO, NO ANIMATION.
Still PNGs only. There is no GIF, no MP4, no WebM, no APNG and no animated SVG
export. Audio is not recorded by SessionForge and is not synthesised here. If
you want the whole recording as one moving image, that is ScreenFlow's job, not
this one. If you want to edit the timeline, that is RecordDeck.

THE TERMINAL EMULATION IS A DOCUMENTED SUBSET, NOT VT100 OR XTERM.
Everything the emulator supports is listed under THE TERMINAL EMULATOR above.
That list is the whole truth. Specifically NOT implemented:

  - Scroll regions (DECSTBM, CSI r), insert/delete line (IL, DL), insert/delete
    character (ICH, DCH), scroll up/down (SU, SD), erase character (ECH).
  - The alternate screen buffer. CSI ?1049h and ?1047h are counted and ignored,
    so a full-screen program that switches buffers is drawn on the one screen
    there is. The picture is usually still readable; it is not what a real
    terminal would have shown.
  - Cursor save and restore (DECSC/DECRC, CSI s / CSI u), reverse index (ESC M).
  - Cursor visibility, focus reporting, bracketed paste, mouse reporting,
    origin mode, auto-wrap mode, application keypad - every DEC private mode is
    counted and ignored.
  - Device status reports and identification (CSI n, CSI c). CaptureStudio has
    nothing to reply to and nowhere to reply to it.
  - Blink, italic, strike-through, conceal, framed/encircled/overlined, and
    underline colour (SGR 58/59). Underline is drawn; the rest are counted and
    ignored. There is no second underline style.
  - The cursor itself is not drawn. Frames show the screen contents only.

  Run with --strict to get an exact tally of what a given cast used that this
  build could not render. If that list is long, the picture is a rough guide
  and you should say so when you paste it into a ticket.

THE FONT IS ASCII-ONLY.
The embedded bitmap font covers U+0020 to U+007E and nothing else. Any other
rune - Unicode box-drawing characters, block elements, braille, accented
letters, CJK, emoji, powerline glyphs - is stored correctly in the grid and
drawn as an empty rectangle, the conventional missing-glyph box. So a TUI drawn
with box-drawing characters comes out as a rectangle of rectangles, and an
emoji in a build log is a small empty box. There is no font fallback, no system
font lookup and no way to supply your own font: shipping a self-contained
binary with no font files is the trade being made here.

Related: every rune occupies exactly ONE cell. Double-width CJK and emoji, and
zero-width combining marks, are not measured correctly, so a line containing
them will be misaligned relative to a real terminal.

NO SCROLLBACK.
The emulator holds exactly the visible screen. A line that scrolls off the top
is gone and cannot be captured, searched or scrolled back to. If a command
printed 900 lines into an 80x24 grid, a frame at the end shows the last 24 -
the same as a real terminal with scrollback disabled. There is no --scrollback
flag and no way to render a taller virtual screen than the one being emulated
(--rows changes the emulated screen size, which changes what scrolls and when,
not what is retained).

OTHER HONEST GAPS

  - No text output of a frame. There is no `capturestudio text --at T` that
    dumps the reconstructed screen as plain text, though the machinery exists
    internally.
  - Moment finding is heuristic. It has no idea what your output MEANS. It
    cannot find "the frame with the error" unless the error also happened to be
    the biggest change followed by the longest pause. It is a good first pass
    that saves you scrubbing, not a semantic understanding of your build log.
  - Frame selection has no minimum-time-apart rule beyond the burst grouping
    itself, so a chatty program with many small bursts a second apart can yield
    several visually similar frames.
  - Preview lines are the text of the grid row that changed most. For a
    colour-only change, or a change that only wiped text, the preview falls
    back to the raw bytes of the burst and can read oddly.
  - No stdout streaming. PNGs go to files; you cannot pipe one.
  - No image formats other than PNG. No JPEG, no WebP, no SVG, no PDF.
  - Only two themes, dark and light, both hard-coded. No custom palettes, no
    theme files, no per-colour overrides, no transparent background.
  - No annotation: no captions burned into frames, no arrows, no highlighting
    of the changed region, no redaction of secrets. A cast is plaintext and so
    is the image made from it; if the command printed a credential, the PNG
    contains that credential.
  - No cropping to a region of the screen, and no trimming of trailing blank
    rows.
  - SessionForge's own limits are inherited wholesale. It records pipes, not a
    PTY, so programs that disabled colour or progress bars because they were
    not on a TTY were already colourless when the cast was written. No amount
    of rendering brings that back. See sessionforge/README.txt.


EXIT CODES
==========

    0   Success. This includes a `moments` run that finds nothing, and a
        --strict run that reports skipped sequences: an honest "the screen
        never changed" or "this cast used sequences I do not draw" is an
        answer, not a failure.
    1   Bad invocation (unknown command, missing required flag, unparseable
        timestamp, unknown theme), or an I/O error (missing or malformed cast,
        refusing to overwrite an output without --force, an image that would
        exceed the size guards). Explicit help exits 0.

Every error message goes to stderr and starts with "capturestudio: ". Usage
after a bad invocation goes to stderr; usage from -h, --help or help goes to
stdout. --strict output always goes to stderr so it never contaminates --json.


JSON OUTPUT
===========

--json is available on every command. moments and info emit a report object;
shot, shots and contact-sheet emit a record of what was written, including the
pixel dimensions and byte size of each file, so a script can chain on it.

    $ capturestudio moments build.jsonl --count 1 --json
    {
      "file": "build.jsonl",
      "cols": 80,
      "rows": 24,
      "duration": 6.941171,
      "quiet": 0.25,
      "found": 14,
      "listed": 1,
      "moments": [
        {
          "rank": 1,
          "at": 6.941171,
          "score": 107.79...,
          "changed_cells": 425,
          "total_cells": 1920,
          "events": 1,
          "quiet_after": 0.25,
          "preview": "artifact techlosoft-nightly-4412.tar.zst"
        }
      ]
    }