# Screenshots

URL: https://tuios.gaurav.zip/docs/screenshots

> Capture a pane, a region or the whole screen as a styled PNG, SVG, HTML or text file.

TUIOS renders screenshots from the pane's own cells, not from pixels on your screen. Colours, bold, italics and links are exact, and it works over SSH, in the browser, and on a detached session. A PNG or SVG gets a frame: padding, a background derived from the theme, rounded corners, a shadow and a title bar.

## In the app

| How                                          | What it captures                                   |
| -------------------------------------------- | -------------------------------------------------- |
| Ctrl+B C                                     | Enter capture mode, then pick a pane               |
| Palette: `Screenshot this window`            | The focused pane, at once                          |
| Palette: `Screenshot a region`               | Enter capture mode and drag over the area you want |
| Palette: `Screenshot the screen`             | The whole screen: panes, rail and dock             |
| Right-click a pane: `Screenshot this window` | That pane                                          |

In capture mode:

| Key               | Action                       |
| ----------------- | ---------------------------- |
| Tab, arrows, hjkl | Move between panes           |
| Enter or Space    | Capture the highlighted pane |
| Mouse drag        | Capture a region             |
| f                 | Capture the full screen      |
| Esc, q            | Cancel                       |

After a capture a preview panel opens (`screenshot.preview`). On a terminal with kitty graphics it shows the framed image. Elsewhere it shows the cells.

| Key                     | Action                          |
| ----------------------- | ------------------------------- |
| Enter, q                | Keep the file and close         |
| Esc                     | Delete the file and close       |
| c                       | Copy the image to the clipboard |
| o                       | Open the file                   |
| r                       | Retake                          |
| Arrows, PgUp/PgDn, Home | Scroll the preview              |

Files are saved under `screenshot.directory`, which defaults to `~/Pictures/tuios`.

The action names `screenshot_window` and `screenshot_screen` have no default key. Bind them in `[keybindings]` if you want one-key captures.

## From the command line

`tuios screenshot` asks the daemon to render a pane, so nobody needs to be attached.

```bash
# The focused pane, as a PNG in screenshot.directory
tuios screenshot

# A named pane in a named session
tuios screenshot -s work -w build

# Include the last 200 lines of history above the screen
tuios screenshot --scrollback --lines 200

# An SVG for a README
tuios screenshot --format svg --out demo.svg

# Render in a different theme
tuios screenshot --theme catppuccin_mocha
```

| Flag                  | Meaning                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `-s`, `--session`     | Target session                                                                            |
| `-w`, `--window`      | Target pane, by name or id                                                                |
| `-f`, `--format`      | `png`, `svg`, `html`, `ansi` or `txt`                                                     |
| `--frame`             | `window`, `plain` or `none`                                                               |
| `--theme`             | Render in this theme instead of the session's                                             |
| `-o`, `--out`         | Output path instead of a generated name                                                   |
| `-S`, `--scrollback`  | Put the pane's history above the screen                                                   |
| `--lines`             | Limit the history to the last N rows                                                      |
| `--cursor`            | Draw the cursor                                                                           |
| `--copy`, `--no-copy` | Copy to the clipboard, or do not                                                          |
| `--json`              | Print the result as JSON: `path`, `format`, `cols`, `rows`, `bytes`, `copied`, `warnings` |

A tape can take a screenshot too, with the `Screenshot` command. It renders the focused pane.

## Formats

| Format | What you get                                                       |
| ------ | ------------------------------------------------------------------ |
| `png`  | An image with the frame. `screenshot.scale` sets the pixel density |
| `svg`  | A vector image with the frame. Text stays text                     |
| `html` | A page with the styled cells                                       |
| `ansi` | The pane as text with colour escape codes, no frame                |
| `txt`  | Plain text, no frame                                               |

> **Set a theme for exact colours**
>
> With no theme set, TUIOS does not know your terminal's palette, so the 16 basic colours fall back to the xterm defaults and the result says so. Set `appearance.theme`, or pass `--theme`, to render in a known palette.

## The frame

Every part of the frame is a `[screenshot]` option. `--frame`, `--format`, `--cursor` and `--copy`/`--no-copy` override the matching option for one capture.

```toml
[screenshot]
format = "png"
directory = "~/Pictures/tuios"
frame = "window"         # window, plain or none
background = "auto"      # auto, none, #rrggbb, or #rrggbb..#rrggbb for a gradient
padding = 48             # pixels, 0 to 128
radius = 10              # corner radius, 0 to 32
shadow = true
controls = "auto"        # auto, macos, glyphs or none
title_format = "{title}" # {title}, {index}, {cwd}
scale = 2                # PNG size multiplier, 1 to 4
copy = true
preview = true
```

To draw text in a particular font, set `font_family`, or `font_file` to a font file. `font_file` is used for PNG and embedded in SVG and HTML. The full table is in [Configuration](https://tuios.gaurav.zip/docs/configuration#the-screenshot-table).

## Related

*[An interactive figure goes here. Open the page to use it.](https://tuios.gaurav.zip/docs/screenshots)*