### Install agg with Cargo

Source: https://github.com/asciinema/agg/blob/main/README.md

Installs the agg binary to your Cargo bin directory. Ensure this directory is in your system's PATH.

```bash
cargo install --git https://github.com/asciinema/agg
```

--------------------------------

### Frame Selection Examples for Asciinema

Source: https://github.com/asciinema/agg/blob/main/_autodocs/00-START-HERE.md

Demonstrates various ways to select specific frames for conversion, including time ranges, percentages, discrete positions, and markers.

```text
"5..30"              # 5 to 30 seconds
"..50%"              # Start to halfway
"1,10,20"            # Discrete positions
"marker:build..marker:test"  # Between markers
"markers"            # All marked moments
```

--------------------------------

### Marker Selection Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Select all markers in the recording using a single keyword. This is equivalent to resolving all marker positions but is more concise. Fails if the recording contains no markers.

```shell
markers         # All marker positions
```

--------------------------------

### V2 Asciicast File Format Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

An example of a V2 Asciicast file, using tab-separated values for events.

```text
{"version":2,"width":80,"height":24,"idle_time_limit":5}
0.123	o	$ echo hello
1.234	o	hello
1.456	o	$ 
5.5	m	done
10.0	i	ls
```

--------------------------------

### V3 Asciicast File Format Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

An example of a V3 Asciicast file, which includes a header and a list of events with timestamps and output data.

```json
{"version":3,"width":80,"height":24,"idle_time_limit":5}
[0.123,"o","$ echo hello\r\n"]
[1.234,"o","hello\r\n"]
[1.456,"o","$ "]
[5.5,"m","done"]
[10.0,"x"]
```

--------------------------------

### Custom Theme Format Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

Illustrates the format for custom themes, which is a comma-separated string of hex color triplets for background, foreground, and ANSI colors.

```text
"282a36,f8f8f2,21222c,ff5555,50fa7b,f1fa8c,bd93f9,ff79c6,8be9fd,f8f8f2,6272a4,ff6e6e,69ff94,ffffa5,d6acff,ff92df,a4ffff,ffffff"
```

--------------------------------

### V1 Asciicast File Format Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

An example of a V1 Asciicast file, which contains a header and a 'stdout' array with timestamped output.

```json
{
  "version": 1,
  "width": 80,
  "height": 24,
  "title": "Demo",
  "duration": 10.0,
  "stdout": [
    [0.123, "$ echo hello\r\n"],
    [1.234, "hello\r\n"],
    [1.456, "$ "],
    [10.0, "exit\r\n"]
  ]
}
```

--------------------------------

### TimelinePosition Parsing Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/types.md

Illustrates parsing different string representations for TimelinePosition. Includes absolute time (seconds, units, clock notation), percentages, and marker/event references.

```rust
"12.5"
```

```rust
"12.5s"
```

```rust
"1m20s"
```

```rust
"1:20"
```

```rust
"1h2m3s"
```

```rust
"50%"
```

```rust
"100%"
```

```rust
"marker:0"
```

```rust
"marker:2"
```

```rust
"marker:build"
```

```rust
"marker:BUI"
```

```rust
"event:100"
```

```rust
"event:0"
```

--------------------------------

### Color Rendering Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/rendering.md

Illustrates the process of rendering a cell with ANSI green in the Dracula theme, from asciicast data to final GIF pixel bytes.

```text
1. Cell in asciicast: { char: 'A', foreground: Indexed(2), ... }
2. Theme lookup: dracula.palette[2] = RGB8(0x50, 0xfa, 0x7b)
3. Rendering: Rasterize 'A' in RGB(80, 250, 123)
4. GIF: Pixel bytes contain (80, 250, 123, 255)
```

--------------------------------

### Asciicast V2 Event Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

Subsequent lines in an Asciicast V2 file represent events, tab-separated with time, type, and data. Examples show output, marker, input, and resize events.

```text
5.123 o output text
10.5  m marker label
15.0  i input text
20.0  r 25x80
```

--------------------------------

### ANSI Escape Codes Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

Demonstrates raw terminal escape sequences for text coloring and styling.

```text
\x1b[38;5;196mRED TEXT\x1b[0m
\x1b[1;32mBOLD GREEN\x1b(B\x1b[m
```

--------------------------------

### Time Range Selection Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Select output events within a specified time range. Supports various time formats including seconds, percentages, markers, and event indices. The default behavior generates frames at a fixed FPS, keeping the latest state per window.

```shell
5..30           # 5 seconds to 30 seconds
0..10s          # 0 to 10 seconds
1m..2m          # 1 minute to 2 minutes
10%..90%        # 10% to 90% of duration
..50%           # Start to halfway
marker:build..marker:test   # From "build" marker to "test" marker
event:10..event:50          # From event 10 to event 50
5..marker:done  # 5 seconds to "done" marker (mixed types)
```

--------------------------------

### Build agg Docker Image

Source: https://github.com/asciinema/agg/blob/main/README.md

Builds a Docker container image for agg. This method does not require a local Rust toolchain installation.

