ascii-chat API Documentation

Introduction

ascii-chat is a real-time terminal-based video chat application that converts video streams to ASCII art for display in terminals. It supports multiple clients, audio streaming, and end-to-end encryption.

This documentation provides comprehensive API reference and architectural guidance for developers working with ascii-chat. Whether you're integrating ascii-chat into your application, extending its functionality, or contributing to the project, this documentation will help you understand the codebase structure and implementation details.

Note

Getting Started? We recommend starting with the Build System topic to understand how to compile ascii-chat on Windows, Linux, and macOS, configure the build system, and set up your development environment.

Warning

Important: When exploring this documentation, navigate to Topics in the sidebar. Many topic pages have "README" in their title and provide comprehensive subsystem overviews. These are excellent entry points for understanding major subsystems. You can also start with Topic Categories for an organized index. See the Exploring the Documentation section below for detailed navigation guidance.

Exploring the Documentation

Understanding the Sidebar

The left sidebar is your primary navigation tool. It contains the following main sections:

• ascii-chat API Documentation - The main landing page (you are here)
• Topics - Comprehensive architectural documentation (the most important section for understanding the system)
• Topic Categories - Index page that lists all topics organized by category (start here to browse topics!)
• Data Structures - All struct and typedef definitions organized by functionality
• Files - Browse source files organized by directory structure
• Examples - Code examples and usage patterns
• Search - Use the search bar at the top of the page to find anything quickly

Finding Topics in the Sidebar

Topics are directly accessible in the sidebar. To access them:

1. Look for Topics in the left sidebar (or click here)
2. Click to expand the topics tree.
3. Each topic has a tree to expand with files, functions, enums and structs, custom documentation pages, etc.

Alternatively, you can start with Topic Categories in the sidebar, which provides an organized index of all topics grouped by category. This is an excellent starting point!

The Topics page includes comprehensive architectural guides with names like:

• Build System README - Comprehensive build documentation
• Cryptography - Crypto architecture and usage
• Handshake Module README - Protocol and authentication details
• Keys Module README - SSH/GPG key management
• And many more detailed guides...

Warning

Important: These links go to the full topic page that has all the topic's functions and enums and structs etc documentation listed first, before the documentation that you wanted when you clicked the link... either scroll down to where the custom documentation starts, or expand the topic in the sidebar to see a direct link to the page you desire (in the sidebar tree, it will be down past the topic's files and structs).

Note

Pro Tip: Many topic pages have "README" in their title and/or descriptive names with capitalized titles (Pages Titled Like This). These are comprehensive overview documents that explain entire subsystems in detail.

Pro Tip: Many topic pages have the same name as their topic. For instance the Packet Queue topic has a page called "Packet Queue" that explains the code in more detail than the header file documentation does. Look for these pages.

How to Navigate the Sidebar

Looking for architectural documentation?

• Click Topics in the sidebar to see all topic pages
• Or start with Topic Categories for an organized index of all topics
• Look for topic pages with "README" in the title for comprehensive subsystem overviews

Looking for a specific function or struct?

• Use the search bar at the top of the page (fastest method)
• Or check Data Structures to find type definitions
• Or browse Files to see all functions in a particular source file

Looking for implementation details? Check the sidebar!

• Check Files to browse source files by directory
• Review Data Structures to understand type definitions
• Read Topics for architectural context, then drill into specific files
• Check Examples for code samples and usage patterns

Topics: Comprehensive Architectural Documentation

Topics are detailed guides that explain subsystems comprehensively. They combine:

• Architectural overviews and design rationale
• API documentation with usage examples
• Integration patterns and best practices
• Performance considerations and optimization notes

Access topics directly via Topics in the sidebar, or start with Topic Categories in the sidebar for an organized index of all topics grouped by category.

Key topics to explore:

Getting Started:

