dhobsd/castty

A CLI tool to record audio-enabled screencasts of your terminal, for the web.

CasTTY

CasTTY is a program similar to ttyrec and asciinema that makes it easy to create audio-enabled, terminal-based screencasts for publication on webpages. It was originally a fork of ttyrec, but has since effectively been rewritten from scratch.

There may be bugs. Feel free to contribute patches or file an issue!

You probably want to see what you get after you use this.

Compatibility

I've tested CasTTY on macOS Sierra and Linux. It should work on other systems, but if not, please feel free to send a patch. It probably can't record if you don't have a microphone, unless you have some weird audio mixing setup.

Building

Dependencies

It depends on libsoundio. Ubuntu 16.04 seems to ship a broken version of libsoundio that depends on a version of JACK that doesn't work. This is fixed in the libsoundio repo, but you will have to build it yourself.

CasTTY also depends on LAME (and in particular, libmp3lame) for on-the-fly MP3 encoding. It is possible to compile without LAME (and therefore without mp3 support) by modifying config.mk to contain WITH_LAME = no.

There are no UI build dependencies because I find that idea a little silly.

Make

To build, simply run make once dependencies have been installed. If they were installed to a location other than /usr/local/, you will have to edit the Makefile.

Usage

usage: castty record [-acdelrt] [out.json]
 -a <outfile>   Output audio to <outfile>. Must be specified with -d.
 -c <cols>      Use <cols> columns in the recorded shell session.
 -D <outfile>   Send debugging information into <outfile>
 -d <device>    Use audio device <device> for input.
 -e <cmd>       Execute <cmd> from the recorded shell session.
 -l             List available audio input devices and exit.
 -m             Encode audio to mp3 before writing.
 -r <rows>      Use <rows> rows in the recorded shell session.
 -R             Use a raw sound device.
 -t <title>     Title of the cast.

 [out.json]     Optional output filename of recorded events. If not specified,
                a file "events.json" will be created.

To list usable input devices for recording, just run castty record -l. Output will look something like this:

Available input devices:
   0: Built-in Microphone 44100Hz
      castty -d 'AppleHDAEngineInput:1B,0,1,0:1' -a audio.raw

The -d 'AppleHDAEngineInput:1B,0,1,0:1' argument can be pasted directly to CasTTY to choose that device for recording. The audio format and sample rate CasTTY will use is also provided.

CasTTY supports MP3 output by default, but other encodings may be desirable. Without the -m flag, CasTTY outputs interleaved PCM audio. (CasTTY upgrades mono audio to stereo.)

Utilities like sox may be used to convert the audio into more useful formats for web publication.

% sox -D -r 44100 -e signed -b 16 -c 2 -L audio.raw audio.wav

By default, CasTTY does not record audio and sends its terminal event output to a file called events.js.

Runtime Commands

CasTTY contains a runtime command interface. Commands are entered with the sequence ^a (C-a, Control-a), followed by the command character. Currently supported commands are:

• ^a: Send a literal ^a to the recorded session.
• a: Send a literal ^a to the recorded session.
• m: Mute or unmute the recording. Recording will continue, but without any audio until unmuted.
• p: Pause or unpause the recording. Neither terminal nor audio will be recorded during the paused period. When unpausing, CasTTY requests the screen to be redrawn. This may cause your terminal buffer to clear.

Miscellaneous

CasTTY does support window resizing. However, because the size of the player is automatically calculated based on the size of the original window, the recorded window size can only ever be as large or smaller than the original window size.

CasTTY supports UTF-8 input.

CasTTY outputs in asciicast v1 format. Its output files should be compatible with the asciinema player (though that player does not support audio).

Web Interface

The ui directory of the repository is a self-contained implementation of a CasTTY player. Utilities used include:

• jQuery
• rangeslider.js
• xterm.js

Licenses for all these utilities can be found in their respective repositories and in the LICENSE file in this repository.

To create a cast, simply modify ui/index.html to point to the correct audio file and events.js output from castty.

castty's Issues

Control-panel TUI

It would be nice to have some kind of TUI for castty to allow various levels of recording control and configuration at runtime. This would probably be using e.g. http://www.leonerd.org.uk/code/libtickit/ and http://www.leonerd.org.uk/code/libvterm/.

