# Tape Recording

URL: https://tuios.dev/docs/tape-recording

> Record what you do in TUIOS into a tape you can edit and replay.

TUIOS can record what you do into a `.tape` file. A recording holds actions, such as "open a window" and "type this text", not terminal output. The result is a plain text [tape](https://tuios.dev/docs/tape-scripting) that you can read, edit and replay.

## Record a tape

> > ### Start
> >
> > Press Ctrl+B T r. Type a name, or keep the suggested `recording_<date>_<time>`, and press Enter.
> >
> > The dock shows `[REC]` while recording is on. If a window is focused, TUIOS switches to terminal mode so your typing is recorded.
>
> > ### Work as usual
> >
> > Open windows, type commands, switch workspaces. Each action is added to the recording.
>
> > ### Stop
> >
> > Press Ctrl+B T s. TUIOS writes the tape to disk and shows the file name.
>
> > ### Replay
> >
> > ```bash
> > tuios tape play "$(tuios tape dir)/my-workflow.tape"
> > ```

## Keys

The tape prefix is Ctrl+B T, followed by:

| Key | Action                                                                                |
| --- | ------------------------------------------------------------------------------------- |
| r   | Start recording (asks for a name)                                                     |
| s   | Stop recording and save                                                               |
| m   | Open the tape manager                                                                 |
| t   | Review a detected [project tape](https://tuios.dev/docs/tape-scripting#project-tapes) |
| Esc | Cancel the prefix                                                                     |

The tape manager lists your recordings. Use j and k or the arrow keys to select, Enter to play in the current session, r to record and d to delete.

## What a recording looks like

```bash
# my-workflow
# Recorded: 2026-09-22T10:15:04+04:00

# Disable animations for consistent playback
DisableAnimations

EnableTiling
WindowManagementMode
NewWindow
Sleep 1.204s
TerminalMode
Type "ls -la"
Sleep 612ms
Enter

# Re-enable animations
EnableAnimations
```

Every recording has the same frame:

- A header comment with the name and the start time.
- `DisableAnimations` at the start and `EnableAnimations` at the end, so playback does not depend on your animation setting.
- The state at the moment you started: `SwitchWorkspace` if you were not on workspace 1, then `EnableTiling` or `DisableTiling`, then the mode.

Between actions, a pause longer than 100 ms becomes a `Sleep`, rounded to the millisecond.

Printable keys you type into a pane are joined into one `Type` command. The text is written out when the next non-text key, action, mode switch or workspace switch happens, or when you stop recording.

## What is recorded

| Recorded                                         | As                                                                              |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| New, close, next and previous window             | `NewWindow`, `CloseWindow`, `NextWindow`, `PrevWindow`                          |
| Minimize                                         | `MinimizeWindow`                                                                |
| Toggle tiling                                    | `ToggleTiling`                                                                  |
| Every other action you run with a key            | `Action <name>`, such as `Action toggle_zoom` or `Action prefix_split_vertical` |
| Workspace switch                                 | `SwitchWorkspace <n>`                                                           |
| Mode switch                                      | `TerminalMode`, `WindowManagementMode`                                          |
| Text typed into a pane                           | `Type "..."`                                                                    |
| Special keys and key combinations sent to a pane | `Enter`, `Tab`, `Up`, `ctrl+c` and so on                                        |

An `Action` line does what the key did, so splits, zoom, snaps, layouts, the scratch pane and the rest replay the same way. See [Any action](https://tuios.dev/docs/tape-scripting#any-action).

Not recorded:

- Mouse actions: clicks, drags and resizes.
- Keys you type into a dialog or an overlay. An action that opens a dialog, such as `rename_window`, replays as the open dialog. Replace it with `RenameWindow "name"` by hand.
- The keys that only open a prefix, and the tape keys themselves.

## Managing recordings

```bash
tuios tape list              # name, size and date of each recording
tuios tape show my-workflow  # print a recording
tuios tape delete my-workflow
tuios tape dir               # print the recordings directory
```

`show` and `delete` take the name with or without `.tape`. `delete` asks for confirmation.

Recordings are saved in the `tuios` folder of your data directory, which `tuios tape dir` prints:

| Platform      | Default location                       |
| ------------- | -------------------------------------- |
| Linux and BSD | `~/.local/share/tuios/`                |
| macOS         | `~/Library/Application Support/tuios/` |

Setting `XDG_DATA_HOME` moves it on every platform. Only files ending in `.tape` are listed.

## Editing a recording

A recording is a normal tape, so you can:

- add comments,
- replace the exact `Sleep` values with round ones,
- add `WaitFor` so playback waits for real output,
- add `Expect` lines that check the result,
- replace an opened rename dialog with `RenameWindow "name"`,
- delete mistakes.

For example, a recording that starts a dev server can wait for it before opening a second pane:

```bash
EnableTiling
NewWindow
RenameWindow "server"
Type "npm start"
Enter
WaitFor text "listening on" 15s

SmartSplit
WaitFor panes 2
RenameWindow "shell"
```

Run `tuios tape validate` on the file after editing. `tuios tape play` and `tuios tape exec` both honour the waits.

## Tips

- Turn tiling on before you record. Tiled layouts replay the same way at any terminal size. Floating window positions are not recorded.
- Keep one task per tape. Short tapes are easier to fix than a whole afternoon.
- Start from a known state. `tape play` starts with no windows, so a recording made in a busy session will not replay the same way.
- Recording writes the file once, when you stop. Nothing is written per keystroke.

## Related

*[An interactive figure goes here. Open the page to use it.](https://tuios.dev/docs/tape-recording)*