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/recordr@v0.2.2
        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