Tape Recording

TUIOS can record your terminal sessions into .tape files that can be replayed, shared, or used for automated testing. Think of it as recording a macro of everything you do in TUIOS.

Quick Start

tuios tape play ~/.local/share/tuios/tapes/my-workflow.tape

Recording Keybindings

All recording commands use the tape prefix menu:

What Gets Recorded

Captured

• Window Operations: New, close, rename, minimize, restore
• Navigation: Next/previous window, select by number
• Workspaces: Switch, move window to workspace
• Layout: Toggle tiling, snap operations, splits
• Mode Switches: Window management ↔ Terminal mode
• Keyboard Input: Text typed in terminals, special keys
• Timing: Automatic delays between actions

Not Captured

• Mouse Events: Clicks, drags, resizes
• Terminal Output: Only input is recorded
• Visual State: Window positions in non-tiling mode
• Copy Mode: Scrollback navigation

Managing Recordings

List Recordings

tuios tape list

Shows all recordings with sizes and modification times.

View Contents

tuios tape show my-workflow

Display the tape file. The .tape extension is optional.

Delete Recording

tuios tape delete my-workflow

Show Directory

tuios tape dir

Prints the path: ~/.local/share/tuios/tapes/

Recording Workflow

Initial State Capture

When recording starts, TUIOS captures:

• Current mode (Window Management or Terminal)
• Active workspace number
• Tiling enabled/disabled

The tape file begins with commands to restore this state during playback.

Timing Capture

Time delays between actions are automatically calculated and inserted as Sleep commands:

NewWindow
Sleep 500ms
TerminalMode
Type "ls -la"
Sleep 200ms
Enter

Typing Buffer

Rapid typing is merged into single Type commands. A flush occurs when:

• 500ms passes with no typing
• Mode switches occur
• Window management actions occur
• Recording stops

Use Cases

Best Practices

Naming Conventions

Use descriptive names:

# Good
dev-setup.tape
project-build.tape
multi-workspace-demo.tape

# Bad
recording-1.tape
test.tape
tmp.tape

Recording for Playback

Keep recordings focused: One task per tape rather than entire sessions.

Start in a clean state: Begin with no windows or a known configuration.

Avoid mistakes: If you make an error, stop and start over. Editing tapes is tedious.

Recording for Documentation

Add comments after recording: Document what each section does:

# Setup development environment
WindowManagementMode
EnableTiling

# Create editor window
NewWindow
Sleep 500ms
TerminalMode
Type "vim main.go"
Enter

Use meaningful window titles: Rename windows during recording for clarity.

Technical Details

Storage Location

Default: ~/.local/share/tuios/tapes/

Follows XDG Base Directory specification. Created automatically on first recording.

File Format

Standard .tape files using the TUIOS tape scripting language. See Tape Scripting for the complete language reference.

Performance

Recording overhead is minimal:

• Memory: ~100 bytes per action
• CPU: < 0.1% on modern systems
• Disk: 1-10KB per recording

Recording does not impact terminal performance or increase latency.

Examples

Example 1: Development Environment

# Recorded: 2024-12-18
# Development environment setup

WindowManagementMode
EnableTiling
Sleep 300ms

# Editor window
NewWindow
Sleep 500ms
TerminalMode
Type "vim main.go"
Enter
Sleep 800ms

# Terminal window
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "go run ."
Enter

Example 2: Multi-Workspace Setup

# Setup project workspaces

WindowManagementMode

# Workspace 1: Coding
SwitchWorkspace 1
EnableTiling
NewWindow
TerminalMode
Type "vim main.go"
Enter

# Workspace 2: Testing
WindowManagementMode
SwitchWorkspace 2
NewWindow
TerminalMode
Type "go test -v ./..."
Enter

# Return to main workspace
WindowManagementMode
SwitchWorkspace 1

Example 3: CI/CD Testing

Record a test execution workflow:

# Start recording
tuios
# Ctrl+B T r
# Name: "ci-test-suite"

# Run tests
n
i
npm test
# Wait for completion...
Ctrl+C

# Stop recording
# Ctrl+B T s

Edit to add proper waiting:

WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "npm test"
Enter
WaitUntilRegex "Tests passed" 30000

Run in CI:

#!/bin/bash
tuios tape run ci-test-suite.tape

Editing Recordings

Tape files are plain text. Edit them to:

• Add comments explaining steps
• Insert additional Sleep commands for pacing
• Add WaitUntilRegex for output synchronization
• Remove mistakes
• Combine multiple recordings

Before editing:

WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "echo hello"
Enter

After editing:

WindowManagementMode
NewWindow
Sleep 500ms

# Start server and wait for it
TerminalMode
Type "npm start"
Enter
WaitUntilRegex "Server listening" 10000

# Open another window for testing
WindowManagementMode
NewWindow
Sleep 300ms

Troubleshooting

Recording Not Starting

Check tape directory:

ls -la ~/.local/share/tuios/tapes/

If it doesn't exist, TUIOS creates it automatically. Check filesystem permissions if creation fails.

Only one recording at a time: Stop any existing recording with Ctrl+B T s before starting a new one.

Playback Issues

Validate syntax:

tuios tape validate my-recording.tape

Add timing: If playback is too fast, add Sleep commands:

NewWindow
Sleep 500ms  # Add pauses

Clean starting state: Recordings assume a fresh TUIOS session. Start fresh before playback.

Related Documentation