# 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.204113s
TerminalMode
Type "ls -la"
Sleep 612.40875ms
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` with the exact measured time. Round the values by hand if you want a tidier file.

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`                                       |
| Restore all minimized                            | `RestoreWindow`                                        |
| Toggle tiling                                    | `ToggleTiling`                                         |
| Snap left, right, fullscreen                     | `SnapLeft`, `SnapRight`, `SnapFullscreen`              |
| Select window by number                          | `FocusWindow <n>`                                      |
| 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               |

Not recorded:

- Mouse actions: clicks, drags and resizes.
- Splits, zoom and other BSP actions. A session built from splits replays as if you never split.
- Renames, and moving a window to another workspace.
- Copy mode, overlays and anything else not in the table above.

Some recorded commands do not replay the way you performed them:

- `RestoreWindow` restores only the focused window, not every minimized one.
- `FocusWindow <n>` looks for a window named or with the ID `n`, not the window at position `n`, so it usually does nothing.
- `SnapFullscreen` snaps to the top-left quarter.

Fix these by hand after recording. `SmartSplit`, `RenameWindow "name"` and `FocusWindow <name>` all work on playback. See [Tape Scripting](https://tuios.dev/docs/tape-scripting#commands) for every command.

## 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 `WaitUntilRegex` so playback waits for real output,
- add the splits and renames the recorder missed,
- 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
WaitUntilRegex "listening on" 15000

SmartSplit
RenameWindow "shell"
```

Run `tuios tape validate` on the file after editing.

> `Wait` and `WaitUntilRegex` only work under `tuios tape play`. `tuios tape exec` skips them, so a tape meant for both should pace itself with `Sleep`.

## 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)*