rich_record/lib.rs
1//! Record scripted terminal sessions: tapes (#599).
2//!
3//! A tape scripts a session: type, press keys, wait for text on the screen,
4//! take screenshots. [`record::record`] runs it in `bash` on a real PTY with a
5//! pinned environment, follows the screen with a VT emulator, and returns the
6//! screenshots and a timeline. [`record::write`] turns them into files:
7//!
8//! - per screenshot, a PNG in a window frame, an SVG with selectable text
9//! (drawn by rich-ext's frame exporter, [`rich_ext::frame::Frame::to_svg`]),
10//! and a text grid (through [`rich_ext::frame::Frame`]);
11//! - an asciinema v2 cast with input events and the theme in its header;
12//! - a GIF with a key overlay, and an MP4 when FFmpeg is installed;
13//! - a self-contained HTML page with a small player and the screenshots.
14//!
15//! The window frame, a caption and the key overlay can each be switched on
16//! or off ([`record::Presentation`]), and a tape's `Output` chooses what is
17//! written.
18//!
19//! [`record::check`] compares a new run's text grids with committed ones, so
20//! documentation media cannot drift from the program it shows.
21//!
22//! ```no_run
23//! use rich_record::{record, tape};
24//! let source = std::fs::read_to_string("demo.tape")?;
25//! let tape = tape::parse(&source)?;
26//! let recording = record::record(&tape, "demo", &record::Options::default())?;
27//! let fonts = rich_record::render::raster::Fonts::embedded();
28//! record::write(&recording, "media/demo".as_ref(), "demo", record::Formats::ALL,
29//! &fonts, &Default::default(), None)?;
30//! # Ok::<(), Box<dyn std::error::Error>>(())
31//! ```
32//!
33//! Linux and macOS are supported. Windows builds through ConPTY but needs
34//! `bash` on `PATH` and is experimental.
35
36pub mod record;
37pub mod render;
38pub mod screen;
39pub mod session;
40pub mod tape;
41pub mod terminal;
42
43pub use record::{Formats, Options, Presentation, Problem, Recording};
44pub use screen::{Snapshot, Theme};
45pub use tape::{Format, Output, Tape, TapeError};