```bash
docker build -t agg .
```

--------------------------------

### Asciicast V3 Theme Object Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

An optional theme object can be embedded in the v3 header to specify background, foreground, and color palette.

```json
{
  "background": "#282a36",
  "foreground": "#f8f8f2",
  "palette": "#21222c:#ff5555:#50fa7b:..."
}
```

--------------------------------

### Discrete Position Selection Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Select specific frames by timestamp using various position formats. Positions are resolved to timestamps, sorted, and deduplicated. This is useful for creating slide-show-like GIFs.

```shell
1,5,10          # Frames at 1s, 5s, 10s
0,50%,100%      # Start, middle, end
marker:0,marker:1,marker:2  # All first three markers
event:0,event:50,event:100  # Every 50th event
1,50%,marker:build,event:100  # Mixed position types
```

--------------------------------

### SelectionSpec Parsing Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/types.md

Demonstrates parsing various string formats into SelectionSpec enum variants. Handles time ranges, comma-separated positions, and marker selections.

```rust
"5..30"
```

```rust
"..100%"
```

```rust
"1,50%,marker:build"
```

```rust
"markers"
```

--------------------------------

### Asciicast V3 Event Examples

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

Subsequent lines in a v3 asciicast file represent events. These include output, markers, resize, custom, and exit events, each with a timestamp.

```json
[seconds, "o", "output data"]
```

```json
[seconds, "m", "marker label"]
```

```json
[seconds, "r", "rows"]
```

```json
[seconds, "c", "value"]
```

```json
[seconds, "x"]
```

--------------------------------

### Asciicast V3 Header Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

The first line of a v3 asciicast file contains metadata. This includes version, terminal dimensions, and optional fields like timestamp, title, and theme.

```json
{"version": 3, "width": 80, "height": 24, "timestamp": 1234567890, "title": "...", "idle_time_limit": 5, "theme": {...}}
```

--------------------------------

### Main Entry Point

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

The `run` function is the main entry point for generating a GIF from asciicast input. It takes an input reader, an output writer, and a `Config` struct to customize the GIF generation process.

```APIDOC
## run

### Description
Generates a GIF from asciicast input with the provided configuration.

### Signature
`pub fn run<I: BufRead, O: Write + Send>(input: I, output: O, config: Config) -> Result<()>`

### Parameters
* `input`: A type implementing `BufRead` for reading asciicast data.
* `output`: A type implementing `Write + Send` for writing the generated GIF.
* `config`: A `Config` struct containing settings for GIF generation.
```

--------------------------------

### run

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

The main entry point for GIF generation. Orchestrates the complete pipeline: opening the asciicast, applying idle time limiting and speed adjustments, resolving frame selections, generating terminal snapshots, initializing fonts and renderer, and finally encoding frames into a GIF.

```APIDOC
## Function: run

### Description
The main entry point for GIF generation. Orchestrates the complete pipeline: opening the asciicast, applying idle time limiting and speed adjustments, resolving frame selections, generating terminal snapshots, initializing fonts and renderer, and finally encoding frames into a GIF.

### Signature
```rust
pub fn run<I: BufRead, O: Write + Send>(input: I, output: O, config: Config) -> Result<()>
```

### Parameters
#### Arguments
- **input** (`I: BufRead`) - Required - A buffered reader providing asciicast data
- **output** (`O: Write + Send`) - Required - A writable output stream for GIF data
- **config** (`Config`) - Required - Configuration struct controlling rendering behavior

### Return type
`Result<()>` - Returns `Ok(())` on successful GIF generation, or an error detailing what failed.

### Throws/Rejects
- **Invalid terminal size**: Recording header has `term_cols` or `term_rows` equal to 0
- **No output events**: Recording contains no `Output` events (selection resolution fails)
- **Font initialization**: No font families match the configured options
- **Timeline errors**: Event processing, timeline transformation, or frame generation fails
- **GIF encoding**: gifski encoder initialization or frame writing fails

### Example Usage
```rust
use std::fs::File;
use std::io::BufReader;
use agg::{Config, run};

let input = BufReader::new(File::open("demo.cast")?);
let output = File::create("output.gif")?;
let config = Config::default();
run(input, output, config)?;
```
```

--------------------------------

### Initialize Fonts and Handle Errors

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Initializes fonts with provided directories and options. Returns an error if no font families match the specified options.

```rust
fonts::init(&config.font_dirs, font_options)
    .ok_or_else(|| anyhow!("no faces matching font family options"))?;
```

--------------------------------

### Custom Configuration with Theme and Renderer

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Create a custom configuration with specific font size, font family, theme, renderer, FPS cap, speed, loop behavior, and idle time limit. This allows fine-grained control over the aggregation process.

```rust
use agg::{Config, Theme, Renderer, SelectionSpec};

let config = Config {
    font_size: 18,
    font_family: Some("Fira Code".to_string()),
    theme: Some(Theme::SolarizedDark),
    renderer: Renderer::Resvg,
    fps_cap: 60,
    speed: 1.5,
    no_loop: true,
    idle_time_limit: Some(2.0),
    ..Default::default()
};

agg::run(input, output, config)?
```

