Helper stream function:

int open_stream(int fd, const char* url, int mode, const char **error);

This function opens a stream designated by the url. If the given url ends in ".gz", ".xz", ".bz2" or ".zst"), the stream is assumed to be compressed and gets passed through the appropriate [un]packer. If the fd is not -1, it is the descriptor you already opened; if it is -1, the file is opened. The mode can be:

Format encoders:

const char* ttyrec_w_find_format(const char *format, const char *filename, const char *fallback);

This function searches for a format that would fit the filename provided -- that is, abc.ttyrec.gz returns "ttyrec". If no known extension is found, the function returns whatever you gave as fallback. You can force a format yourself, in this case, it is only validated and if invalid, 0 is returned regardless of the other two arguments.

recorder ttyrec_w_open(int fd, const char *format, const char *filename, const struct timeval *ts);

A recorder is opened, writing to the file fd; if it's not given (=-1), the function calls open_stream(). Recording is done in the given format, if not provided, the format is guessed based on the filename. If you provide a timestamp ts, it becomes date of the recording.

int ttyrec_w_write(recorder r, const struct timeval *tm, const char *data, int len);

A chunk of data of length len is written to recorder r, with timestamp tm. Returns 1 if some sort of write error happened.

int ttyrec_w_close(recorder r);

All pending data is flushed, recorder closed and its memory freed. Returns 1 if there's some kind of failure.

const char* ttyrec_w_get_format_name(int i);

You can use this function to enumerate known write formats by calling it with i being subsequent numbers starting at 0. An invalid i will return a null pointer.

const char* ttyrec_w_get_format_ext(const char *format);

If the given write format is associated with a file extension, it is returned.

Format decoders:

const char* ttyrec_r_find_format(const char *format, const char *filename, const char *fallback);

See the _w_ function, except that read formats are searched instead.

const char* ttyrec_r_get_format_name(int i);

ditto

const char* ttyrec_r_get_format_ext(const char *format);

ditto

int ttyrec_r_play(int fd, const char *format, const char *filename, void (*synch_init_wait)(const struct timeval *ts, void *arg), void (*synch_wait)(const struct timeval *delay, void *arg), void (*synch_print)(const char *data, int len, void *arg), void *arg);

This function decodes the file fd (opening filename if fd=-1). If its contents contain the date of the recording, you'll receive it through the callback synch_init_wait. Between frames, the delay is passed through synch_wait. The actual frame data goes through synch_print. Note that in some formats, two or more consecutive delays or two consecutive frames can happen one after another. If you provide an arbitrary arg, it will be passed to all callbacks.

The function doesn't return until the end of input data. Returns 1 on success, 0 on failure.

The following functions deal with in-memory ttyrecs:

ttyrec ttyrec_init(tty vt);

An empty one is allocated. If a vt is provided, it becomes the screen that the ttyrec is internally played on; otherwise, a blank 80x25 one is allocated. The vt is consumed.

ttyrec ttyrec_load(int fd, const char *format, const char *filename, tty vt);

This function will load a ttyrec from the file designated with fd. If it's not open yet (fd=-1), it will be opened with open_stream. The ttyrec is played on the vt you provide -- or on a new 80x25 one.

void ttyrec_free(ttyrec tr);

Destroys the in-memory ttyrec, freeing its memory.

You can read the ttyrec's data while it's being read; all functions are thread-safe with regard to reading. The frames are stored in structures like this:

typedef struct {
struct timeval t;
int len;
char *data; } *ttyrec_frame;

ttyrec_frame ttyrec_seek(ttyrec tr, const struct timeval *t, tty *vt);

Finds the frame that should be shown at time *t, or the first frame if t is null. If vt is not-null, it will receive a terminal containing the screen at that frame.

ttyrec_frame ttyrec_next_frame(ttyrec tr, ttyrec_frame tfv);

Returns the next frame after frame tfv, or null if tfv was the last.

void ttyrec_add_frame(ttyrec tr, const struct timeval *delay, const char *data, int len);

Creates a new frame and appends it to ttyrec tr.

int ttyrec_save(ttyrec tr, int fd, const char *format, const char *filename, const struct timeval *selstart, const struct timeval *selend);

Exports the ttyrec to a new file. If selstart and/or selend are given, they designate the part that should be exported -- if not, the whole is.

struct timeval arithmetics:

A handful of macros for operating on timeval values:

tadd(t, d)

t+=d;

tsub(t, d)

t-=d;

tmul1000(t, m)

t*=m/1000;

tdiv1000(t, m)

t/=m/1000;

tcmp(t1, t2)

If t1<t2, -1. If t1>t2, +1. 0 otherwise.