@b0xs/binary

BoxsBinary format encoder/decoder for efficient terminal session recordings.

Features

• Compact binary format - 30-50% smaller than text-based formats
• Chunk-based storage - Split recordings into 60-second chunks for streaming and seeking
• Compression - Zstandard compression for optimal size
• Fast seeking - Jump to any point in the recording instantly
• Type-safe - Full TypeScript support with detailed types

Installation

npm install @b0xs/binary

Usage

Encoding a Session

import { BoxsBinaryEncoder, FrameType, EventType } from '@b0xs/binary';

// Create encoder
const encoder = new BoxsBinaryEncoder({
  sessionId: 'session-uuid',
  userId: 'user-id',
  terminalSize: { cols: 80, rows: 24 },
  compression: true,
  chunkDuration: 60000 // 60 seconds
});

// Write terminal output
encoder.writeFrame({
  type: FrameType.OUTPUT,
  data: Buffer.from('$ ls -la\n')
});

// Write events
encoder.writeEvent({
  type: EventType.COMMAND,
  data: {
    type: 'command_executed',
    command: 'ls -la',
    lineNumber: 1
  }
});

// Flush chunk (returns compressed binary data)
const chunk = await encoder.flushChunk();

// Get all chunks when done
const allChunks = encoder.getAllChunks();

Decoding a Session

import { BoxsBinaryDecoder } from '@b0xs/binary';

// Create decoder
const decoder = new BoxsBinaryDecoder();

// Load chunks
await decoder.loadChunk(chunkData);

// Parse header
const header = decoder.getHeader();
console.log(header.sessionId, header.totalDuration);

// Get frames and events
const frames = decoder.getFrames(0); // chunk index 0
const events = decoder.getEvents(0);

// Seek to timestamp
const frameAtTime = decoder.seekToTimestamp(5000); // 5 seconds

Format Specification

The BoxsBinary format consists of:

• File Header (256 bytes) - Session metadata, terminal size, duration
• Chunks (variable) - 60-second segments with frames and events
• Footer - Seek index for random access

Frame Types

• OUTPUT - Terminal output (stdout/stderr)
• INPUT - User input
• RESIZE - Terminal resize events
• CURSOR - Cursor position changes
• CLEAR - Screen clear
• STYLE - Style/color changes

Event Types

• COMMAND - Command execution
• PHASE - Session phase changes
• ERROR - Errors and warnings
• SCREENSHOT - Terminal screenshots
• ANNOTATION - User annotations
• FEEDBACK - Feedback markers

API Reference

BoxsBinaryEncoder

class BoxsBinaryEncoder {
  constructor(options: EncoderOptions)

  writeFrame(frame: BoxsBinaryFrame): void
  writeEvent(event: BoxsBinaryEvent): void
  flushChunk(): Promise<Buffer>
  getAllChunks(): BoxsBinaryChunk[]
  generateHeader(): Buffer
  generateFooter(): Buffer
}

BoxsBinaryDecoder

class BoxsBinaryDecoder {
  loadChunk(chunkData: Buffer): Promise<void>
  getHeader(): BoxsBinaryHeader
  getFrames(chunkIndex: number): BoxsBinaryFrame[]
  getEvents(chunkIndex: number): BoxsBinaryEvent[]
  seekToTimestamp(timestamp: number): { chunk: number; frame: BoxsBinaryFrame }
}

License

MIT

Related Packages

• @b0xs/recorder - CLI tool for recording sessions
• @b0xs/termbox - React component for playing sessions

Links

• GitHub
• Documentation
• Website