bkahlert/recordr

About

Recordr lets you record terminal sessions and convert them to SVG.

Recordr Demo

Recordr recording the Recordr Demo

Recordr recording the logr Demo

Recordr recording chafa converting Nyan Cat

Bash script

recordr is a Bash script.

In order to use it, it can either be downloaded and run like a binary or used as a Docker image.

To download recordr you can type:

sudo curl -LfsSo /usr/local/bin/recordr https://raw.githubusercontent.com/bkahlert/recordr/master/recordr
chmod +x /usr/local/bin/recordr

Docker image

Build locally

git clone https://github.com/bkahlert/recordr.git
cd recordr

# Build image and output to docker (default)
docker buildx bake

# Build multi-platform image
docker buildx bake image-all

Image

Docker Hub bkahlert/recordr
GitHub Container Registry ghcr.io/bkahlert/recordr

Following platforms for this image are available:

linux/amd64
linux/arm64/v8

Usage

By default, recordr looks for a rec directory in the current working directory, converts all contained ● rec files concurrently to SVG animations and puts them in a docs directory.

The following options can be used to customize the conversion:

--rows — number of rows to use for recording and conversion (default: 25)
--indicator — name of the environmental variable set during recording (default: RECORDING)
--term — value to use for the TERM environmental variable (default: xterm-256color)
--out-dir — path to copy the created SVG files to (default: docs/)
--columns — number of columns to use for recording and conversion (default: 132)
--parallel — maximum number of conversions that run at once; 0 will run as many conversions as possible (default: 4)
--restart-delay — number of seconds until the animation restart (default: 5)
--build-dir — path to store (intermediate) build artifacts (default: build/rec/)
--term-profile — path to the terminal profile to use for conversion (default: auto)
--hide-recording — whether to hide the recording process (default: false)
--delete-build — whether to delete intermediary build files on completion (default: false)

Files: There are basically two ways to specify which ● rec files to convert:

Convert a single file: ./recordr rec/foo.rec
same as: ./rec/foo.rec (interpreter form)
same as: ./recordr --build-dir build/rec --out-dir docs rec/foo.rec (explicit directories)
Before:

📁work             ⬅︎ you are here  
└─📁rec
  ├─🔴foo.rec
  └─📁bar
    └─🔴baz.rec

After:

📁work             ⬅︎ you are here  
├─📁rec
│ ├─🔴foo.rec
│ └─📁bar
│   └─🔴baz.rec
├─📁build
│ └─📁rec
│   ├─📄foo.sh
│   ├─📄foo.svg.0
│   ├─📄foo.svg.⋮
│   └─📄foo.svg.n
└─📁docs
  └─🔴foo.svg      ⬅︎ to SVG converted rec file

Convert a file tree: ./recordr rec
same as: ./recordr (default directory: rec)
same as: ./recordr --build-dir build/rec --out-dir docs rec (explicit default directories)
same as: ./recordr rec foo.rec bar/baz.rec (explicit files)
Before:

📁work             ⬅︎ you are here  
└─📁rec
  ├─🔴foo.rec
  └─📁bar
    └─🔴baz.rec

After:

📁work             ⬅︎ you are here  
├─📁rec
│ ├─🔴foo.rec
│ └─📁bar
│   └─🔴baz.rec
├─📁build
│ └─📁rec
│   ├─📄foo.sh
│   ├─📄foo.svg.0
│   ├─📄foo.svg.⋮
│   ├─📄foo.svg.n
│   └─📁bar
│     ├─📄baz.sh
│     ├─📄baz.svg.0
│     ├─📄baz.svg.⋮
│     └─📄baz.svg.n
└─📁docs
  ├─🔴foo.svg      ⬅︎ to SVG converted rec file
  └─📁bar
    └─🔴baz.svg    ⬅︎ to SVG converted rec file

To customize colors just export your settings from your favourite terminal emulator (see supported profiles) and put the profile in the directory containing your ● rec files.
The profile will be picked up automatically if you leave --term-profile to auto.

Bash script

recordr [OPTIONS] [DIR[/ ]FILE [FILE...]]

Docker image

docker run -it --rm \
  -e TERM="$TERM" \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  bkahlert/recordr [OPTIONS] [DIR[/ ]FILE [FILE...]]

Wrapper

The Recordr Wrapper recordrw needs nothing but a working Docker installation and either curl , wget, or wget2:

curl

curl -LfsS https://git.io/recordrw | "$SHELL" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]

wget

wget -qO- https://git.io/recordrw | "$SHELL" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]

wget2

wget2 -nv -O- https://git.io/recordrw | "$SHELL" -s -- [OPTIONS] [DIR[/ ]FILE [FILE...]]

GitHub Action

Recordr can also be used to automatically convert your terminal sessions to SVG files as part of your workflow.

The example below demonstrates how Recordr can be used to create a pull request containing all updated SVG files and their preview to show up right inside the pull request's description.

