https://github.com/arthurdick/term-to-svg
Convert terminal session recordings into animated SVG files.
https://github.com/arthurdick/term-to-svg
animation cli php recorder svg terminal
Last synced: 5 months ago
JSON representation
Convert terminal session recordings into animated SVG files.
- Host: GitHub
- URL: https://github.com/arthurdick/term-to-svg
- Owner: arthurdick
- License: mit
- Created: 2025-07-26T21:16:33.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-10-08T19:04:07.000Z (9 months ago)
- Last Synced: 2025-10-20T23:27:40.344Z (8 months ago)
- Topics: animation, cli, php, recorder, svg, terminal
- Language: PHP
- Homepage:
- Size: 460 KB
- Stars: 42
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# term-to-svg: Animated Terminal Session Recorder
`term-to-svg` is a command-line PHP tool that converts terminal session recordings (made with the `script` command) into highly customizable, animated SVG files. This allows you to easily embed interactive and visually appealing terminal demonstrations directly into your project `README`s, websites, or documentation.
Unlike GIF animations, SVG files are vector-based, resulting in sharper visuals at any zoom level, smaller file sizes, and the ability to be manipulated with CSS and JavaScript.
-----
## Features
* **High Fidelity Playback**: Accurately interprets ANSI escape codes for cursor movement, color changes, inverse video, character/line manipulation, scroll regions, and screen clearing to reproduce your terminal session as precisely as possible.
* **Multiple Animation Engines**: Choose between two animation engines:
* **CSS Animations (Default)**: A modern, efficient engine that is widely supported and ideal for web embedding.
* **SMIL**: A powerful, self-contained animation engine that is also well-supported.
* **Powerful Theming**: Customize the look and feel of your SVG with a simple JSON theme file. A variety of pre-made light and dark themes are included.
* **Configurable**: Supports configuration for terminal dimensions, font size, and more via command-line flags that can override theme settings.
* **Automatic Geometry Detection**: Can automatically detect terminal dimensions from the `script` log file if available.
* **Lightweight**: A lightweight PHP application with no external runtime dependencies.
-----
## Installation & Usage
There are three ways to use `term-to-svg`, depending on your needs.
### Method 1: Standalone PHAR (Recommended)
This method provides a single, executable file, but **requires PHP to be installed** on your system.
**Best for:** Most users, including non-developers, who want a simple way to run the tool.
1. **Download:** Grab the latest `term-to-svg.phar` file from the project's **Releases** page on GitHub.
2. **Make Executable:** Open your terminal and make the downloaded file executable.
```bash
chmod +x term-to-svg.phar
```
3. **Run:** You can now run the tool directly.
```bash
./term-to-svg.phar -t my_session.log -i my_session.time -o output.svg
```
#### Making it Globally Available (Optional)
To run `term-to-svg` from any directory without typing `./term-to-svg.phar`, you can move it to a directory in your system's `PATH`.
1. **Move & Rename:** Move the phar to a common location for binaries and rename it for convenience. `/usr/local/bin` is a good choice.
```bash
sudo mv term-to-svg.phar /usr/local/bin/term-to-svg
```
2. **Verify:** Close and reopen your terminal, then check if the command is available:
```bash
term-to-svg --version
```
If it's not found, ensure `/usr/local/bin` is in your `PATH`. You can check with `echo $PATH`. If it's missing, add it to your shell's startup file (e.g., `~/.bashrc`, `~/.zshrc`):
```bash
export PATH="/usr/local/bin:$PATH"
```
### Method 2: Global Install with Composer
**Best for:** PHP developers who want the `term-to-svg` command to be available system-wide.
1. **Install:** Use Composer to install the tool globally.
```bash
composer global require arthurdick/term-to-svg
```
2. **Update PATH:** Make sure your Composer `bin` directory is in your system's `PATH`.
3. **Run:**
```bash
term-to-svg -t my_session.log -i my_session.time -o output.svg
```
### Method 3: From Source
**Best for:** Developers who want to contribute to the project or modify the source code.
1. **Clone:** Clone the repository to your local machine.
```bash
git clone https://github.com/arthurdick/term-to-svg.git
cd term-to-svg
```
2. **Install Dependencies:**
```bash
composer install
```
3. **Run:** Execute the script using PHP.
```bash
php bin/term-to-svg -t my_session.log -i my_session.time -o output.svg
```
-----
## The Recording Process
No matter how you installed the tool, the recording process is the same.
1. **Record:** Use the standard `script` command with the `--timing` option.
```bash
script --timing=rec.time rec.log
```
2. **Perform Actions:** A subshell will start. Perform the commands you want to record.
3. **Exit:** When you're finished, type `exit` to end the recording session.
You will now have two files: `rec.log` (the terminal output) and `rec.time` (the timing information), ready for conversion.
-----
## Configuration
You can customize the output by using command-line flags. Flags will always override any settings provided by a theme.
```
Usage: term-to-svg [options]
Options:
-t, --typescript_file Path to the typescript file (required).
-i, --timing_file Path to the timing file (required).
-o, --output_file Path to the output SVG file (required).
--generator Animation generator to use (css or smil). Default: css.
--theme Path to a custom theme JSON file.
--id ID to use for the root SVG element.
--rows Number of terminal rows.
--cols Number of terminal columns.
--font_size Font size.
--line_height_factor Line height factor.
--font_width_factor Font width factor.
--font_family Font family (overrides theme).
--default_fg Default foreground color (overrides theme).
--default_bg Default background color (overrides theme).
--animation_pause_seconds Animation pause in seconds at the end.
--poster_at
**Note on Geometry Detection**: If your `rec.log` file was generated with a `script` version that includes `COLUMNS` and `LINES` information in its first line (e.g., `COLUMNS="80" LINES="24"`), the script will automatically use these dimensions, overriding the `--rows` and `--cols` flags.
-----
## Theming
You can easily change the appearance of the output SVG by using a theme file. A number of pre-made themes are available in the `themes/` directory.
### Using a Theme
To use a theme, pass the path to the theme file using the `--theme` flag:
```bash
./term-to-svg -t rec.log -i rec.time -o output.svg --theme themes/dracula.json
```
### Creating a Custom Theme
You can create your own themes by making a JSON file with the following structure:
```json
{
"font_family": "Menlo, Monaco, \"Courier New\", monospace",
"default_fg": "#f8f8f2",
"default_bg": "#282a36",
"ansi_16_colors": {
"30": "#000000", "31": "#ff5555", "32": "#50fa7b", "33": "#f1fa8c",
"34": "#bd93f9", "35": "#ff79c6", "36": "#8be9fd", "37": "#f8f8f2",
"90": "#6272a4", "91": "#ff6e6e", "92": "#69ff94", "93": "#ffffa5",
"94": "#d6acff", "95": "#ff92df", "96": "#a4ffff", "97": "#ffffff"
}
}
```
-----
## Requirements
* PHP 7.4 or higher.
* The `mbstring` PHP extension.
* A Unix-like operating system with the `script` command available.
-----
## Contributing
Contributions are welcome\! If you find a bug or have a feature request, please open an issue or submit a pull request.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.