LIBTTYREC(3)

🌸 NAME 🌸

libttyrec — a whole entire library for handling ttyrec files 💖 no cap

---

✨ SYNOPSIS ✨

#include <ttyrec.h>

Link with -ltty. that's it. that's the whole vibe check 🫶

---

🎀 DESCRIPTION 🎀

okay so bestie, this is the libttyrec(3) page from the termrec manual, and it's lowkey a whole tour of everything you can do with ttyrec files. grab a snack, we're going section by section 🍓

🦋 Helper stream function 🦋

• int open_stream(int fd, const char* url, int mode, const char **error); — this one opens a stream for the url you hand it. and here's the cute part: if that url ends in .gz, .xz, .bz2 or .zst, the stream is assumed to be compressed and gets passed through the appropriate [un]packer. iconic. now, if fd is not -1, that's the descriptor you already opened; if it is -1, the file gets opened for you. and the mode can be:
  • SM_READ
  • SM_WRITE
  • SM_REPREAD
  • SM_APPEND

on error, -1 comes back. if you want the actual message, pass a non-null pointer as error and it'll be filled in for you 💅

🔥 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 you gave it — like, abc.ttyrec.gz returns "ttyrec". if no known extension turns up, it just returns whatever you gave as fallback. and if you wanna force a format yourself? go off — but then it's only validated, and if it's invalid, 0 is returned regardless of the other two arguments. periodt.
• recorder ttyrec_w_open(int fd, const char *format, const char *filename, const struct timeval *ts); — a recorder gets opened, writing to the file fd. if fd isn't given (=-1), the function calls open_stream(). recording happens in the given format, and if you didn't provide one, it's guessed from the filename. if you pass a timestamp ts, that becomes the 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 gets written to recorder r, with timestamp tm. returns 1 if some sort of write error happened. (so 1 = bad news bestie 😭)
• int ttyrec_w_close(recorder r); — all pending data is flushed, the recorder is closed and its memory is freed. returns 1 if there's some kind of failure.
• const char* ttyrec_w_get_format_name(int i); — use this to enumerate known write formats by calling it with i being subsequent numbers starting at 0. an invalid i returns a null pointer.
• const char* ttyrec_w_get_format_ext(const char *format); — if the given write format is associated with a file extension, that extension is returned.

🧚 Format decoders 🧚

• const char* ttyrec_r_find_format(const char *format, const char *filename, const char *fallback); — literally 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 one 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. and the actual frame data goes through synch_print. heads up tho: in some formats, two or more consecutive delays, or two consecutive frames, can happen one after another. if you provide an arbitrary arg, it gets passed to all the 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. also — the vt is consumed. gone. absorbed. main character behavior fr.
• ttyrec ttyrec_load(int fd, const char *format, const char *filename, tty vt); — this loads a ttyrec from the file designated with fd. if it's not open yet (fd=-1), it gets 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. bye babe 🫶

you can read the ttyrec's data while it's being read — and yes, all functions are thread-safe with regard to reading. slay. 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 — and if not, the whole thing is. no cuts, full director's cut 💅

🌈 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.

---

🌟 SEE ALSO 🌟

• libtty(3)

---

and that's the whole page bestie, you ate that 🎀 this was libttyrec(3) from the termrec manual, version 0.19, dated 2024-04-01 — go forth and handle those ttyrec files like the icon you are 💖✨👑