Crate ascii_linker 

ascii_linker

A procedural macro crate for embedding ASCII art animation frames from .bapple files directly into your Rust binary at compile time.

Overview

This crate provides two macros for working with .bapple files:

• link_frames! - Embeds decompressed ASCII frames as strings
• embed_full! - Embeds compressed frames with audio data and timing metadata

File Format

The .bapple format is a tar archive where:

• Each entry represents a frame of ASCII art (zstd-compressed)
• A special file named “metadata” contains timing information in RON format
• A special file named “audio” contains audio data
• All other entries are treated as animation frames

Generating .bapple Files

The .bapple files used by this crate are generated using asciic, an ASCII art animation compiler. See the asciic documentation for details on creating .bapple files from video sources.

Examples

Using link_frames!

use ascii_linker::link_frames;

// Embed frames at compile time
const FRAMES: &[&str] = link_frames!("./animations/bad_apple.bapple");

fn main() {
    // Iterate through frames
    for (i, frame) in FRAMES.iter().enumerate() {
        println!("Frame {}: \n{}", i, frame);
    }
}

Using embed_full!

When using embed_full!, you’ll need to add zstd to your dependencies to decompress frames at runtime:

[dependencies]
ascii_linker = "..."
zstd = "0.13"

use ascii_linker::embed_full;

// Embed compressed frames, audio, and timing
const BAPPLE: (&[&[u8]], &[u8], u64) = embed_full!("./animations/bad_apple.bapple");

fn main() {
    let (frames, audio, frametime) = BAPPLE;
     
    println!("Total frames: {}", frames.len());
    println!("Audio size: {} bytes", audio.len());
    println!("Frame time: {}μs", frametime);
     
    // Decompress frames at runtime using zstd
    for compressed_frame in frames {
        let frame = zstd::decode_all(&compressed_frame[..]).unwrap();
        let frame_str = String::from_utf8(frame).unwrap();
        println!("{}", frame_str);
    }
}

Macros

embed_full

Embeds a complete .bapple file (compressed frames, audio, and timing) at compile time.

link_frames

Embeds ASCII art animation frames from a .bapple file into your binary at compile time.