Usage Example

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - name: Prepare
        id: prep
        run: |
          echo ::set-output name=recordr-branch::"${{ github.ref_name }}--docs"

      - name: Checkout
        uses: actions/checkout@v2

      - name: ● REC terminal sessions
        if: github.event_name != 'pull_request'
        id: recordr
        uses: bkahlert/[email protected]
        with:
          branch: ${{ steps.prep.outputs.recordr-branch }}

      - name: Create pull request
        uses: peter-evans/create-pull-request@v3
        if: startsWith(github.ref, 'refs/heads/')
        with:
          commit-message: |
            ${{ github.workflow }}(docs): update ${{ steps.recordr.outputs.file-list }}
          title: |
            ${{ github.workflow }}(docs): update ${{ steps.recordr.outputs.file-list }}
          body: |
            Updates ${{ steps.recordr.outputs.file-list }}
            ${{ steps.recordr.outputs.markdown }}
          labels: recordr,docs,rec
          branch: ${{ steps.prep.outputs.recordr-branch }}

All described options can be used to customize the conversion. Please consult action.yml for detailed information.

Recordr GitHub Action

Image Configuration

This 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.
You 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 configuration on each container start.

APP_USER Name of the main user (default: recordr)
APP_GROUP Name of the main user's group (default: recordr)
DEBUG Whether to log debug information (default: 0)
TZ Timezone the container runs in (default: UTC)
LANG Language/locale to use (default: C.UTF-8)
PUID User ID of the libguestfs user (default: 1000)
PGID Group ID of the libguestfs group (default: 1000)

# Build single image with build argument TZ
docker buildx bake --build-arg TZ="$(date +"%Z")"

# Build multi-platform image with build argument TZ
docker buildx bake image-all --build-arg TZ="$(date +"%Z")"

# Start container with environment variable TZ
docker run --rm \
  -e TZ="$(date +"%Z")" \
  -v "$(pwd):$(pwd)" \
  -w "$(pwd)" \
  recordr:local

Authoring ● rec files

Before you can convert ● rec files to SVG you need to create them.
The following code snippet should suffice as a starting point:

#!/usr/bin/env recordr
rec echo "Hello World!"

hello-world.rec

Hello World! Example

To convert your file just execute it with recordr on your PATH:

PATH=.:$PATH ./hello-world.rec
# or
./recordr hello-world.rec

The environment variable TESTING will reduce animations to a minimum.
Set it to 1 for an even better efficiency.

Recordr recording the Hello World! Example

#!/usr/bin/env recordr
rec echo "Hello World!"

Testing

git clone https://github.com/bkahlert/recordr.git
cd recordr

# Use Bats wrapper to run tests
curl -LfsS https://git.io/batsw \
  | DOCKER_BAKE="--set '*.tags=test'" "$SHELL" -s -- --batsw:-e --batsw:BUILD_TAG=test test

Bats Wrapper is a self-contained wrapper to run tests based on the Bash testing framework Bats.

💡 To accelerate testing, the Bats Wrapper checks if any test is prefixed with a capital X and if so, only runs those tests.

Troubleshooting

You might experience problems when converting very long or complex terminal sessions.
Try increasing the corresponding NODE_OPTIONS as you can see below.
To avoid permission problems with generated files, you can use your local user/group ID (see PUID/PGID).
If you need access to Docker, its command line interface is already installed.
You can control your host instance by mounting /var/run/docker.sock.

docker run -it --rm \
  -e PUID="$(id -u)" \
  -e PGID="$(id -g)" \
  -e NODE_OPTIONS="--max-old-space-size=16384" \
  -e TERM="$TERM" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  bkahlert/recordr:edge

Authoring rec files benefits from short round-trips

Contributing

Want 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 a Paypal donation to ensure this journey continues indefinitely!

Thanks again for your support, it is much appreciated! 🙏

License

MIT. See LICENSE for more details.

TODO

add support for dim and italic

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
.github		.github
.run		.run
docs		docs
rec		rec
rootfs/usr/local		rootfs/usr/local
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
docker-bake.hcl		docker-bake.hcl
logr.sh		logr.sh
recordr		recordr
recordrw		recordrw

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

bkahlert/recordr

About

Bash script

Docker image

Build locally

Image

Usage

Bash script

Docker image

Wrapper

curl

wget

wget2

GitHub Action

Usage Example

Image Configuration

Authoring ● rec files

Testing

Troubleshooting

Contributing

License

TODO

About

Releases 4

Sponsor this project

Packages

Contributors 2

Languages

License

bkahlert/recordr

Folders and files

Latest commit

History

Repository files navigation

bkahlert/recordr

About

Bash script

Docker image

Build locally

Image

Usage

Bash script

Docker image

Wrapper

curl

wget

wget2

GitHub Action

Usage Example

Image Configuration

Authoring ● rec files

Testing

Troubleshooting

Contributing

License

TODO

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 4

Sponsor this project

Packages 0

Contributors 2

Languages

Packages