{"id":17384251,"url":"https://github.com/bkahlert/recordr","last_synced_at":"2025-04-15T10:10:31.987Z","repository":{"id":40476807,"uuid":"420575297","full_name":"bkahlert/recordr","owner":"bkahlert","description":"Recordr is an automated terminal session recorder and SVG converter","archived":false,"fork":false,"pushed_at":"2022-10-05T22:38:38.000Z","size":1051,"stargazers_count":5,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T05:06:49.923Z","etag":null,"topics":["bash","conversion","converter","linux","recorder","recording","session","svg","terminal"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/bkahlert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"paypal.me/bkahlert"}},"created_at":"2021-10-24T03:12:35.000Z","updated_at":"2024-12-24T10:30:58.000Z","dependencies_parsed_at":"2023-01-11T17:21:54.083Z","dependency_job_id":null,"html_url":"https://github.com/bkahlert/recordr","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkahlert%2Frecordr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkahlert%2Frecordr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkahlert%2Frecordr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkahlert%2Frecordr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkahlert","download_url":"https://codeload.github.com/bkahlert/recordr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824666,"owners_count":21167343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bash","conversion","converter","linux","recorder","recording","session","svg","terminal"],"created_at":"2024-10-16T07:44:56.990Z","updated_at":"2025-04-15T10:10:31.953Z","avatar_url":"https://github.com/bkahlert.png","language":"Shell","funding_links":["paypal.me/bkahlert","https://www.paypal.me/bkahlert"],"categories":[],"sub_categories":[],"readme":"# bkahlert/recordr [![Build Status](https://img.shields.io/github/workflow/status/bkahlert/recordr/build?label=Build\u0026logo=github\u0026logoColor=fff)](https://github.com/bkahlert/recordr/actions/workflows/build.yml) [![Repository Size](https://img.shields.io/github/repo-size/bkahlert/recordr?color=01818F\u0026label=Repo%20Size\u0026logo=Git\u0026logoColor=fff)](https://github.com/bkahlert/recordr) [![Repository Size](https://img.shields.io/github/license/bkahlert/recordr?color=29ABE2\u0026label=License\u0026logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1OTAgNTkwIiAgeG1sbnM6dj0iaHR0cHM6Ly92ZWN0YS5pby9uYW5vIj48cGF0aCBkPSJNMzI4LjcgMzk1LjhjNDAuMy0xNSA2MS40LTQzLjggNjEuNC05My40UzM0OC4zIDIwOSAyOTYgMjA4LjljLTU1LjEtLjEtOTYuOCA0My42LTk2LjEgOTMuNXMyNC40IDgzIDYyLjQgOTQuOUwxOTUgNTYzQzEwNC44IDUzOS43IDEzLjIgNDMzLjMgMTMuMiAzMDIuNCAxMy4yIDE0Ny4zIDEzNy44IDIxLjUgMjk0IDIxLjVzMjgyLjggMTI1LjcgMjgyLjggMjgwLjhjMCAxMzMtOTAuOCAyMzcuOS0xODIuOSAyNjEuMWwtNjUuMi0xNjcuNnoiIGZpbGw9IiNmZmYiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxOS4yMTIiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4%3D)](https://github.com/bkahlert/recordr/blob/master/LICENSE)\n\n## About\n\n**Recordr** lets you record terminal sessions and convert them to SVG.\n\n[![recorded terminal session demonstrating the recordr tool](docs/demo.svg \"Recordr Demo\")  \n*Recordr Demo*](../../raw/master/docs/demo.svg)\n\n[![recorded terminal session demonstrating the recordr tool recording the demo](docs/recording-demo.svg \"Recordr recording the Recordr Demo\")  \n*Recordr recording the Recordr Demo*](../../raw/master/docs/recording-demo.svg)\n\n[![recorded terminal session demonstrating the logr logging library](docs/logr.svg \"logr Demo\")  \n*Recordr recording the logr Demo*](../../raw/master/docs/logr.svg)\n\n[![recorded terminal session demonstrating the images to ANSI converter](docs/chafa.svg \"chafa Demo\")  \n*Recordr recording chafa converting Nyan Cat*](../../raw/master/docs/chafa.svg)\n\n## Bash script\n\n`recordr` is a Bash script.\n\nIn order to use it, it can either be downloaded and run like a binary or used as a [Docker image](#docker-image).\n\nTo download recordr you can type:\n\n```shell\nsudo curl -LfsSo /usr/local/bin/recordr https://raw.githubusercontent.com/bkahlert/recordr/master/recordr\nchmod +x /usr/local/bin/recordr\n```\n\n## Docker image\n\n### Build locally\n\n```shell\ngit clone https://github.com/bkahlert/recordr.git\ncd recordr\n\n# Build image and output to docker (default)\ndocker buildx bake\n\n# Build multi-platform image\ndocker buildx bake image-all\n```\n\n### Image\n\n* [Docker Hub](https://hub.docker.com/r/bkahlert/recordr/) `bkahlert/recordr`\n* [GitHub Container Registry](https://github.com/users/bkahlert/packages/container/package/recordr) `ghcr.io/bkahlert/recordr`\n\nFollowing platforms for this image are available:\n\n* linux/amd64\n* linux/arm64/v8\n\n## Usage\n\nBy default, `recordr` looks for a `rec` directory in the current working directory, converts all contained\n\u003cspan style=\"color:#c21e73\"\u003e● rec\u003c/span\u003e files concurrently to SVG animations and puts them in a `docs`\ndirectory.\n\nThe following options can be used to customize the conversion:\n\n- `--rows` — number of rows to use for recording and conversion (default: 25)\n- `--indicator` — name of the environmental variable set during recording (default: RECORDING)\n- `--term` — value to use for the TERM environmental variable (default: xterm-256color)\n- `--out-dir` — path to copy the created SVG files to (default: docs/)\n- `--columns` — number of columns to use for recording and conversion (default: 132)\n- `--parallel` — maximum number of conversions that run at once; 0 will run as many conversions as possible (default: 4)\n- `--restart-delay` — number of seconds until the animation restart (default: 5)\n- `--build-dir` — path to store (intermediate) build artifacts (default: build/rec/)\n- `--term-profile` — path to the terminal profile to use for conversion (default: auto)\n- `--hide-recording` — whether to hide the recording process (default: false)\n- `--delete-build` — whether to delete intermediary build files on completion (default: false)\n\n**Files:**\nThere are basically two ways to specify which\n\u003cspan style=\"color:#c21e73\"\u003e● rec\u003c/span\u003e files to convert:\n\n- **Convert a single file: `./recordr rec/foo.rec`**  \n  *same as: `./rec/foo.rec` (interpreter form)*  \n  *same as: `./recordr --build-dir build/rec --out-dir docs rec/foo.rec` (explicit directories)*  \n  **Before:**\n  ```text\n  📁work             ⬅︎ you are here  \n  └─📁rec\n    ├─🔴foo.rec\n    └─📁bar\n      └─🔴baz.rec\n  ```\n  **After:**\n  ```text\n  📁work             ⬅︎ you are here  \n  ├─📁rec\n  │ ├─🔴foo.rec\n  │ └─📁bar\n  │   └─🔴baz.rec\n  ├─📁build\n  │ └─📁rec\n  │   ├─📄foo.sh\n  │   ├─📄foo.svg.0\n  │   ├─📄foo.svg.⋮\n  │   └─📄foo.svg.n\n  └─📁docs\n    └─🔴foo.svg      ⬅︎ to SVG converted rec file   \n  ```\n\n- **Convert a file tree: `./recordr rec`**  \n  *same as: `./recordr` (default directory: rec)*  \n  *same as: `./recordr --build-dir build/rec --out-dir docs rec` (explicit default directories)*    \n  *same as: `./recordr rec foo.rec bar/baz.rec` (explicit files)*    \n  **Before:**\n  ```text\n  📁work             ⬅︎ you are here  \n  └─📁rec\n    ├─🔴foo.rec\n    └─📁bar\n      └─🔴baz.rec\n  ```\n  **After:**\n  ```text\n  📁work             ⬅︎ you are here  \n  ├─📁rec\n  │ ├─🔴foo.rec\n  │ └─📁bar\n  │   └─🔴baz.rec\n  ├─📁build\n  │ └─📁rec\n  │   ├─📄foo.sh\n  │   ├─📄foo.svg.0\n  │   ├─📄foo.svg.⋮\n  │   ├─📄foo.svg.n\n  │   └─📁bar\n  │     ├─📄baz.sh\n  │     ├─📄baz.svg.0\n  │     ├─📄baz.svg.⋮\n  │     └─📄baz.svg.n\n  └─📁docs\n    ├─🔴foo.svg      ⬅︎ to SVG converted rec file\n    └─📁bar\n      └─🔴baz.svg    ⬅︎ to SVG converted rec file\n  ```\n\nTo customize colors just export your settings from your favourite terminal emulator\n(see [supported profiles](https://github.com/marionebl/term-schemes#supported-formats)) and put the profile in the directory containing your\n\u003cspan style=\"color:#c21e73\"\u003e● rec\u003c/span\u003e files.  \nThe profile will be picked up automatically if you leave `--term-profile` to `auto`.\n\n### Bash script\n\n```shell\nrecordr [OPTIONS] [DIR[/ ]FILE [FILE...]]\n```\n\n### Docker image\n\n```shell\ndocker run -it --rm \\\n  -e TERM=\"$TERM\" \\\n  -v \"$PWD\":\"$PWD\" \\\n  -w \"$PWD\" \\\n  bkahlert/recordr [OPTIONS] [DIR[/ ]FILE [FILE...]]\n```\n\n### Wrapper\n\nThe Recordr Wrapper `recordrw` needs nothing but a working Docker installation and either [`curl`](https://curl.se/download.html)\n, [`wget`](http://wget.addictivecode.org/FrequentlyAskedQuestions.html#download),\nor [`wget2`](https://gitlab.com/gnuwget/wget2#downloading-and-building-from-tarball):\n\n#### curl\n\n```shell\ncurl -LfsS https://git.io/recordrw | \"$SHELL\" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]\n```\n\n#### wget\n\n```shell\nwget -qO- https://git.io/recordrw | \"$SHELL\" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]\n```\n\n#### wget2\n\n```shell\nwget2 -nv -O- https://git.io/recordrw | \"$SHELL\" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]\n```\n\n### GitHub Action\n\nRecordr can also be used to automatically convert your terminal sessions to SVG files as part of your workflow.\n\nThe example below demonstrates how Recordr can be used to create a pull request containing all updated SVG files and \ntheir preview to show up right inside the pull request's description.  \n\n#### Usage Example\n\n```yml\njobs:\n  docs:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Prepare\n        id: prep\n        run: |\n          echo ::set-output name=recordr-branch::\"${{ github.ref_name }}--docs\"\n\n      - name: Checkout\n        uses: actions/checkout@v2\n\n      - name: ● REC terminal sessions\n        if: github.event_name != 'pull_request'\n        id: recordr\n        uses: bkahlert/recordr@v0.2.2\n        with:\n          branch: ${{ steps.prep.outputs.recordr-branch }}\n\n      - name: Create pull request\n        uses: peter-evans/create-pull-request@v3\n        if: startsWith(github.ref, 'refs/heads/')\n        with:\n          commit-message: |\n            ${{ github.workflow }}(docs): update ${{ steps.recordr.outputs.file-list }}\n          title: |\n            ${{ github.workflow }}(docs): update ${{ steps.recordr.outputs.file-list }}\n          body: |\n            Updates ${{ steps.recordr.outputs.file-list }}\n            ${{ steps.recordr.outputs.markdown }}\n          labels: recordr,docs,rec\n          branch: ${{ steps.prep.outputs.recordr-branch }}\n```\n\nAll [described options](#usage) can be used to customize the conversion. Please consult [action.yml](action.yml) for detailed information. \n\n[![pull request created by GitHub action](docs/action/pull-request.png \"Recordr GitHub Action\")  \n*Recordr GitHub Action*](.github/workflows/docs.yml)\n\n## Image Configuration\n\nThis image can be configured using the following options of which all but `APP_USER` and `APP_GROUP` exist as both—build argument and environment variable.  \nYou should go for build arguments if you want to set custom defaults you don't intend to change (often). Environment variables will overrule any existing\nconfiguration on each container start.\n\n- `APP_USER` Name of the main user (default: `recordr`)\n- `APP_GROUP` Name of the main user's group (default: `recordr`)\n- `DEBUG` Whether to log debug information (default: `0`)\n- `TZ` Timezone the container runs in (default: `UTC`)\n- `LANG` Language/locale to use (default: `C.UTF-8`)\n- `PUID` User ID of the `libguestfs` user (default: `1000`)\n- `PGID` Group ID of the `libguestfs` group (default: `1000`)\n\n```shell\n# Build single image with build argument TZ\ndocker buildx bake --build-arg TZ=\"$(date +\"%Z\")\"\n\n# Build multi-platform image with build argument TZ\ndocker buildx bake image-all --build-arg TZ=\"$(date +\"%Z\")\"\n\n# Start container with environment variable TZ\ndocker run --rm \\\n  -e TZ=\"$(date +\"%Z\")\" \\\n  -v \"$(pwd):$(pwd)\" \\\n  -w \"$(pwd)\" \\\n  recordr:local\n```\n\n## Authoring \u003cspan style=\"color:#c21e73\"\u003e● rec\u003c/span\u003e files\n\nBefore you can convert \u003cspan style=\"color:#c21e73\"\u003e● rec\u003c/span\u003e files to SVG you need to create them.  \nThe following code snippet should suffice as a starting point:\n\n```sh\n#!/usr/bin/env recordr\nrec echo \"Hello World!\"\n```\n[*hello-world.rec*](rec/hello-world.rec)\n\n[![recorded terminal session printing \"Hello World!\"](docs/hello-world.svg \"Hello World!\")  \n*Hello World! Example*](../../raw/master/docs/hello-world.svg)\n\nTo convert your file just execute it with `recordr` on your `PATH`:\n```shell\nPATH=.:$PATH ./hello-world.rec\n# or\n./recordr hello-world.rec\n```\n\nThe environment variable `TESTING` will reduce animations to a minimum.  \nSet it to `1` for an even better efficiency.\n\n[![recorded terminal session demonstrating the recordr tool recording the example](docs/recording-hello-world.svg \"Recordr recording the Hello World! Example\")  \n*Recordr recording the Hello World! Example*](../../raw/master/docs/recording-hello-world.svg)\n\n```sh\n#!/usr/bin/env recordr\nrec echo \"Hello World!\"\n```\n\n## Testing\n\n```shell\ngit clone https://github.com/bkahlert/recordr.git\ncd recordr\n\n# Use Bats wrapper to run tests\ncurl -LfsS https://git.io/batsw \\\n  | DOCKER_BAKE=\"--set '*.tags=test'\" \"$SHELL\" -s -- --batsw:-e --batsw:BUILD_TAG=test test\n```\n\n[Bats Wrapper](https://github.com/bkahlert/bats-wrapper) is a self-contained wrapper to run tests based on the Bash testing\nframework [Bats](https://github.com/bats-core/bats-core).\n\n\u003e 💡 To accelerate testing, the Bats Wrapper checks if any test is prefixed with a capital X and if so, only runs those tests.\n\n## Troubleshooting\n\n- You might experience problems when converting very long or complex terminal sessions.   \n  Try increasing the corresponding `NODE_OPTIONS` as you can see below.\n- To avoid permission problems with generated files, you can use your local user/group ID (see `PUID`/`PGID`).\n- If you need access to Docker, its command line interface is already installed.  \n  You can control your host instance by mounting `/var/run/docker.sock`.\n\n```shell\ndocker run -it --rm \\\n  -e PUID=\"$(id -u)\" \\\n  -e PGID=\"$(id -g)\" \\\n  -e NODE_OPTIONS=\"--max-old-space-size=16384\" \\\n  -e TERM=\"$TERM\" \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v \"$PWD\":\"$PWD\" \\\n  -w \"$PWD\" \\\n  bkahlert/recordr:edge\n```\n\n- Authoring rec files benefits from short round-trips\n\n## Contributing\n\nWant to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by making\na [Paypal donation](https://www.paypal.me/bkahlert) to ensure this journey continues indefinitely!\n\nThanks again for your support, it is much appreciated! :pray:\n\n## License\n\nMIT. See [LICENSE](LICENSE) for more details.\n\n## TODO\n- [ ] add support for dim and italic\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkahlert%2Frecordr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkahlert%2Frecordr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkahlert%2Frecordr/lists"}