--------------------------------

### Additional Font Directory

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Specifies an additional directory from which to load fonts. This allows users to include custom font installations.

```rust
let config = Config {
    font_dirs: vec!["~/.local/share/fonts".to_string()],
    ..Default::default()
};
```

--------------------------------

### Frame Selection by Time Range

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

Select frames within a specific time range, from the start second to the end second.

```text
"5..30"
```

--------------------------------

### Run agg with Podman (Rootless)

Source: https://github.com/asciinema/agg/blob/main/README.md

Executes agg using a Podman container in root-less mode. Mounts the current directory as a volume for data access.

```bash
podman run --rm -v $PWD:/data agg demo.cast demo.gif
```

--------------------------------

### Main Entry Point Function

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

The main entry point for generating a GIF from asciicast input. It takes a readable input, a writable output, and a configuration object.

```rust
pub fn run<I: BufRead, O: Write + Send>(input: I, output: O, config: Config) -> Result<()>
```

--------------------------------

### Data Flow Visualization

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

Illustrates the step-by-step process from an Asciicast File to a GIF File, including transformations and selections.

```text
Asciicast File
  ↓ (asciicast::open)
Events + Header
  ↓ (timeline transformation)
Adjusted Events
  ↓ (selection::resolve)
Frame Selection Plan
  ↓ (frames generation)
Terminal Snapshots
  ↓ (font resolution + rendering)
RGBA Pixels
  ↓ (gifski encoding)
GIF File
```

--------------------------------

### Build agg from Source

Source: https://github.com/asciinema/agg/blob/main/README.md

Clones the agg repository and builds a release executable. The binary will be located in target/release/agg.

```bash
git clone https://github.com/asciinema/agg
cd agg
cargo build --release
```

--------------------------------

### Record Demo with Markers

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Record a terminal session and mark important moments using Ctrl+A Ctrl+M. These markers can then be used to generate GIFs showing only the marked sections or specific ranges.

```bash
# Record with markers
ascinema rec demo.cast

# While recording, mark important moments with Ctrl+A Ctrl+M
# (records marker events in the asciicast file)

# Generate GIF showing only marked moments
agg --select markers demo.cast demo.gif

# Or show a range with markers as boundaries
agg --select 'marker:start..marker:end' demo.cast demo.gif
```

--------------------------------

### Default Configuration

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Use the default configuration settings for the aggregation tool. This is the simplest way to run the tool.

```rust
let config = Config::default();
agg::run(input, output, config)?;
```

--------------------------------

### Asciicast V2 Header Example

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

The first line of an Asciicast V2 file is a JSON object containing metadata about the recording. This includes version, terminal dimensions, timestamp, and title.

```json
{"version": 2, "width": 80, "height": 24, "timestamp": 1234567890, "title": "...", "idle_time_limit": 5}
```

--------------------------------

### Initialize Font Database

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Initializes the font database by loading custom directories, system fonts, platform-specific emoji fonts, and built-in fonts.

```rust
pub fn init(font_dirs: &[String], options: Options<'_>) -> Option<Fonts>
```

--------------------------------

### Cap FPS

Source: https://github.com/asciinema/agg/blob/main/_autodocs/modules.md

Limits the frame rate by retaining only the latest terminal state within each time window defined by the FPS cap. Timestamps are set to the start of their respective windows.

```rust
cap_fps(frames, fps_cap) -> Iterator<Frame>
```

--------------------------------

### Run GIF Generation

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

The main entry point for GIF generation. Use this function to orchestrate the complete pipeline from asciicast input to GIF output. Ensure necessary imports and provide valid input, output, and configuration.

```rust
use std::fs::File;
use std::io::BufReader;
use agg::{Config, run};

let input = BufReader::new(File::open("demo.cast")?);
let output = File::create("output.gif")?;
let config = Config::default();
run(input, output, config)?;
```

--------------------------------

### Run agg with Input, Output, and Config

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

This is the primary function to call for rendering asciicast files. Ensure you have a valid Config struct, input, and output paths.

```rust
agg::run(input, output, config)
```

--------------------------------

### Environment Variable Expansion in Font Paths

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Demonstrates how to use environment variables within font directory paths. The `shellexpand` crate is used to expand variables like `$HOME` and `~`.

```rust
config.font_dirs = vec!["$HOME/.fonts".to_string()];
// or
config.font_dirs = vec!["~/.fonts".to_string()]; // ~ is expanded to home directory
```

--------------------------------

### Load Custom Font Directories

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Configures custom font directories to be loaded before system fonts. Supports path expansion for user directories like '~/.fonts' and environment variables like '$HOME/my-fonts'.

```rust
config.font_dirs = vec!["~/.fonts".to_string(), "$HOME/my-fonts".to_string()];
// Both paths are expanded and fonts are loaded
```

--------------------------------

### Custom Configuration for Asciinema Aggregator

Source: https://github.com/asciinema/agg/blob/main/_autodocs/00-START-HERE.md

