Metadata-Version: 2.4
Name: ttylog
Version: 0.1.0
Summary: Record terminal sessions as .cast files — trim idle gaps, export to standalone HTML, no account needed
Project-URL: Homepage, https://github.com/gitwingo/ttylog
Project-URL: Repository, https://github.com/gitwingo/ttylog
Project-URL: Bug Tracker, https://github.com/gitwingo/ttylog/issues
Author-email: gitwingo <gitwingo@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: asciinema,cast,cli,developer-tools,recording,screencast,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

<div align="center">

<h1>ttylog</h1>

<p>Record your terminal. Trim the dead air. Share as a single HTML file. No account. No upload.</p>

[![PyPI version](https://img.shields.io/pypi/v/ttylog?color=27c93f&labelColor=0d1117&logo=pypi&logoColor=white)](https://pypi.org/project/ttylog)
[![Python](https://img.shields.io/pypi/pyversions/ttylog?color=27c93f&labelColor=0d1117&logo=python&logoColor=white)](https://pypi.org/project/ttylog)
[![License: MIT](https://img.shields.io/badge/license-MIT-27c93f?labelColor=0d1117)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/ttylog?color=27c93f&labelColor=0d1117)](https://pypi.org/project/ttylog)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-27c93f?labelColor=0d1117)](https://pypi.org/project/ttylog)

<img src="https://raw.githubusercontent.com/gitwingo/ttylog/main/docs/images/screenshot.png" alt="ttylog terminal screenshot" width="820">

</div>

---

`ttylog` (TeleTYpewriter log) records your terminal session to a standard `.cast` file (asciinema v2 format), lets you trim out the idle gaps, replay it in your terminal, and export it as a fully self-contained HTML file you can open in any browser — no server, no asciinema account, no upload required.

The exported HTML embeds the player and the recording in a single file. Send it in a Slack message, attach it to a GitHub issue, drop it in docs. It just works.

---

## Install

```bash
pip install ttylog
```

Or with pipx:

```bash
pipx install ttylog
```

> **Note:** Recording (`ttylog record`) requires Linux or macOS — it uses Unix PTY. Playback, trimming, and HTML export work on all platforms including Windows.

---

## Usage

### Record

```bash
# Record your default shell
ttylog record session.cast

# Record a specific command
ttylog record session.cast --command "python demo.py"

# Add a title
ttylog record session.cast --title "Deploy walkthrough"

# Suppress the startup banner
ttylog record session.cast --quiet
```

Press **Ctrl-D** or type `exit` to stop recording.

### Replay

```bash
# Replay at normal speed
ttylog play session.cast

# Replay at 2× speed
ttylog play session.cast --speed 2

# Replay at 0.5× (slow motion)
ttylog play session.cast --speed 0.5
```

### Trim idle gaps

```bash
# Trim gaps longer than 2 seconds (default)
ttylog trim session.cast session_trimmed.cast

# Custom gap threshold
ttylog trim session.cast session_trimmed.cast --max-gap 1.5
```

### Export to HTML

```bash
# Export as self-contained HTML — no server needed
ttylog export session.cast session.html
```

Open `session.html` in any browser. The recording plays automatically. No internet connection required — the player is embedded.

### Inspect a recording

```bash
ttylog info session.cast
```

Shows title, command, terminal dimensions, duration, event count, and file size.

---

## .cast format compatibility

`ttylog` uses the standard **asciinema v2** `.cast` format. Files recorded with `ttylog` are fully compatible with:

| Tool | Use |
|---|---|
| [asciinema.org](https://asciinema.org) | Upload and share online |
| [agg](https://github.com/asciinema/agg) | Convert to animated GIF |
| [svg-term](https://github.com/marionebl/svg-term-cli) | Convert to SVG |
| [asciinema-player](https://github.com/asciinema/asciinema-player) | Embed in your own website |

You can also use files recorded with `asciinema` directly with `ttylog trim`, `ttylog export`, and `ttylog info`.

---

## All commands

```
ttylog record  OUTPUT         Record a terminal session to a .cast file
ttylog play    SOURCE         Replay a session in the terminal
ttylog export  SOURCE OUTPUT  Export a session as self-contained HTML
ttylog trim    SOURCE OUTPUT  Remove idle gaps from a recording
ttylog info    SOURCE         Show metadata and statistics
```

### `record` options
```
--command, -c   Command to run instead of $SHELL
--title,   -t   Session title
--quiet,   -q   Suppress startup banner
```

### `play` options
```
--speed, -s   Playback speed multiplier (default: 1.0, range: 0.1–10.0)
```

### `trim` options
```
--max-gap, -g   Max idle gap in seconds (default: 2.0)
```

---

## Windows users

Recording requires a Unix PTY and is not supported natively on Windows. Use **WSL2** to record sessions. Playback (`ttylog play`), export (`ttylog export`), trim (`ttylog trim`), and info (`ttylog info`) all work natively on Windows.

---

## Development

```bash
git clone https://github.com/gitwingo/ttylog
cd ttylog
pip install -e .
```
---
## Support

If ttylog has been useful to you, consider supporting its development:

<a href="https://ko-fi.com/gitwingo">
  <img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Buy Me a Ko-Fi" />
</a>


## Connect

- GitHub: [@gitwingo](https://github.com/gitwingo)
- Reddit: [u/gitwingo](https://reddit.com/user/gitwingo)
- X / Twitter: [@gitwingo](https://x.com/gitwingo)

---

<div align="center">
  <sub>Made with 💖 by <a href="https://github.com/gitwingo">Gitwingo</a></sub>
</div>

---

## License

MIT © [gitwingo](https://github.com/gitwingo)
