beecast

BeeCast turns an asciinema .cast recording into a single, fully self-contained .html file that plays in any browser — online, offline, from a web server, or straight off a file:// path. Zero network requests, zero external dependencies, zero console errors or warnings. If you Save the page from a browser and open the copy on a plane, it works exactly the same.

beecast build demo.cast            # → demo.html, next to the cast
open demo.html                     # play it — fully offline

What the page gives you

• Playback of asciicast v1, v2, and v3 recordings, via a vendored, inlined asciinema-player (Apache-2.0).

• Title and summary — rendered from the optional metadata sidecar (see below).

• Chapter navigation — one button per chapter, plus markers on the player timeline.

• Speed up / slow down — 0.5× · 1× · 1.5× · 2× · 3×, switchable mid-playback.

• Deep links — share a link to an exact moment, optionally with your own comment:

  demo.html?t=93.5
  demo.html?t=1:33.5&note=Here+is+where+the+build+goes+red
  

  Deep links use URL query parameters, not fragments or server routes, so they keep working when the file is opened locally. The page has a copy link at current time button with an optional comment field; the linked-to comment is shown as a banner and the player is parked (poster frame) at the linked timestamp.

The metadata sidecar

Playback works with the bare .cast alone. To get a title, a summary, and chapters, put a JSON sidecar next to the recording — demo.cast → demo.meta.json — or point at any file with --meta. The shape is defined by the beecast-dto crate (the source of truth); its human rendering is dto/SCHEMA.md and the formal schema is dto/schema/beecast-meta.schema.json:

{
  "title": "Rebuilding the parser",
  "summary": "One sentence on what the recording shows.",
  "chapters": [
    { "t": 0,     "title": "Setup" },
    { "t": 42.5,  "title": "First failing test" },
    { "t": 187.0, "title": "Green build" }
  ]
}

The timekey t is seconds into the recording — fractional values are welcome — and the first chapter must start at t: 0. Chapters are strictly ascending. Unknown JSON fields are rejected loudly, per the house rule that typos must die at parse time.

Sidecars are written by hand or generated by SeeCast, the AI annotator that lives in this repo under seecast/.

CLI

beecast build <recording.cast> [--meta <file.json>] [-o <output.html>]
beecast schema        # print the metadata JSON Schema to stdout
beecast help [topic]  # topics: build, schema, exitcodes
beecast version

• --meta defaults to <recording>.meta.json when that file exists.
• -o - writes the HTML to stdout (data on stdout, diagnostics on stderr — always).
• Human at a TTY gets human-readable output; --json (or a piped/captured stdout) gets a two-space-indented single-key JSON document with a request-specific variant: { "Built": { output, bytes, cast_version, chapters, meta, warnings } }, { "Version": { … } }, and on failure { "Error": { message, stage } } where stage is usage or request. Warnings land on stderr and in the JSON.
• Exit codes: 0 success, 1 failure, 2 usage, 130 interrupted. beecast help exitcodes prints the table; a broken pipe ends the program quietly.
• Color at a TTY by default; --color=never, --color=no, or NO_COLOR turn it off.
• beecast schema is also the codegen script: it prints the schema generated from the beecast-dto Rust types, which a test in that crate pins byte-for-byte to the shipped file.

Not this tool's job

Installing

cargo install beecast                                      # from crates.io
cargo install --git https://github.com/dkorolev/beecast   # from git
cargo install --path cli                                   # from a checkout (workspace root)

License

BeeCast's own code is MIT (text in LICENSE, shipped with the crate). The vendored, inlined asciinema-player is Apache-2.0 (© the asciinema-player authors), redistributed unmodified in the beecast-page crate — and every beecast binary and generated page embeds it, so this crate's SPDX license stays MIT AND Apache-2.0; see ../page/src/vendor/README.md.