feat: record every sample machine's boot as an animated WebP

Each sample machine now has a VM check, including new ones for
text-console and scripted-initrd. While a check runs, a recorder takes a
frame every half second through a second QEMU monitor socket, and
record-screencasts encodes the frames into recordings/<machine>.webp with
img2webp, dropping the BIOS frames at other resolutions. The guide shows
each machine's recording in the section it illustrates, replacing the PNG
screenshots. The checks are now named vm-<machine>.
This commit is contained in:
Willem Vanhulle committed 2026-10-30 14:59:10 +01:00
1 parent 7e95cbd8e9
commit c5e2e16b67
21 files changed
+402 -106

No files matched your search

+9 -10
View File
@@ -16,8 +16,8 @@ struct RepoTasks {
#[derive(Subcommand)]
enum Task {
#[command(
about = "Record the screencasts with vhs and copy the passphrase and failures screenshots \
into recordings/"
about = "Record the screencasts with vhs and convert the passphrase and failures \
screenshots to WebP in recordings/"
)]
RecordScreencasts(RecordScreencastsOptions),
#[command(
@@ -28,19 +28,18 @@ enum Task {
#[derive(Args)]
struct RecordScreencastsOptions {
#[arg(long, help = "passphrase.png produced by the vm-luks-passphrase check")]
passphrase_png: PathBuf,
#[arg(long, help = "failures.png produced by the vm-failures check")]
failures_png: PathBuf,
#[arg(
long,
help = "Directory with one entry per sample machine, each the output of its vm-<machine> \
check"
)]
vm_check_outputs: PathBuf,
}
fn main() -> ExitCode {
let outcome = match RepoTasks::parse().task {
Task::RecordScreencasts(options) => {
record_screencasts::record_screencasts(&record_screencasts::CheckScreenshots {
passphrase_png: &options.passphrase_png,
failures_png: &options.failures_png,
})
record_screencasts::record_screencasts(&options.vm_check_outputs)
}
Task::SyncDefaultConfig => sync_default_config::sync_default_config(),
};
+93 -19
View File
@@ -1,7 +1,7 @@
use std::{
fs::{self, Permissions},
os::unix::fs::PermissionsExt,
path::Path,
fs::{self, File},
io::Read,
path::{Path, PathBuf},
};
use xshell::{Shell, cmd};
@@ -12,27 +12,100 @@ const TAPES: [&str; 2] = [
"scripted-demos/tapes/scripted-boot.tape",
"scripted-demos/tapes/scripted-shutdown.tape",
];
const RECORDING_FRAME_MILLISECONDS: &str = "500";
pub struct CheckScreenshots<'a> {
pub passphrase_png: &'a Path,
pub failures_png: &'a Path,
fn sorted_entries(directory: &Path) -> Result<Vec<PathBuf>, TaskError> {
let read_failure = |source| TaskError::File {
path: directory.to_path_buf(),
source,
};
let mut entries = fs::read_dir(directory)
.map_err(read_failure)?
.map(|entry| entry.map(|entry| entry.path()))
.collect::<Result<Vec<_>, _>>()
.map_err(read_failure)?;
entries.sort();
Ok(entries)
}
fn copy_screenshot(
screenshot: &Path,
recordings: &Path,
published_name: &str,
) -> Result<(), TaskError> {
let copied_png = recordings.join(published_name);
fs::copy(screenshot, &copied_png)
.and_then(|_| fs::set_permissions(&copied_png, Permissions::from_mode(0o644)))
#[derive(PartialEq, Eq)]
struct FrameSize {
width: u32,
height: u32,
}
fn png_frame_size(frame: &Path) -> Result<FrameSize, TaskError> {
let mut header = [0_u8; 24];
File::open(frame)
.and_then(|mut file| file.read_exact(&mut header))
.map_err(|source| TaskError::File {
path: copied_png,
path: frame.to_path_buf(),
source,
})
})?;
let big_endian = |offset: usize| {
u32::from_be_bytes([
header[offset],
header[offset + 1],
header[offset + 2],
header[offset + 3],
])
};
Ok(FrameSize {
width: big_endian(16),
height: big_endian(20),
})
}
pub fn record_screencasts(screenshots: &CheckScreenshots) -> Result<(), TaskError> {
fn frames_at_final_size(frames: Vec<PathBuf>) -> Result<Vec<PathBuf>, TaskError> {
let Some(final_frame) = frames.last() else {
return Ok(frames);
};
let final_size = png_frame_size(final_frame)?;
let sizes = frames
.iter()
.map(|frame| png_frame_size(frame))
.collect::<Result<Vec<_>, _>>()?;
Ok(frames
.into_iter()
.zip(sizes)
.filter(|(_, size)| *size == final_size)
.map(|(frame, _)| frame)
.collect())
}
fn encode_machine_recording(
shell: &Shell,
check_output: &Path,
recordings: &Path,
) -> Result<(), TaskError> {
let Some(machine_name) = check_output.file_name() else {
return Ok(());
};
let frames = frames_at_final_size(
sorted_entries(&check_output.join("recording"))?
.into_iter()
.filter(|frame| {
frame
.extension()
.is_some_and(|extension| extension == "png")
})
.collect(),
)?;
if frames.is_empty() {
return Err(TaskError::NoRecordingFrames(check_output.to_path_buf()));
}
let animation = recordings.join(machine_name).with_extension("webp");
let frame_duration = RECORDING_FRAME_MILLISECONDS;
cmd!(
shell,
"img2webp -loop 0 -min_size -mixed -d {frame_duration} {frames...} -o {animation}"
)
.quiet()
.run()?;
Ok(())
}
pub fn record_screencasts(vm_check_outputs: &Path) -> Result<(), TaskError> {
let recordings = Path::new("recordings");
if !recordings.is_dir() {
return Err(TaskError::NotInRepositoryRoot);
@@ -42,6 +115,7 @@ pub fn record_screencasts(screenshots: &CheckScreenshots) -> Result<(), TaskErro
let tape_path = Path::new(tape);
cmd!(shell, "vhs {tape_path}").run()
})?;
copy_screenshot(screenshots.passphrase_png, recordings, "passphrase.png")?;
copy_screenshot(screenshots.failures_png, recordings, "failures.png")
sorted_entries(vm_check_outputs)?
.iter()
.try_for_each(|check_output| encode_machine_recording(&shell, check_output, recordings))
}
+2
View File
@@ -8,6 +8,8 @@ pub enum TaskError {
Shell(#[from] xshell::Error),
#[error("{}: {source}", path.display())]
File { path: PathBuf, source: io::Error },
#[error("{} has no recording frames", .0.display())]
NoRecordingFrames(PathBuf),
#[error("no recordings directory here; run from the repository root")]
NotInRepositoryRoot,
#[error("{0} has no ```toml block under its Defaults heading")]