Support window resizing

I don't really see this as a bug, resizing window probably ends up looking confusing during playback. But it should probably be handled in a nice way.

Add ability to append to an existing recording

When the C portion was forked, ttyrec had an "append" mode, but this was broken when it was made to output JS. Adding an append mode might be useful, and shouldn't be too hard.

87e0d2c introduces errors during compiling

After a quick bisect, I have found that 87e0d2c has introduced some compilation errors. Namely:

castty.c: In function ‘setup_sighandlers’:
castty.c:218:15: error: incompatible types when assigning to type ‘__sigset_t {aka struct <anonymous>}’ from type ‘int’
  chld.sa_mask = 0;
               ^
castty.c:224:16: error: incompatible types when assigning to type ‘__sigset_t {aka struct <anonymous>}’ from type ‘int’
  crash.sa_mask = 0;
                ^
castty.c:237:16: error: incompatible types when assigning to type ‘__sigset_t {aka struct <anonymous>}’ from type ‘int’
  winch.sa_mask = 0;
                ^

Building on:

• linux x86_64
• gcc (GCC) 6.3.1 20170109
• glibc 2.24

I haven't looked into it yet but I'm adding this issue just to track progress.

Support asciicast v2 format

There's still work ongoing for this at asciinema/asciinema#196, but this will need to be done.

Improve player UI look and feel

Improve the look and feel of the player, especially on mobile devices (phones, tablets). Accessible themes for xterm.js would be nice, too (especially ones to support non-xterm color schemes).

Runtime audio encoding

It would be nice to have some runtime encoding of audio -- especially for larger recordings. This would also be basically required before we could make castty support live casts. I'd prefer to use some library for this, and preferably one that can support output for all browsers.

This would also allow us to specify multiple output formats to get multiple files for wider browser support.

Improve seek performance in long recordings

When seeking backwards, we have to replay the whole cast from the beginning because of the terminal codes. This isn't so bad for recordings that are just a couple minutes long, but I imagine there's noticeable seek latency on longer recordings.

Probably this would involve the player creating keyframes as it goes such that it has a place to restore from.

Add "terminal-recording" topic to this repo

As an educator, I'd like to be able to advertise the concept of creating animations from the terminal. Thus, I like to link to https://github.com/topics/terminal-recording instead of collecting several tool links.

How about castty joins the small club and also adds the topic terminal-recording to this repo?

Live casting

Add an ability to do a live-cast to castty and its player. Castty would also record the broadcast.

Pausing audio is broken

Need to bisect to figure out what caused this. (It was working after the conversion to libsoundio). Also in general, we should be turning off recording entirely when this happens. That would make it easier to implement, too.

Unicode is currently unsupported.

Right now unicode does not appear to survive the recording and playback, it would be nice to have this working to allow for internationalization among other things.

Add ability to mute microphone during recording

And an ability to mute microphone during recording. PortAudio doesn't provide this functionality. Instead, we can probably write zeroes for each frame instead of what we would have recorded.

Audio inputs with duplicated names

When multiple audio devices have the same name, it is impossible to select anything but the first of them.

A proof of concept for a solution would be
this patch, which will also allow you to specify an index with -d - although it would also make sense to have a separate option for that, to prevent confusion if a device has an integer as its name.

Compress JS output by recording delta between each event

This makes the JS output smaller, but will also require a change in the player.

Recording on Mac Catalina no sound & stop rec?

I managed to compile with make command on Macbook pro Catalina latest

I had to change from lame_encode_buffer_ieee_float to lame_encode_buffer_float in writter-lame.c as it was not compiling.

I use the command:
./castty record -d 'BuiltInMicrophoneDevice' -a audio2.mp3 -m

But how I can stop the recording? I can only stopping it by force close from Activity Monitor.

And I can not hear anything in the recorded file..

Devices:
cotfas@192-168-0-146 src % ./castty record -l
Available input devices:
0: Boom2Device, 48000Hz, format: 'float 32-bit LE'
castty record -d 'Boom2Engine:0' -a audio.raw
1: MacBook Pro Microphone, 44100Hz, format: 'float 32-bit LE'
castty record -d 'BuiltInMicrophoneDevice' -a audio.raw
cotfas@192-168-0-146 src %