Configure advanced rendering options like font size, theme, renderer, and frame selection. This allows for fine-grained control over the output GIF.

```rust
use agg::{Config, Theme, Renderer, SelectionSpec};

let config = Config {
    font_size: 18,
    theme: Some(Theme::SolarizedDark),
    renderer: Renderer::Resvg,
    selection: "5..30".parse::<SelectionSpec>()?,
    ..Default::default()
};

run(input, output, config)?;
```

--------------------------------

### Run agg with Docker

Source: https://github.com/asciinema/agg/blob/main/README.md

Executes agg using a Docker container, converting a demo cast file to a GIF. Mounts the current directory as a volume for data access.

```bash
docker run --rm -u $(id -u):$(id -g) -v $PWD:/data agg demo.cast demo.gif
```

--------------------------------

### Rendering Flow in `run()` Function

Source: https://github.com/asciinema/agg/blob/main/_autodocs/rendering.md

This function parses asciicast data, applies transformations, resolves frame selection, generates frames, initializes fonts and themes, creates a renderer, and encodes the frames into a GIF. Rendering is done on-the-fly without frame buffering.

```rust
pub fn run<I, O>(input, output, config) -> Result<()> {
    // 1. Parse asciicast
    let Asciicast { header, events } = asciicast::open(input)?;
    
    // 2. Apply timeline transformations
    let events = timeline::limit_idle_time(events, itl);
    let events = timeline::accelerate(events, config.speed);
    let events = events.collect::<Result<Vec<_>>>()?;
    
    // 3. Resolve frame selection
    let plan = selection::resolve(&config.selection, &summary)?;
    
    // 4. Generate frames (terminal snapshots)
    let frames: Vec<Frame> = match plan {
        SelectionPlan::Range { start, end } => {
            let frames = frames::from_range(&events, terminal_size, start, end);
            let frames = output::dedupe_visual_changes(frames);
            let frames = output::adjust_timeline_timestamps(frames);
            output::cap_fps(frames, config.fps_cap).collect()
        },
        SelectionPlan::Positions(positions) => {
            let frames = frames::at_positions(&events, terminal_size, positions);
            output::adjust_discrete_timestamps(frames, config.last_frame_duration).collect()
        }
    };
    
    // 5. Initialize fonts
    let fonts = fonts::init(&config.font_dirs, font_options)?;
    
    // 6. Resolve theme
    let theme_opt = config.theme.or_else(|| header.term_theme.map(Theme::Embedded))
        .unwrap_or(Theme::Dracula);
    let theme = theme_opt.try_into()?;
    
    // 7. Create renderer settings and renderer
    let settings = renderer::Settings { ... };
    let mut renderer: Box<dyn renderer::Renderer> = match config.renderer {
        Renderer::Swash => Box::new(renderer::swash(settings)),
        Renderer::Resvg => Box::new(renderer::resvg(settings)),
    };
    
    // 8. Create GIF encoder
    let (collector, writer) = gifski::new(gifski_settings)?;
    
    // 9. Render frames and encode GIF
    for (i, frame) in frames.into_iter().enumerate() {
        let image = renderer.render(&frame.snapshot);
        collector.add_frame_rgba(i, image, frame.time + config.last_frame_duration)?;
    }
    
    drop(collector);
    writer.write(output, &mut progress)?;
}
```

--------------------------------

### Advanced Configuration for Asciinema Aggregator

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

Demonstrates extensive configuration options for text rendering, colors, speed, and frame selection. This snippet requires understanding of the Config struct fields and their possible values.

```rust
use agg::{Config, Theme, Renderer, SelectionSpec};

let config = Config {
    // Text rendering
    font_size: 20,
    line_height: 1.3,
    text_font_family: "Fira Code".to_string(),
    emoji_font_family: "Noto Emoji".to_string(),
    font_dirs: vec!["~/.fonts".to_string()],
    
    // Colors
    theme: Some(Theme::Custom(
        "282a36,f8f8f2,21222c,ff5555,50fa7b,f1fa8c,bd93f9,ff79c6,8be9fd,f8f8f2,6272a4,ff6e6e,69ff94,ffffa5,d6acff,ff92df,a4ffff,ffffff".to_string()
    )),
    bold_is_bright: true,
    
    // Rendering
    renderer: Renderer::Resvg,
    fps_cap: 60,
    
    // Timing
    speed: 1.5,
    idle_time_limit: Some(2.0),
    
    // Frame selection
    selection: "5..30".parse::<SelectionSpec>()?,
    
    ..Default::default()
};
```

--------------------------------

### Frame Selection by Percentage and Marker

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Configure the tool to select frames based on a percentage of the total duration and a specific marker. This allows for precise selection of frames at key points.

```rust
use agg::{Config, SelectionSpec};

// Select discrete positions
let config = Config {
    selection: "1,50%,marker:build".parse::<SelectionSpec>()?,
    ..Default::default()
};
```

--------------------------------

### Open and Read Asciicast File in Rust

