Files
luxe/scripts/cast-edit.py

279 lines
11 KiB
Python
Raw Permalink Normal View History

#!/usr/bin/env python3
"""Cut a raw screen recording down to a demo.
A real session is recorded at the speed a real session runs: a provider thinks for eleven seconds,
a build takes forty, and the interesting part is the two seconds either side. Played back untouched
that is a video of a progress bar. This trims the dead air without touching a single frame's
content — every byte the terminal emitted is still there, in order, and only the *gaps between*
them move.
Three edits, in this order:
window keep what lies between two marks the recording script dropped, so the take can start
before the app is up and end after it has been told to quit — opening with a rebuilt
picture of the screen as it stood at the mark, because a terminal recording is *state*
and a prefix cannot simply be dropped
clamp cap any gap longer than `--max-idle`, which is the whole trick: waiting is compressed,
reading time is not, because a hold the script asked for is shorter than the cap
pad hold the last frame, so a demo that ends on its own final state does not blink away
Before them all, `squeeze`: the stretch between a `squeeze` mark and a `resume` mark (or any
`squeeze-NAME` and `resume-NAME` pair) plays in `--squeeze-to` seconds. It is for a wait that is not dead air, a spinner turning while a model
writes, which clamping cannot touch because the screen never stops changing. Every frame is kept,
in order, and a clock on screen still says how long the wait really was.
`--speed` scales what is left. Clamping only reaches the *gaps*, and a model that streams for
ninety seconds without pausing has no gaps to give — so a long take needs the stream itself played
faster. Applied last, and sparingly: text arriving quickly is still readable, because what a reader
actually reads is the frame it settles on.
Input is asciicast v2 — a JSON header line, then one `[time, "o", data]` array per line. Output is
the same, which is what `asciinema-player` reads.
scripts/cast-edit.py raw.cast --out demo.cast --marks raw.marks --max-idle 1.2
"""
from __future__ import annotations
import argparse
import json
import pathlib
import sys
import pyte
# A gap shorter than this is somebody typing, not somebody waiting. Left alone entirely, so the
# cadence of a typed prompt survives the edit.
KEYSTROKE = 0.25
def load(path: pathlib.Path) -> tuple[dict, list[list]]:
"""Reads an asciicast v2 file into its header and its events."""
header: dict | None = None
events: list[list] = []
for line in path.read_text(encoding="utf8").splitlines():
if not line.strip():
continue
parsed = json.loads(line)
if header is None:
if not isinstance(parsed, dict):
sys.exit(f"{path}: first line is not an asciicast header")
header = parsed
continue
events.append(parsed)
if header is None:
sys.exit(f"{path}: empty recording")
return header, events
def window(
events: list[list],
start: float | None,
end: float | None,
size: tuple[int, int],
) -> list[list]:
"""Keeps the events between two marks, opening on the screen as it stood at the first.
A recording is not a film strip, it is a stream of *edits* to a screen. Ratatui writes only the
cells that changed, so the frame that drew the sidebar, the borders and the composer may be
thousands of events before the moment a demo wants to begin. Slicing the prefix away therefore
does not trim a run-up — it deletes the picture, and the take opens on a blank terminal with a
half-typed line floating in it, which is exactly how the commit demo shipped.
So the prefix is *replayed* rather than dropped, and the take opens with one synthetic event
that paints the resulting screen in full. Everything after the mark is a genuine recording.
"""
before = [e for e in events if start is None or e[0] < start]
kept = [e for e in events if (start is None or e[0] >= start) and (end is None or e[0] <= end)]
if not kept:
return []
offset = kept[0][0]
rebased = [[round(e[0] - offset, 6), *e[1:]] for e in kept]
if not before:
return rebased
return [[0.0, "o", repaint(before, size)], *rebased]
def repaint(events: list[list], size: tuple[int, int]) -> str:
"""Replays events into a screen and returns the escape sequence that redraws it."""
columns, rows = size
screen = pyte.Screen(columns, rows)
stream = pyte.Stream(screen)
for event in events:
stream.feed(event[2])
# Alternate screen, hidden cursor, cleared — the same state the app put the terminal in, so the
# player starts from what it would have had rather than from a fresh terminal's defaults.
out = ["\x1b[?1049h", "\x1b[?25l", "\x1b[H", "\x1b[2J"]
for row in range(rows):
line = screen.buffer[row]
out.append(f"\x1b[{row + 1};1H")
run, style = "", None
for column in range(columns + 1):
cell = line[column] if column < columns else None
here = (cell.fg, cell.bg, cell.bold, cell.reverse) if cell else None
if here != style:
if run:
out.append(run)
out.append(sgr(here) if here else "\x1b[0m")
run, style = "", here
if cell:
run += cell.data or " "
if run:
out.append(run)
out.append("\x1b[0m")
return "".join(out)
def sgr(style: tuple[str, str, bool, bool]) -> str:
"""One cell style as an SGR sequence."""
foreground, background, bold, reverse = style
parts = ["0"]
if bold:
parts.append("1")
if reverse:
parts.append("7")
for value, prefix in ((foreground, "38"), (background, "48")):
if value == "default" or not value:
continue
if len(value) == 6 and all(c in "0123456789abcdefABCDEF" for c in value):
parts += [prefix, "2", str(int(value[0:2], 16)), str(int(value[2:4], 16)), str(int(value[4:6], 16))]
return f"\x1b[{';'.join(parts)}m"
def clamp(events: list[list], max_idle: float) -> list[list]:
"""Caps every gap at `max_idle`, leaving the events themselves untouched.
Deliberately not a uniform speed-up. Scaling the whole timeline would squeeze the pauses the
script asked for — the beat after a prompt lands, the seconds a review screen needs to be read
— by exactly as much as it squeezes the provider's thinking time, and those are opposite
problems. So only the long gaps give.
"""
out: list[list] = []
previous = 0.0
shift = 0.0
for event in events:
gap = event[0] - previous
if gap > max_idle:
shift += gap - max_idle
previous = event[0]
out.append([round(event[0] - shift, 6), *event[1:]])
return out
def accelerate(events: list[list], factor: float) -> list[list]:
"""Plays the whole timeline `factor` times faster."""
if factor == 1.0:
return events
return [[round(e[0] / factor, 6), *e[1:]] for e in events]
def pad(events: list[list], seconds: float) -> list[list]:
"""Holds the last frame by emitting a no-op after it.
The player stops on its final frame, but "stops" is measured from the last event — so a demo
whose last event is the keystroke that produced the payoff cuts the instant the payoff appears.
A zero-width sequence costs nothing and buys the beat.
"""
if not events or seconds <= 0:
return events
return [*events, [round(events[-1][0] + seconds, 6), "o", ""]]
def squeeze(events: list[list], found: dict[str, float], seconds: float) -> list[list]:
"""Plays each `squeeze`…`resume` stretch in `seconds`, moving every later event and mark up by
the time saved. Taken latest first, so an earlier pair's marks are not yet moved when it is."""
pairs = sorted(
(name for name in found if name == "squeeze" or name.startswith("squeeze-")),
key=lambda name: found[name],
reverse=True,
)
for name in pairs:
events = squeeze_one(events, found, name, "resume" + name[len("squeeze"):], seconds)
return events
def squeeze_one(
events: list[list], found: dict[str, float], open_mark: str, close_mark: str, seconds: float
) -> list[list]:
start, end = found.get(open_mark), found.get(close_mark)
if start is None or end is None or end - start <= seconds:
return events
span = end - start
saved = span - seconds
def moved(at: float) -> float:
if at < start:
return at
if at <= end:
return start + (at - start) * seconds / span
return at - saved
for name, at in list(found.items()):
found[name] = moved(at)
return [[round(moved(e[0]), 6), *e[1:]] for e in events]
def marks(path: pathlib.Path | None) -> dict[str, float]:
"""Reads the `name<TAB>seconds` sidecar the recording script writes."""
if path is None or not path.exists():
return {}
found: dict[str, float] = {}
for line in path.read_text(encoding="utf8").splitlines():
name, _, seconds = line.partition("\t")
if seconds:
found[name.strip()] = float(seconds)
return found
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("source", type=pathlib.Path)
parser.add_argument("--out", type=pathlib.Path, required=True)
parser.add_argument("--marks", type=pathlib.Path)
parser.add_argument("--max-idle", type=float, default=1.2, help="cap on a gap, in seconds")
parser.add_argument("--tail", type=float, default=2.5, help="hold on the last frame")
parser.add_argument("--speed", type=float, default=1.0, help="playback multiplier")
parser.add_argument(
"--squeeze-to", type=float, default=2.0, help="seconds the squeeze/resume stretch plays in"
)
parser.add_argument("--from-mark", default="start")
parser.add_argument("--to-mark", default="end")
parser.add_argument("--title")
args = parser.parse_args()
if args.max_idle <= KEYSTROKE:
sys.exit(f"--max-idle must exceed {KEYSTROKE}s, or typing is compressed with the waiting")
header, events = load(args.source)
found = marks(args.marks)
events = squeeze(events, found, args.squeeze_to)
size = (int(header.get("width", 80)), int(header.get("height", 24)))
events = window(events, found.get(args.from_mark), found.get(args.to_mark), size)
if not events:
sys.exit(f"{args.source}: nothing between the {args.from_mark} and {args.to_mark} marks")
raw_duration = events[-1][0]
events = pad(accelerate(clamp(events, args.max_idle), args.speed), args.tail)
if args.title:
header["title"] = args.title
# Regenerated on every edit rather than trusted from the recorder: the player reserves its box
# from this number, and a stale one is a page that jumps when the demo loads.
header["duration"] = events[-1][0]
with args.out.open("w", encoding="utf8") as handle:
handle.write(json.dumps(header) + "\n")
for event in events:
handle.write(json.dumps(event) + "\n")
print(
f"{args.out.name}: {raw_duration:.1f}s recorded → {events[-1][0]:.1f}s played"
f" ({len(events)} frames)"
)
if __name__ == "__main__":
main()