Tried with both devices..

Seeking seems to break in long videos

After a certain point, seeking seems to break in long videos. Need to debug and fix -- I suspect this is due to something like how duration is calculated vs how the seek is updated.

Reset terminal based on termcap entry

Restoring the terminal with just tcsetattr and TIOCSWINWZ seems to still leave the terminal in a weird state. Instead, I think we really need to read the termcap entry for the terminal we're using and restore based on that.

Stacktrace on exiting castty (pulseaudio related)

When exiting castty with audio recording enabled I get a stacktrace following a pulseaudio assertion failure:

pa_write() failed while trying to wake up the mainloop: Broken pipe
                                                                   pa_write() failed while trying to wake up the mainloop: Broken pipe
                                     pa_write() failed while trying to wake up the mainloop: Broken pipe
       pa_write() failed while trying to wake up the mainloop: Broken pipe
                                                                          Assertion 'pa_close(fds[0]) == 0' failed at pulsecore/core-util.c:2625, function pa_close_pipe(). Aborting.

Process -303538095 got signal 6
	at faultaddr: 0x55c9ede86051 errno: 21961 code: 1662301864
Backtrace:

./src/castty(+0x2c80) [0x55c9ec40cc80]
/usr/lib/libpthread.so.0(+0x11080) [0x7fef63750080]
/usr/lib/libc.so.6(gsignal+0xcf) [0x7fef6315d04f]
/usr/lib/libc.so.6(abort+0x16a) [0x7fef6315e47a]
/usr/lib/pulseaudio/libpulsecommon-10.0.so(pa_close_pipe+0x85) [0x7fef61a7b645]
/usr/lib/libpulse.so.0(pa_mainloop_free+0x42) [0x7fef62cb6602]
/usr/lib/libpulse.so.0(pa_threaded_mainloop_free+0x3d) [0x7fef62cc61bd]
/usr/lib/libsoundio.so.1(+0xd359) [0x7fef63969359]
/usr/lib/libsoundio.so.1(soundio_disconnect+0x30) [0x7fef63963950]
/usr/lib/libsoundio.so.1(soundio_destroy+0x1c) [0x7fef63963b0c]
./src/castty(+0x4ff5) [0x55c9ec40eff5]
./src/castty(+0x5fe9) [0x55c9ec40ffe9]
./src/castty(main+0x520) [0x55c9ec40dcb7]
/usr/lib/libc.so.6(__libc_start_main+0xf1) [0x7fef6314a291]
./src/castty(+0x2b2a) [0x55c9ec40cb2a]

./src/castty(+0x4ff5) is ./src/audio.c:472

If I pause the recording mid-way, and then exit, there is no backtrace (log is clear too).

This is on archlinux x86_64 with:

• libsoundio 1.1.0
• libpulse 10.0
• glibc 2.24
• gcc (GCC) 6.3.1 20170109

Pause recording in castty

Add the ability to pause a recording. This would immediately stop reading new audio and terminal events, and would continue adding new events with no delay from the pause point.

Add volume controls for various PortAudio Host APIs

I really only use OS X for this, so that'll probably get done first. It would be nice to have actual volume and input controls for different host APIs. (Also, it'd probably be nice to ask folks how they want to record when we pick the audio device.)

Initially this could be a thing that works while paused, if adding a runtime TUI is too difficult.

Tag the source

It would be very helpful if you could tag the source and create a release. This would enable distributions to work with releases and allow then to easier keep track of changes.

Thanks

Themes for xterm.js

Different terminals have different settings, and it can be odd for someone using a 16-color terminal to have their colors misinterpreted by something assuming xterm colors. Mostly this would just be styling colors to match various terminals. Then castty could detect what kind of terminal it was running in (using $TERM) and feed that info to the player, which could auto-choose the theme.

Themes related to accessibility would also be nice.

Improve v2 header output

In #35, support for v2 rewinds the output file to insert some duration information at the end. This works, but is potentially fragile. Rework this to write a header to a new file and merge in the output at exit.

What is ui/js/min.js?

Re: #4, etc., can it be confirmed that min.js contains all of:

• jQuery
• rangeslider.js
• xterm.js

(from the README) in the minimize form? What versions of the components were used? How that file can be (re)produced?