Source: https://github.com/asciinema/agg/blob/main/_autodocs/asciicast-format.md

Demonstrates how to open a local asciicast file using `File::open` and `BufReader`, then parse its header and events using `asciicast::open`. Supports reading from any `BufRead` stream.

```rust
use std::fs::File;
use std::io::BufReader;
use agg::asciicast;

let file = File::open("demo.cast")?;
let reader = BufReader::new(file);
let Asciicast { header, events } = asciicast::open(reader)?;

println!("Size: {}x{}", header.term_cols, header.term_rows);
for event in events {
    let event = event?;
    // Process event
}
```

--------------------------------

### Config Struct

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

This struct defines the configuration options for rendering GIFs from asciinema recordings. It covers visual aspects like fonts and dimensions, timing controls such as speed and FPS, and output format settings like looping and frame duration.

```APIDOC
## Config Struct

### Description
Configuration struct controlling all aspects of GIF rendering: visual properties (fonts, colors, dimensions), timing (speed, FPS, idle time), output format (looping, frame duration), and frame selection.

### Fields

- **`bold_is_bright`** (`bool`) - Optional - Render bold text using ANSI 8–15 bright colors instead of standard 0–7 colors with bold attribute. Default: `false`.
- **`cols`** (`Option<usize>`) - Optional - Override terminal width; if `None`, uses the recording's width.
- **`emoji_font_family`** (`String`) - Optional - Comma-separated fallback font families for emoji glyphs. Default: `"Apple Color Emoji,Segoe UI Emoji,Noto Color Emoji,JoyPixels,Twemoji,Noto Emoji"`.
- **`font_size`** (`usize`) - Optional - Font size in pixels. Default: `16`.
- **`font_dirs`** (`Vec<String>`) - Optional - Paths to additional font directories to load (supports shell expansion via `~`). Default: empty.
- **`font_family`** (`Option<String>`) - Optional - Complete comma-separated font family list, bypassing automatic fallbacks; must start with a monospace font. Mutually exclusive with `text_font_family` and `emoji_font_family`.
- **`font_aa_levels`** (`u16`) - Optional - Font antialiasing quantization levels (2–256, affects swash renderer only). Default: `6`.
- **`font_hinting`** (`bool`) - Optional - Enable font hinting for improved rendering (swash renderer only). Default: `true`.
- **`fps_cap`** (`u8`) - Optional - Maximum frames per second in the output GIF. Default: `30`.
- **`idle_time_limit`** (`Option<f64>`) - Optional - Maximum seconds of idle time per gap; if `None`, uses the recording's limit or the global default of 5.0.
- **`last_frame_duration`** (`f64`) - Optional - Display duration of the final frame in seconds. Default: `3.0`.
- **`line_height`** (`f64`) - Optional - Multiplier for line spacing (relative to font size). Default: `1.4`.
- **`no_loop`** (`bool`) - Optional - If `true`, the GIF plays once and stops; if `false`, it loops infinitely. Default: `false`.
- **`renderer`** (`Renderer`) - Optional - Backend renderer: either `Swash` or `Resvg`. Default: `Renderer::Swash`.
- **`rows`** (`Option<usize>`) - Optional - Override terminal height; if `None`, uses the recording's height.
- **`selection`** (`SelectionSpec`) - Optional - Frame selection specification: a time range, discrete positions, or all markers. Default: `SelectionSpec::Range { start: None, end: None }`.
- **`speed`** (`f64`) - Optional - Playback speed multiplier (>1 = faster, <1 = slower). Default: `1.0`.
- **`text_font_family`** (`String`) - Optional - Comma-separated fallback font families for text; will be extended with symbol and emoji fallbacks. Default: `"JetBrains Mono,Fira Code,SF Mono,Menlo,Consolas,DejaVu Sans Mono,Liberation Mono"`.
- **`theme`** (`Option<Theme>`) - Optional - Color theme; if `None`, uses the recording's embedded theme or defaults to Dracula.
- **`show_progress_bar`** (`bool`) - Optional - Display a progress bar during GIF encoding. Default: `true`.

### Default Implementation

```rust
impl Default for Config {
    fn default() -> Self {
        Self {
            bold_is_bright: DEFAULT_BOLD_IS_BRIGHT,
            cols: None,
            emoji_font_family: String::from(DEFAULT_EMOJI_FONT_FAMILY),
            font_dirs: vec![],
            font_family: None,
            font_aa_levels: DEFAULT_FONT_AA_LEVELS,
            font_size: DEFAULT_FONT_SIZE,
            fps_cap: DEFAULT_FPS_CAP,
            font_hinting: DEFAULT_FONT_HINTING,
            idle_time_limit: None,
            last_frame_duration: DEFAULT_LAST_FRAME_DURATION,
            line_height: DEFAULT_LINE_HEIGHT,
            no_loop: DEFAULT_NO_LOOP,
            renderer: Default::default(),
            rows: None,
            selection: SelectionSpec::default(),
            speed: DEFAULT_SPEED,
            text_font_family: String::from(DEFAULT_TEXT_FONT_FAMILY),
            theme: Default::default(),
            show_progress_bar: true,
        }
    }
}
```
```

