# Clips, recordings and the Library

The watcher keeps the last **120 seconds (at most 32 MiB)** of each watched device's video,
in whole GOPs, while a page watches the device or a recording runs (and 15 s after).

- **Clip** saves part of that retained video: choose the start and end with **Set start
  here** / **Set end here** while scrubbing, then **Save clip**. A clip starts at the key frame
  at or before its start.
- **Record** records the device from its latest key frame until **Stop**, for at most 30
  minutes or 1 GiB. Recording runs in the watcher's back end: closing the tab does not stop
  or lose it. It carries on through rotations and through a server restart (it waits for the
  video to come back); stopping the watcher saves it.

A video file holds one stream, and the watcher never re-encodes, so a clip or recording that
spans a rotation is saved in **parts**: `video-1.mp4` (portrait), `video-2.mp4` (landscape)
and so on, each at its own size. The Library plays them back to back.

## The Library

Clips and recordings are saved in `~/.tap/recordings/watcher/<id>/` (or
`TAP_WATCHER_RECORDINGS`): the video parts and `steps.json`. The **Library** view lists them
by day, with their device, length, actions, failures and size, and:

- shows how much of the **2 GiB** cap is used (a full library refuses new saves);
- searches by device or connection and filters recordings or clips;
- deletes one, or several at once (tick them, then **Delete**), after a confirmation that
  says what goes and how much space it frees;
- plays one on a single timeline, its parts back to back: action markers (failures in red)
  and a dashed tick where the device rotated; click an action or a marker to jump to it, and
  download it as a ZIP of all its files.

Keyboard in the player: `space` play / pause, `←` / `→` one second (`shift` for 5), `j` / `k`
next / previous action.

Saved videos are kept until you delete them, also across watcher restarts. To have old ones
deleted for you, start the watcher with `--keep-days N`: entries older than N days are
removed at start and hourly after. A save interrupted by a crash leaves an unfinished
folder; the watcher removes those when it starts, never one another watcher on the same
library is still writing.

`steps.json` (`tap-watch-steps/2`) lists the parts (file, stream and clock identity, size,
where each starts on the joint timeline, and every frame's timestamps) and each action that
overlaps the video with its original event, its part, its offset in that part and on the
whole recording, and whether it began or ended outside the video. MP4 files keep the
variable frame timing without re-encoding.