{"id":39286500,"url":"https://github.com/arthurdick/term-to-svg","last_synced_at":"2026-01-18T01:10:43.307Z","repository":{"id":306669127,"uuid":"1026897800","full_name":"arthurdick/term-to-svg","owner":"arthurdick","description":"Convert terminal session recordings into animated SVG files.","archived":false,"fork":false,"pushed_at":"2025-10-08T19:04:07.000Z","size":471,"stargazers_count":42,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T23:27:40.344Z","etag":null,"topics":["animation","cli","php","recorder","svg","terminal"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arthurdick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T21:16:33.000Z","updated_at":"2025-10-09T00:41:21.000Z","dependencies_parsed_at":"2025-07-27T01:20:59.278Z","dependency_job_id":"588b0ab5-ee92-4f13-b1b1-28e854b945af","html_url":"https://github.com/arthurdick/term-to-svg","commit_stats":null,"previous_names":["arthurdick/term-to-svg"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/arthurdick/term-to-svg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurdick%2Fterm-to-svg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurdick%2Fterm-to-svg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurdick%2Fterm-to-svg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurdick%2Fterm-to-svg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arthurdick","download_url":"https://codeload.github.com/arthurdick/term-to-svg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arthurdick%2Fterm-to-svg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28525682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"ssl_error","status_checked_at":"2026-01-18T00:39:39.467Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","cli","php","recorder","svg","terminal"],"created_at":"2026-01-18T01:10:43.227Z","updated_at":"2026-01-18T01:10:43.296Z","avatar_url":"https://github.com/arthurdick.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# term-to-svg: Animated Terminal Session Recorder\n\n![term-to-svg Demo](demo.svg)\n\n`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.\n\nUnlike 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.\n\n-----\n\n## Features\n\n  * **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.\n  * **Multiple Animation Engines**: Choose between two animation engines:\n    * **CSS Animations (Default)**: A modern, efficient engine that is widely supported and ideal for web embedding.\n    * **SMIL**: A powerful, self-contained animation engine that is also well-supported.\n  * **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.\n  * **Configurable**: Supports configuration for terminal dimensions, font size, and more via command-line flags that can override theme settings.\n  * **Automatic Geometry Detection**: Can automatically detect terminal dimensions from the `script` log file if available.\n  * **Lightweight**: A lightweight PHP application with no external runtime dependencies.\n\n-----\n\n## Installation \u0026 Usage\n\nThere are three ways to use `term-to-svg`, depending on your needs.\n\n### Method 1: Standalone PHAR (Recommended)\n\nThis method provides a single, executable file, but **requires PHP to be installed** on your system.\n\n**Best for:** Most users, including non-developers, who want a simple way to run the tool.\n\n1.  **Download:** Grab the latest `term-to-svg.phar` file from the project's **Releases** page on GitHub.\n2.  **Make Executable:** Open your terminal and make the downloaded file executable.\n    ```bash\n    chmod +x term-to-svg.phar\n    ```\n3.  **Run:** You can now run the tool directly.\n    ```bash\n    ./term-to-svg.phar -t my_session.log -i my_session.time -o output.svg\n    ```\n\n#### Making it Globally Available (Optional)\n\nTo 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`.\n\n1.  **Move \u0026 Rename:** Move the phar to a common location for binaries and rename it for convenience. `/usr/local/bin` is a good choice.\n    ```bash\n    sudo mv term-to-svg.phar /usr/local/bin/term-to-svg\n    ```\n2.  **Verify:** Close and reopen your terminal, then check if the command is available:\n    ```bash\n    term-to-svg --version\n    ```\n\nIf 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`):\n\n```bash\nexport PATH=\"/usr/local/bin:$PATH\"\n```\n\n### Method 2: Global Install with Composer\n\n**Best for:** PHP developers who want the `term-to-svg` command to be available system-wide.\n\n1.  **Install:** Use Composer to install the tool globally.\n    ```bash\n    composer global require arthurdick/term-to-svg\n    ```\n2.  **Update PATH:** Make sure your Composer `bin` directory is in your system's `PATH`.\n3.  **Run:**\n    ```bash\n    term-to-svg -t my_session.log -i my_session.time -o output.svg\n    ```\n\n### Method 3: From Source\n\n**Best for:** Developers who want to contribute to the project or modify the source code.\n\n1.  **Clone:** Clone the repository to your local machine.\n    ```bash\n    git clone https://github.com/arthurdick/term-to-svg.git\n    cd term-to-svg\n    ```\n2.  **Install Dependencies:**\n    ```bash\n    composer install\n    ```\n3.  **Run:** Execute the script using PHP.\n    ```bash\n    php bin/term-to-svg -t my_session.log -i my_session.time -o output.svg\n    ```\n\n-----\n\n## The Recording Process\n\nNo matter how you installed the tool, the recording process is the same.\n\n1.  **Record:** Use the standard `script` command with the `--timing` option.\n    ```bash\n    script --timing=rec.time rec.log\n    ```\n2.  **Perform Actions:** A subshell will start. Perform the commands you want to record.\n3.  **Exit:** When you're finished, type `exit` to end the recording session.\n\nYou will now have two files: `rec.log` (the terminal output) and `rec.time` (the timing information), ready for conversion.\n\n-----\n\n## Configuration\n\nYou can customize the output by using command-line flags. Flags will always override any settings provided by a theme.\n\n```\nUsage: term-to-svg [options]\n\nOptions:\n  -t, --typescript_file \u003cfile\u003e  Path to the typescript file (required).\n  -i, --timing_file \u003cfile\u003e      Path to the timing file (required).\n  -o, --output_file \u003cfile\u003e      Path to the output SVG file (required).\n  --generator \u003ccss|smil\u003e    Animation generator to use (css or smil). Default: css.\n  --theme \u003cfile\u003e            Path to a custom theme JSON file.\n  --id \u003cstring\u003e             ID to use for the root SVG element.\n  --rows \u003cnumber\u003e           Number of terminal rows.\n  --cols \u003cnumber\u003e           Number of terminal columns.\n  --font_size \u003cnumber\u003e      Font size.\n  --line_height_factor \u003cfloat\u003e Line height factor.\n  --font_width_factor \u003cfloat\u003e Font width factor.\n  --font_family \u003cstring\u003e    Font family (overrides theme).\n  --default_fg \u003chex\u003e        Default foreground color (overrides theme).\n  --default_bg \u003chex\u003e        Default background color (overrides theme).\n  --animation_pause_seconds \u003cnumber\u003e Animation pause in seconds at the end.\n  --poster_at \u003ctime|end\u003e    Generate a non-animated SVG of a single frame at a specific time or at the end.\n  --interactive             Enable interactive player controls.\n  -v, --version             Display the version number.\n  -h, --help                Display this help message.\n```\n\n**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.\n\n-----\n\n## Theming\n\nYou 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.\n\n### Using a Theme\n\nTo use a theme, pass the path to the theme file using the `--theme` flag:\n\n```bash\n./term-to-svg -t rec.log -i rec.time -o output.svg --theme themes/dracula.json\n```\n\n### Creating a Custom Theme\n\nYou can create your own themes by making a JSON file with the following structure:\n\n```json\n{\n    \"font_family\": \"Menlo, Monaco, \\\"Courier New\\\", monospace\",\n    \"default_fg\": \"#f8f8f2\",\n    \"default_bg\": \"#282a36\",\n    \"ansi_16_colors\": {\n        \"30\": \"#000000\", \"31\": \"#ff5555\", \"32\": \"#50fa7b\", \"33\": \"#f1fa8c\",\n        \"34\": \"#bd93f9\", \"35\": \"#ff79c6\", \"36\": \"#8be9fd\", \"37\": \"#f8f8f2\",\n        \"90\": \"#6272a4\", \"91\": \"#ff6e6e\", \"92\": \"#69ff94\", \"93\": \"#ffffa5\",\n        \"94\": \"#d6acff\", \"95\": \"#ff92df\", \"96\": \"#a4ffff\", \"97\": \"#ffffff\"\n    }\n}\n```\n\n-----\n\n## Requirements\n\n  * PHP 7.4 or higher.\n  * The `mbstring` PHP extension.\n  * A Unix-like operating system with the `script` command available.\n\n-----\n\n## Contributing\n\nContributions are welcome\\! If you find a bug or have a feature request, please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurdick%2Fterm-to-svg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurdick%2Fterm-to-svg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurdick%2Fterm-to-svg/lists"}