--------------------------------

### Default Configuration

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Creates a configuration object with all default font settings. This typically includes a default text font like JetBrains Mono and system emoji support.

```rust
let config = Config::default();
// Uses all defaults: JetBrains Mono + system emoji
```

--------------------------------

### Configuration Struct

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

The `Config` struct allows detailed customization of the GIF generation process, including font properties, rendering options, and playback speed.

```APIDOC
## Config Struct

### Description
Configuration options for GIF generation.

### Fields
* `bold_is_bright` (bool): Whether bold text should be rendered as bright.
* `cols` (Option<usize>): The number of columns for the terminal output.
* `emoji_font_family` (String): The font family to use for emojis.
* `font_size` (usize): The font size in pixels.
* `font_dirs` (Vec<String>): A list of directories to search for fonts.
* `font_family` (Option<String>): The primary font family to use.
* `font_aa_levels` (u16): Font anti-aliasing levels.
* `font_hinting` (bool): Whether to enable font hinting.
* `fps_cap` (u8): The maximum frames per second for the GIF.
* `idle_time_limit` (Option<f64>): The limit for idle time before stopping.
* `last_frame_duration` (f64): The duration to display the last frame.
* `line_height` (f64): The multiplier for line height.
* `no_loop` (bool): Whether to disable GIF looping.
* `renderer` (Renderer): The rendering engine to use.
* `rows` (Option<usize>): The number of rows for the terminal output.
* `selection` (SelectionSpec): Specifies which parts of the recording to include.
* `speed` (f64): The playback speed multiplier.
* `text_font_family` (String): The font family to use for text.
* `theme` (Option<Theme>): The color theme to apply.
* `show_progress_bar` (bool): Whether to display a progress bar.
```

--------------------------------

### Config Struct Definition

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

Defines the configuration options for rendering Asciinema recordings into GIFs. It covers visual aspects like fonts and colors, timing controls, and output format settings.

```rust
pub struct Config {
    pub bold_is_bright: bool,
    pub cols: Option<usize>,
    pub emoji_font_family: String,
    pub font_size: usize,
    pub font_dirs: Vec<String>,
    pub font_family: Option<String>,
    pub font_aa_levels: u16,
    pub font_hinting: bool,
    pub fps_cap: u8,
    pub idle_time_limit: Option<f64>,
    pub last_frame_duration: f64,
    pub line_height: f64,
    pub no_loop: bool,
    pub renderer: Renderer,
    pub rows: Option<usize>,
    pub selection: SelectionSpec,
    pub speed: f64,
    pub text_font_family: String,
    pub theme: Option<Theme>,
    pub show_progress_bar: bool,
}
```

--------------------------------

### Speed Up Demo with Idle Time Limit

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Accelerate a slow-motion demo recording by increasing playback speed and limiting idle time to a specified duration. This can also be used to select a specific time range from the recording.

```bash
# Play at 2x speed, limiting idle gaps to 2 seconds
agg --speed 2 --idle-time-limit 2 slow.cast fast.gif

# Select only the interesting part
agg --speed 2 --select '5..30' slow.cast fast.gif
```

--------------------------------

### Basic Usage of Asciinema Aggregator

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

Converts a .cast file to a .gif file using default settings. Ensure the input file 'demo.cast' exists and the output file 'demo.gif' can be created.

```rust
use std::fs::File;
use std::io::BufReader;
use agg::{Config, Theme, run};

fn main() -> anyhow::Result<()> {
    let input = BufReader::new(File::open("demo.cast")?);
    let output = File::create("demo.gif")?;
    
    let config = Config {
        font_size: 18,
        theme: Some(Theme::SolarizedDark),
        ..Default::default()
    };
    
    run(input, output, config)?;
    Ok(())
}
```

--------------------------------

### Minimal Usage of Asciinema Aggregator

Source: https://github.com/asciinema/agg/blob/main/_autodocs/00-START-HERE.md

Use this snippet for basic conversion of a .cast file to a GIF. Ensure the input and output files are correctly specified and the 'agg' crate is included.

```rust
use std::fs::File;
use std::io::BufReader;
use agg::{Config, run};

let input = BufReader::new(File::open("demo.cast")?);
let output = File::create("demo.gif")?;
run(input, output, Config::default())?;
```

--------------------------------

### Enums

Source: https://github.com/asciinema/agg/blob/main/_autodocs/README.md

Enumerations for selecting rendering engines, color themes, and selection specifications.