• Build System: CMake configuration, cross-platform compilation, build types, platform-specific gotchas, static builds, and build optimizations (start here if new to the project!)
• Platform Abstraction Layer README: Complete cross-platform abstraction guide covering threads, mutexes, sockets, terminal I/O, crash handling, and OS portability (essential for understanding Windows/Linux/macOS support!)
• Testing Framework: Test infrastructure, test runner, Docker testing, coverage

Core Infrastructure:

• Common Definitions: Core utilities, macros, memory debugging, constants
• Error Handling System: Typed error codes, error context, thread-safe errors
• Logging System: Level-based logging, rate limiting, file output
• Options and Configuration: Command-line parsing and TOML config

Cryptography:

• Cryptography: Encryption architecture and security details
• Handshake Protocol: Secure connection establishment with X25519
• Keys Module: SSH/GPG key parsing and validation

Data Structures:

• Owned Buffers: Bounded aligned storage with explicit ownership
• Ring Buffer: Lock-free circular buffers for audio/video
• Packet Queue: Thread-safe per-client packet queues
• uthash library: High-performance client ID lookup - https://troydhanson.github.io/uthash/

Media Processing:

• Video to ASCII Conversion: Video frame conversion with SIMD optimization
• Grid Layout System: Multi-frame layout for multi-user video
• Audio System: Audio capture and playback with PortAudio
• Audio Mixer: Multi-client audio mixing with ducking
• Palette Management: ASCII character palettes with UTF-8 support

Network Layer:

• Network I/O: Socket operations, timeouts, packet protocol
• Audio/Video Networking: Network APIs for audio/video streaming
• Packet Types: Network packet structures and definitions
• Network Compression: zstd compression for payload optimization

Client Application:

• Client Overview: Complete client architecture
• Client Main: Main lifecycle orchestration and reconnection logic
• Connection Management: Server connection and packet transmission
• Protocol Handler: Packet reception and processing
• Media Capture: Webcam video capture and transmission
• Terminal Display: Terminal rendering and TTY management
• Audio Processing: Audio capture, playback, and jitter buffering
• Client Cryptography: Handshake and key management

Server Application:

• Server Overview: Multi-client server with per-client threading
• Server Main: Server initialization and connection management
• Client Management: Per-client lifecycle and threading coordination
• Protocol Handler: Network packet processing
• Stream Generation: Multi-client video mixing and ASCII generation
• Render Threads: Per-client rendering threads with rate limiting
• Statistics and Monitoring: Performance monitoring and resource tracking
• Server Cryptography: Per-client handshake and session encryption

Discovery Service (ACDS):

• ACDS Overview: Session discovery, NAT traversal, and WebRTC signaling
• ACDS Server: TCP connection handling and packet dispatch
• Session Database: SQLite-based session storage
• WebRTC Signaling: SDP/ICE relay for P2P connections

For more details, explore the Topic Categories page, which provides links to all topics organized by category. Key topics include:

• Build System: Complete build documentation, CMake configuration, cross-platform compilation, build types, and optimization
• Platform Abstraction Layer README: Comprehensive guide to cross-platform abstractions, threading, sockets, terminal I/O, and OS portability
• Cryptography: Encryption architecture, cryptographic operations, and security details
• Handshake Module README: How client and server establish secure encrypted sessions using X25519 key exchange
• Keys Module README: SSH/GPG key handling, key validation, and authentication mechanisms
• Audio/Video Networking: Media packet APIs, compression, and streaming protocols
• Network I/O: Packet I/O operations, socket management, and network abstractions

Note

Finding Topics: All topics are accessible via Topics in the sidebar. Many topics have "README" in their title and/or descriptive names with capitalized titles (Pages Titled Like This), indicating they are comprehensive subsystem documentation. You can also start with Topic Categories for an organized index, or use the search bar at the top of the page to find topics.

Development & Debugging:

• Debugging Utilities: Error tracking, memory leak detection, diagnostics
• Lock Debugging: Lock tracking, deadlock detection, contention analysis

Quick Start

New to ascii-chat? Start here:

1. Set up your build environment: Read Build System to learn how to compile ascii-chat on your platform (Windows, Linux, or macOS) and understand the CMake configuration, build types, and platform-specific considerations
2. Read this main page to understand the project overview
3. Visit Topic Categories to browse detailed guides
4. Check out Getting Started section below for code examples
5. Explore Topics for architectural documentation and Files or Data Structures for API reference

Finding Code Elements

Looking for a specific function or structure?

• Use the search bar at the top of the page (Ctrl+F / Cmd+F in browser)
• Browse Data Structures to find related types grouped together
• Check Files to see all functions in a particular source file
• Review Topics for architectural context and usage examples

Understanding the System

Want to understand how things work together?

1. Start with Topics: Navigate to Topics in the sidebar, or visit Topic Categories for an organized index. Topics provide comprehensive architectural documentation that explains how subsystems work together.
2. Look for README pages: Many topics have "README" in their title (e.g., "Build System README", "Cryptography Module README"). These are the most comprehensive guides and are excellent entry points.
3. Follow cross-references: Click on @ref links in documentation (like Build System or Cryptography) to navigate between related concepts.
4. Review "See also" sections: Most documentation blocks include "See also" references at the bottom that link to related topics, modules, or functions.
5. Check Integration sections: Topic pages include "Integration" sections that explain how modules interact with each other in the larger system.

Contributing to the Project

Planning to contribute code?

• Set up your build environment: Read Build System to configure your development environment and understand build types, CMake presets, and testing setup
• Read Topic Pages to understand the architecture before making changes
• Review Best Practices sections for coding standards and patterns
• Check

  Note

  @note tags that look like this and

  Warning

  @warning tags that look like this in documentation for important details

• Follow the existing documentation style when adding new code and format with clang-format

Library Structure

The library is organized into several major modules:

Core Library

• Common Definitions - Error codes, macros, core types
• Options module - Command-line options
• Config module - File-based configuration
• Logging Module - Logging API and utilities

Platform Abstractions

• Platform Abstraction Layer README - Comprehensive guide to cross-platform abstractions for threads, mutexes, sockets, terminal I/O, crash handling, and OS portability (Windows/Linux/macOS)
• Platform Layer - API reference for platform abstractions
• Webcam Capture - Cross-platform webcam capture functionality

Core Libraries

• Owned Buffers - Memory management with pre-allocated buffers
• Ring Buffer - Circular buffer implementation
• Packet Queue - Queue management for network packets

Network Layer

• Network Module - Socket operations, timeouts, connections
• Packet Types - Network packet structures and definitions
• Audio/Video Networking - Network APIs for audio/video streaming

Cryptography

• Cryptography - Core cryptographic operations
• Handshake Protocol - Cryptographic handshake implementation
• Keys Module - SSH key, GPG key, and key validation APIs

Media Processing

• Audio System - Audio capture and playback
• Palette Management - ASCII palette configuration and UTF-8 support
• Video to ASCII - Image conversion and ASCII rendering
• Video Frames - Video frame buffer management

Utilities

• Utilities - String manipulation, path handling, IP parsing, math utilities, UTF-8 support

Getting Started

Note

Before diving into the code, make sure you've read the Build System topic to understand how to compile and configure ascii-chat for your platform.

This section provides a quick overview of how to use the ascii-chat library. For detailed documentation on each component, see the Topic Categories page.

Typical Workflow

The typical workflow for using the ascii-chat library:

1. Initialize the logging system with log_init()
2. Initialize common subsystems with asciichat_common_init()
3. Initialize platform-specific components (audio, video, network)
4. Set up cryptographic context and perform handshake
5. Start audio/video capture and network streaming
6. Handle incoming packets and render to terminal

Modern connection walkthrough

This is the current shape of a native client connection. The important distinction is that the application owns the connection lifecycle while the transport owns delivery. The application never needs to know whether the peer is reached by TCP, WebSocket, WebRTC, QUIC, or WebTransport.

1. Open one connection