```APIDOC
## Enums

### Renderer
Specifies the rendering engine.
* `Swash`: Default renderer.
* `Resvg`: Alternative renderer.

### Theme
Defines the color theme for the output.
* `Asciinema`
* `Dracula`: Default theme.
* `GithubDark`, `GithubLight`
* `Kanagawa`, `KanagawaDragon`, `KanagawaLight`
* `Monokai`, `Nord`
* `SolarizedDark`, `SolarizedLight`
* `GruvboxDark`
* `Custom(String)`: Use a custom theme defined by a string.
* `Embedded(theme::Theme)`: Use an embedded theme.

### SelectionSpec
Determines which parts of the asciicast to render.
* `Range { start: Option<TimelinePosition>, end: Option<TimelinePosition> }`: Render a range of time or events.
* `Positions(Vec<TimelinePosition>)`: Render specific timeline positions.
* `Markers`: Render all sections marked by markers.

### TimelinePosition
Represents a specific point in the timeline.
* `Time(f64)`: Position by time in seconds.
* `Percent(f64)`: Position by percentage of total duration.
* `MarkerIndex(usize)`: Position by the index of a marker.
* `MarkerPrefix(String)`: Position by the prefix of a marker name.
* `EventIndex(usize)`: Position by the index of an event.
```

--------------------------------

### Create Swash Renderer

Source: https://github.com/asciinema/agg/blob/main/_autodocs/rendering.md

Constructs a SwashRenderer for fast glyph rasterization with font hinting and antialiasing. Suitable for performance-critical applications.

```rust
pub fn swash(settings: Settings) -> swash::SwashRenderer {
    swash::SwashRenderer::new(settings)
}
```

--------------------------------

### Public API Reference

Source: https://github.com/asciinema/agg/blob/main/_autodocs/MANIFEST.txt

This section details the public API of the agg converter, including the `run()` function, `Config` struct, `Theme` enum, and `Renderer` enum. It is intended for library integrators.

```APIDOC
## Public API

This document outlines the public API available for the agg asciicast-to-GIF converter.

### Functions

#### `run()`

**Description:** Executes the asciicast-to-GIF conversion process.

**Parameters:**
- `config` (Config): The configuration object for the conversion.

**Returns:**
- `Result<(), Error>`: Ok if successful, or an error if the conversion fails.

### Structs

#### `Config`

**Description:** Represents the configuration for the rendering process. It contains 20 fields that control various aspects of the conversion.

**Fields:**
(Details for each of the 20 fields, including type, default value, constraints, and description, are available in the `configuration.md` document.)

### Enums

#### `Theme`

**Description:** Defines the available color themes for the output. Supports 12 built-in themes and custom theme definitions.

**Variants:**
(Details for each theme variant are available in the `configuration.md` document.)

#### `Renderer`

**Description:** Specifies the rendering backend to use. Options include `Swash` for fast rasterization and `Resvg` for full SVG feature support.

**Variants:**
- **Swash**: Fast glyph rasterization.
- **Resvg**: Full SVG rendering capabilities.
```

--------------------------------

### Config Struct Default Implementation

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Provides the default configuration for GIF generation when using the `Config` struct. This is automatically used by the `run()` function if no custom configuration is provided.

```rust
impl Default for Config {
    fn default() -> Self {
        Self {
            bold_is_bright: DEFAULT_BOLD_IS_BRIGHT,
            cols: None,
            emoji_font_family: String::from(DEFAULT_EMOJI_FONT_FAMILY),
            font_dirs: vec![],
            font_family: None,
            font_aa_levels: DEFAULT_FONT_AA_LEVELS,
            font_size: DEFAULT_FONT_SIZE,
            fps_cap: DEFAULT_FPS_CAP,
            font_hinting: DEFAULT_FONT_HINTING,
            idle_time_limit: None,
            last_frame_duration: DEFAULT_LAST_FRAME_DURATION,
            line_height: DEFAULT_LINE_HEIGHT,
            no_loop: DEFAULT_NO_LOOP,
            renderer: Default::default(),
            rows: None,
            selection: SelectionSpec::default(),
            speed: DEFAULT_SPEED,
            text_font_family: String::from(DEFAULT_TEXT_FONT_FAMILY),
            theme: Default::default(),
            show_progress_bar: true,
        }
    }
}
```

--------------------------------

### Custom Theme Configuration

Source: https://github.com/asciinema/agg/blob/main/_autodocs/configuration.md

Specifies a custom theme using a comma-separated string of hex color triplets. The format includes background, foreground, and ANSI colors.

```rust
Theme::Custom("282a36,f8f8f2,21222c,ff5555,50fa7b,f1fa8c,bd93f9,ff79c6,8be9fd,f8f8f2,6272a4,ff6e6e,69ff94,ffffa5,d6acff,ff92df,a4ffff,ffffff".to_string())
```

--------------------------------

### Constants

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

Configuration constants for the asciinema aggregator.

```APIDOC
## Constants

| Constant | Type | Value | Description |
|---|---|---|---|
| `DEFAULT_BOLD_IS_BRIGHT` | `bool` | `false` | Default for bold-as-bright mode |
| `DEFAULT_FONT_HINTING` | `bool` | `true` | Default for font hinting |
| `DEFAULT_TEXT_FONT_FAMILY` | `&str` | "JetBrains Mono,Fira Code,SF Mono,Menlo,Consolas,DejaVu Sans Mono,Liberation Mono" | Default text font fallback list |
| `DEFAULT_EMOJI_FONT_FAMILY` | `&str` | "Apple Color Emoji,Segoe UI Emoji,Noto Color Emoji,JoyPixels,Twemoji,Noto Emoji" | Default emoji font fallback list |
| `FULL_FONT_AA_LEVELS` | `u16` | 256 | Maximum antialiasing quantization level |
| `DEFAULT_FONT_AA_LEVELS` | `u16` | 6 | Default antialiasing quantization level |
| `DEFAULT_FONT_SIZE` | `usize` | 16 | Default font size in pixels |
| `DEFAULT_FPS_CAP` | `u8` | 30 | Default FPS cap |
| `DEFAULT_LAST_FRAME_DURATION` | `f64` | 3.0 | Default final frame duration in seconds |
| `DEFAULT_LINE_HEIGHT` | `f64` | 1.4 | Default line height multiplier |
| `DEFAULT_NO_LOOP` | `bool` | `false` | Default looping behavior (false = loop) |
| `DEFAULT_SPEED` | `f64` | 1.0 | Default playback speed |
| `DEFAULT_IDLE_TIME_LIMIT` | `f64` | 5.0 | Default idle time cap in seconds |
```

--------------------------------

### Select Font Families (Direct)

Source: https://github.com/asciinema/agg/blob/main/_autodocs/font-handling.md

Uses a single, explicitly provided font family. This option replaces all other font family configurations.

```rust
fn select_font_families(font_db, options) -> Option<Vec<String>>
```

--------------------------------

### Enum: Theme

Source: https://github.com/asciinema/agg/blob/main/_autodocs/api-reference.md

Predefined and custom color themes for terminal output. Custom themes accept a comma-separated string of 6-digit hex colors.

```APIDOC
## Enum: `Theme`

### Description
Predefined and custom color themes for terminal output. Custom themes accept a comma-separated string of 6-digit hex colors: first is background, second is foreground, followed by 8 or 16 ANSI colors.

### Variants
- `Asciinema`: Asciinema's default theme
- `Dracula`: Dracula dark theme (default)
- `GithubDark`: GitHub dark theme
- `GithubLight`: GitHub light theme
- `Kanagawa`: Kanagawa theme
- `KanagawaDragon`: Kanagawa Dragon variant
- `KanagawaLight`: Kanagawa light variant
- `Monokai`: Monokai theme
- `Nord`: Nord theme
- `SolarizedDark`: Solarized dark theme
- `SolarizedLight`: Solarized light theme
- `GruvboxDark`: Gruvbox dark theme
- `Custom(String)`: Custom theme as a comma-separated hex color string (10 or 18 triplets: "bg,fg,color0,...,color15")
- `Embedded(theme::Theme)`: Internal theme parsed from recording metadata

### Default
`Theme::Dracula`

### Custom Theme Format
`"282a36,f8f8f2,21222c,ff5555,50fa7b,f1fa8c,bd93f9,ff79c6,8be9fd,f8f8f2,6272a4,ff6e6e,69ff94,ffffa5,d6acff,ff92df,a4ffff,ffffff"`
```

--------------------------------

### Renderer Settings Structure

Source: https://github.com/asciinema/agg/blob/main/_autodocs/rendering.md

Defines the configuration options for the renderer, including terminal size, font settings, and color themes. These fields are mapped from configuration sources.

```rust
pub struct Settings {
    pub terminal_size: (usize, usize),      // cols × rows
    pub font_db: fontdb::Database,           // Available fonts
    pub font_families: Vec<String>,          // Font fallback list
    pub text_family: String,                 // Primary text font
    pub font_aa_levels: u16,                 // AA quantization (swash only)
    pub font_size: usize,                    // Pixels
    pub line_height: f64,                    // Multiplier
    pub theme: Theme,                        // Color palette
    pub bold_is_bright: bool,                // ANSI 0–7 → 8–15 for bold
    pub hinting: bool,                       // Font hinting (swash only)
}
```

--------------------------------

### Highlight Specific Timestamps

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Generate GIFs that highlight specific moments in a recording by selecting exact timestamps or percentages of the total duration. This is useful for showcasing key points or performance metrics.

```bash
# Show frames at exact moments (in seconds)
agg --select '2,5,10,15,20' demo.cast moments.gif

# Mix percentages and seconds
agg --select '10%,25%,50%,75%,90%' demo.cast percentiles.gif
```

--------------------------------

### Extract Multi-Scene Recordings

Source: https://github.com/asciinema/agg/blob/main/_autodocs/selection.md

Extract individual scenes from a multi-scene recording by using markers to define scene boundaries. This allows for the creation of separate GIFs for each scene or a collection of slides.

```bash
# Record multiple scenes, mark each with markers
# "scene-1-start", "scene-2-start", "scene-3-start"

# Extract just scene 1
agg --select 'marker:scene-1..marker:scene-2' demo.cast scene1.gif

# Or extract all three as separate slides
agg --select 'marker:scene-1-start,marker:scene-2-start,marker:scene-3-start' demo.cast slides.gif
```