Resolve and establish the endpoint through the shared connection layer. The endpoint parser selects the backend from the address and the connection keeps the transport, handshake state, deadlines, and worker together.

network_connection_t *connection = NULL;
connection_endpoint_t endpoint;
network_connect_config_t connect_config = {
    .timeout_ms = 5000,
    .should_exit_callback = should_exit,
    .callback_data = app,
    .tls_ca_file = NULL,
    .quic_visual_datagrams = true,
    .quic_audio_datagrams = true,
};
 
asciichat_error_t result = network_connection_open(
    "client_connection", address, default_port, &connect_config,
    &connection, &endpoint);
if (result != ASCIICHAT_OK) {
    log_error("connection failed: %s", asciichat_error_string(result));
    return result;
}

2. Let the connection perform negotiation

Register callbacks for application state, packets, closing, and final cleanup. The callback contract is transport-neutral: packet payloads are borrowed until the callback returns, and teardown can retain dependencies when a worker has not joined yet.

static const network_connection_callbacks_t callbacks = {
    .open = app_connection_open,
    .packet = app_packet_received,
    .closing = app_connection_closing,
    .closed = app_connection_closed,
};
 
result = network_connection_run(connection, &callbacks, app);

During network_connection_run(), the shared pipeline performs the crypto handshake, validates ACIP framing, applies negotiated compression/security, and dispatches packets to app_packet_received. Application code does not call recv(), decrypt packet buffers by hand, or create a receive thread for each transport.

3. Send media through ACIP

Media producers hand frames and audio batches to type-specific ACIP helpers. Those helpers feed the shared outbound scheduler, which applies bounded admission, control-packet priority, media dropping, encryption sequencing, and negotiated datagram behavior.

acip_transport_t *transport = network_connection_transport(connection);
 
result = acip_send_ascii_frame_contract(
    transport, &frame_workspace, frame, frame_length,
    width, height, NULL, 0, 0);
if (result != ASCIICHAT_OK) {
    log_warn("frame was not accepted: %s", asciichat_error_string(result));
}
 
result = acip_send_audio_opus_batch(
    transport, audio, audio_length, frame_sizes, frame_count,
    sample_rate, frame_duration_ms);

Do not add a mode-owned video queue, audio queue, or transport send thread. The scheduler is the single admission point shared by every backend. It may choose reliable delivery or a negotiated visual/audio datagram according to explicit send options and current transport capabilities.

4. Handle the peer and application state

A packet callback updates application state or forwards the payload to the media pipeline. It must finish using the borrowed payload before returning; retain a copy only when a later worker needs it. Long-running work belongs in an owned queue or worker, not inside the backend event loop.

5. Shut down in ownership order

Request cancellation, stop media producers, and let connection callbacks drain. The closing callback joins application workers without holding a lock those workers need. The closed callback releases application state after transport callbacks have stopped. Finally destroy the connection:

network_connection_request_stop(connection);
result = network_connection_run(connection, &callbacks, app);
network_connection_destroy(&connection);

Servers use the same contracts with network_server_t; an already connected transport can be adopted with network_server_adopt() or network_server_adopt_negotiating(). ACDS supplies session and endpoint metadata, but it does not replace the connection/transport lifecycle.

For the implementation map, read Network and Transport Architecture. For detailed runtime rules, read Network runtime and connection ownership, Event-driven I/O, and Transport backpressure.

Building Documentation

To build this documentation, you'll need Doxygen configured. See Build System for information on configuring the project with CMake, including documentation generation.

To build this documentation:

cmake --build build --target docs

The documentation will be generated in build/docs/html/index.html.

To open the documentation in your browser:

cmake --build build --target docs-open

For more information on the build system, including CMake configuration, build types, and platform-specific considerations, see Build System.

License

See the LICENSE.txt file for license information.

Links

• Project Homepage: https://github.com/zfogg/ascii-chat
• Issues: https://github.com/zfogg/ascii-chat/issues
• Releases: https://github.com/zfogg/ascii-chat/releases