Session Management Module

Real-time audio-video session abstraction layer. More...

Files
file	splash.c
	Intro and status screen display implementation with animated rainbow effects.
file	update_banner.c
	Update available prompt screen implementation.
file	fps_counter.c
	FPS counter implementation using rolling-window timestamp buffer.
file	audio.c
	🔊 Session-level audio coordination implementation
file	audio.h
	🔊 Session-level audio coordination wrapper
file	capture.c
	📹 Unified media capture implementation
file	capture.h
	📹 Unified media capture abstraction for session-based video sources
file	client_like.c
	Shared initialization and teardown for client-like modes.
file	client_like.h
	Shared initialization and teardown for client-like modes (mirror, client, discovery).
file	consensus.c
	Mode-agnostic ring consensus abstraction implementation.
file	consensus.h
	Mode-agnostic ring consensus abstraction for session discovery.
file	consensus_integration.c
	Integration helpers for session consensus in discovery mode.
file	consensus_integration.h
	Integration helpers for session consensus across modes.
file	display.c
	🖥️ Unified terminal display implementation
file	display.h
	🖥️ Unified terminal display abstraction for session-based rendering
file	host.c
	🏠 Server-side session hosting implementation
file	host.h
	🏠 Server-side session hosting abstraction
file	keyboard_handler.c
	Keyboard input handler implementation.
file	keyboard_handler.h
	🎮 Keyboard input handler for interactive session controls
file	participant.c
	👤 Client-side session participation implementation
file	participant.h
	👤 Client-side session participation abstraction
file	pipeline.c
	Three-thread render pipeline implementation.
file	pipeline.h
	Three-thread render pipeline: capture → display/encode.
file	render.c
	Unified render loop implementation for all display modes.
file	render.h
	Centralized render loop abstraction for all display modes.
file	server_like.c
	Unified lifecycle for server-like modes (server, discovery-service).
file	session_log_buffer.h
	Thread-safe circular log buffer for session screens (status, splash).
file	keyboard_help.h
	🆘 Interactive keyboard help overlay for session keyboard shortcuts
file	splash.h
	Intro and status screen display for ascii-chat with animated rainbow effects.
file	status.h
	📊 Status screen display and management for server/discovery service modes
file	update_banner.h
	Update available prompt screen shown after splash.
file	fps_counter.h
	⏱️ FPS counter for measuring output write throughput

Data Structures
struct	session_capture_config_t
	Media-source and loader settings used to create a session capture context. More...
struct	session_display_config_t
	Terminal-rendering and snapshot settings used to create a display context. More...
struct	session_host_client_info_t
	Snapshot of the address, identity, activity, and connection time for one host client. More...
struct	session_host_callbacks_t
	Snapshot of the address, identity, activity, and connection time for one host client. More...
struct	session_host_config_t
	Host-side event hooks for joins, departures, media, and errors. More...
struct	session_participant_callbacks_t
	Client-side event hooks for connection, media, settings, and errors. More...
struct	session_participant_config_t
	Client-side event hooks for connection, media, settings, and errors. More...

Typedefs
typedef struct session_audio_ctx	session_audio_ctx_t
	Opaque session audio context handle.
typedef bool(*	session_capture_should_exit_fn) (void *user_data)
	Callback type to check if initialization should be cancelled.
typedef struct session_capture_ctx	session_capture_ctx_t
	session capture config keeps the values that move through the subsystem: type, path, target_fps, loop. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself.
typedef bool(*	session_display_should_exit_fn) (void *user_data)
	Callback type to check if initialization should be cancelled.
typedef struct session_display_ctx	session_display_ctx_t
	session display config is intentionally a small, concrete record. Fields such as snapshot_mode, palette_type, custom_palette, color_mode give callers the identity and current value they need. It is normally borrowed from, or owned by, the surrounding subsystem—not independently managed.
typedef struct session_host	session_host_t
	Opaque session host handle.
typedef struct acip_transport	acip_transport_t
	Forward declaration of ACIP transport.
typedef struct session_display_ctx	session_display_ctx_t
	Runtime terminal state and reusable workspaces for ASCII rendering.
typedef struct session_participant	session_participant_t
	Client session state spanning connection, transport, media workers, and callbacks.
typedef struct acip_transport	acip_transport_t
	Forward declaration of ACIP transport.
typedef bool(*	session_should_exit_fn) (void *user_data)
	Exit condition callback type.
typedef image_t *(*	session_capture_fn) (void *user_data)
	Capture callback for event-driven frame source.
typedef void(*	session_sleep_for_frame_fn) (void *user_data)
	Sleep callback for custom frame timing.
typedef void(*	session_keyboard_handler_fn) (session_capture_ctx_t *capture, int key, void *user_data)
	Keyboard input handler callback type.
typedef struct session_display_ctx	session_display_ctx_t
typedef struct fps_counter_s	fps_counter_t
	Opaque FPS counter handle.

Functions
session_audio_ctx_t *	session_audio_create (bool is_host)
	Create a new session audio context.
void	session_audio_destroy (session_audio_ctx_t *ctx)
	Destroy session audio context and free resources.
asciichat_error_t	session_audio_start_capture (session_audio_ctx_t *ctx)
	Start audio capture (microphone input).
asciichat_error_t	session_audio_start_playback (session_audio_ctx_t *ctx)
	Start audio playback (speaker output).
asciichat_error_t	session_audio_start_duplex (session_audio_ctx_t *ctx)
	Start full-duplex audio (simultaneous capture and playback).
void	session_audio_stop (session_audio_ctx_t *ctx)
	Stop all audio streams.
bool	session_audio_is_running (session_audio_ctx_t *ctx)
	Check if audio is currently running.
size_t	session_audio_read_captured (session_audio_ctx_t *ctx, float *buffer, size_t num_samples)
	Read captured audio samples.
asciichat_error_t	session_audio_write_playback (session_audio_ctx_t *ctx, const float *buffer, size_t num_samples)
	Write audio samples for playback.
asciichat_error_t	session_audio_add_source (session_audio_ctx_t *ctx, uint32_t source_id)
	Add an audio source for mixing (host only).
void	session_audio_remove_source (session_audio_ctx_t *ctx, uint32_t source_id)
	Remove an audio source from mixing (host only).
asciichat_error_t	session_audio_write_source (session_audio_ctx_t *ctx, uint32_t source_id, const float *samples, size_t num_samples)
	Write audio samples from a specific source (host only).
size_t	session_audio_mix_excluding (session_audio_ctx_t *ctx, uint32_t exclude_id, float *output, size_t num_samples)
	Mix all sources except one and return the result (host only).
session_capture_ctx_t *	session_mirror_capture_create (const session_capture_config_t *config)
	Create a new session capture context.
session_capture_ctx_t *	session_network_capture_create (uint32_t target_fps)
	Create network mode capture context without media source.
session_capture_ctx_t *	session_capture_create (const session_capture_config_t *config)
	Legacy function - creates either mirror or network capture based on options.
void	session_capture_destroy (session_capture_ctx_t *ctx)
	Destroy session capture context and free resources.
image_t *	session_capture_read_frame (session_capture_ctx_t *ctx)
	Read the next video frame from the capture source.
image_t *	session_capture_process_for_transmission (session_capture_ctx_t *ctx, image_t *frame)
	Process a frame for network transmission (resize if needed).
void	session_capture_sleep_for_fps (session_capture_ctx_t *ctx)
	Sleep to maintain target frame rate.
bool	session_capture_at_end (session_capture_ctx_t *ctx)
	Check if capture source has reached end of stream.
bool	session_capture_is_valid (session_capture_ctx_t *ctx)
	Check if capture context is initialized and valid.
double	session_capture_get_current_fps (session_capture_ctx_t *ctx)
	Get the current FPS being achieved by the capture source.
uint32_t	session_capture_get_target_fps (session_capture_ctx_t *ctx)
	Get the target FPS configured for this capture context.
bool	session_capture_has_audio (session_capture_ctx_t *ctx)
	Check if capture source has audio available.
size_t	session_capture_read_audio (session_capture_ctx_t *ctx, float *buffer, size_t num_samples)
	Read audio samples from capture source.
bool	session_capture_using_file_audio (session_capture_ctx_t *ctx)
	Check if currently using file audio vs microphone fallback.
void *	session_capture_get_media_source (session_capture_ctx_t *ctx)
	Get the underlying media source from capture context.
terminal_fd_reader_t *	session_client_like_get_stdin_reader (void)
session_display_ctx_t *	session_display_create (const session_display_config_t *config)
	Create a new session display context.
session_display_ctx_t *	session_display_get_global_context (void)
	Get the global display context (used for signal handlers and special cleanup).
void	session_display_set_global_context_public (session_display_ctx_t *ctx)
	Set the global display context (public setter for discovery cleanup).
asciichat_error_t	session_display_finish_render_file (session_display_ctx_t *ctx)
	Destroy session display context and free resources.
void	session_display_begin_drain (session_display_ctx_t *ctx, uint64_t total, bool total_known)
void	session_display_destroy (session_display_ctx_t *ctx)
void	session_display_set_stdin_reader (session_display_ctx_t *ctx, void *reader)
	Set stdin frame reader for ASCII-to-video rendering.
bool	session_display_has_tty (session_display_ctx_t *ctx)
	Check if display has a TTY (terminal) available.
const terminal_capabilities_t *	session_display_get_caps (session_display_ctx_t *ctx)
	Get detected terminal capabilities.
const char *	session_display_get_palette_chars (session_display_ctx_t *ctx)
	Get the palette characters string.
size_t	session_display_get_palette_len (session_display_ctx_t *ctx)
	Get the palette character count.
const char *	session_display_get_luminance_palette (session_display_ctx_t *ctx)
	Get the luminance mapping palette.
int	session_display_get_tty_fd (session_display_ctx_t *ctx)
	Get the TTY file descriptor.
void *	session_display_get_stdin_reader (session_display_ctx_t *ctx)
	Get the stdin frame reader for ASCII-to-video rendering.
bool	session_display_has_render_file (session_display_ctx_t *ctx)
	Check if display has render-file configured.
uint32_t	session_display_get_render_fps (session_display_ctx_t *ctx)
	Get the render FPS configured for file output.
void	session_display_set_render_fps (session_display_ctx_t *ctx, uint32_t fps)
	Set the render FPS for file output encoding.
bool	session_display_has_first_frame (session_display_ctx_t *ctx)
	Check if the display has rendered its first frame.
void	session_display_reset_first_frame (session_display_ctx_t *ctx)
	Reset the first frame flag to allow splash screen to show again on next render.
char *	session_display_convert_to_ascii (session_display_ctx_t *ctx, const image_t *image)
	Convert an image to ASCII art using display context and command-line options.
void	session_display_write_ascii (session_display_ctx_t *ctx, const char *frame_data)
	Write ASCII frame to terminal only (no encoding).
asciichat_error_t	session_display_encode_frame (session_display_ctx_t *ctx, const image_t *image, uint64_t captured_ns)
	Encode frame to render-file (FFmpeg only, no terminal output).
void	session_display_render_frame (session_display_ctx_t *ctx, const char *frame_data)
	Render an ASCII frame to the terminal.
void	session_display_write_raw (session_display_ctx_t *ctx, const char *data, size_t len)
	Render raw bytes to the terminal without frame processing.
void	session_display_set_snapshot_actual_duration (session_display_ctx_t *ctx, double actual_duration_sec)
	Set the actual wall-clock duration for snapshot mode frame timing.
void	session_display_reset (session_display_ctx_t *ctx)
	Reset terminal to default state.
void	session_display_clear (session_display_ctx_t *ctx)
	Clear the terminal screen.
void	session_display_cursor_home (session_display_ctx_t *ctx)
	Move cursor to home position (top-left).
bool	session_display_has_audio_playback (session_display_ctx_t *ctx)
	Check if display has audio playback configured.
asciichat_error_t	session_display_write_audio (session_display_ctx_t *ctx, const float *buffer, size_t num_samples)
	Write audio samples to playback buffer.
session_host_t *	session_host_create (const session_host_config_t *config)
	Create a new session host.
asciichat_error_t	session_host_destroy (session_host_t *host)
	Destroy session host and free resources.
asciichat_error_t	session_host_start (session_host_t *host)
	Start accepting client connections.
asciichat_error_t	session_host_stop (session_host_t *host)
	Stop accepting connections and disconnect all clients.
bool	session_host_is_running (session_host_t *host)
	Check if host is running.
uint32_t	session_host_add_memory_participant (session_host_t *host)
	Add a memory participant (host's own media).
asciichat_error_t	session_host_inject_frame (session_host_t *host, uint32_t participant_id, const image_t *frame)
	Inject a video frame from memory participant.
asciichat_error_t	session_host_inject_audio (session_host_t *host, uint32_t participant_id, const float *samples, size_t count)
	Inject audio samples from memory participant.
asciichat_error_t	session_host_remove_client (session_host_t *host, uint32_t client_id)
	Remove a client by ID.
asciichat_error_t	session_host_find_client (session_host_t *host, uint32_t client_id, session_host_client_info_t *info)
	Find a client by ID.
int	session_host_get_client_count (session_host_t *host)
	Get number of connected clients.
int	session_host_get_client_ids (session_host_t *host, uint32_t *ids, int max_ids)
	Get list of all connected client IDs.
asciichat_error_t	session_host_broadcast_frame (session_host_t *host, const char *frame)
	Broadcast ASCII frame to all clients.
asciichat_error_t	session_host_send_frame (session_host_t *host, uint32_t client_id, const char *frame)
	Send ASCII frame to a specific client.
asciichat_error_t	session_host_set_display (session_host_t *host, struct session_display_ctx *display)
	Set a native terminal display context for local frame rendering.
asciichat_error_t	session_host_start_render (session_host_t *host)
	Start media rendering thread (video mixing and audio distribution).
void	session_host_stop_render (session_host_t *host)
	Stop media rendering thread.
asciichat_error_t	session_host_set_client_transport (session_host_t *host, uint32_t client_id, acip_transport_t *transport, acip_transport_ownership_t ownership)
	Select a transport for a specific client in the host.
acip_transport_t *	session_host_get_client_transport (session_host_t *host, uint32_t client_id)
	Get the current transport for a specific client in the host.
bool	session_host_client_has_transport (session_host_t *host, uint32_t client_id)
	Check if a specific client has an active ACIP transport.
void	session_handle_keyboard_input (session_capture_ctx_t *capture, session_display_ctx_t *display, keyboard_key_t key)
	Handle keyboard input in a session.
session_participant_t *	session_participant_create (const session_participant_config_t *config)
	Server address, security, media, transport, and callback settings for a participant.
void	session_participant_destroy (session_participant_t *p)
	Destroy session participant and free resources.
asciichat_error_t	session_participant_connect (session_participant_t *p)
	Connect to session server.
void	session_participant_disconnect (session_participant_t *p)
	Disconnect from session server.
bool	session_participant_is_connected (session_participant_t *p)
	Check if participant is connected.
uint32_t	session_participant_get_client_id (session_participant_t *p)
	Get assigned client ID.
asciichat_error_t	session_participant_start_video (session_participant_t *p)
	Start video capture and streaming.
void	session_participant_stop_video (session_participant_t *p)
	Stop and join video capture, then release its resources Also stops audio when it may borrow the video media source.
bool	session_participant_is_video_active (session_participant_t *p)
	Check if video is streaming.
asciichat_error_t	session_participant_start_audio (session_participant_t *p)
	Start audio capture and streaming.
void	session_participant_stop_audio (session_participant_t *p)
	Stop audio capture and streaming.
bool	session_participant_is_audio_active (session_participant_t *p)
	Check if audio is streaming.
asciichat_error_t	session_participant_get_settings (session_participant_t *p, session_settings_t *settings)
	Get current session settings.
asciichat_error_t	session_participant_request_settings (session_participant_t *p, const session_settings_t *settings)
	Request this participant's remote rendering update.
asciichat_error_t	session_participant_set_transport (session_participant_t *p, acip_transport_t *transport, acip_transport_ownership_t ownership)
	Select a transport and its ownership mode for the participant.
acip_transport_t *	session_participant_get_transport (session_participant_t *p)
	Get the current transport for the participant.
bool	session_participant_has_transport (session_participant_t *p)
	Check if participant has a selected transport.
asciichat_error_t	session_render_loop (session_capture_ctx_t *capture, session_display_ctx_t *display, session_should_exit_fn should_exit, session_capture_fn capture_cb, session_sleep_for_frame_fn sleep_cb, session_keyboard_handler_fn keyboard_handler, void *user_data)
	Unified render loop for all display modes.
void	keyboard_help_toggle (session_display_ctx_t *ctx)
	Toggle keyboard help on/off.
void	keyboard_help_toggle_terminal (int fd)
int	keyboard_help_parent_screen (void)
const char *	keyboard_help_screen_name (int parent)
bool	keyboard_help_is_active (session_display_ctx_t *ctx)
	Check if keyboard help is currently active.
void	keyboard_help_render (session_display_ctx_t *ctx)
	Render keyboard help TUI overlay.
void	session_display_set_global_context (session_display_ctx_t *ctx)
	Set the global display context (for signal handlers like Ctrl+C).
bool	keyboard_help_is_active_global (void)
	Check if keyboard help is active (global accessor for signal handlers).
void	keyboard_help_toggle_global (void)
	Toggle keyboard help (global accessor for signal handlers).
void	keyboard_help_signal_cancel (void)
	Request help screen closure from signal handler (Ctrl+C).
bool	keyboard_help_check_signal_cancel (void)
	Check if help screen closure was requested by signal handler.
void	splash_log_init (void)
	Initialize log buffer for splash animation.
void	splash_log_destroy (void)
	Destroy splash log buffer.
void	splash_log_clear (void)
	Clear splash log buffer.
void	splash_log_append (const char *message)
	Append message to splash log buffer.
int	splash_intro_start (session_display_ctx_t *ctx)
	Start animated intro screen with rainbow ASCII art (non-blocking).
int	splash_intro_done (void)
	Signal that intro splash should end (first frame ready to render).
void	splash_wait_for_animation (void)
	Wait for splash animation thread to fully exit.
bool	splash_should_display (bool is_intro)
	Check if splash screen should display.
void	splash_restore_stderr (void)
	Restore stderr after splash animation completes.
void	splash_set_update_notification (const char *notification)
	Set update notification to display on splash/status screens.
void	splash_clear_display_context (void)
	Clear the cached display context to prevent use-after-free.
void	splash_notify_first_frame (void)
	Notify splash that the first frame has been rendered.
bool	splash_is_running (void)
	Check if splash screen animation is currently running.
void	update_banner_set_result (const update_check_result_t *result)
	Store the update check result (thread-safe).
bool	update_banner_has_update (void)
	Check if an update is available (thread-safe).
bool	update_banner_show_prompt (struct session_display_ctx *ctx)
	Show the update prompt screen and wait for user input.
void	update_banner_print_instructions (void)
	Print upgrade instructions to stdout and prepare for clean exit.
bool	update_banner_install_update (void)
void	update_banner_start_check (void)
	Start the background update check thread.
void	update_banner_wait_for_check (void)
	Wait for the background update check thread to finish.
void	update_banner_cancel_check (void)
void	update_banner_toggle_overlay (void)
bool	update_banner_handle_key (int key)
bool	update_banner_is_checking (void)
bool	update_banner_is_overlay_open (void)
fps_counter_t *	fps_counter_create (void)
	Create a new FPS counter.
void	fps_counter_destroy (fps_counter_t *counter)
	Destroy FPS counter and free resources.
void	fps_counter_tick (fps_counter_t *counter)
	Record a frame timestamp.
float	fps_counter_get (fps_counter_t *counter)
	Get the current FPS value.
void	fps_counter_reset (fps_counter_t *counter)
void	fps_counter_tick_at (fps_counter_t *counter, uint64_t now)
float	fps_counter_get_at (fps_counter_t *counter, uint64_t now)
bool	fps_counter_set_visible (fps_counter_t *counter, bool visible)
void	fps_counter_set_effective_fps (fps_counter_t *counter, unsigned int fps)
void	fps_counter_frame_begin (fps_counter_t *counter, bool measure)
void	fps_counter_write_begin (fps_counter_t *counter)
void	fps_counter_write_end (fps_counter_t *counter, bool complete)
void	fps_counter_frame_end (fps_counter_t *counter, uint64_t now)
void	fps_counter_render (fps_counter_t *counter, int fd, int columns, bool redrawn)

Detailed Description

Real-time audio-video session abstraction layer.

The Session Module provides a unified, cross-platform abstraction for managing real-time audio-video sessions in ascii-chat. It encapsulates:

• Server-side hosting with multi-client support and media mixing
• Client-side participation with encrypted streams and state coordination
• Shared infrastructure for media capture, terminal rendering, and audio handling
• Consensus protocol for distributed state management and host election
• Interactive controls via keyboard input and configuration

Module Organization

The session module is organized into several layers:

High-Level APIs

• session_host_t (host.h) - Server session management
• session_participant_t (participant.h) - Client session participation
• session_client_like_config_t (client_like.h) - Unified client-like mode framework

Shared Infrastructure

• session_capture_ctx_t (capture.h) - Media source abstraction (webcam/file/URL)
• session_display_ctx_t (display.h) - Terminal rendering abstraction
• session_render_loop() (render.h) - Unified frame processing loop
• session_audio_* (audio.h) - Audio capture and playback
• session_handle_keyboard_input() (keyboard_handler.h) - Interactive controls
• session_log_buffer_t (session_log_buffer.h) - Log capture for UI screens
• session_client_like_run() (client_like.h) - Unified initialization/cleanup framework

State Management

• session_settings_* (settings.h) - Thread-safe global settings (RCU-based)
• session_consensus_t (consensus.h) - Distributed consensus and host election

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Session Module                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Server-Side          ←  Consensus Protocol  →  Client-Side │
│  ────────────                 ──────────         ──────────  │
│  session_host_t               Ring Consensus    session_participant_t
│  - Listen/Accept              State Election    - Connect
│  - Client Registry            Coordination      - Stream
│  - Media Mixing               Distributed       - Receive
│  - Broadcasting               State Mgmt        - Disconnect
│                                                              │
│           ┌─────────────────────────────────┐              │
│           │  Shared Session Infrastructure  │              │
│           ├─────────────────────────────────┤              │
│           │ Capture (webcam/file/URL)       │              │
│           │ Display (terminal/TTY)          │              │
│           │ Render Loop (unified)           │              │
│           │ Audio (capture/playback)        │              │
│           │ Keyboard (interactive)          │              │
│           │ Settings (RCU-based)            │              │
│           │ Log Buffer (UI support)         │              │
│           └─────────────────────────────────┘              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Session State Machines

Each major component in the session module has a well-defined state machine:

Host State Machine

┌─────────────────────────────────────────────────────────────┐
│ SESSION HOST LIFECYCLE                                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  session_host_create()                                      │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  CREATED     │  - Allocated but not listening           │
│  │              │  - No network socket yet                 │
│  │              │  - Config applied, ready for start       │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_host_start()                                       │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  LISTENING   │  - Socket listening on configured port   │
│  │              │  - Accepting client connections          │
│  │              │  - Client registry initialized           │
│  └──────────────┘                                           │
│   ↕ (accepts clients)                                       │
│  ┌──────────────┐                                           │
│  │  HOSTING     │  - One or more clients connected         │
│  │   CLIENTS    │  - Callbacks fired on client events      │
│  │              │  - Render thread can be started          │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_host_stop()                                        │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  STOPPED     │  - Socket closed, no new connections     │
│  │              │  - Existing clients still drain buffers  │
│  │              │  - Ready for destroy                     │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_host_destroy()                                     │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  DESTROYED   │  - All resources freed                   │
│  │              │  - Handle invalid                        │
│  └──────────────┘                                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Participant State Machine

┌─────────────────────────────────────────────────────────────┐
│ SESSION PARTICIPANT LIFECYCLE                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  session_participant_create()                               │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  CREATED     │  - Allocated but not connected           │
│  │              │  - Config applied, no network socket     │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_participant_connect()                              │
│         │                                                   │
│         v (handshake)                                       │
│  ┌──────────────┐                                           │
│  │  CONNECTING  │  - TCP connection established            │
│  │              │  - Crypto handshake in progress          │
│  │              │  - Waiting for server acknowledgment     │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  CONNECTED   │  - Encrypted connection established      │
│  │              │  - Received unique client ID             │
│  │              │  - on_connected callback fired           │
│  │              │  - Ready for video/audio streams         │
│  └──────────────┘                                           │
│         │                                                   │
│         ├─ session_participant_start_video()               │
│         │         │                                         │
│         │         v                                         │
│         │  ┌──────────────────┐                             │
│         │  │  VIDEO STREAMING │  - Sending local frames    │
│         │  │                  │  - on_frame_received fired  │
│         │  └──────────────────┘                             │
│         │                                                   │
│         ├─ session_participant_start_audio()               │
│         │         │                                         │
│         │         v                                         │
│         │  ┌──────────────────┐                             │
│         │  │  AUDIO STREAMING │  - Sending audio samples   │
│         │  │                  │  - on_audio_received fired  │
│         │  └──────────────────┘                             │
│         │                                                   │
│         v                                                   │
│  session_participant_disconnect()                           │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  DISCONNECTED│  - Connection closed                     │
│  │              │  - Streams stopped, socket closed        │
│  │              │  - on_disconnected callback fired        │
│  │              │  - Ready for destroy                     │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_participant_destroy()                              │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  DESTROYED   │  - All resources freed                   │
│  │              │  - Handle invalid                        │
│  └──────────────┘                                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Capture Context State Machine

┌─────────────────────────────────────────────────────────────┐
│ CAPTURE CONTEXT LIFECYCLE                                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  session_capture_create()                                   │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  IDLE        │  - Media source initialized              │
│  │              │  - FFmpeg/webcam opened                  │
│  │              │  - First frame potentially buffered      │
│  │              │  - FPS tracking active                   │
│  └──────────────┘                                           │
│   ↕ (pause/resume)                                          │
│  ┌──────────────┐                                           │
│  │  PLAYING     │  - Frames being read and delivered       │
│  │              │  - FPS regulation active                 │
│  │              │  - seek_relative() affects playback      │
│  │              │  - Video loop on file sources            │
│  └──────────────┘                                           │
│   ↕ (pause)                                                 │
│  ┌──────────────┐                                           │
│  │  PAUSED      │  - Same frame returned repeatedly        │
│  │              │  - seek_relative() queued for resume     │
│  │              │  - FPS regulation continues              │
│  └──────────────┘                                           │
│         │                                                   │
│         v                                                   │
│  session_capture_destroy()                                  │
│         │                                                   │
│         v                                                   │
│  ┌──────────────┐                                           │
│  │  DESTROYED   │  - Media source closed                   │
│  │              │  - FFmpeg subprocess terminated          │
│  │              │  - Handle invalid                        │
│  └──────────────┘                                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Thread Coordination

The session module uses thread-safe components and clear ownership patterns:

Thread Safety by Component

Fully Thread-Safe (Can be accessed from multiple threads):

• session_settings_* (RCU-based lock-free reads)
• session_handle_keyboard_input() (thread-safe input queuing)
• session_host_t send operations (async, internally synchronized)
• session_log_buffer_t (circular append with atomic operations)

Thread-Confined (Single-threaded access only):

• session_capture_ctx_t - media source not thread-safe
• session_display_ctx_t - terminal rendering not atomic
• Individual frame/audio buffers

Multi-Threaded (Clear thread ownership):

• session_host_t callbacks run from any thread (host determines timing)
• session_participant_t receive callbacks from dedicated receive thread
• session_host_t render thread separate from accept thread

Render Loop Threading Pattern

Main Thread                   Render Thread
────────────────────────────────────────────
session_client_like_run()
  ├─ Initialize capture      (main thread)
  ├─ Initialize display      (main thread)
  ├─ Initialize audio        (main thread)
  │
  ├─ Start render thread ─────┐
  │                           │
  │                           v
  │                    session_render_loop()
  │                      while (!exit):
  │                        read frame (capture)
  │                        process frame
  │                        write display
  │                        handle keyboard ← lock-free read
  │                        update settings ← RCU read
  │                        sleep for FPS
  │
  ├─ Wait for render thread ←─┘
  │
  └─ Cleanup
       ├─ Destroy capture
       ├─ Destroy display
       ├─ Cleanup audio

Synchronization Primitives

RCU (Read-Copy-Update) for Settings:

• Multiple readers (render thread) never block
• Writers (keyboard handler) briefly lock for atomic swap
• Use case: pause state, volume, color mode changes

Circular Buffer for Logs:

• Lock-free append for log entries
• Atomic read for recent entries
• Multiple readers, single writer pattern

Mutex-Based Synchronization (if needed):

• Client registry in session_host_t
• Callback notification timing

Capture Integration

The capture abstraction integrates seamlessly with the render loop and state machine:

Capture Sources and Behavior

Webcam Source (Direct Platform Camera):

• Opens platform camera device (e.g., /dev/video0 on Linux)
• Reads frames at native device frame rate
• session_capture_sleep_for_fps() throttles to target FPS
• No seek support (live stream)

File Source (FFmpeg):

• Spawns FFmpeg subprocess to decode video
• Reads frames via stdout pipe at variable rate
• Seeks supported: session_capture_seek_relative()
• Loop support: restarts FFmpeg when end reached

URL Source (FFmpeg with yt-dlp resolution):

• Media resolver (lib/media/source.c):
  1. Direct detection: .mp4, .m3u8 → FFmpeg directly (fastest)
  2. yt-dlp extraction: YouTube, TikTok, etc. → extract stream URL
  3. Fallback: try FFmpeg as last resort
• Result: streaming URL passed to FFmpeg subprocess
• Seek support varies by protocol (HLS/DASH may not support)

Test Pattern (Procedural):

• Generates frames algorithmically
• Useful for testing without camera/media files
• Precise frame rate control

FPS Detection and Adaptation

The client_like framework probes source FPS:

// During initialization:
session_capture_probe_fps(capture, 1.0)  // Read for 1 second
// Result: detected_fps (e.g., 30, 60, etc.)
 
// Render loop then uses:
session_capture_sleep_for_fps(capture)  // Adaptive sleep

Adaptive Sleep Strategy:

• Tracks actual frame delivery times
• Compensates for processing delays
• Prevents frame drops or excessive buffering
• Critical for smooth playback

Pause/Resume Behavior

Pause is coordinated via session_settings_*:

// Keyboard handler (any thread):
session_settings_set_pause_state(true);
 
// Render loop (single-threaded):
while (!exit) {
    bool paused = session_settings_get_pause_state();  // Lock-free read
    image_t *frame = session_capture_read_frame(ctx);  // Pause state affects?
    // Paused: same frame returned repeatedly
    // Playing: next frame from source
}

Resource Lifecycle

Complete lifecycle from creation to destruction:

Initialization Sequence (session_client_like_run)

1. Keepawake System
   └─ Prevent OS sleep while running
 
2. Terminal Output Check
   └─ Detect if stdout is piped (affects splash screen)
 
3. Media Source Setup
   ├─ session_capture_create()
   ├─ Probe source FPS
   └─ Initialize frame buffer
 
4. Audio System Setup
   ├─ Platform audio context (PortAudio, JACK, etc.)
   ├─ Allocate audio buffers
   └─ Start capture thread (if needed)
 
5. Display Context Creation
   ├─ Detect terminal capabilities (color, resolution)
   ├─ Initialize color palette
   └─ Set up rendering state
 
6. Splash Screen
   ├─ Animated ASCII art display
   ├─ Shows log capture buffer
   └─ User can dismiss with keypress
 
7. Mode-Specific Initialization
   └─ Passed to run_fn callback (mode-dependent)
 
8. Main Loop Execution
   └─ session_render_loop() or custom mode loop

Cleanup Sequence (Error Recovery and Normal Exit)

1. Exit Render Loop
   └─ Graceful shutdown signal set
 
2. Render Thread Join
   └─ Wait for render thread to finish current frame
 
3. Keyboard Handler Cleanup
   ├─ Clear any queued input
   └─ Disable async input if needed
 
4. Audio System Shutdown
   ├─ Stop capture thread
   ├─ Drain remaining samples
   └─ CRITICAL: Stop BEFORE display cleanup (PortAudio constraint)
 
5. Capture Context Cleanup
   ├─ Close media source
   ├─ Terminate FFmpeg if running
   └─ Free frame buffers
 
6. Display Context Cleanup
   ├─ Restore terminal state
   ├─ Clear any partial renders
   └─ Re-enable cursor if needed
 
7. Keepawake Release
   └─ Re-enable system sleep
 
8. Memory Reports
   └─ Print leak detection (debug builds)

Critical Ordering Notes:

• Audio MUST be stopped before display (PortAudio cleans up terminal)
• Display cleanup must restore full terminal state before exit
• Render thread must be joined before freeing shared buffers

Memory Ownership

Clear ownership prevents double-frees and memory leaks:

session_client_like_run owns and manages:

• session_capture_ctx_t (owns underlying media source)
• session_display_ctx_t (owns terminal state)
• Audio context (owns PortAudio/JACK resources)
• Session log buffer (owns circular buffer)

Mode callbacks receive:

• Initialized, ready-to-use contexts
• MUST NOT attempt to free or destroy contexts
• Can read and modify state through provided APIs

Framebuffer Policy:

• Capture context owns frame buffers returned by session_capture_read_frame()
• Caller receives pointer, must not free
• Capture destruction releases all frame buffers

Error Recovery

If error occurs during execution:

capture_open fails ───────┐
audio_start fails ────────┤─→ Skip mode callback
display_create fails ─────┤─→ Run cleanup sequence
render_loop fails ────────┘─→ Exit with error
 
Result: all allocated resources freed, terminal restored

Key Concepts

Media Capture

The capture abstraction (session_capture_ctx_t) unifies all media sources:

• Webcam: Direct camera input via platform abstraction
• Files: Local video files (MP4, MKV, etc.) via FFmpeg
• URLs: Streaming URLs (HTTP, RTSP, DASH, HLS) via FFmpeg
• YouTube/TikTok: Via yt-dlp extraction, then FFmpeg playback
• Test Patterns: Procedurally generated for testing

All sources provide a unified interface:

• session_capture_read_frame() - Get next frame
• session_capture_sleep_for_fps() - FPS-aware sleep
• session_capture_toggle_pause() - Pause/resume
• session_capture_seek_relative() - Seek in time

Terminal Display

The display abstraction (session_display_ctx_t) manages terminal rendering:

• TTY Detection: Check if output is a terminal
• Capability Detection: Detect color support (mono/16/256/truecolor)
• Palette Selection: Choose luminance mapping for ASCII conversion
• Frame Rendering: Convert and output to terminal
• Color Modes: Support for ANSI, 256-color, and true color

Render Loop

The unified render loop (session_render_loop) abstracts two patterns:

Synchronous Mode (with capture context):

• Capture drives the loop
• Frame rate determined by media source
• Automatic FPS limiting via adaptive sleep
• Used by: mirror mode, discovery participant mode

Event-Driven Mode (with custom callbacks):

• Protocol/network drives the loop
• Custom frame and sleep callbacks
• Integration with network event loops
• Used by: client mode (network receives frames)

Audio Handling

Audio operations are decoupled from media source:

• Capture: Get samples from default audio input (microphone)
• Playback: Send samples to default audio output (speakers)
• Audio Context: Platform-specific state (PortAudio, JACK optional)
• Format: Float32 mono, normalized to [-1.0, 1.0]

Keyboard Input

Interactive controls via keyboard (session_handle_keyboard_input):

• ? - Toggle help screen
• SPACE - Play/pause
• ← / → - Seek ±30 seconds
• ↑ / ↓ - Volume ±10%
• m - Mute toggle
• c - Cycle color modes
• f - Flip webcam (mirror)

Thread-safe: Can be called from any thread (including render threads)

State Management

Session settings (session_settings_*) use RCU (Read-Copy-Update) for lock-free reads and atomic writes:

• session_settings_get_volume() - Read current volume (lock-free)
• session_settings_set_color_mode() - Update color mode (brief lock)
• session_settings_get_pause_state() - Check pause state (lock-free)

Manages:

• Color mode (mono/16/256/true color)
• Pause state (playing/paused)
• Volume level (0.0 to 1.0)
• Flip state (for webcam mirroring)
• Help screen visibility

Consensus Protocol

The consensus module (session_consensus_t) implements a distributed ring consensus protocol for:

• Host Election: Elect the best-suited participant as session host
• State Coordination: Synchronize pause/play state across participants
• Metrics Collection: Gather network quality metrics from all participants
• Topology Management: Maintain ring topology for state propagation

Used primarily in Discovery Mode for P2P scenarios without a central server.

Usage Patterns

Server Mode

// Configure server
session_host_config_t config = {
    .port = 27224,
    .max_clients = 32,
    .callbacks = {
        .on_client_join = handle_join,
        .on_frame_received = handle_frame,
        .on_audio_received = handle_audio,
    },
    .user_data = app_context
};
 
// Create and start
session_host_t *host = session_host_create(&config);
session_host_start(host);
 
// Render thread (mixes video/audio)
session_host_start_render(host);
 
// Cleanup
session_host_stop_render(host);
session_host_stop(host);
session_host_destroy(host);

Client Mode

// Configure participant
session_participant_config_t config = {
    .address = "server.example.com",
    .port = 27224,
    .callbacks = {
        .on_connected = handle_connected,
        .on_frame_received = render_frame,
        .on_audio_received = play_audio,
    },
    .user_data = app_context
};
 
// Create and connect
session_participant_t *p = session_participant_create(&config);
session_participant_connect(p);
 
// Start streams
session_participant_start_video(p);
session_participant_start_audio(p);
 
// Cleanup
session_participant_disconnect(p);
session_participant_destroy(p);

Mirror Mode (via client_like framework)

// Configure unified framework
session_client_like_config_t config = {
    .media_source = { .type = MEDIA_SOURCE_WEBCAM },
    .run_fn = mirror_main_loop,
    .run_user_data = app_context,
    // ... audio, display, keyboard config ...
};
 
// Run (all setup and teardown handled)
asciichat_error_t result = session_client_like_run(&config);
// Automatic cleanup

Error Handling

All functions return asciichat_error_t. On error:

asciichat_error_t result = session_host_start(host);
if (result != ASCIICHAT_OK) {
    asciichat_error_context_t ctx;
    if (HAS_ERRNO(&ctx)) {
        log_error("Failed: %s", ctx.context_message);
    }
    return result;
}

Thread Safety

• session_host_t: Fully thread-safe for all operations
  • Callbacks may be invoked from any thread
  • Safe to call from render threads
• session_participant_t: Thread-safe for stream control
  • Async send operations
  • Receive callbacks from dedicated thread
• session_capture_ctx_t: Single-threaded design
  • Safe to call from single render thread
  • Intended for synchronous media reading
• session_display_ctx_t: Single-threaded design
  • Safe to call from single render thread
  • Terminal operations not atomic across threads
• **session_settings_***: Fully thread-safe (RCU-based)
  • Lock-free reads
  • Brief lock for writes
  • Safe from any thread
• session_handle_keyboard_input(): Thread-safe
  • Can be called from any thread
  • Safe to call concurrently

Memory Management

All allocations are tracked via SAFE_MALLOC/CALLOC/FREE:

// Automatic tracking
uint8_t *buffer = SAFE_MALLOC(1024, uint8_t *);
// Memory report printed at program exit (debug builds)
SAFE_FREE(buffer);

Encryption and Authentication

All connections are encrypted by default using:

• X25519: Key exchange
• XSalsa20-Poly1305: AEAD symmetric encryption
• Ed25519: Signature verification (SSH key auth)

Supported authentication modes:

• Ephemeral: Anonymous encrypted connection
• Password: Both sides prove knowledge of password
• SSH Key: Server authenticates with Ed25519 key

Configuration:

config.encryption_enabled = true;      // Default
config.password = "secret";             // Password auth
config.key_path = "~/.ssh/id_ed25519";  // SSH key auth

Files Reference

host.h - Server session management participant.h - Client session participation client_like.h - Unified client-like mode framework capture.h - Media source abstraction display.h - Terminal rendering abstraction render.h - Unified render loop audio.h - Audio capture and playback keyboard_handler.h - Interactive keyboard controls session_log_buffer.h - Log capture for UI settings.h - Thread-safe session settings consensus.h - Distributed consensus protocol consensus_integration.h - Consensus integration helpers

See Also

• Session README: README.md (comprehensive overview)
• Cryptography: lib/crypto/ (encryption implementation)
• Network Protocol: lib/network/ (ACIP packet protocol)
• Media: lib/media/ (FFmpeg/yt-dlp integration)
• Platform: lib/platform/ (cross-platform abstractions)

This header provides a thin wrapper around the lib/audio/ system for session-level audio coordination. It handles the differences between host (mixing) and participant (simple capture/playback) modes.

CORE FEATURES:

• Unified API for both host and participant audio handling
• Host-only audio mixing for multi-participant sessions
• Source management for tracking participant audio streams
• Clean startup/shutdown coordination

USAGE:

// Create audio context for a participant
session_audio_ctx_t *ctx = session_audio_create(false);
 
// Start capture and playback
session_audio_start_capture(ctx);
session_audio_start_playback(ctx);
 
// Cleanup
session_audio_destroy(ctx);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

This header provides a unified interface for media capture that abstracts over webcam, file, stdin, and test pattern sources. It is designed to be reusable across different modes (client, mirror, and discovery mode).

CORE FEATURES:

• Unified API for all media source types (webcam, file, stdin, test)
• Configurable frame rate with adaptive sleep
• Optional frame resizing for network transmission
• FPS tracking and reporting
• Loop support for file sources

USAGE:

// Create capture context for webcam at 60 FPS
session_capture_config_t config = {
    .type = MEDIA_SOURCE_WEBCAM,
    .path = "0",
    .target_fps = 60,
    .loop = false,
    .resize_for_network = false
};
session_capture_ctx_t *ctx = session_capture_create(&config);
 
// Read and process frames
while (!done) {
    image_t *frame = session_capture_read_frame(ctx);
    if (frame) {
        // Process frame...
    }
    session_capture_sleep_for_fps(ctx);
}
 
// Cleanup
session_capture_destroy(ctx);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

This header provides a unified interface for terminal display that abstracts TTY detection, palette initialization, and frame rendering. It is designed to be reusable across different modes (client, mirror, and discovery mode).

CORE FEATURES:

• TTY detection and management
• Terminal capability detection (color, UTF-8)
• Palette initialization and luminance mapping
• Frame rendering with RLE expansion support
• Snapshot mode support for single-frame capture

USAGE:

// Create display context with color support
session_display_config_t config = {
    .snapshot_mode = false,
    .palette_type = PALETTE_STANDARD,
    .custom_palette = NULL,
    .color_mode = TERM_COLOR_AUTO
};
session_display_ctx_t *ctx = session_display_create(&config);
 
// Render frames
const char *frame_data = ...; // ASCII frame from server
session_display_render_frame(ctx, frame_data, false);
 
// Cleanup
session_display_destroy(ctx);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

This header provides the server-side session hosting abstraction, encapsulating client management, connection acceptance, and event handling for session hosts.

CORE FEATURES:

• Server lifecycle management (start, stop)
• Client connection handling (add, remove, lookup)
• Callback-based event notification
• Encryption and authentication support

USAGE:

// Define callbacks
void on_client_join(session_host_t *h, uint32_t id, void *data) {
    printf("Client %u joined\n", id);
}
 
void on_frame(session_host_t *h, uint32_t id, const image_t *frame, void *data) {
    // Process video frame from client
}
 
// Create and start host
session_host_config_t config = {
    .port = 27224,
    .max_clients = 32,
    .callbacks = { .on_client_join = on_client_join, .on_frame_received = on_frame }
};
session_host_t *h = session_host_create(&config);
session_host_start(h);
 
// Run until stopped...
 
// Cleanup
session_host_destroy(h);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Provides keyboard input handling for session-level controls including:

• Media playback control (play/pause, seek)
• Audio control (volume, mute)
• Display control (color mode, webcam flip)
• Help screen toggle

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

This header provides the client-side session participation abstraction, encapsulating connection management, media streaming, and event handling for session participants.

CORE FEATURES:

• Connection lifecycle management (connect, disconnect, reconnect)
• Video and audio stream control
• Callback-based event notification
• Encryption and authentication support

USAGE:

// Define callbacks
void on_connected(session_participant_t *p, uint32_t id, void *data) {
    printf("Connected with ID %u\n", id);
}
 
void on_frame(session_participant_t *p, const char *frame, void *data) {
    // Render ASCII frame
}
 
// Create and connect
session_participant_config_t config = {
    .address = "127.0.0.1",
    .port = 27224,
    .enable_video = true,
    .callbacks = { .on_connected = on_connected, .on_frame_received = on_frame }
};
session_participant_t *p = session_participant_create(&config);
session_participant_connect(p);
 
// Start streaming
if (session_participant_start_video(p) != ASCIICHAT_OK) {
    session_participant_destroy(p);
    return;
}
 
// Cleanup
session_participant_destroy(p);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Provides an interactive keyboard help overlay that displays:

• Available keyboard shortcuts
• Current program state (volume, color mode, webcam flip, audio, mute status)

The keyboard help is toggled with '?' key and suppresses frame rendering while network reception continues in the background.

Display State:

• Horizontally and vertically centered in terminal
• Box-drawing border with UTF-8 fallback to ASCII
• Real-time updates of option values (no network latency)

Threading:

• Keyboard help state: Shared atomic interactive-screen selection
• Terminal writes: Serialized via session_display_write_raw()
• Option reads: Lock-free via RCU (GET_OPTION macro)

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Provides a blocking prompt screen that shows when a new version of ascii-chat is available. Displayed after the splash screen ends, before video rendering begins. The user can choose to exit and update (Y/Enter) or continue (N/Esc).

Thread-safe: update_banner_set_result() can be called from the background update check thread while the splash is still running.

Provides a rolling-window FPS counter that measures the actual throughput of frame output operations (platform_write_all). Maintains a circular buffer of timestamps to compute stable FPS readings.

USAGE:

fps_counter_t *fps = fps_counter_create();
 
// After each frame write to terminal
fps_counter_tick(fps);
 
// Get current FPS for display
float current_fps = fps_counter_get(fps);
 
fps_counter_destroy(fps);

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Typedef Documentation

acip_transport_t [1/2]

typedef struct acip_transport acip_transport_t

#include <src/common/session/host.h>

Forward declaration of ACIP transport.

Forward declaration of transport implementation.

Opaque transport interface for send/receive operations. Used for WebRTC DataChannels, WebSockets, and other transports.

See also

acip_transport_t in network/acip/transport.h

Opaque handle to transport-specific state. Each transport implementation defines its own state structure.

Definition at line 506 of file host.h.

acip_transport_t [2/2]

typedef struct acip_transport acip_transport_t

#include <src/common/session/participant.h>

Forward declaration of ACIP transport.

Opaque transport interface for send/receive operations. Used for WebRTC DataChannels, WebSockets, and other transports.

See also

acip_transport_t in network/acip/transport.h

Definition at line 377 of file participant.h.

fps_counter_t

typedef struct fps_counter_s fps_counter_t

#include <include/ascii-chat/ui/fps_counter.h>

Opaque FPS counter handle.

Maintains a rolling window of frame timestamps for FPS calculation.

Definition at line 40 of file fps_counter.h.

session_audio_ctx_t

typedef struct session_audio_ctx session_audio_ctx_t

#include <src/common/session/audio.h>

Opaque session audio context handle.

Manages audio capture, playback, and optional mixing state. Created via session_audio_create(), destroyed via session_audio_destroy().

Definition at line 56 of file src/common/session/audio.h.

session_capture_ctx_t

typedef struct session_capture_ctx session_capture_ctx_t

#include <src/common/session/capture.h>

session capture config keeps the values that move through the subsystem: type, path, target_fps, loop. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself.

Opaque session capture context handle

Manages media source, FPS tracking, and adaptive sleep state. Created via session_capture_create(), destroyed via session_capture_destroy().

Definition at line 134 of file common/session/capture.h.

session_capture_fn

typedef image_t *(* session_capture_fn) (void *user_data)

#include <src/common/session/render.h>

Capture callback for event-driven frame source.

Called to obtain the next frame for rendering. Can return NULL if no frame is currently available.

Used when capture context is NULL (event-driven mode). Not called if capture context is provided (synchronous mode).

Parameters

user_data

Opaque pointer provided by caller

Returns

Pointer to frame (caller must not free), or NULL if unavailable

Definition at line 59 of file src/common/session/render.h.

session_capture_should_exit_fn

typedef bool(* session_capture_should_exit_fn) (void *user_data)

#include <src/common/session/capture.h>

Callback type to check if initialization should be cancelled.

Called periodically during initialization to allow graceful cancellation. Should return true if initialization should stop immediately.

Parameters

user_data

Opaque pointer provided by caller

Returns

true to cancel initialization, false to continue

Definition at line 71 of file common/session/capture.h.

session_display_ctx_t [1/3]

typedef struct session_display_ctx session_display_ctx_t

#include <include/ascii-chat/tui/keyboard_help.h>

Definition at line 33 of file keyboard_help.h.

session_display_ctx_t [2/3]

typedef struct session_display_ctx session_display_ctx_t

#include <src/client/display.h>

session display config is intentionally a small, concrete record. Fields such as snapshot_mode, palette_type, custom_palette, color_mode give callers the identity and current value they need. It is normally borrowed from, or owned by, the surrounding subsystem—not independently managed.

Opaque session display context handle

Manages TTY state, terminal capabilities, palette, and rendering state. Created via session_display_create(), destroyed via session_display_destroy().

Definition at line 29 of file src/client/display.h.

session_display_ctx_t [3/3]

typedef struct session_display_ctx session_display_ctx_t

#include <src/common/session/display.c>

Runtime terminal state and reusable workspaces for ASCII rendering.

Runtime terminal state and reusable workspaces for ASCII rendering.

It owns TTY capability data, palette lookup tables, stabilizers, output and resize buffers, render-file timing, and the flags that stop output after the consumer disappears. Audio context pointers remain borrowed from the caller.

session_display_should_exit_fn

typedef bool(* session_display_should_exit_fn) (void *user_data)

#include <src/common/session/display.h>

Callback type to check if initialization should be cancelled.

Called periodically during initialization to allow graceful cancellation. Should return true if initialization should stop immediately.

Parameters

user_data

Opaque pointer provided by caller

Returns

true to cancel initialization, false to continue

Definition at line 66 of file src/common/session/display.h.

session_host_t

typedef struct session_host session_host_t

#include <src/common/session/host.c>

Opaque session host handle.

Manages server state, client connections, and event callbacks. Created via session_host_create(), destroyed via session_host_destroy().

session_keyboard_handler_fn

typedef void(* session_keyboard_handler_fn) (session_capture_ctx_t *capture, int key, void *user_data)

#include <src/common/session/render.h>

Keyboard input handler callback type.

Called when keyboard input is detected during render loop iteration. Allows applications to respond to interactive keyboard controls.

Parameters

capture	Capture context (may be NULL for client mode)
key	Keyboard key code from keyboard_read_nonblocking()
user_data	Opaque pointer provided by caller

Definition at line 87 of file src/common/session/render.h.

session_participant_t

typedef struct session_participant session_participant_t

#include <src/common/session/participant.c>

Client session state spanning connection, transport, media workers, and callbacks.

Opaque session participant handle.

Client session state spanning connection, transport, media workers, and callbacks.

The participant owns its copied address/password settings and worker handles, while the selected transport and network connection follow their explicit ownership fields. Audio/video lifecycle state prevents stale workers from using a connection during shutdown.

Contains connection state, media stream state, and callback configuration.

Manages connection state, media streams, and event callbacks. Created via session_participant_create(), destroyed via session_participant_destroy().

session_should_exit_fn

typedef bool(* session_should_exit_fn) (void *user_data)

#include <src/common/session/render.h>

Exit condition callback type.

Called each iteration to check if render loop should terminate. Return true to exit, false to continue.

Parameters

user_data

Opaque pointer provided by caller

Returns

true if loop should exit, false to continue

Definition at line 43 of file src/common/session/render.h.

session_sleep_for_frame_fn

typedef void(* session_sleep_for_frame_fn) (void *user_data)

#include <src/common/session/render.h>

Sleep callback for custom frame timing.

Called to sleep/wait until the next frame is ready. Allows custom timing logic.

Used when capture context is NULL (event-driven mode). Not called if capture context is provided (synchronous mode).

Parameters

user_data

Opaque pointer provided by caller

Definition at line 73 of file src/common/session/render.h.

Function Documentation

fps_counter_create()

fps_counter_t * fps_counter_create

(

void

)

#include <include/ascii-chat/ui/fps_counter.h>

Create a new FPS counter.

Returns

Pointer to counter, or NULL on failure

Creates and initializes a rolling-window FPS counter with a buffer for 30 frame timestamps.

Note

Call fps_counter_destroy() to free resources when done.

Definition at line 50 of file fps_counter.c.

                                        {
  fps_counter_t *counter = SAFE_CALLOC(1, sizeof(fps_counter_t), fps_counter_t *);
  if (!counter) {
    return NULL;
  }
 
  counter->last_fps = -1;
  counter->effective_fps = 60;
  counter->report_start = time_get_ns();
 
  // Initialize circular buffer pointers
  counter->head = 0;
  counter->count = 0;
  memset(counter->frame_times, 0, sizeof(counter->frame_times));
 
  return counter;
}

References fps_counter_s::count, fps_counter_s::effective_fps, fps_counter_s::frame_times, fps_counter_s::head, fps_counter_s::last_fps, fps_counter_s::report_start, and SAFE_CALLOC.

fps_counter_destroy()

void fps_counter_destroy

(

fps_counter_t *

counter

)

#include <include/ascii-chat/ui/fps_counter.h>

Destroy FPS counter and free resources.

Parameters

counter

Counter to destroy (can be NULL)

Definition at line 68 of file fps_counter.c.

                                                 {
  if (counter) {
    SAFE_FREE(counter);
  }
}

References SAFE_FREE.

fps_counter_frame_begin()

void fps_counter_frame_begin	(	fps_counter_t *	counter,
		bool	measure )

#include <include/ascii-chat/ui/fps_counter.h>

Definition at line 161 of file fps_counter.c.

                                                                   {
  if (!counter)
    return;
  counter->current_frame_id = 0;
  counter->measuring = measure;
  counter->written = counter->failed = false;
  counter->frame_write_ns = 0;
}

References fps_counter_s::current_frame_id, fps_counter_s::failed, fps_counter_s::frame_write_ns, fps_counter_s::measuring, and fps_counter_s::written.

Referenced by fps_counter_frame_begin_id().

fps_counter_frame_end()

void fps_counter_frame_end	(	fps_counter_t *	counter,
		uint64_t	now )

#include <include/ascii-chat/ui/fps_counter.h>

Finish at the supplied monotonic timestamp; failed or empty presentations do not count.

Definition at line 191 of file fps_counter.c.

                                                                 {
  if (!counter)
    return;
  if (counter->measuring && counter->written && !counter->failed) {
    fps_counter_tick_at(counter, now);
    if (counter->current_frame_id)
      counter->completed_frame_id = counter->current_frame_id;
    counter->report_writes += counter->frame_write_ns;
    counter->report_frames++;
  }
  counter->measuring = false;
}

References fps_counter_s::completed_frame_id, fps_counter_s::current_frame_id, fps_counter_s::failed, fps_counter_tick_at(), fps_counter_s::frame_write_ns, fps_counter_s::measuring, fps_counter_s::report_frames, fps_counter_s::report_writes, and fps_counter_s::written.

fps_counter_get()

float fps_counter_get

(

fps_counter_t *

counter

)

#include <include/ascii-chat/ui/fps_counter.h>

Get the current FPS value.

Parameters

counter

FPS counter (can be NULL)

Returns

Current FPS as a float, or 0.0 if counter is NULL or insufficient data

Returns a rolling-window average FPS based on the last 30 frames. Stable FPS reading after at least 2 frames have been recorded. Returns zero after two seconds without a completed frame. The next tick starts a fresh window so pauses do not distort resumed playback.

Definition at line 112 of file fps_counter.c.

                                              {
  return fps_counter_get_at(counter, time_get_ns());
}

References fps_counter_get_at().

fps_counter_get_at()

float fps_counter_get_at	(	fps_counter_t *	counter,
		uint64_t	now )

#include <include/ascii-chat/ui/fps_counter.h>

Definition at line 116 of file fps_counter.c.

                                                               {
  if (!counter || counter->count < 2) {
    return 0.0f;
  }
 
  // Find indices of oldest and newest timestamps in the buffer
  int oldest_idx = (counter->head - counter->count + FPS_WINDOW_SIZE) % FPS_WINDOW_SIZE;
  int newest_idx = (counter->head - 1 + FPS_WINDOW_SIZE) % FPS_WINDOW_SIZE;
 
  // Get the elapsed time between oldest and newest frames
  uint64_t oldest_time = counter->frame_times[oldest_idx];
  uint64_t newest_time = counter->frame_times[newest_idx];
  if (now < newest_time || now - newest_time >= 2000000000ULL)
    return 0.0f;
  // Include time since the last completed frame so stalled output decays immediately.
  uint64_t elapsed_ns = now - oldest_time;
 
  // Avoid division by zero
  if (elapsed_ns == 0) {
    return 0.0f;
  }
 
  // FPS = (number of frames) / elapsed_time
  // We have (count - 1) frames across the elapsed time
  // (count - 1) frames means count timestamps, so count-1 intervals
  return (float)(counter->count - 1) * 1e9f / (float)elapsed_ns;
}

References fps_counter_s::count, FPS_WINDOW_SIZE, fps_counter_s::frame_times, and fps_counter_s::head.

Referenced by fps_counter_get(), and fps_counter_render().

fps_counter_render()

void fps_counter_render	(	fps_counter_t *	counter,
		int	fd,
		int	columns,
		bool	redrawn )

#include <include/ascii-chat/ui/fps_counter.h>

Draw the overlay if visible and changed, and periodically report output timing.

Definition at line 204 of file fps_counter.c.

                                                                                   {
  if (!counter)
    return;
  uint64_t now = time_get_ns();
  float measured = fps_counter_get_at(counter, now);
  // A UI overlay can repaint for longer than the media counter's inactivity
  // window. Keep the last visible value during a forced overlay redraw so
  // opening keyboard help does not make an otherwise-live stream display 0.
  int value = measured >= 999.0f ? 999 : (int)(measured + 0.5f);
  if (redrawn && value == 0 && counter->last_fps > 0)
    value = counter->last_fps;
  // `FPS:ddd/ddd` is ten columns wide. Start nine columns before the
  // terminal's rightmost column so the complete overlay stays on one line.
  if (counter->visible && columns >= 10 && (redrawn || value != counter->last_fps)) {
    // Restore the cursor so the right-margin overlay cannot wrap the next write.
    const char *style = terminal_has_dark_background() ? "\033[97;40m" : "\033[30;47m";
    if (ui_output_printf(fd, "\0337\033[1;%dH%sFPS:%3d/%u\033[0m\0338", columns - 9, style, value,
                         counter->effective_fps) == ASCIICHAT_OK)
      counter->last_fps = value;
  }
  if (now - counter->report_start >= 3 * NS_PER_SEC_INT) {
    if (counter->report_frames)
      log_debug("FPS_OUTPUT: frames=%llu elapsed_ms=%.3f write_ms=%.3f", (unsigned long long)counter->report_frames,
                (double)(now - counter->report_start) / NS_PER_MS_INT, (double)counter->report_writes / NS_PER_MS_INT);
    counter->report_start = now;
    counter->report_writes = counter->report_frames = 0;
  }
}

References ASCIICHAT_OK, fps_counter_s::effective_fps, fps_counter_get_at(), fps_counter_s::last_fps, log_debug, NS_PER_MS_INT, NS_PER_SEC_INT, fps_counter_s::report_frames, fps_counter_s::report_start, fps_counter_s::report_writes, ui_output_printf(), and fps_counter_s::visible.

fps_counter_reset()

void fps_counter_reset

(

fps_counter_t *

counter

)

#include <include/ascii-chat/ui/fps_counter.h>

Clear samples when the displayed screen changes. Single-owner API.

Definition at line 82 of file fps_counter.c.

                                               {
  if (counter) {
    counter->head = counter->count = 0;
    memset(counter->frame_times, 0, sizeof(counter->frame_times));
  }
}

References fps_counter_s::count, fps_counter_s::frame_times, and fps_counter_s::head.

Referenced by fps_counter_tick_at().

fps_counter_set_effective_fps()

void fps_counter_set_effective_fps	(	fps_counter_t *	counter,
		unsigned int	fps )

#include <include/ascii-chat/ui/fps_counter.h>

Set the effective frame-rate target shown beside the measured rate.

Definition at line 154 of file fps_counter.c.

                                                                             {
  if (counter) {
    counter->effective_fps = fps > 0 ? fps : 60;
    counter->last_fps = -1;
  }
}

References fps_counter_s::effective_fps, and fps_counter_s::last_fps.

Referenced by ui_controller_set_effective_fps().

fps_counter_set_visible()

bool fps_counter_set_visible	(	fps_counter_t *	counter,
		bool	visible )

#include <include/ascii-chat/ui/fps_counter.h>

Presentation hooks. All calls for a counter must run on its owning thread.

Definition at line 144 of file fps_counter.c.

                                                                   {
  if (!counter)
    return false;
  bool changed = counter->visible != visible;
  counter->visible = visible;
  if (changed)
    counter->last_fps = -1;
  return changed;
}

References fps_counter_s::last_fps, and fps_counter_s::visible.

fps_counter_tick()

void fps_counter_tick

(

fps_counter_t *

counter

)

#include <include/ascii-chat/ui/fps_counter.h>

Record a frame timestamp.

Parameters

counter

FPS counter (must not be NULL)

Call this immediately after a frame write completes to record the output throughput. Uses nanosecond-precision timing.

Definition at line 78 of file fps_counter.c.

                                              {
  fps_counter_tick_at(counter, time_get_ns());
}

References fps_counter_tick_at().

fps_counter_tick_at()

void fps_counter_tick_at	(	fps_counter_t *	counter,
		uint64_t	now )

#include <include/ascii-chat/ui/fps_counter.h>

Record/read using an explicit monotonic timestamp, in nanoseconds.

Definition at line 89 of file fps_counter.c.

                                                               {
  if (!counter) {
    return;
  }
 
  if (counter->count) {
    uint64_t previous = counter->frame_times[(counter->head + FPS_WINDOW_SIZE - 1) % FPS_WINDOW_SIZE];
    if (now <= previous || now - previous >= 2000000000ULL)
      fps_counter_reset(counter);
  }
 
  // Record current time at head position
  counter->frame_times[counter->head] = now;
 
  // Advance head pointer with wraparound
  counter->head = (counter->head + 1) % FPS_WINDOW_SIZE;
 
  // Track how many valid entries we have (up to FPS_WINDOW_SIZE)
  if (counter->count < FPS_WINDOW_SIZE) {
    counter->count++;
  }
}

References fps_counter_s::count, fps_counter_reset(), FPS_WINDOW_SIZE, fps_counter_s::frame_times, and fps_counter_s::head.

Referenced by fps_counter_frame_end(), and fps_counter_tick().

fps_counter_write_begin()

void fps_counter_write_begin

(

fps_counter_t *

counter

)

#include <include/ascii-chat/ui/fps_counter.h>

Definition at line 178 of file fps_counter.c.

                                                     {
  if (counter && counter->measuring)
    counter->write_start = time_get_ns();
}

References fps_counter_s::measuring, and fps_counter_s::write_start.

Referenced by ui_controller_write().

fps_counter_write_end()

void fps_counter_write_end	(	fps_counter_t *	counter,
		bool	complete )

#include <include/ascii-chat/ui/fps_counter.h>

Definition at line 183 of file fps_counter.c.

                                                                  {
  if (!counter || !counter->measuring)
    return;
  counter->frame_write_ns += time_get_ns() - counter->write_start;
  counter->failed |= !complete;
  counter->written |= complete;
}

References fps_counter_s::failed, fps_counter_s::frame_write_ns, fps_counter_s::measuring, fps_counter_s::write_start, and fps_counter_s::written.

Referenced by ui_controller_write().

keyboard_help_check_signal_cancel()

bool keyboard_help_check_signal_cancel

(

void

)

#include <include/ascii-chat/tui/keyboard_help.h>

Check if help screen closure was requested by signal handler.

Returns

true if signal requested help closure (and clears the flag), false otherwise

Called by render loop to detect and handle Ctrl+C while help is active. Uses atomic compare-and-swap to clear flag while returning the previous value.

Note

Thread-safe using atomic operations

Definition at line 1480 of file src/common/session/display.c.

                                             {
  bool expected = true;
  return atomic_cas_bool(&g_help_signal_cancel, &expected, false);
}

Referenced by session_render_loop(), and ui_input_read_key().

keyboard_help_is_active()

bool keyboard_help_is_active

(

session_display_ctx_t *

ctx

)

#include <include/ascii-chat/tui/keyboard_help.h>

Check if keyboard help is currently active.

Parameters

ctx	Display context (must not be NULL)

Returns

true if keyboard help is active, false otherwise

Non-blocking check of keyboard help state.

Note

Thread-safe: Uses atomic load

Definition at line 1485 of file src/common/session/display.c.

                                                         {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return false;
  }
 
  // Disable help in snapshot mode only - allow help state check even if stdin/stdout aren't TTYs
  if (GET_OPTION(snapshot_mode)) {
    return false;
  }
 
  return ui_controller_interactive_screen() == UI_SCREEN_HELP;
}

References ERROR_INVALID_PARAM, GET_OPTION, SET_ERRNO, ui_controller_interactive_screen(), and UI_SCREEN_HELP.

Referenced by display_render_frame(), and keyboard_help_render().

keyboard_help_is_active_global()

bool keyboard_help_is_active_global

(

void

)

#include <include/ascii-chat/tui/keyboard_help.h>

Check if keyboard help is active (global accessor for signal handlers).

Returns

true if keyboard help is active, false otherwise

Signal-handler-safe version of keyboard_help_is_active() that doesn't require passing a context. Used by Ctrl+C handler to check if help is active before deciding to exit.

Note

Safe to call from signal handlers

Definition at line 1502 of file src/common/session/display.c.

                                          {
  session_display_ctx_t *ctx = get_current_display_ctx();
  return ctx && !ui_controller_is_blocked() && (ui_controller_interactive_screen() == UI_SCREEN_HELP);
}

References ui_controller_interactive_screen(), ui_controller_is_blocked(), and UI_SCREEN_HELP.

keyboard_help_parent_screen()

int keyboard_help_parent_screen

(

void

)

#include <include/ascii-chat/tui/keyboard_help.h>

Definition at line 16 of file keyboard_help.c.

                                      {
  return atomic_load(&g_help_parent);
}

Referenced by keyboard_help_toggle_terminal(), ui_controller_current_screen(), ui_controller_write(), and ui_input_read_key().

keyboard_help_render()

void keyboard_help_render

(

session_display_ctx_t *

ctx

)

#include <include/ascii-chat/tui/keyboard_help.h>

Render keyboard help TUI overlay.

Parameters

ctx	Display context (must not be NULL)

Renders a centered keyboard help screen showing:

• Keyboard shortcuts and their functions
• Current program state values:
  • Volume (displayed as bar graph: ████████░░ 80%)
  • Color mode (Mono, 16-color, 256-color, Truecolor)
  • Webcam flip state (Normal or Flipped)
  • Audio status (Enabled or Disabled)
  • Mute status (in volume display)

Layout:

• Centered horizontally: col = (term_width - box_width) / 2
• Centered vertically: row = (term_height - box_height) / 2
• Border: Box drawing chars (╔═╗║╚╝) with ASCII fallback (+|-) for UTF-8-less terminals

Edge Cases:

• Terminal too small: Shows simplified help or warning
• Non-TTY: Skips rendering (no terminal for display)

Note

Reads live option values via GET_OPTION() - values reflect current state

Uses session_display_write_raw() for atomic terminal output

Definition at line 80 of file keyboard_help.c.

                                                      {
  if (ctx && keyboard_help_is_active(ctx))
    ui_controller_redraw();
}

References keyboard_help_is_active(), and ui_controller_redraw().

Referenced by display_render_frame().

keyboard_help_screen_name()

const char * keyboard_help_screen_name

(

int

parent

)

#include <include/ascii-chat/tui/keyboard_help.h>

Fixed telemetry identity matching the help menu rendered for this parent.

Definition at line 20 of file keyboard_help.c.

                                                  {
  switch (parent) {
  case UI_SCREEN_STATS:
    return "stats_help";
  case UI_SCREEN_SYNC:
    return "sync_help";
  case UI_SCREEN_ERRNO:
    return "errno_help";
  case UI_SCREEN_PROMPT:
    return "media_input_help";
  case UI_SCREEN_MDNS:
    return "mdns_help";
  case UI_SCREEN_UPDATE:
    return "update_help";
  case UI_SCREEN_ERROR:
    return "error_help";
  default:
    return "help";
  }
}

References UI_SCREEN_ERRNO, UI_SCREEN_ERROR, UI_SCREEN_MDNS, UI_SCREEN_PROMPT, UI_SCREEN_STATS, UI_SCREEN_SYNC, and UI_SCREEN_UPDATE.

Referenced by keyboard_help_toggle_terminal().

keyboard_help_signal_cancel()

void keyboard_help_signal_cancel

(

void

)

#include <include/ascii-chat/tui/keyboard_help.h>

Request help screen closure from signal handler (Ctrl+C).

Signal-handler-safe way to request that the help screen be closed. Sets an atomic flag that the render loop checks. The render loop then toggles off the help screen and continues running.

Note

Safe to call from signal handlers

Definition at line 1475 of file src/common/session/display.c.

                                       {
  atomic_store_bool(&g_help_signal_cancel, true);
}

Referenced by keyboard_help_toggle_global().

keyboard_help_toggle()

void keyboard_help_toggle

(

session_display_ctx_t *

ctx

)

#include <include/ascii-chat/tui/keyboard_help.h>

Toggle keyboard help on/off.

Parameters

ctx	Display context (must not be NULL)

Atomically toggles the keyboard help active state. When active, the keyboard help is displayed and frame rendering is suppressed. Network reception continues in the background.

Note

Shares the controller selection with logs, sync and media input

Definition at line 75 of file keyboard_help.c.

                                                      {
  if (ctx)
    keyboard_help_toggle_terminal(STDOUT_FILENO);
}

References keyboard_help_toggle_terminal().

Referenced by session_render_loop().

keyboard_help_toggle_global()

void keyboard_help_toggle_global

(

void

)

#include <include/ascii-chat/tui/keyboard_help.h>

Toggle keyboard help (global accessor for signal handlers).

Signal-handler-safe version of keyboard_help_toggle() that doesn't require passing a context. Used by Ctrl+C handler to close the help screen instead of exiting the app.

Note

Safe to call from signal handlers

Definition at line 1507 of file src/common/session/display.c.

                                       {
  keyboard_help_signal_cancel();
}

References keyboard_help_signal_cancel().

keyboard_help_toggle_terminal()

void keyboard_help_toggle_terminal

(

int

fd

)

#include <include/ascii-chat/tui/keyboard_help.h>

Shared mode-aware help without a media display dependency.

Definition at line 51 of file keyboard_help.c.

                                           {
  int parent =
      ui_controller_current_screen() == UI_SCREEN_HELP ? keyboard_help_parent_screen() : ui_controller_current_screen();
  ascii_otel_ui_usage(keyboard_help_screen_name(parent), "shortcut", 0);
  if (ui_controller_current_screen() == UI_SCREEN_HELP) {
    // Keep the underlying worker active throughout dismissal. An intermediate
    // empty selection could make it retire its screen after we restore it.
    ui_controller_dismiss(UI_SCREEN_HELP, keyboard_help_previous_interactive());
    return;
  }
  if (parent == UI_SCREEN_ERROR)
    ascii_otel_ui_usage("error", "help_viewed", 0);
  atomic_store(&g_help_previous, ui_controller_interactive_screen());
  atomic_store(&g_help_parent, ui_controller_current_screen());
  terminal_size_t minimum;
  char *text =
      ui_session_context_help_render(ui_controller_size(), (ui_screen_t)keyboard_help_parent_screen(), &minimum);
  if (!text)
    return;
  if (!GET_OPTION(snapshot_mode))
    (void)ui_controller_submit(UI_SCREEN_HELP, fd, minimum, render_help_snapshot, &fd, sizeof(fd));
  SAFE_FREE(text);
}

References ascii_otel_ui_usage(), GET_OPTION, keyboard_help_parent_screen(), keyboard_help_previous_interactive(), keyboard_help_screen_name(), SAFE_FREE, ui_controller_current_screen(), ui_controller_dismiss(), ui_controller_interactive_screen(), ui_controller_size(), ui_controller_submit(), UI_SCREEN_ERROR, UI_SCREEN_HELP, and ui_session_context_help_render().

Referenced by keyboard_help_toggle(), ui_controller_first_use_key(), and ui_input_read_key().

session_audio_add_source()

asciichat_error_t session_audio_add_source	(	session_audio_ctx_t *	ctx,
		uint32_t	source_id )

#include <src/common/session/audio.h>

Add an audio source for mixing (host only).

Parameters

ctx	Audio context (must not be NULL, must be host context)
source_id	Unique identifier for this source

Returns

ASCIICHAT_OK on success, error code on failure

Registers a new audio source for the mixer. Each participant should have a unique source_id.

Note

Only available when context was created with is_host=true.

Definition at line 243 of file src/common/session/audio.c.

                                                                                         {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid context");
  }
 
  if (!ctx->is_host) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not a host context");
  }
 
  // Check if source already exists
  for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
    if (ctx->sources[i].active && ctx->sources[i].source_id == source_id) {
      return ASCIICHAT_OK; // Already registered
    }
  }
 
  // Find empty slot
  for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
    if (!ctx->sources[i].active) {
      ctx->sources[i].source_id = source_id;
      ctx->sources[i].active = true;
      ctx->sources[i].buffer = audio_ring_buffer_create_format(AUDIO_CHANNELS, false);
      if (!ctx->sources[i].buffer) {
        ctx->sources[i].active = false;
        return SET_ERRNO(ERROR_MEMORY, "Failed to create audio buffer for source");
      }
      ctx->source_count++;
      return ASCIICHAT_OK;
    }
  }
 
  return SET_ERRNO(ERROR_RESOURCE_EXHAUSTED, "Maximum audio sources reached");
}

References session_audio_source_t::active, ASCIICHAT_OK, AUDIO_CHANNELS, audio_ring_buffer_create_format(), session_audio_source_t::buffer, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_RESOURCE_EXHAUSTED, session_audio_ctx::initialized, session_audio_ctx::is_host, SESSION_AUDIO_MAX_SOURCES, SET_ERRNO, session_audio_ctx::source_count, session_audio_source_t::source_id, and session_audio_ctx::sources.

session_audio_create()

session_audio_ctx_t * session_audio_create

(

bool

is_host

)

#include <src/common/session/audio.h>

Create a new session audio context.

Parameters

is_host

true if this context is for a session host (enables mixing)

Returns

Pointer to audio context, or NULL on failure

Creates and initializes a session audio context. Hosts get audio mixing capabilities while participants only get basic capture/playback.

Note

Call session_audio_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 88 of file src/common/session/audio.c.

                                                        {
  // Allocate context
  session_audio_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_audio_ctx_t), session_audio_ctx_t *);
 
  ctx->is_host = is_host;
  ctx->running = false;
 
  // Initialize underlying audio context
  asciichat_error_t result = audio_init(&ctx->audio_ctx);
  if (result != ASCIICHAT_OK) {
    log_error("Failed to initialize audio context: %d", result);
    SAFE_FREE(ctx);
    return NULL;
  }
 
  // Initialize mixing resources for host
  if (is_host) {
    // Allocate mix buffer (enough for one audio buffer worth)
    ctx->mix_buffer_size = AUDIO_BUFFER_SIZE * 4; // Extra space for safety
    ctx->mix_buffer = SAFE_CALLOC(ctx->mix_buffer_size, sizeof(float), float *);
 
    // Initialize source array
    for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
      ctx->sources[i].source_id = 0;
      ctx->sources[i].active = false;
      ctx->sources[i].buffer = NULL;
    }
    ctx->source_count = 0;
  }
 
  ctx->initialized = true;
  return ctx;
}

References session_audio_source_t::active, ASCIICHAT_OK, AUDIO_BUFFER_SIZE, session_audio_ctx::audio_ctx, audio_init(), session_audio_source_t::buffer, session_audio_ctx::initialized, session_audio_ctx::is_host, log_error, session_audio_ctx::mix_buffer, session_audio_ctx::mix_buffer_size, session_audio_ctx::running, SAFE_CALLOC, SAFE_FREE, SESSION_AUDIO_MAX_SOURCES, session_audio_ctx::source_count, session_audio_source_t::source_id, and session_audio_ctx::sources.

Referenced by session_host_start_render(), and session_participant_start_audio().

session_audio_destroy()

void session_audio_destroy

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Destroy session audio context and free resources.

Parameters

ctx	Audio context to destroy (can be NULL)

Stops all audio streams, cleans up mixers (if host), and releases all resources. Safe to call with NULL.

Definition at line 122 of file src/common/session/audio.c.

                                                     {
  if (!ctx) {
    return;
  }
 
  // Stop audio if running
  if (ctx->running) {
    session_audio_stop(ctx);
  }
 
  // Cleanup host-specific resources
  if (ctx->is_host) {
    // Destroy source buffers
    for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
      if (ctx->sources[i].buffer) {
        audio_ring_buffer_destroy(ctx->sources[i].buffer);
        ctx->sources[i].buffer = NULL;
      }
    }
 
    // Free mix buffer
    if (ctx->mix_buffer) {
      SAFE_FREE(ctx->mix_buffer);
    }
  }
 
  // Destroy underlying audio context
  audio_destroy(&ctx->audio_ctx);
  client_audio_pipeline_destroy(ctx->pipeline);
 
  ctx->initialized = false;
  SAFE_FREE(ctx);
}

References session_audio_ctx::audio_ctx, audio_destroy(), audio_ring_buffer_destroy(), session_audio_source_t::buffer, client_audio_pipeline_destroy(), session_audio_ctx::initialized, session_audio_ctx::is_host, session_audio_ctx::mix_buffer, session_audio_ctx::pipeline, session_audio_ctx::running, SAFE_FREE, SESSION_AUDIO_MAX_SOURCES, session_audio_stop(), and session_audio_ctx::sources.

Referenced by session_host_destroy(), session_host_stop_render(), and session_participant_stop_audio().

session_audio_is_running()

bool session_audio_is_running

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Check if audio is currently running.

Parameters

ctx	Audio context (can be NULL)

Returns

true if audio is active, false otherwise

Definition at line 212 of file src/common/session/audio.c.

                                                        {
  if (!ctx || !ctx->initialized) {
    return false;
  }
  return ctx->running;
}

References session_audio_ctx::initialized, and session_audio_ctx::running.

session_audio_mix_excluding()

size_t session_audio_mix_excluding	(	session_audio_ctx_t *	ctx,
		uint32_t	exclude_id,
		float *	output,
		size_t	num_samples )

#include <src/common/session/audio.h>

Mix all sources except one and return the result (host only).

Parameters

ctx	Audio context (must not be NULL, must be host context)
exclude_id	Source ID to exclude from mix (for echo prevention)
output	Output buffer for mixed audio (must not be NULL)
num_samples	Number of samples to mix

Returns

Number of samples actually mixed

Mixes audio from all registered sources except exclude_id. This allows sending each participant a mix of all other participants without their own audio (preventing echo).

Note

Only available when context was created with is_host=true.

Definition at line 319 of file src/common/session/audio.c.

                                                                                                                     {
  if (!ctx || !ctx->initialized || !output || num_samples == 0) {
    return 0;
  }
 
  if (!ctx->is_host) {
    return 0;
  }
 
  // Initialize output to silence
  memset(output, 0, num_samples * sizeof(float));
 
  // Ensure we have a mix buffer
  if (!ctx->mix_buffer || num_samples > ctx->mix_buffer_size) {
    return 0;
  }
 
  int sources_mixed = 0;
 
  // Mix all active sources except the excluded one
  for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
    if (!ctx->sources[i].active || ctx->sources[i].source_id == exclude_id) {
      continue;
    }
 
    if (!ctx->sources[i].buffer) {
      continue;
    }
 
    // Read samples from this source
    size_t samples_read = audio_ring_buffer_read(ctx->sources[i].buffer, ctx->mix_buffer, num_samples);
 
    if (samples_read == 0) {
      continue;
    }
 
    // Add to output mix
    for (size_t j = 0; j < samples_read; j++) {
      output[j] += ctx->mix_buffer[j];
    }
 
    sources_mixed++;
  }
 
  // Apply simple clipping prevention if multiple sources were mixed
  if (sources_mixed > 1) {
    float scale = 1.0f / (float)sources_mixed;
    for (size_t i = 0; i < num_samples; i++) {
      output[i] *= scale;
      // Soft clipping
      if (output[i] > 1.0f) {
        output[i] = 1.0f;
      } else if (output[i] < -1.0f) {
        output[i] = -1.0f;
      }
    }
  }
 
  return num_samples;
}

References session_audio_source_t::active, audio_ring_buffer_read(), session_audio_source_t::buffer, session_audio_ctx::initialized, session_audio_ctx::is_host, session_audio_ctx::mix_buffer, session_audio_ctx::mix_buffer_size, SESSION_AUDIO_MAX_SOURCES, session_audio_source_t::source_id, and session_audio_ctx::sources.

session_audio_read_captured()

size_t session_audio_read_captured	(	session_audio_ctx_t *	ctx,
		float *	buffer,
		size_t	num_samples )

#include <src/common/session/audio.h>

Read captured audio samples.

Parameters

ctx	Audio context (must not be NULL)
buffer	Output buffer for audio samples (must not be NULL)
num_samples	Maximum number of samples to read

Returns

Number of samples actually read

Reads captured audio samples from the capture ring buffer. Samples are in float format (-1.0 to 1.0 range).

Definition at line 223 of file src/common/session/audio.c.

                                                                                                {
  if (!ctx || !ctx->initialized || !buffer || num_samples == 0) {
    return 0;
  }
 
  return audio_ring_buffer_read(ctx->audio_ctx.capture_buffer, buffer, num_samples);
}

References session_audio_ctx::audio_ctx, audio_ring_buffer_read(), audio_context_t::capture_buffer, and session_audio_ctx::initialized.

session_audio_remove_source()

void session_audio_remove_source	(	session_audio_ctx_t *	ctx,
		uint32_t	source_id )

#include <src/common/session/audio.h>

Remove an audio source from mixing (host only).

Parameters

ctx	Audio context (must not be NULL, must be host context)
source_id	Source identifier to remove

Unregisters an audio source from the mixer.

Note

Only available when context was created with is_host=true.

Definition at line 277 of file src/common/session/audio.c.

                                                                               {
  if (!ctx || !ctx->initialized || !ctx->is_host) {
    return;
  }
 
  for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
    if (ctx->sources[i].active && ctx->sources[i].source_id == source_id) {
      if (ctx->sources[i].buffer) {
        audio_ring_buffer_destroy(ctx->sources[i].buffer);
        ctx->sources[i].buffer = NULL;
      }
      ctx->sources[i].active = false;
      ctx->sources[i].source_id = 0;
      ctx->source_count--;
      return;
    }
  }
}

References session_audio_source_t::active, audio_ring_buffer_destroy(), session_audio_source_t::buffer, session_audio_ctx::initialized, session_audio_ctx::is_host, SESSION_AUDIO_MAX_SOURCES, session_audio_ctx::source_count, session_audio_source_t::source_id, and session_audio_ctx::sources.

session_audio_start_capture()

asciichat_error_t session_audio_start_capture

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Start audio capture (microphone input).

Parameters

ctx	Audio context (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts capturing audio from the default input device. Captured audio is available for transmission via session_audio_read_captured().

Definition at line 160 of file src/common/session/audio.c.

                                                                        {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid context");
  }
 
  // Use full duplex for proper echo cancellation
  return session_audio_start_duplex(ctx);
}

References ERROR_INVALID_PARAM, session_audio_ctx::initialized, session_audio_start_duplex(), and SET_ERRNO.

session_audio_start_duplex()

asciichat_error_t session_audio_start_duplex

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Start full-duplex audio (simultaneous capture and playback).

Parameters

ctx	Audio context (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts both capture and playback in a single full-duplex stream. This is preferred over separate start_capture/start_playback calls as it provides better echo cancellation support.

Definition at line 178 of file src/common/session/audio.c.

                                                                       {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid context");
  }
 
  if (ctx->running) {
    return ASCIICHAT_OK; // Already running
  }
 
  if (!ctx->pipeline) {
    client_audio_pipeline_config_t config = client_audio_pipeline_config_for_source(
        ctx->audio_ctx.capture_media_source && media_source_has_audio(ctx->audio_ctx.capture_media_source));
    ctx->pipeline = client_audio_pipeline_create(&config);
    if (!ctx->pipeline)
      return SET_ERRNO(ERROR_AUDIO, "Cannot initialize session audio processing");
    audio_set_pipeline(&ctx->audio_ctx, ctx->pipeline);
  }
  asciichat_error_t result = audio_start_duplex(&ctx->audio_ctx);
  if (result == ASCIICHAT_OK) {
    ctx->running = true;
  }
 
  return result;
}

References ASCIICHAT_OK, session_audio_ctx::audio_ctx, audio_set_pipeline(), audio_start_duplex(), audio_context_t::capture_media_source, client_audio_pipeline_config_for_source(), client_audio_pipeline_create(), ERROR_AUDIO, ERROR_INVALID_PARAM, session_audio_ctx::initialized, media_source_has_audio(), session_audio_ctx::pipeline, session_audio_ctx::running, and SET_ERRNO.

Referenced by session_audio_start_capture(), session_audio_start_playback(), and session_participant_start_audio().

session_audio_start_playback()

asciichat_error_t session_audio_start_playback

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Start audio playback (speaker output).

Parameters

ctx	Audio context (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts playback on the default output device. Audio for playback should be provided via session_audio_write_playback().

Definition at line 169 of file src/common/session/audio.c.

                                                                         {
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid context");
  }
 
  // Use full duplex for proper echo cancellation
  return session_audio_start_duplex(ctx);
}

References ERROR_INVALID_PARAM, session_audio_ctx::initialized, session_audio_start_duplex(), and SET_ERRNO.

session_audio_stop()

void session_audio_stop

(

session_audio_ctx_t *

ctx

)

#include <src/common/session/audio.h>

Stop all audio streams.

Parameters

ctx	Audio context (must not be NULL)

Stops capture, playback, and any mixing operations.

Definition at line 203 of file src/common/session/audio.c.

                                                  {
  if (!ctx || !ctx->initialized || !ctx->running) {
    return;
  }
 
  (void)audio_stop_duplex(&ctx->audio_ctx);
  ctx->running = false;
}

References session_audio_ctx::audio_ctx, audio_stop_duplex(), session_audio_ctx::initialized, and session_audio_ctx::running.

Referenced by session_audio_destroy().

session_audio_write_playback()

asciichat_error_t session_audio_write_playback	(	session_audio_ctx_t *	ctx,
		const float *	buffer,
		size_t	num_samples )

#include <src/common/session/audio.h>

Write audio samples for playback.

Parameters

ctx	Audio context (must not be NULL)
buffer	Input buffer with audio samples (must not be NULL)
num_samples	Number of samples to write

Returns

ASCIICHAT_OK on success, error code on failure

Writes audio samples to the playback ring buffer. Samples should be in float format (-1.0 to 1.0 range).

Definition at line 231 of file src/common/session/audio.c.

                                                                                                                  {
  if (!ctx || !ctx->initialized || !buffer) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  return audio_write_samples(&ctx->audio_ctx, buffer, (int)num_samples);
}

References session_audio_ctx::audio_ctx, audio_write_samples(), ERROR_INVALID_PARAM, session_audio_ctx::initialized, and SET_ERRNO.

session_audio_write_source()

asciichat_error_t session_audio_write_source	(	session_audio_ctx_t *	ctx,
		uint32_t	source_id,
		const float *	samples,
		size_t	num_samples )

#include <src/common/session/audio.h>

Write audio samples from a specific source (host only).

Parameters

ctx	Audio context (must not be NULL, must be host context)
source_id	Source identifier
samples	Audio samples from this source
num_samples	Number of samples

Returns

ASCIICHAT_OK on success, error code on failure

Provides audio data from a specific participant to the mixer.

Note

Only available when context was created with is_host=true.

Definition at line 296 of file src/common/session/audio.c.

                                                                 {
  if (!ctx || !ctx->initialized || !samples) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  if (!ctx->is_host) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not a host context");
  }
 
  // Find the source
  for (int i = 0; i < SESSION_AUDIO_MAX_SOURCES; i++) {
    if (ctx->sources[i].active && ctx->sources[i].source_id == source_id) {
      if (ctx->sources[i].buffer) {
        return audio_ring_buffer_write(ctx->sources[i].buffer, samples, (int)num_samples);
      }
      return SET_ERRNO(ERROR_INVALID_STATE, "Source buffer not initialized");
    }
  }
 
  return SET_ERRNO(ERROR_NOT_FOUND, "Audio source not found: %u", source_id);
}

References session_audio_source_t::active, audio_ring_buffer_write(), session_audio_source_t::buffer, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NOT_FOUND, session_audio_ctx::initialized, session_audio_ctx::is_host, SESSION_AUDIO_MAX_SOURCES, SET_ERRNO, session_audio_source_t::source_id, and session_audio_ctx::sources.

session_capture_at_end()

bool session_capture_at_end

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Check if capture source has reached end of stream.

Parameters

ctx	Capture context (must not be NULL)

Returns

true if end of stream reached, false otherwise

Useful for detecting end of file sources. Webcam and test pattern sources never reach end.

Definition at line 1106 of file common/session/capture.c.

                                                        {
  if (!ctx || !ctx->initialized || !ctx->source) {
    return true;
  }
 
  bool pending = ctx->loader_created;
  size_t next;
  if (pending || (!ctx->advance_failed && (media_playlist_adjacent(&ctx->playlist, 1, &next) ||
                                           (GET_OPTION(media_loop) && ctx->playlist.count > 1))))
    return false;
  if (media_source_get_type(ctx->source) == MEDIA_SOURCE_FILE && !GET_OPTION(snapshot_mode) &&
      !GET_OPTION(render_file)[0])
    return false;
  return media_source_at_end(ctx->source);
}

References session_capture_ctx::advance_failed, media_playlist_t::count, GET_OPTION, session_capture_ctx::initialized, session_capture_ctx::loader_created, media_playlist_adjacent(), media_source_at_end(), MEDIA_SOURCE_FILE, media_source_get_type(), session_capture_ctx::playlist, and session_capture_ctx::source.

session_capture_create()

session_capture_ctx_t * session_capture_create

(

const session_capture_config_t *

config

)

#include <src/common/session/capture.h>

Legacy function - creates either mirror or network capture based on options.

Maintained for backwards compatibility. New code should use session_mirror_capture_create() or session_network_capture_create() directly.

Parameters

config

Capture configuration

Returns

Capture context, or NULL on error

Deprecated

Use session_mirror_capture_create() or session_network_capture_create()

Definition at line 289 of file common/session/capture.c.

                                                                                      {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_CREATE);
  // Auto-create config from command-line options if NULL
  session_capture_config_t auto_config = {0};
  if (!config) {
    // Auto-initialization from GET_OPTION() only works when options have been parsed
    // Verify by checking if we can access options (would SET_ERRNO if not)
    const char *media_file = GET_OPTION(media_file);
    bool media_from_stdin = GET_OPTION(media_from_stdin);
 
    if (media_file[0] != '\0') {
      // File or stdin streaming
      auto_config.type = media_from_stdin ? MEDIA_SOURCE_STDIN : MEDIA_SOURCE_FILE;
      auto_config.path = media_file;
      auto_config.loop = GET_OPTION(media_loop) && !media_from_stdin;
    } else if (GET_OPTION(test_pattern)) {
      // Test pattern mode
      auto_config.type = MEDIA_SOURCE_TEST;
      auto_config.path = NULL;
    } else {
      // Webcam mode (default)
      static char webcam_index_str[SESSION_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE];
      unsigned int idx = GET_OPTION(webcam_index);
      safe_snprintf(webcam_index_str, sizeof(webcam_index_str), "%u", idx);
      auto_config.type = MEDIA_SOURCE_WEBCAM;
      auto_config.path = webcam_index_str;
      log_debug("Webcam mode: using device index %u", idx);
    }
 
    // Default settings suitable for local display
    auto_config.target_fps = DEFAULT_MAX_FPS;
    auto_config.resize_for_network = false;
    config = &auto_config;
  }
 
  // Check if we should exit before starting initialization
  if (config->should_exit_callback && config->should_exit_callback(config->callback_data)) {
    return NULL;
  }
 
  // Allocate context
  session_capture_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_capture_ctx_t), session_capture_ctx_t *);
 
  if (!ctx)
    return NULL;
  if (mutex_init(&ctx->source_mutex, "capture_source") != 0) {
    SAFE_FREE(ctx);
    return NULL;
  }
  if (mutex_init(&ctx->load_mutex, "capture_load") != 0) {
    mutex_destroy(&ctx->source_mutex);
    SAFE_FREE(ctx);
    return NULL;
  }
  ctx->media_locks_ready = true;
  if (config->type == MEDIA_SOURCE_FILE && config->path) {
    media_playlist_t configured = GET_OPTION(media_playlist);
    if (configured.count && strcmp(configured.paths[0], config->path) == 0)
      ctx->playlist = configured;
    else if (media_playlist_append(&ctx->playlist, config->path, strstr(config->path, "://") != NULL) != ASCIICHAT_OK)
      CLEAR_ERRNO();
  }
 
  // Store configuration
  ctx->target_fps = config->target_fps > 0 ? config->target_fps : DEFAULT_MAX_FPS;
  ctx->resize_for_network = config->resize_for_network;
  ctx->should_exit_callback = config->should_exit_callback;
  ctx->callback_data = config->callback_data;
 
  // Store audio configuration
  ctx->audio_enabled = config->enable_audio;
  ctx->audio_fallback_enabled = config->audio_fallback_to_mic;
  ctx->mic_audio_ctx = config->mic_audio_ctx;
  ctx->using_file_audio = false;
  ctx->file_has_audio = false;
 
  // Create media source from config type and path
  asciichat_errno_scope_t create_scope = errno_checkpoint();
  ctx->source = media_source_create_interruptible(config->type, config->path, playback_cancelled, ctx);
 
  if (!ctx->source) {
    // Preserve existing error if set, otherwise set generic error
    asciichat_error_context_t failure;
    asciichat_error_t existing_error = errno_peek_since(create_scope, &failure) ? failure.code : ASCIICHAT_OK;
    if (existing_error == ASCIICHAT_OK) {
      SET_ERRNO(ERROR_MEDIA_INIT, "Failed to create media source");
    }
    if (config->type == MEDIA_SOURCE_FILE && !playback_cancelled(ctx))
      NOTICE(WARNING, "MEDIA COULD NOT BE OPENED", "Failed to open media: %s", config->path ? config->path : "");
    if (ctx->media_locks_ready) {
      mutex_destroy(&ctx->load_mutex);
      mutex_destroy(&ctx->source_mutex);
    }
    SAFE_FREE(ctx);
    return NULL;
  }
 
  if (media_source_start_video(ctx->source) != ASCIICHAT_OK) {
    media_source_destroy(ctx->source);
    if (ctx->media_locks_ready) {
      mutex_destroy(&ctx->load_mutex);
      mutex_destroy(&ctx->source_mutex);
    }
    SAFE_FREE(ctx);
    return NULL;
  }
 
  if (config->type == MEDIA_SOURCE_WEBCAM && GET_OPTION(fps) == 0 && !GET_OPTION(waveform) && !GET_OPTION(fft)) {
    double source_fps = media_source_get_video_fps(ctx->source);
    if (source_fps >= 0.5 && source_fps <= 1000.0) {
      ctx->target_fps = (uint32_t)(source_fps + 0.5);
      log_info("Using negotiated webcam capture rate: %.3f FPS", source_fps);
    } else {
      log_warn("Webcam capture rate unavailable; using %u FPS", ctx->target_fps);
    }
  }
 
  if (config->type == MEDIA_SOURCE_FILE) {
    ctx->saved_matrix = GET_OPTION(matrix_rain);
    ctx->saved_waveform = GET_OPTION(waveform);
    ctx->saved_fft = GET_OPTION(fft);
    // Explicit visualization flags also apply to the initial media source.
  }
 
  // Set up exit callback on media source for graceful shutdown during I/O
  // This allows Ctrl+C to abort blocking FFmpeg calls like YouTube HTTP requests
  media_source_set_exit_callback(ctx->source, playback_cancelled, ctx);
 
  // Detect if media source has audio
  if (ctx->audio_enabled && ctx->source) {
    ctx->file_has_audio = media_source_has_audio(ctx->source);
    if (ctx->file_has_audio) {
      ctx->using_file_audio = true;
      log_info("Audio capture enabled: using file audio");
    } else if (ctx->audio_fallback_enabled && ctx->mic_audio_ctx) {
      ctx->using_file_audio = false;
      log_info("Audio capture enabled: file has no audio, using microphone fallback");
    } else {
      ctx->audio_enabled = false;
      log_debug("Audio capture disabled: no file audio and no fallback configured");
    }
  }
 
  // Enable loop if requested (only for file sources)
  if (config->loop && config->type == MEDIA_SOURCE_FILE && ctx->playlist.count <= 1) {
    media_source_set_loop(ctx->source, true);
  }
 
  // Set initial pause state if requested (only for file sources)
  // Note: We don't pause yet - we'll pause AFTER reading the first frame in the render loop
  // This is because paused sources return NULL from read_video()
  if (config->type == MEDIA_SOURCE_FILE && GET_OPTION(pause)) {
    ctx->should_pause_after_first_frame = true;
    log_debug("Will pause after first frame (--pause flag)");
  }
 
  // Perform initial seek if requested
  if (config->initial_seek_timestamp > 0.0) {
    log_debug("Seeking to %.2f seconds", config->initial_seek_timestamp);
    asciichat_error_t seek_err = media_source_seek(ctx->source, config->initial_seek_timestamp);
    if (seek_err != ASCIICHAT_OK) {
      log_warn("Failed to seek to %.2f seconds: %d", config->initial_seek_timestamp, seek_err);
      // Continue anyway - seeking is best-effort
    } else {
      log_debug("Successfully seeked to %.2f seconds", config->initial_seek_timestamp);
      // Codec buffers are flushed during seek, so next frame read will use correct position
 
      // Reset timing state after seek to prevent FPS calculation confusion
      // (frame_count and elapsed_time must match the new playback position)
      ctx->frame_count = 0;
      ctx->start_time_ns = time_get_ns();
    }
  }
 
  // Initialize FPS tracker
  // Note: Must allocate tracker_name on heap since fps_init stores a pointer to it
  char *tracker_name = SAFE_MALLOC(CAPTURE_TRACKER_NAME_BUFFER_SIZE, char *);
  if (!tracker_name) {
    media_source_destroy(ctx->source);
    if (ctx->media_locks_ready) {
      mutex_destroy(&ctx->load_mutex);
      mutex_destroy(&ctx->source_mutex);
    }
    SAFE_FREE(ctx);
    return NULL;
  }
  safe_snprintf(tracker_name, CAPTURE_TRACKER_NAME_BUFFER_SIZE, "CAPTURE_%u", ctx->target_fps);
  fps_init(&ctx->fps_tracker, (int)ctx->target_fps, tracker_name);
 
  // Record start time for FPS calculation (nanoseconds)
  ctx->start_time_ns = time_get_ns();
 
  ctx->initialized = true;
  capture_sync_entries(ctx, true);
  return ctx;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, session_capture_ctx::audio_enabled, session_capture_ctx::audio_fallback_enabled, session_capture_config_t::audio_fallback_to_mic, session_capture_config_t::callback_data, session_capture_ctx::callback_data, CAPTURE_TRACKER_NAME_BUFFER_SIZE, CLEAR_ERRNO, asciichat_error_context_t::code, media_playlist_t::count, DEFAULT_MAX_FPS, session_capture_config_t::enable_audio, errno_checkpoint(), errno_peek_since(), ERROR_MEDIA_INIT, session_capture_ctx::file_has_audio, fps_init(), session_capture_ctx::fps_tracker, session_capture_ctx::frame_count, GET_OPTION, session_capture_config_t::initial_seek_timestamp, session_capture_ctx::initialized, session_capture_ctx::load_mutex, log_debug, log_info, log_warn, session_capture_config_t::loop, session_capture_ctx::media_locks_ready, media_playlist_append(), media_source_create_interruptible(), media_source_destroy(), MEDIA_SOURCE_FILE, media_source_get_video_fps(), media_source_has_audio(), media_source_seek(), media_source_set_exit_callback(), media_source_set_loop(), media_source_start_video(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, session_capture_config_t::mic_audio_ctx, session_capture_ctx::mic_audio_ctx, NOTICE, session_capture_config_t::path, media_playlist_t::paths, session_capture_ctx::playlist, session_capture_config_t::resize_for_network, session_capture_ctx::resize_for_network, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, safe_snprintf(), session_capture_ctx::saved_fft, session_capture_ctx::saved_matrix, session_capture_ctx::saved_waveform, SESSION_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE, SET_ERRNO, session_capture_config_t::should_exit_callback, session_capture_ctx::should_exit_callback, session_capture_ctx::should_pause_after_first_frame, session_capture_ctx::source, session_capture_ctx::source_mutex, session_capture_ctx::start_time_ns, session_capture_config_t::target_fps, session_capture_ctx::target_fps, session_capture_config_t::type, and session_capture_ctx::using_file_audio.

Referenced by capture_init(), display_init(), session_mirror_capture_create(), and session_participant_start_video().

session_capture_destroy()

void session_capture_destroy

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Destroy session capture context and free resources.

Parameters

ctx	Capture context to destroy (can be NULL)

Cleans up the capture context and releases all resources including the media source. Safe to call with NULL.

Definition at line 486 of file common/session/capture.c.

                                                         {
  if (!ctx) {
    return;
  }
 
  if (ctx->loader_created) {
    atomic_store_bool(&ctx->load_cancel, true);
    ASCII_OTEL_SCOPE(MEDIA_TRANSITION_COMMIT);
    if (thread_join(&ctx->loader, NULL) != 0) {
      log_error("Cannot join media loader; retaining capture resources");
      return;
    }
    ui_controller_remove(UI_SCREEN_RENDER_PROGRESS);
  }
  if (ctx->loaded_frame)
    image_destroy(ctx->loaded_frame);
  if (ctx->initial_frame)
    image_destroy(ctx->initial_frame);
  if (ctx->loaded_source) {
    media_source_destroy(ctx->loaded_source);
    ctx->loaded_source = NULL;
  }
  if (ctx->media_locks_ready) {
    mutex_destroy(&ctx->load_mutex);
    mutex_destroy(&ctx->source_mutex);
  }
  if (ctx->webcam_source)
    media_source_destroy(ctx->webcam_source);
  if (ctx->last_media_frame)
    image_destroy(ctx->last_media_frame);
  if (ctx->empty_frame)
    image_destroy(ctx->empty_frame);
  face_follow_image_destroy(ctx->face_follow);
  ctx->face_follow = NULL;
  // Destroy media source
  if (ctx->source) {
    media_source_destroy(ctx->source);
    ctx->source = NULL;
  }
 
  // Free FPS tracker name (allocated in session_capture_create)
  if (ctx->fps_tracker.tracker_name) {
    char *temp = (char *)ctx->fps_tracker.tracker_name;
    SAFE_FREE(temp);
  }
 
  ctx->initialized = false;
  capture_sync_entries(ctx, false);
  SAFE_FREE(ctx);
}

References ASCII_OTEL_SCOPE, session_capture_ctx::empty_frame, session_capture_ctx::face_follow, face_follow_image_destroy(), session_capture_ctx::fps_tracker, image_destroy(), session_capture_ctx::initial_frame, session_capture_ctx::initialized, session_capture_ctx::last_media_frame, session_capture_ctx::load_cancel, session_capture_ctx::load_mutex, session_capture_ctx::loaded_frame, session_capture_ctx::loaded_source, session_capture_ctx::loader, session_capture_ctx::loader_created, log_error, session_capture_ctx::media_locks_ready, media_source_destroy(), SAFE_FREE, session_capture_ctx::source, session_capture_ctx::source_mutex, fps_t::tracker_name, ui_controller_remove(), UI_SCREEN_RENDER_PROGRESS, and session_capture_ctx::webcam_source.

Referenced by capture_cleanup(), display_cleanup(), and session_participant_stop_video().

session_capture_get_current_fps()

double session_capture_get_current_fps

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Get the current FPS being achieved by the capture source.

Parameters

ctx	Capture context (must not be NULL)

Returns

Current FPS, or 0.0 if not enough frames captured yet

Definition at line 1126 of file common/session/capture.c.

                                                                   {
  if (!ctx || !ctx->initialized || ctx->frame_count == 0) {
    return 0.0;
  }
 
  // Calculate elapsed time in nanoseconds then convert to seconds
  uint64_t elapsed_ns = time_elapsed_ns(ctx->start_time_ns, time_get_ns());
  double elapsed_sec = time_ns_to_s(elapsed_ns);
 
  if (elapsed_sec <= 0.0) {
    return 0.0;
  }
 
  return (double)ctx->frame_count / elapsed_sec;
}

References session_capture_ctx::frame_count, session_capture_ctx::initialized, session_capture_ctx::start_time_ns, and time_elapsed_ns().

session_capture_get_media_source()

void * session_capture_get_media_source

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Get the underlying media source from capture context.

Parameters

ctx	Capture context (must not be NULL)

Returns

Pointer to media source (cast to media_source_t*), or NULL if not available

Returns the underlying media_source_t for operations like seeking, pause/resume, or checking media type. Used by audio playback and interactive controls (keyboard input).

Note

Pointer is owned by the capture context and should not be freed

Use for advanced control like pause/resume or seek operations

Definition at line 1197 of file common/session/capture.c.

                                                                   {
  if (!ctx || !ctx->initialized || !ctx->source) {
    return NULL;
  }
  return (void *)ctx->source;
}

References session_capture_ctx::initialized, and session_capture_ctx::source.

Referenced by audio_connection_init(), capture_get_media_source(), client_protocol_start(), session_participant_start_audio(), and session_pipeline_create().

session_capture_get_target_fps()

uint32_t session_capture_get_target_fps

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Get the target FPS configured for this capture context.

Parameters

ctx	Capture context (must not be NULL)

Returns

Target FPS from configuration

Definition at line 1142 of file common/session/capture.c.

                                                                    {
  if (!ctx) {
    return 0;
  }
  return ctx->target_fps;
}

References session_capture_ctx::target_fps.

session_capture_has_audio()

bool session_capture_has_audio

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Check if capture source has audio available.

Parameters

ctx	Capture context (must not be NULL)

Returns

true if audio is available, false otherwise

Returns whether the capture source has audio and it is enabled.

Definition at line 1149 of file common/session/capture.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    return false;
  }
  return ctx->audio_enabled;
}

References session_capture_ctx::audio_enabled, and session_capture_ctx::initialized.

session_capture_is_valid()

bool session_capture_is_valid

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Check if capture context is initialized and valid.

Parameters

ctx	Capture context (can be NULL)

Returns

true if context is valid and initialized, false otherwise

Definition at line 1122 of file common/session/capture.c.

                                                          {
  return ctx != NULL && ctx->initialized && ctx->source != NULL;
}

References session_capture_ctx::initialized, and session_capture_ctx::source.

session_capture_process_for_transmission()

image_t * session_capture_process_for_transmission	(	session_capture_ctx_t *	ctx,
		image_t *	frame )

#include <src/common/session/capture.h>

Process a frame for network transmission (resize if needed).

Parameters

ctx	Capture context (must not be NULL)
frame	Input frame from session_capture_read_frame() (must not be NULL)

Returns

Processed image ready for transmission, or NULL on error

Resizes the frame to network-optimal dimensions if resize_for_network was enabled in the configuration. The returned image is a new allocation owned by the caller and must be freed with image_destroy().

Note

Returns a copy if no resizing is needed.

Caller owns the returned image and must call image_destroy().

Definition at line 1083 of file common/session/capture.c.

                                                                                              {
  image_t *output = NULL;
  if (session_capture_process_for_transmission_into(ctx, frame, &output) != ASCIICHAT_OK)
    return NULL;
  return output;
}

References ASCIICHAT_OK, and session_capture_process_for_transmission_into().

session_capture_read_audio()

size_t session_capture_read_audio	(	session_capture_ctx_t *	ctx,
		float *	buffer,
		size_t	num_samples )

#include <src/common/session/capture.h>

Read audio samples from capture source.

Parameters

ctx	Capture context (must not be NULL)
buffer	Output buffer for audio samples (must not be NULL)
num_samples	Number of samples to read

Returns

Number of samples actually read (0 if no audio available)

Reads audio samples from the media source. Audio is read from either:

• File if available and enabled
• Microphone if using fallback

Returns 0 if audio is not enabled or available.

Definition at line 1182 of file common/session/capture.c.

                                                                                                 {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_READ_AUDIO);
  session_capture_lock_source(ctx);
  size_t count = capture_read_audio(ctx, buffer, num_samples);
  session_capture_unlock_source(ctx);
  return count;
}

References ASCII_OTEL_SCOPE, session_capture_lock_source(), and session_capture_unlock_source().

session_capture_read_frame()

image_t * session_capture_read_frame

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Read the next video frame from the capture source.

Parameters

ctx	Capture context (must not be NULL)

Returns

Pointer to image frame, or NULL on error/end

Reads the next video frame from the media source. The returned image is owned by the media source and should NOT be freed by the caller.

Note

Frame is valid until next call or context destruction.

Check session_capture_at_end() to distinguish error from EOF.

Definition at line 1048 of file common/session/capture.c.

                                                                {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_READ_FRAME);
  if (!ctx)
    return NULL;
  session_capture_lock_source(ctx);
  image_t *frame = capture_read_frame(ctx);
  session_capture_unlock_source(ctx);
  return frame;
}

References ASCII_OTEL_SCOPE, session_capture_lock_source(), and session_capture_unlock_source().

session_capture_sleep_for_fps()

void session_capture_sleep_for_fps

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Sleep to maintain target frame rate.

Parameters

ctx	Capture context (must not be NULL)

Implements adaptive sleep to maintain the configured target frame rate. Call this once per frame capture iteration.

Note

Uses adaptive sleep for smooth frame rate limiting.

Definition at line 1090 of file common/session/capture.c.

                                                               {
  if (!ctx || !ctx->initialized || !ctx->source) {
    return;
  }
 
  uint64_t frame_interval_ns = NS_PER_SEC_INT / ctx->target_fps;
  if (frame_interval_ns == 0) {
    return;
  }
 
  uint64_t now_ns = time_get_ns();
  ctx->next_frame_deadline_ns = capture_pacing_deadline(ctx->next_frame_deadline_ns, now_ns, frame_interval_ns);
  if (ctx->next_frame_deadline_ns > now_ns)
    platform_sleep_ns(ctx->next_frame_deadline_ns - now_ns);
}

References session_capture_ctx::initialized, session_capture_ctx::next_frame_deadline_ns, NS_PER_SEC_INT, session_capture_ctx::source, and session_capture_ctx::target_fps.

session_capture_using_file_audio()

bool session_capture_using_file_audio

(

session_capture_ctx_t *

ctx

)

#include <src/common/session/capture.h>

Check if currently using file audio vs microphone fallback.

Parameters

ctx	Capture context (must not be NULL)

Returns

true if using file audio, false if using microphone or no audio

Useful for logging and debugging which audio source is active.

Definition at line 1190 of file common/session/capture.c.

                                                                  {
  if (!ctx || !ctx->initialized) {
    return false;
  }
  return ctx->using_file_audio;
}

References session_capture_ctx::initialized, and session_capture_ctx::using_file_audio.

session_client_like_get_stdin_reader()

terminal_fd_reader_t * session_client_like_get_stdin_reader

(

void

)

#include <src/common/session/client_like.h>

Get the stdin frame reader for ASCII-to-video rendering (stdin render mode only).

Returns the stdin reader created when stdin render mode is active. Only valid after session_client_like_run() is called and during run_fn execution. May be NULL if not in stdin render mode.

Returns

Pointer to terminal_fd_reader_t, or NULL if not in stdin render mode

Definition at line 105 of file client_like.c.

                                                                 {
  return g_stdin_reader;
}

session_display_begin_drain()

void session_display_begin_drain	(	session_display_ctx_t *	ctx,
		uint64_t	total,
		bool	total_known )

#include <src/common/session/display.h>

Definition at line 416 of file src/common/session/display.c.

                                                                                               {
  if (ctx && ctx->render_file) {
    ui_controller_remove(UI_SCREEN_HELP);
    render_file_begin_drain(ctx->render_file, total, total_known);
  }
}

References session_display_ctx::render_file, render_file_begin_drain(), ui_controller_remove(), and UI_SCREEN_HELP.

Referenced by session_pipeline_destroy().

session_display_clear()

void session_display_clear

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Clear the terminal screen.

Parameters

ctx	Display context (must not be NULL)

Clears the terminal screen and moves cursor to home position.

Definition at line 1370 of file src/common/session/display.c.

                                                       {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}

References session_display_ctx::snapshot_mode, and ui_controller_redraw().

session_display_convert_to_ascii()

char * session_display_convert_to_ascii	(	session_display_ctx_t *	ctx,
		const image_t *	image )

#include <src/common/session/display.h>

Convert an image to ASCII art using display context and command-line options.

Parameters

ctx	Display context (must not be NULL)
image	Image to convert (must not be NULL)

Returns

Dynamically allocated ASCII string, or NULL on error

Converts the given image to ASCII art using:

• Palette and terminal capabilities from display context
• Width, height, stretch, and aspect ratio settings from GET_OPTION()

This completely encapsulates ASCII conversion complexity so callers don't need to manage palette, terminal capabilities, or conversion options.

The returned string must be freed by caller with SAFE_FREE().

Definition at line 928 of file src/common/session/display.c.

                                                                                         {
  return convert_to_ascii(ctx, image, false);
}

Referenced by session_display_encode_frame().

session_display_create()

session_display_ctx_t * session_display_create

(

const session_display_config_t *

config

)

#include <src/common/session/display.h>

Create a new session display context.

Parameters

config

Display configuration (must not be NULL)

Returns

Pointer to display context, or NULL on failure

Creates and initializes a session display context with the specified configuration. Detects terminal capabilities and initializes palette.

Note

Call session_display_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 224 of file src/common/session/display.c.

                                                                                      {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_CREATE);
  if (GET_OPTION(zalgo) > 0 && (GET_OPTION(force_utf8) == UTF8_SETTING_FALSE ||
                                (GET_OPTION(force_utf8) == UTF8_SETTING_AUTO && terminal_is_stdout_tty() &&
                                 !detect_terminal_capabilities(options_terminal_settings()).utf8_support))) {
    SET_ERRNO(ERROR_USAGE, "--zalgo requires UTF-8 terminal output (on Windows, run chcp 65001 first)");
    return NULL;
  }
  // Auto-create config from command-line options if NULL
  session_display_config_t auto_config = {0};
  if (!config) {
    auto_config.snapshot_mode = GET_OPTION(snapshot_mode);
    auto_config.palette_type = GET_OPTION(palette_type);
    auto_config.custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL;
    auto_config.color_mode = TERM_COLOR_AUTO;
    config = &auto_config;
  }
 
  // Check if we should exit before starting initialization
  if (config->should_exit_callback && config->should_exit_callback(config->callback_data)) {
    return NULL;
  }
 
  // Allocate context
  session_display_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_display_ctx_t), session_display_ctx_t *);
 
  // Store configuration
  ctx->snapshot_mode = config->snapshot_mode;
  ctx->palette_type = config->palette_type;
  ctx->audio_playback_enabled = config->enable_audio_playback;
  ctx->audio_ctx = config->audio_ctx;
  ctx->render_fps = config->render_fps;
  atomic_store_bool(&ctx->first_frame, true);
  atomic_store_bool(&ctx->output_failed, false);
 
  // Get TTY info for direct terminal access
  ctx->tty_info = get_current_tty();
 
  // Presentation follows stdout. Opening a separate controlling terminal can
  // fail under ConPTY even though stdout is an interactive console.
  ctx->has_tty = terminal_is_stdout_tty();
  const char *stdout_output = GET_OPTION(render_file);
  bool owns_stdout = GET_OPTION(render_kitty) || strcmp(stdout_output, "--kitty") == 0 ||
                     strcmp(stdout_output, "-") == 0 || strcmp(stdout_output, "pipe:") == 0;
  if (owns_stdout)
    ctx->has_tty = false;
  if (ctx->has_tty) {
    // Retain the terminal before decoder/audio workers redirect process stdio
    // through LOG_IO. The first media submission must remain interactive too.
    int output = platform_dup(STDOUT_FILENO);
    if (output >= 0 && platform_isatty(output)) {
      if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0)
        platform_close(ctx->tty_info.fd);
      ctx->tty_info.fd = output;
      ctx->tty_info.owns_fd = true;
    } else if (output >= 0) {
      platform_close(output);
    }
  }
  if (ctx->has_tty && (ctx->tty_info.fd < 0 || !platform_isatty(ctx->tty_info.fd))) {
    if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0)
      platform_close(ctx->tty_info.fd);
    ctx->tty_info.fd = STDOUT_FILENO;
    ctx->tty_info.owns_fd = false;
  }
 
  // In piped mode, force all logs to stderr to prevent frame data corruption
  if (terminal_should_force_stderr()) {
    log_set_force_stderr(true);
    // Disable buffering for stdout to ensure frames appear immediately
    // Each frame ends with newline, so unbuffered output is critical for real-time display
    (void)setvbuf(stdout, NULL, _IONBF, 0);
  }
 
  // Also disable buffering for TTY mode to ensure smooth 40+ FPS animation
  setvbuf(stdout, NULL, _IONBF, 0);
 
  // Detect terminal capabilities
  ctx->caps = detect_terminal_capabilities(options_terminal_settings());
 
  // Set wants_padding based on terminal output mode
  // Enable padding for all rendering modes (including snapshot) to center output
  // The padding adds newlines at the top, which is useful for visual centering
  bool is_snapshot_mode = config->snapshot_mode;
  ctx->caps.wants_padding = true;
 
  // Calculate pad_height: when padding is enabled, add top padding for centering
  // Halfblock mode uses 2 source rows per output row, so padding is halved
  if (ctx->caps.wants_padding) {
    ctx->caps.pad_height = 5; // Halfblock needs half the padding (10 / 2 = 5)
  } else {
    ctx->caps.pad_height = 0;
  }
 
  log_debug("Padding mode: wants_padding=%d (snapshot=%d, has_tty=%d, stdin_tty=%d, stdout_tty=%d), pad_height=%zu",
            ctx->caps.wants_padding, is_snapshot_mode, ctx->has_tty, terminal_is_stdin_tty(), terminal_is_stdout_tty(),
            ctx->caps.pad_height);
 
  // Apply color mode override if specified
  if (config->color_mode != TERM_COLOR_AUTO) {
    ctx->caps.color_level = config->color_mode;
  }
 
  // Apply command-line overrides
  ctx->caps = apply_color_mode_override(ctx->caps, options_terminal_settings());
 
  // Initialize palette
  int palette_result = initialize_client_palette(config->palette_type, config->custom_palette, ctx->palette_chars,
                                                 &ctx->palette_len, ctx->luminance_palette);
  if (palette_result != ASCIICHAT_OK) {
    log_warn("Failed to initialize palette, using default");
    // Fall back to standard palette
    (void)initialize_client_palette(PALETTE_STANDARD, NULL, ctx->palette_chars, &ctx->palette_len,
                                    ctx->luminance_palette);
  }
 
  // Pre-warm UTF-8 palette cache during initialization (not during rendering)
  // This is expensive on first use (creates lookup tables), so warm it up now to avoid frame lag
  // This function is imported from lib/video/simd/common.h
  (void)get_utf8_palette_cache((const char *)ctx->palette_chars);
  log_debug("UTF-8 palette cache pre-warmed during display initialization");
 
  // Initialize ANSI fast lookup tables based on terminal capabilities
  if (ctx->caps.color_level == TERM_COLOR_TRUECOLOR) {
    ansi_fast_init();
  } else if (ctx->caps.color_level == TERM_COLOR_256) {
    ansi_fast_init_256color();
  } else if (ctx->caps.color_level == TERM_COLOR_16) {
    ansi_fast_init_16color();
  }
  // TERM_COLOR_MONO requires no init
 
  // Initialize ASCII output system if we have a TTY
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_init(ctx->tty_info.fd, false);
  }
 
  // Initialize digital rain effect if enabled
  if (GET_OPTION(matrix_rain)) {
    // Get terminal dimensions for grid size
    unsigned short int width_us = terminal_get_effective_width(GET_OPTION(width), 80);
    unsigned short int height_us = terminal_get_effective_height(GET_OPTION(height), 24);
 
    int width = (int)width_us;
    int height = (int)height_us;
 
    ctx->digital_rain = digital_rain_init(width, height);
    if (ctx->digital_rain) {
      // Set color from color filter if active
      color_filter_t filter = GET_OPTION(color_filter);
      digital_rain_set_color_from_filter(ctx->digital_rain, filter);
      log_info("Digital rain effect enabled: %dx%d grid", width, height);
    } else {
      log_warn("Failed to initialize digital rain effect");
    }
    ctx->last_frame_time_ns = time_get_ns();
  }
 
  if (GET_OPTION(fft) && audio_visualization_fft_init() != ASCIICHAT_OK) {
    session_display_destroy(ctx);
    return NULL;
  }
 
  display_sync_entries(ctx, true);
 
  // Initialize render-file unless media setup needs to determine its timing first.
  const char *render_file_opt = GET_OPTION(render_file);
  log_debug("render-file opt='%s' (len=%zu), deferred=%d", render_file_opt ? render_file_opt : "(null)",
            render_file_opt ? strlen(render_file_opt) : 0, config->defer_render_file);
  if (!config->defer_render_file) {
    asciichat_error_t render_err = session_display_init_render_file(ctx, config->render_fps);
    if (render_err != ASCIICHAT_OK) {
      log_error("render-file: Initialization failed %s", asciichat_error_format(NULL, render_err));
      asciichat_error_context_t error;
      bool has_error = HAS_ERRNO(&error);
      session_display_destroy(ctx);
      SET_ERRNO(render_err, "%s", has_error ? error.context_message : "Render-file initialization failed");
      return NULL;
    }
  }
 
  ctx->initialized = true;
  if (ctx->has_tty && !ctx->snapshot_mode) {
    const char initial[] = "\033[H";
    (void)ui_controller_present_retained(UI_SCREEN_MEDIA, ctx->tty_info.fd,
                                         (terminal_size_t){.cols = UI_MEDIA_MIN_COLS, .rows = UI_MEDIA_MIN_ROWS},
                                         initial, sizeof(initial) - 1);
  }
 
  return ctx;
}

References ansi_fast_init(), ansi_fast_init_16color(), ansi_fast_init_256color(), ASCII_OTEL_SCOPE, ascii_write_init(), asciichat_error_format(), ASCIICHAT_OK, session_display_config_t::audio_ctx, session_display_ctx::audio_ctx, session_display_ctx::audio_playback_enabled, audio_visualization_fft_init(), session_display_config_t::callback_data, session_display_ctx::caps, session_display_config_t::color_mode, asciichat_error_context_t::context_message, session_display_config_t::custom_palette, session_display_config_t::defer_render_file, session_display_ctx::digital_rain, digital_rain_init(), digital_rain_set_color_from_filter(), session_display_config_t::enable_audio_playback, ERROR_USAGE, session_display_ctx::first_frame, GET_OPTION, get_utf8_palette_cache(), HAS_ERRNO, session_display_ctx::has_tty, height, initialize_client_palette(), session_display_ctx::initialized, session_display_ctx::last_frame_time_ns, log_debug, log_error, log_info, log_set_force_stderr(), log_warn, session_display_ctx::luminance_palette, options_terminal_settings, session_display_ctx::output_failed, session_display_ctx::palette_chars, session_display_ctx::palette_len, PALETTE_STANDARD, session_display_config_t::palette_type, session_display_ctx::palette_type, platform_dup(), session_display_config_t::render_fps, session_display_ctx::render_fps, SAFE_CALLOC, session_display_destroy(), session_display_init_render_file(), SET_ERRNO, session_display_config_t::should_exit_callback, session_display_config_t::snapshot_mode, session_display_ctx::snapshot_mode, session_display_ctx::tty_info, ui_controller_present_retained(), UI_SCREEN_MEDIA, UTF8_SETTING_AUTO, UTF8_SETTING_FALSE, and width.

Referenced by display_init().

session_display_cursor_home()

void session_display_cursor_home

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Move cursor to home position (top-left).

Parameters

ctx	Display context (must not be NULL)

Moves the cursor to the top-left corner (1,1) of the terminal.

Definition at line 1375 of file src/common/session/display.c.

                                                             {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}

References session_display_ctx::snapshot_mode, and ui_controller_redraw().

session_display_destroy()

void session_display_destroy

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Definition at line 431 of file src/common/session/display.c.

                                                         {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  session_display_finish_render_file(ctx);
 
  ui_controller_remove(UI_SCREEN_HELP);
  ui_controller_remove(UI_SCREEN_MEDIA);
 
  // Cleanup ASCII rendering if we had a TTY
  // Don't reset terminal in snapshot mode to preserve the rendered output
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    ascii_write_destroy(ctx->tty_info.fd, !ctx->snapshot_mode);
  }
 
  // Close the controlling terminal if we opened it
  if (ctx->tty_info.owns_fd && ctx->tty_info.fd >= 0) {
    (void)platform_close(ctx->tty_info.fd);
    ctx->tty_info.fd = -1;
    ctx->tty_info.owns_fd = false;
  }
 
  // Cleanup digital rain effect
  if (ctx->digital_rain) {
    digital_rain_destroy(ctx->digital_rain);
    ctx->digital_rain = NULL;
  }
 
  image_destroy(ctx->resize_workspace);
  image_destroy(ctx->flip_workspace);
  image_destroy(ctx->filter_workspace);
  ctx->resize_workspace = ctx->flip_workspace = ctx->filter_workspace = NULL;
  SAFE_FREE(ctx->tty_frame_buffer);
  ascii_stabilizer_reset(&ctx->stabilizer);
  ascii_stabilizer_reset(&ctx->recording_stabilizer);
  SAFE_FREE(ctx->ascii_workspace.buf);
  ctx->initialized = false;
 
  // Clear the cached display context in splash state to prevent use-after-free
  // when worker threads try to access the display after it's been freed
  splash_clear_display_context();
 
  display_sync_entries(ctx, false);
  SAFE_FREE(ctx);
}

References ascii_stabilizer_reset(), session_display_ctx::ascii_workspace, ascii_write_destroy(), outbuf_t::buf, session_display_ctx::digital_rain, digital_rain_destroy(), ERROR_INVALID_PARAM, session_display_ctx::filter_workspace, session_display_ctx::flip_workspace, session_display_ctx::has_tty, image_destroy(), session_display_ctx::initialized, session_display_ctx::recording_stabilizer, session_display_ctx::resize_workspace, SAFE_FREE, session_display_finish_render_file(), SET_ERRNO, session_display_ctx::snapshot_mode, splash_clear_display_context(), session_display_ctx::stabilizer, session_display_ctx::tty_frame_buffer, session_display_ctx::tty_info, ui_controller_remove(), UI_SCREEN_HELP, and UI_SCREEN_MEDIA.

Referenced by session_display_create().

session_display_encode_frame()

asciichat_error_t session_display_encode_frame	(	session_display_ctx_t *	ctx,
		const image_t *	image,
		uint64_t	captured_ns )

#include <src/common/session/display.h>

Encode frame to render-file (FFmpeg only, no terminal output).

Parameters

ctx	Display context (must not be NULL)
image	Raw image to encode (must not be NULL)

Encodes image via render_file/FFmpeg encoder. No-op if –render-file not set. Used by the encode thread in the threaded pipeline.

Definition at line 1285 of file src/common/session/display.c.

                                                                                                                       {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_ENCODE_FRAME);
  static int call_count = 0;
  if (call_count++ < 5) {
    log_debug("ctx=%p, image=%p, captured_ns=%llu, ctx->render_file=%p", (void *)ctx, (void *)image,
              (unsigned long long)captured_ns, ctx ? (void *)ctx->render_file : NULL);
  }
 
  if (!ctx || !ctx->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL or uninitialized");
  }
 
  if (!image) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Image is NULL");
  }
 
  // Only encode if render_file is active
  if (!ctx->render_file) {
    log_warn_every(10 * US_PER_SEC_INT, "render_file is NULL, skipping encode");
    return ASCIICHAT_OK;
  }
 
  // Convert image to ASCII
  uint64_t conversion_started_ns = time_get_ns();
  char *ascii = session_display_convert_to_ascii(ctx, image);
  uint64_t converted_ns = time_get_ns();
  if (!ascii) {
    log_warn("Failed to convert image to ASCII");
    return SET_ERRNO(ERROR_MEDIA_INIT, "Cannot convert recording frame to ASCII");
  }
 
  // Write the same selected visualization used by the terminal to the render-file encoder.
  char *visualization_frame = NULL;
  const char *render_frame = ascii;
  if (GET_OPTION(waveform) || GET_OPTION(fft)) {
    visualization_frame = session_display_create_visualization_frame(ctx);
    if (visualization_frame)
      render_frame = visualization_frame;
  }
 
  uint64_t stats_record_start = time_get_ns();
  asciichat_error_t fe = render_file_write_frame(ctx->render_file, render_frame, captured_ns);
  uint64_t recorded_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "RECORD_FRAME: convert_ms=%.2f output_ms=%.2f total_ms=%.2f",
                  (double)(converted_ns - conversion_started_ns) / NS_PER_MS_INT,
                  (double)(recorded_ns - converted_ns) / NS_PER_MS_INT,
                  (double)(recorded_ns - conversion_started_ns) / NS_PER_MS_INT);
  stats_duration_record(stats_runtime_scope(), STATS_DURATION_RECORDING, time_get_ns() - stats_record_start);
  if (fe == ASCIICHAT_OK)
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_RECORDING_FRAMES, 1);
  SAFE_FREE(visualization_frame);
  if (fe != ASCIICHAT_OK) {
    log_warn_every(5 * US_PER_SEC_INT, "render-file: encode failed (%s)", asciichat_error_format(NULL, fe));
  }
 
  SAFE_FREE(ascii);
  return fe;
}

References ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_MEDIA_INIT, GET_OPTION, session_display_ctx::initialized, log_debug, log_debug_every, log_warn, log_warn_every, NS_PER_MS_INT, session_display_ctx::render_file, render_file_write_frame(), SAFE_FREE, session_display_convert_to_ascii(), SET_ERRNO, stats_counter_add(), STATS_COUNTER_RECORDING_FRAMES, stats_duration_record(), STATS_DURATION_RECORDING, stats_runtime_scope(), and US_PER_SEC_INT.

session_display_finish_render_file()

asciichat_error_t session_display_finish_render_file

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Destroy session display context and free resources.

Parameters

ctx	Display context to destroy (can be NULL)

Cleans up the display context, restores terminal state, and releases all resources. Safe to call with NULL.

Definition at line 423 of file src/common/session/display.c.

                                                                                 {
  if (!ctx || !ctx->render_file)
    return ASCIICHAT_OK;
  asciichat_error_t err = render_file_destroy(ctx->render_file);
  ctx->render_file = NULL;
  return err;
}

References ASCIICHAT_OK, session_display_ctx::render_file, and render_file_destroy().

Referenced by session_display_destroy().

session_display_get_caps()

const terminal_capabilities_t * session_display_get_caps

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get detected terminal capabilities.

Parameters

ctx	Display context (must not be NULL)

Returns

Pointer to terminal capabilities structure

Returns the detected terminal capabilities including color level, UTF-8 support, and render mode preferences.

Note

Returns NULL if context is NULL or not initialized.

Definition at line 501 of file src/common/session/display.c.

                                                                                    {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return &ctx->caps;
}

References session_display_ctx::caps, ERROR_INVALID_PARAM, session_display_ctx::initialized, and SET_ERRNO.

session_display_get_global_context()

session_display_ctx_t * session_display_get_global_context

(

void

)

#include <src/common/session/display.h>

Get the global display context (used for signal handlers and special cleanup).

Returns

Pointer to global display context, or NULL if not set

Retrieves the display context that was set via session_display_set_global_context(). Signal handlers and special modes (like discovery participant) use this to access the display without having a direct pointer.

Definition at line 1465 of file src/common/session/display.c.

                                                                {
  return get_current_display_ctx();
}

session_display_get_luminance_palette()

const char * session_display_get_luminance_palette

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the luminance mapping palette.

Parameters

ctx	Display context (must not be NULL)

Returns

Pointer to 256-entry luminance mapping array

Returns the luminance mapping palette for direct brightness-to-character lookup during rendering.

Definition at line 525 of file src/common/session/display.c.

                                                                              {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->luminance_palette;
}

References ERROR_INVALID_PARAM, session_display_ctx::initialized, session_display_ctx::luminance_palette, and SET_ERRNO.

session_display_get_palette_chars()

const char * session_display_get_palette_chars

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the palette characters string.

Parameters

ctx	Display context (must not be NULL)

Returns

Pointer to palette character string

Returns the initialized palette character string used for luminance-to-character mapping.

Definition at line 509 of file src/common/session/display.c.

                                                                          {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
  return ctx->palette_chars;
}

References ERROR_INVALID_PARAM, session_display_ctx::initialized, session_display_ctx::palette_chars, and SET_ERRNO.

session_display_get_palette_len()

size_t session_display_get_palette_len

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the palette character count.

Parameters

ctx	Display context (must not be NULL)

Returns

Number of characters in the palette

Definition at line 517 of file src/common/session/display.c.

                                                                   {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return 0;
  }
  return ctx->palette_len;
}

References ERROR_INVALID_PARAM, session_display_ctx::initialized, session_display_ctx::palette_len, and SET_ERRNO.

session_display_get_render_fps()

uint32_t session_display_get_render_fps

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the render FPS configured for file output.

Parameters

ctx	Display context (can be NULL)

Returns

Render FPS value, or 0 if ctx is NULL

Definition at line 550 of file src/common/session/display.c.

                                                                    {
  if (!ctx)
    return 0;
  return ctx->render_fps;
}

References session_display_ctx::render_fps.

Referenced by session_pipeline_create().

session_display_get_stdin_reader()

void * session_display_get_stdin_reader

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the stdin frame reader for ASCII-to-video rendering.

Parameters

ctx	Display context (must not be NULL)

Returns

Pointer to stdin reader, or NULL if not configured

Definition at line 541 of file src/common/session/display.c.

                                                                   {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return NULL;
  }
 
  return ctx->stdin_reader;
}

References ERROR_INVALID_PARAM, session_display_ctx::initialized, SET_ERRNO, and session_display_ctx::stdin_reader.

session_display_get_tty_fd()

int session_display_get_tty_fd

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Get the TTY file descriptor.

Parameters

ctx	Display context (must not be NULL)

Returns

TTY file descriptor, or -1 if no TTY available

Definition at line 533 of file src/common/session/display.c.

                                                           {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return -1;
  }
  return ctx->tty_info.fd;
}

References ERROR_INVALID_PARAM, session_display_ctx::initialized, SET_ERRNO, and session_display_ctx::tty_info.

session_display_has_audio_playback()

bool session_display_has_audio_playback

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Check if display has audio playback configured.

Parameters

ctx	Display context (must not be NULL)

Returns

true if audio playback is available, false otherwise

Definition at line 1380 of file src/common/session/display.c.

                                                                    {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL or uninitialized");
    return false;
  }
  return ctx->audio_playback_enabled;
}

References session_display_ctx::audio_playback_enabled, ERROR_INVALID_PARAM, session_display_ctx::initialized, and SET_ERRNO.

session_display_has_first_frame()

bool session_display_has_first_frame

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Check if the display has rendered its first frame.

Parameters

ctx	Display context (can be NULL)

Returns

true if first frame has been rendered, false if not yet rendered or ctx is NULL

Definition at line 565 of file src/common/session/display.c.

                                                                 {
  if (!ctx) {
    return false;
  }
  // Return true if first_frame flag is false (meaning first frame has been rendered)
  return !atomic_load_bool(&ctx->first_frame);
}

References session_display_ctx::first_frame.

session_display_has_render_file()

bool session_display_has_render_file

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Check if display has render-file configured.

Parameters

ctx	Display context (can be NULL)

Returns

true if render-file is configured, false otherwise

Definition at line 581 of file src/common/session/display.c.

                                                                 {
  if (!ctx) {
    return false;
  }
  return ctx->render_file != NULL;
}

References session_display_ctx::render_file.

Referenced by session_pipeline_create().

session_display_has_tty()

bool session_display_has_tty

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Check if display has a TTY (terminal) available.

Parameters

ctx	Display context (must not be NULL)

Returns

true if TTY is available, false otherwise

Returns whether the display has detected and opened a TTY. When no TTY is available, output goes to stdout.

Definition at line 493 of file src/common/session/display.c.

                                                         {
  if (!ctx || !ctx->initialized) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p", ctx);
    return false;
  }
  return ctx->has_tty;
}

References ERROR_INVALID_PARAM, session_display_ctx::has_tty, session_display_ctx::initialized, and SET_ERRNO.

Referenced by display_has_tty().

session_display_render_frame()

void session_display_render_frame	(	session_display_ctx_t *	ctx,
		const char *	frame_data )

#include <src/common/session/display.h>

Render an ASCII frame to the terminal.

Parameters

ctx	Display context (must not be NULL)
frame_data	ASCII frame data to render (must not be NULL)
is_final	true if this is the final frame (for snapshot mode)

Renders the ASCII frame to the terminal. Handles cursor positioning, RLE expansion if needed, and snapshot mode behavior.

In snapshot mode, renders all frames during the snapshot window. (Legacy function; new code should use split functions for threading.)

Definition at line 899 of file src/common/session/display.c.

                                                                                      {
  // Legacy function: shim that calls both new split functions for backward compatibility
  // This maintains API compatibility with existing code while delegating to specialized functions
 
  if (!ctx || !frame_data) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context or frame data is NULL");
    return;
  }
 
  // Write the selected visualization to the render file as well as the terminal.
  char *visualization_frame = NULL;
  const char *render_frame = frame_data;
  if (GET_OPTION(waveform) || GET_OPTION(fft)) {
    visualization_frame = session_display_create_visualization_frame(ctx);
    if (visualization_frame)
      render_frame = visualization_frame;
  }
 
  // Write ASCII to terminal (main thread output path)
  if (ctx && ctx->render_file) {
    render_file_set_live_timing(ctx->render_file);
    asciichat_error_t err = render_file_write_frame(ctx->render_file, render_frame, time_get_ns());
    if (err != ASCIICHAT_OK)
      log_warn_every(5 * US_PER_SEC_INT, "Recording received frame failed: %s", asciichat_error_format(NULL, err));
  }
  SAFE_FREE(visualization_frame);
  session_display_write_ascii(ctx, frame_data);
}

References asciichat_error_format(), ASCIICHAT_OK, ERROR_INVALID_PARAM, GET_OPTION, log_warn_every, session_display_ctx::render_file, render_file_set_live_timing(), render_file_write_frame(), SAFE_FREE, session_display_write_ascii(), SET_ERRNO, and US_PER_SEC_INT.

Referenced by display_render_frame(), and session_render_loop().

session_display_reset()

void session_display_reset

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Reset terminal to default state.

Parameters

ctx	Display context (must not be NULL)

Resets terminal attributes (colors, cursor visibility, etc.) to defaults. Useful for cleanup or error recovery.

Definition at line 1365 of file src/common/session/display.c.

                                                       {
  if (ctx && !ctx->snapshot_mode)
    ui_controller_redraw();
}

References session_display_ctx::snapshot_mode, and ui_controller_redraw().

Referenced by display_full_reset().

session_display_reset_first_frame()

void session_display_reset_first_frame

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Reset the first frame flag to allow splash screen to show again on next render.

Parameters

ctx	Display context (must not be NULL)

Used during reconnection attempts to re-enable splash screen display. After calling this, the next call to session_display_render_frame() will trigger splash cleanup logic, allowing the splash to be shown again.

Definition at line 573 of file src/common/session/display.c.

                                                                   {
  if (!ctx) {
    return;
  }
  // Reset first_frame flag to true so splash screen can be shown again on next render
  atomic_store_bool(&ctx->first_frame, true);
}

References session_display_ctx::first_frame.

session_display_set_global_context()

void session_display_set_global_context

(

session_display_ctx_t *

ctx

)

#include <include/ascii-chat/tui/keyboard_help.h>

Set the global display context (for signal handlers like Ctrl+C).

Parameters

ctx	Display context (NULL to clear)

Called by the render loop to register the current display context so that signal handlers can access it. This enables Ctrl+C to close the help screen instead of quitting when help is active.

Note

Must be called from the render loop startup/shutdown

Definition at line 1460 of file src/common/session/display.c.

                                                                    {
  atomic_ptr_store(&g_current_display_ctx, (void *)ctx);
}

Referenced by session_display_set_global_context_public(), and session_render_loop().

session_display_set_global_context_public()

void session_display_set_global_context_public

(

session_display_ctx_t *

ctx

)

#include <src/common/session/display.h>

Set the global display context (public setter for discovery cleanup).

Parameters

ctx	Display context to set, or NULL to clear

Sets the global display context. Signal handlers and special modes use this to track the active display context. Used by discovery participant mode to clear the global context after destroying the display early to prevent use-after-free in cleanup code.

Definition at line 1470 of file src/common/session/display.c.

                                                                           {
  session_display_set_global_context(ctx);
}

References session_display_set_global_context().

session_display_set_render_fps()

void session_display_set_render_fps	(	session_display_ctx_t *	ctx,
		uint32_t	fps )

#include <src/common/session/display.h>

Set the render FPS for file output encoding.

Parameters

ctx	Display context
fps	Target FPS for video encoding (detected from input media)

Definition at line 556 of file src/common/session/display.c.

                                                                              {
  if (!ctx)
    return;
  ctx->render_fps = fps;
  if (fps > 0) {
    log_debug("Updated render FPS to %u (for correct video duration)", fps);
  }
}

References log_debug, and session_display_ctx::render_fps.

session_display_set_snapshot_actual_duration()

void session_display_set_snapshot_actual_duration	(	session_display_ctx_t *	ctx,
		double	actual_duration_sec )

#include <src/common/session/display.h>

Set the actual wall-clock duration for snapshot mode frame timing.

Parameters

ctx	Display context (must not be NULL)
actual_duration_sec	Actual elapsed time in seconds

In snapshot mode, this function provides the actual wall-clock duration of frame capture, allowing the encoder to calculate correct frame durations so the output video spans exactly the specified duration.

Definition at line 1511 of file src/common/session/display.c.

                                                                                                          {
  log_debug("duration=%.3f, ctx=%p, render_file=%p", actual_duration_sec, (void *)ctx,
            ctx ? (void *)ctx->render_file : NULL);
 
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Session display context is NULL");
    return;
  }
 
  if (!ctx->render_file) {
    // Terminal snapshots have no render-file encoder; their duration is
    // governed by the capture loop and requires no additional action.
    return;
  }
 
  log_debug("  -> Passing duration %.3f to render_file encoder", actual_duration_sec);
  render_file_set_snapshot_actual_duration(ctx->render_file, actual_duration_sec);
}

References ERROR_INVALID_PARAM, log_debug, session_display_ctx::render_file, render_file_set_snapshot_actual_duration(), and SET_ERRNO.

Referenced by session_render_loop().

session_display_set_stdin_reader()

void session_display_set_stdin_reader	(	session_display_ctx_t *	ctx,
		void *	reader )

#include <src/common/session/display.h>

Set stdin frame reader for ASCII-to-video rendering.

Parameters

ctx	Display context (must not be NULL)
reader	Stdin frame reader (borrowed reference, not owned)

Only used when reading ASCII frames from stdin for rendering.

Definition at line 479 of file src/common/session/display.c.

                                                                                {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Display context is NULL");
    return;
  }
 
  ctx->stdin_reader = (terminal_fd_reader_t *)reader;
  log_debug("stdin_reader set");
}

References ERROR_INVALID_PARAM, log_debug, SET_ERRNO, and session_display_ctx::stdin_reader.

session_display_write_ascii()

void session_display_write_ascii	(	session_display_ctx_t *	ctx,
		const char *	frame_data )

#include <src/common/session/display.h>

Write ASCII frame to terminal only (no encoding).

Parameters

ctx	Display context (must not be NULL)
frame_data	ASCII frame data (must not be NULL)

Writes ANSI string to terminal/stdout without encoding to file. Used by the main thread in the threaded pipeline.

Definition at line 1530 of file src/common/session/display.c.

                                                                                {
  session_display_write_ascii_frame(ctx, ascii, true);
}

References session_display_write_ascii_frame().

Referenced by session_display_render_frame().

session_display_write_audio()

asciichat_error_t session_display_write_audio	(	session_display_ctx_t *	ctx,
		const float *	buffer,
		size_t	num_samples )

#include <src/common/session/display.h>

Write audio samples to playback buffer.

Parameters

ctx	Display context (must not be NULL)
buffer	Audio samples to write (must not be NULL)
num_samples	Number of samples to write

Returns

ASCIICHAT_OK on success, error code on failure

Writes audio samples to the playback ring buffer for playback through speakers. Used in mirror mode to play file audio or other audio sources.

Definition at line 1388 of file src/common/session/display.c.

                                                                                                                   {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_WRITE_AUDIO);
  if (!ctx || !ctx->initialized || !buffer || num_samples == 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, buffer=%p, num_samples=%zu", ctx, buffer,
                     num_samples);
  }
 
  if (!ctx->audio_playback_enabled || !ctx->audio_ctx) {
    // Audio not enabled, but not an error - just skip silently
    return ASCIICHAT_OK;
  }
 
  // For mirror mode with local files: write samples directly without jitter buffering
  // The jitter buffer is designed for network scenarios with irregular packet arrivals
  // For local playback, we just want raw samples flowing to the speakers
  audio_context_t *audio_ctx = (audio_context_t *)ctx->audio_ctx;
  if (audio_ctx && audio_ctx->playback_buffer) {
    audio_ring_buffer_t *rb = audio_ctx->playback_buffer;
 
    // Simple direct write: append samples to ring buffer without network-oriented complexity
    uint32_t write_idx = (uint32_t)atomic_load_u64(&rb->write_index);
    uint32_t read_idx = (uint32_t)atomic_load_u64(&rb->read_index);
 
    // Calculate available space in ring buffer
    uint32_t available = (read_idx - write_idx - 1) & (AUDIO_RING_BUFFER_SIZE - 1);
 
    if ((uint32_t)num_samples > available) {
      // Buffer full - just skip this write to avoid distortion from overwriting old audio
      return ASCIICHAT_OK;
    }
 
    // Direct memcpy to ring buffer, handling wrap-around
    uint32_t space_before_wrap = AUDIO_RING_BUFFER_SIZE - write_idx;
    if ((uint32_t)num_samples <= space_before_wrap) {
      memcpy(&rb->data[write_idx], buffer, num_samples * sizeof(float));
    } else {
      // Split write: first part to end of buffer, second part wraps to beginning
      uint32_t first_part = space_before_wrap;
      uint32_t second_part = num_samples - first_part;
      memcpy(&rb->data[write_idx], buffer, first_part * sizeof(float));
      memcpy(&rb->data[0], &buffer[first_part], second_part * sizeof(float));
    }
 
    // Update write index atomically
    atomic_store_u64(&rb->write_index, (write_idx + num_samples) % AUDIO_RING_BUFFER_SIZE);
 
    return ASCIICHAT_OK;
  }
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, session_display_ctx::audio_ctx, session_display_ctx::audio_playback_enabled, AUDIO_RING_BUFFER_SIZE, audio_ring_buffer::data, ERROR_INVALID_PARAM, session_display_ctx::initialized, audio_context_t::playback_buffer, audio_ring_buffer::read_index, SET_ERRNO, and audio_ring_buffer::write_index.

session_display_write_raw()

void session_display_write_raw	(	session_display_ctx_t *	ctx,
		const char *	data,
		size_t	len )

#include <src/common/session/display.h>

Render raw bytes to the terminal without frame processing.

Parameters

ctx	Display context (must not be NULL)
data	Raw byte data to write (must not be NULL)
len	Length of data in bytes

Directly writes raw bytes to the terminal without any frame processing. Useful for RLE-expanded frames or pre-formatted output.

Definition at line 1344 of file src/common/session/display.c.

                                                                                         {
  ASCII_OTEL_SCOPE(SESSION_DISPLAY_WRITE_RAW);
  if (!ctx || !ctx->initialized || !data || len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: ctx=%p, data=%p, len=%zu", ctx, data, len);
    return;
  }
 
  int fd = -1;
  if (ctx->has_tty && ctx->tty_info.fd >= 0) {
    fd = ctx->tty_info.fd;
  } else {
    fd = STDOUT_FILENO;
  }
 
  // Write all data with automatic retry on transient errors
  (void)ui_controller_write(fd, data, len);
 
  // Flush immediately after write to TTY to ensure data is sent
  (void)terminal_flush(fd);
}

References ASCII_OTEL_SCOPE, ERROR_INVALID_PARAM, session_display_ctx::has_tty, session_display_ctx::initialized, SET_ERRNO, session_display_ctx::tty_info, and ui_controller_write().

session_handle_keyboard_input()

void session_handle_keyboard_input	(	session_capture_ctx_t *	capture,
		session_display_ctx_t *	display,
		keyboard_key_t	key )

#include <src/common/session/keyboard_handler.h>

Handle keyboard input in a session.

Parameters

capture	Capture context (may be NULL for client-only mode)
display	Display context (may be NULL if not needed)
key	Keyboard key code from keyboard_key_t enumeration

Processes keyboard input and performs appropriate session actions. Supports both mirror mode (local capture) and client mode (network rendering).

Keyboard Controls:

• '?' key: Toggle help screen on/off (all modes)
• Left Arrow: Seek -30 seconds (file/URL sources only)
• Right Arrow: Seek +30 seconds (file/URL sources only)
• Up Arrow: Increase volume +10% (all modes with audio)
• Down Arrow: Decrease volume -10% (all modes with audio)
• Spacebar: Play/pause toggle (file/URL sources only)
• 'c' key: Cycle through color modes (mono → 16 → 256 → truecolor)
• 'm' key: Toggle mute (remembers previous volume for unmute)
• 'x' key: Flip webcam horizontally (mirroring)
• 'y' key: Flip webcam vertically

Source-specific behavior:

• Help screen: Works in all modes (toggles with '?')
• Seek/pause controls: Only work with file and URL sources (not webcam)
• Volume/mute: Work with any audio-capable source
• Color cycling: Works with all rendering modes
• Flip: Works with all capture sources (webcam, media files, etc.)

Audio volume:

• Volume range: [0.0, 1.0] (0% = silent, 100% = maximum/normal)
• Default volume: 1.0 (100%)
• Mute state: Remembers the previous non-zero volume when toggled back on
• Volume and mute controls show a right-side bar for 1.5 seconds after the last press
• Feedback works while paused; pausing alone does not show the bar
• Unrecognized keys are silently ignored (no error returned)

Thread safety:

• Safe to call from render thread (video/audio threads)
• Safe to call concurrently from multiple render threads
• Uses RCU-protected options for atomic updates
• No explicit locking required (option system handles synchronization)
• Does not block waiting for I/O or locks

Error handling:

• Always succeeds (void return)
• Invalid or unrecognized keys are silently ignored
• If capture is NULL (client-only mode), seek/pause requests are silently ignored
• If display is NULL (non-TTY mode), help screen toggle is silently ignored
• If audio system is unavailable, volume changes are silently ignored

Parameters

capture	NULL for client-only mode (network rendering), non-NULL for local capture
display	Display context for help screen toggle (may be NULL)
key	Valid key code from keyboard_key_t enum (0-127 for ASCII, special key codes)

Note

Safe to call without prior keyboard_init() (silently handles invalid keys)

In client-only mode, capture is NULL (seek/pause unavailable, other controls work)

Volume adjustments are immediate without audible artifacts

Mute persists across multiple mute toggles with volume memory

Definition at line 214 of file keyboard_handler.c.

                                                                                                                       {
  // Panic-exit bindings are global: they must bypass every modal TUI, prompt,
  // log search, and media shortcut so they remain available during a hang.
  if (key == 'Q' || key == KEY_SHIFT_ESCAPE) {
    platform_force_exit(1);
  }
 
  bool text_entry = log_search_is_entering();
  if (!text_entry && (key == '<' || key == '>')) {
    session_capture_skip_media(capture, key == '>' ? 1 : -1);
    return;
  }
  if (!text_entry && key == KEY_ESCAPE && session_capture_cancel_open(capture))
    return;
  if (!text_entry && (key == KEY_MEDIA_SUBMIT || key == KEY_PASTE || tui_shortcut_action(key) == TUI_SHORTCUT_MEDIA ||
                      key == 'v' || key == 'V')) {
    if ((tui_shortcut_action(key) == TUI_SHORTCUT_MEDIA) && ui_controller_interactive_screen() == UI_SCREEN_PROMPT) {
      ui_prompt_remove();
      return;
    }
    char input[SESSION_KEYBOARD_HANDLER_INPUT_BUFFER_SIZE] = {0},
         normalized[SESSION_KEYBOARD_HANDLER_NORMALIZED_BUFFER_SIZE];
    asciichat_error_t result = ASCIICHAT_OK;
    if (key == KEY_MEDIA_SUBMIT)
      result = ui_input_media_take(input, sizeof(input));
    else if (key == KEY_PASTE)
      result = ui_input_take_paste(input, sizeof(input));
    else if (key == 'v' || key == 'V')
      result = platform_clipboard_read(input, sizeof(input));
    if (result == ASCIICHAT_OK) {
      if (key != KEY_MEDIA_SUBMIT && input[0]) {
        media_playlist_t list;
        result = media_playlist_parse(input, &list);
        if (result == ASCIICHAT_OK)
          result = media_playlist_format(&list, normalized, sizeof(normalized));
        if (result == ASCIICHAT_OK)
          memcpy(input, normalized, strlen(normalized) + 1);
      }
      if (result == ASCIICHAT_OK && key != KEY_MEDIA_SUBMIT)
        result = ui_input_media_begin(input);
      if (result == ASCIICHAT_OK && key == KEY_MEDIA_SUBMIT)
        result = session_capture_open_playlist(capture, input);
    }
    if (key == KEY_MEDIA_SUBMIT)
      ui_prompt_remove();
    if (result != ASCIICHAT_OK) {
      asciichat_error_context_t error;
      if (HAS_ERRNO(&error))
        NOTICE(WARNING, "MEDIA INPUT", "%s", error.context_message);
      CLEAR_ERRNO();
    }
    return;
  }
  session_capture_lock_source(capture);
  handle_keyboard_input(capture, display, key);
  session_capture_unlock_source(capture);
}

References ASCIICHAT_OK, CLEAR_ERRNO, asciichat_error_context_t::context_message, HAS_ERRNO, KEY_ESCAPE, KEY_MEDIA_SUBMIT, KEY_PASTE, KEY_SHIFT_ESCAPE, log_search_is_entering(), media_playlist_format(), media_playlist_parse(), NOTICE, platform_clipboard_read(), platform_force_exit(), session_capture_cancel_open(), session_capture_lock_source(), session_capture_open_playlist(), session_capture_skip_media(), session_capture_unlock_source(), SESSION_KEYBOARD_HANDLER_INPUT_BUFFER_SIZE, SESSION_KEYBOARD_HANDLER_NORMALIZED_BUFFER_SIZE, tui_shortcut_action(), TUI_SHORTCUT_MEDIA, ui_controller_interactive_screen(), ui_input_media_begin(), ui_input_media_take(), ui_input_take_paste(), ui_prompt_remove(), and UI_SCREEN_PROMPT.

Referenced by display_poll_keyboard().

session_host_add_memory_participant()

uint32_t session_host_add_memory_participant

(

session_host_t *

host

)

#include <src/common/session/host.h>

Add a memory participant (host's own media).

Parameters

host	Host handle (must not be NULL)

Returns

Assigned participant ID on success, 0 on failure

Registers a memory participant for the host's own webcam/audio. This allows the host to participate in the session without network loopback. Media is injected directly into the mixer via session_host_inject_frame().

Note

on_client_join callback is invoked on successful registration.

Only one memory participant per host is supported.

Definition at line 1213 of file host.c.

                                                                   {
  if (!host || !host->initialized) {
    return 0;
  }
 
  mutex_lock(&host->clients_mutex);
 
  // Check if we have room
  if (host->client_count >= host->max_clients) {
    mutex_unlock(&host->clients_mutex);
    SET_ERRNO(ERROR_SESSION_FULL, "Maximum clients reached");
    return 0;
  }
 
  // Check if memory participant already exists (only one allowed)
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].participant_type == PARTICIPANT_TYPE_MEMORY) {
      mutex_unlock(&host->clients_mutex);
      SET_ERRNO(ERROR_INVALID_PARAM, "Memory participant already exists");
      return 0;
    }
  }
 
  // Find empty slot
  for (int i = 0; i < host->max_clients; i++) {
    if (!host->clients[i].active) {
      host->clients[i].participant_type = PARTICIPANT_TYPE_MEMORY;
      host->clients[i].client_id = host->next_client_id++;
      SAFE_STRNCPY(host->clients[i].ip_address, "memory", sizeof(host->clients[i].ip_address));
      host->clients[i].port = 0;
      host->clients[i].active = true;
      host->clients[i].video_active = true; // Memory participants always have active video/audio
      host->clients[i].audio_active = true;
      host->clients[i].connected_at = (uint64_t)time(NULL);
      host->clients[i].transport = NULL;
      host->clients[i].transport_ownership = ACIP_TRANSPORT_BORROWED;
 
      // Allocate media buffers (same as network clients)
      host->clients[i].incoming_video = image_new(480, 270);
      host->clients[i].incoming_audio =
          ringbuffer_create(sizeof(float), (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) * HOST_AUDIO_BUFFER_FRAMES);
 
      if (!host->clients[i].incoming_video || !host->clients[i].incoming_audio) {
        if (host->clients[i].incoming_video) {
          image_destroy(host->clients[i].incoming_video);
          host->clients[i].incoming_video = NULL;
        }
        if (host->clients[i].incoming_audio) {
          ringbuffer_destroy(host->clients[i].incoming_audio);
          host->clients[i].incoming_audio = NULL;
        }
        host->clients[i].active = false;
        mutex_unlock(&host->clients_mutex);
        SET_ERRNO(ERROR_MEMORY, "Failed to allocate media buffers for memory participant");
        return 0;
      }
 
      uint32_t participant_id = host->clients[i].client_id;
      host->client_count++;
 
      mutex_unlock(&host->clients_mutex);
 
      log_info("Added memory participant with ID %u", participant_id);
 
      // Invoke callback
      if (host->callbacks.on_client_join) {
        host->callbacks.on_client_join(host, participant_id, host->user_data);
      }
 
      return participant_id;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return 0;
}

References ACIP_TRANSPORT_BORROWED, AUDIO_CHANNELS, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_SESSION_FULL, HOST_AUDIO_BUFFER_FRAMES, image_destroy(), image_new(), log_info, OPUS_FRAME_SAMPLES, participant_id, PARTICIPANT_TYPE_MEMORY, ringbuffer_create(), ringbuffer_destroy(), SAFE_STRNCPY, and SET_ERRNO.

session_host_broadcast_frame()

asciichat_error_t session_host_broadcast_frame	(	session_host_t *	host,
		const char *	frame )

#include <src/common/session/host.h>

Broadcast ASCII frame to all clients.

Parameters

host	Host handle (must not be NULL)
frame	ASCII frame data (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Sends an ASCII frame to all connected clients.

Definition at line 1489 of file host.c.

                                                                                        {
  if (!host || !host->initialized || !frame) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  if (!host->running) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not running");
  }
 
  // Broadcast ASCII frame to all connected clients
  size_t frame_len = strlen(frame);
  asciichat_error_t result = ASCIICHAT_OK;
 
  mutex_lock(&host->clients_mutex);
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].transport) {
      asciichat_error_t send_result = acip_send_ascii_frame(host->clients[i].transport, &host->frame_workspace, frame,
                                                            frame_len, 80, 24, "session-host");
      if (send_result != ASCIICHAT_OK) {
        log_warn("Failed to send ASCII frame to client %u", host->clients[i].client_id);
        result = send_result;
      }
    }
  }
  mutex_unlock(&host->clients_mutex);
 
  return result;
}

References acip_send_ascii_frame(), ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, log_warn, and SET_ERRNO.

session_host_client_has_transport()

bool session_host_client_has_transport	(	session_host_t *	host,
		uint32_t	client_id )

#include <src/common/session/host.h>

Check if a specific client has an active ACIP transport.

Includes TCP, WebRTC, and WebSocket transports.

Parameters

host	Host handle (must not be NULL)
client_id	Client ID to check

Returns

true if a transport is set, false otherwise

Definition at line 1776 of file host.c.

                                                                                 {
  if (!host || !host->initialized) {
    return false;
  }
 
  mutex_lock(&host->clients_mutex);
 
  // Find client with matching ID
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == client_id) {
      bool has_transport = host->clients[i].transport != NULL;
      mutex_unlock(&host->clients_mutex);
      return has_transport;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return false;
}

session_host_create()

session_host_t * session_host_create

(

const session_host_config_t *

config

)

#include <src/common/session/host.h>

Create a new session host.

Parameters

config

Host configuration (must not be NULL)

Returns

Pointer to host handle, or NULL on failure

Creates a session host with the specified configuration. The host is not started until session_host_start() is called.

Note

Call session_host_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 234 of file host.c.

                                                                         {
  if (!config) {
    SET_ERRNO(ERROR_INVALID_PARAM, "NULL config");
    return NULL;
  }
 
  // Allocate host
  session_host_t *host = SAFE_CALLOC(1, sizeof(session_host_t), session_host_t *);
 
  // Copy configuration
  host->port = config->port > 0 ? config->port : OPT_PORT_INT_DEFAULT;
  host->max_clients = config->max_clients > 0 ? config->max_clients : SESSION_HOST_DEFAULT_MAX_CLIENTS;
  host->encryption_enabled = config->encryption_enabled;
  host->configured_quic_listeners = config->configured_quic_listeners;
 
  if (config->ipv4_address) {
    SAFE_STRNCPY(host->ipv4_address, config->ipv4_address, sizeof(host->ipv4_address));
  }
 
  if (config->ipv6_address) {
    SAFE_STRNCPY(host->ipv6_address, config->ipv6_address, sizeof(host->ipv6_address));
  }
 
  if (config->key_path) {
    SAFE_STRNCPY(host->key_path, config->key_path, sizeof(host->key_path));
  }
 
  if (config->password) {
    SAFE_STRNCPY(host->password, config->password, sizeof(host->password));
  }
 
  host->callbacks = config->callbacks;
  host->user_data = config->user_data;
 
  host->running = false;
 
  // Allocate client array
  host->clients = SAFE_CALLOC((size_t)host->max_clients, sizeof(session_host_client_t), session_host_client_t *);
 
  host->client_count = 0;
  host->next_client_id = 1;
 
  // Initialize mutex
  if (mutex_init(&host->clients_mutex, "host_clients") != 0) {
    SET_ERRNO(ERROR_THREAD, "Failed to initialize clients mutex");
    SAFE_FREE(host->clients);
    acip_frame_workspace_destroy(&host->frame_workspace);
    SAFE_FREE(host);
    return NULL;
  }
 
  host->initialized = true;
  return host;
}

References acip_frame_workspace_destroy(), session_host_config_t::callbacks, session_host_config_t::configured_quic_listeners, session_host_config_t::encryption_enabled, ERROR_INVALID_PARAM, ERROR_THREAD, session_host_config_t::ipv4_address, session_host_config_t::ipv6_address, session_host_config_t::key_path, session_host_config_t::max_clients, OPT_PORT_INT_DEFAULT, session_host_config_t::password, session_host_config_t::port, SAFE_CALLOC, SAFE_FREE, SAFE_STRNCPY, SESSION_HOST_DEFAULT_MAX_CLIENTS, SET_ERRNO, and session_host_config_t::user_data.

session_host_destroy()

asciichat_error_t session_host_destroy

(

session_host_t *

host

)

#include <src/common/session/host.h>

Destroy session host and free resources.

Parameters

host	Host to destroy (can be NULL)

Stops if running, disconnects all clients, and releases all resources. Safe to call with NULL.

Definition at line 289 of file host.c.

                                                             {
  if (!host)
    return ASCIICHAT_OK;
  asciichat_error_t result = session_host_stop(host);
  if (result != ASCIICHAT_OK)
    return result;
 
  // Clean up audio resources
  if (host->audio_ctx) {
#ifndef __EMSCRIPTEN__
    session_audio_destroy(host->audio_ctx);
#endif
    host->audio_ctx = NULL;
  }
 
  while (host->render_histories) {
    host_render_history_t *history = host->render_histories;
    host->render_histories = history->next;
    ascii_stabilizer_reset(&history->stabilizer);
    SAFE_FREE(history);
  }
 
  // Free client array and per-client resources
  if (host->clients) {
    for (int i = 0; i < host->max_clients; i++) {
      host_client_release_transport(&host->clients[i]);
      if (host->clients[i].incoming_video) {
        image_destroy(host->clients[i].incoming_video);
        host->clients[i].incoming_video = NULL;
      }
      if (host->clients[i].incoming_audio) {
        ringbuffer_destroy(host->clients[i].incoming_audio);
        host->clients[i].incoming_audio = NULL;
      }
    }
    SAFE_FREE(host->clients);
  }
 
  // Destroy mutex
  mutex_destroy(&host->clients_mutex);
 
  // Clear sensitive data
  memset(host->password, 0, sizeof(host->password));
 
  host->initialized = false;
  acip_frame_workspace_destroy(&host->frame_workspace);
  SAFE_FREE(host);
  return ASCIICHAT_OK;
}

References acip_frame_workspace_destroy(), ascii_stabilizer_reset(), ASCIICHAT_OK, image_destroy(), ringbuffer_destroy(), SAFE_FREE, session_audio_destroy(), and session_host_stop().

Referenced by discovery_session_apply_handoff(), discovery_session_destroy(), and BrowserHostState::reset().

session_host_find_client()

asciichat_error_t session_host_find_client	(	session_host_t *	host,
		uint32_t	client_id,
		session_host_client_info_t *	info )

#include <src/common/session/host.h>

Find a client by ID.

Parameters

host	Host handle (must not be NULL)
client_id	Client ID to find
info	Output client info structure (must not be NULL)

Returns

ASCIICHAT_OK on success, ERROR_NOT_FOUND if not found

Retrieves information about a connected client.

Definition at line 1435 of file host.c.

                                                                                                                       {
  if (!host || !host->initialized || !info) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  mutex_lock(&host->clients_mutex);
 
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == client_id) {
      info->client_id = host->clients[i].client_id;
      SAFE_STRNCPY(info->ip_address, host->clients[i].ip_address, sizeof(info->ip_address));
      info->port = host->clients[i].port;
      info->video_active = host->clients[i].video_active;
      info->audio_active = host->clients[i].audio_active;
      info->connected_at = host->clients[i].connected_at;
 
      mutex_unlock(&host->clients_mutex);
      return ASCIICHAT_OK;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return SET_ERRNO(ERROR_NOT_FOUND, "Client not found: %u", client_id);
}

References ASCIICHAT_OK, session_host_client_info_t::audio_active, session_host_client_info_t::client_id, session_host_client_info_t::connected_at, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, session_host_client_info_t::ip_address, session_host_client_info_t::port, SAFE_STRNCPY, SET_ERRNO, and session_host_client_info_t::video_active.

session_host_get_client_count()

int session_host_get_client_count

(

session_host_t *

host

)

#include <src/common/session/host.h>

Get number of connected clients.

Parameters

host	Host handle (can be NULL)

Returns

Number of connected clients, 0 if NULL

Definition at line 1460 of file host.c.

                                                        {
  if (!host || !host->initialized) {
    return 0;
  }
  return host->client_count;
}

session_host_get_client_ids()

int session_host_get_client_ids	(	session_host_t *	host,
		uint32_t *	ids,
		int	max_ids )

#include <src/common/session/host.h>

Get list of all connected client IDs.

Parameters

host	Host handle (must not be NULL)
ids	Output array for client IDs (must not be NULL)
max_ids	Maximum number of IDs to return (size of ids array)

Returns

Number of IDs written to array

Definition at line 1467 of file host.c.

                                                                                  {
  if (!host || !host->initialized || !ids || max_ids <= 0) {
    return 0;
  }
 
  mutex_lock(&host->clients_mutex);
 
  int count = 0;
  for (int i = 0; i < host->max_clients && count < max_ids; i++) {
    if (host->clients[i].active) {
      ids[count++] = host->clients[i].client_id;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return count;
}

session_host_get_client_transport()

acip_transport_t * session_host_get_client_transport	(	session_host_t *	host,
		uint32_t	client_id )

#include <src/common/session/host.h>

Get the current transport for a specific client in the host.

Returns the currently active transport, regardless of its backend.

Parameters

host	Host handle (must not be NULL)
client_id	Client ID whose transport should be retrieved

Returns

Borrowed transport pointer, NULL if no transport is registered or client not found

Definition at line 1756 of file host.c.

                                                                                              {
  if (!host || !host->initialized) {
    return NULL;
  }
 
  mutex_lock(&host->clients_mutex);
 
  // Find client with matching ID
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == client_id) {
      acip_transport_t *transport = host->clients[i].transport;
      mutex_unlock(&host->clients_mutex);
      return transport;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return NULL;
}

Referenced by session_host_receive_packet().

session_host_inject_audio()

asciichat_error_t session_host_inject_audio	(	session_host_t *	host,
		uint32_t	participant_id,
		const float *	samples,
		size_t	count )

#include <src/common/session/host.h>

Inject audio samples from memory participant.

Parameters

host	Host handle (must not be NULL)
participant_id	Memory participant ID
samples	Audio sample buffer (float format, must not be NULL)
count	Number of samples

Returns

ASCIICHAT_OK on success, error code on failure

Injects audio samples directly into the mixer from a memory participant. This bypasses network I/O and is used when the host participates in the session with their own audio.

Note

Sample data is copied, so caller retains ownership.

Definition at line 1342 of file host.c.

                                                          {
  if (!host || !host->initialized || !samples || count == 0 || count % AUDIO_CHANNELS) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameters");
  }
 
  mutex_lock(&host->clients_mutex);
 
  // Find memory participant
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == participant_id &&
        host->clients[i].participant_type == PARTICIPANT_TYPE_MEMORY) {
 
      if (!host->clients[i].incoming_audio) {
        mutex_unlock(&host->clients_mutex);
        return SET_ERRNO(ERROR_INVALID_STATE, "Memory participant has no audio buffer");
      }
 
      // Write samples to ringbuffer (one at a time)
      size_t written = 0;
      for (size_t j = 0; j < count; j++) {
        if (ringbuffer_write(host->clients[i].incoming_audio, &samples[j])) {
          written++;
        } else {
          break; // Buffer full
        }
      }
 
      if (written < count) {
        log_warn_every(NS_PER_MS_INT, "Audio ringbuffer full, dropped %zu samples", count - written);
      }
 
      host->clients[i].audio_active = true;
 
      mutex_unlock(&host->clients_mutex);
      return ASCIICHAT_OK;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return SET_ERRNO(ERROR_NOT_FOUND, "Memory participant not found");
}

References ASCIICHAT_OK, AUDIO_CHANNELS, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NOT_FOUND, log_warn_every, NS_PER_MS_INT, participant_id, PARTICIPANT_TYPE_MEMORY, ringbuffer_write(), and SET_ERRNO.

session_host_inject_frame()

asciichat_error_t session_host_inject_frame	(	session_host_t *	host,
		uint32_t	participant_id,
		const image_t *	frame )

#include <src/common/session/host.h>

Inject a video frame from memory participant.

Parameters

host	Host handle (must not be NULL)
participant_id	Memory participant ID
frame	Video frame image (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Injects a video frame directly into the mixer from a memory participant. This bypasses network I/O and is used when the host participates in the session with their own webcam.

Note

Frame data is copied, so caller retains ownership.

Definition at line 1290 of file host.c.

                                                                                                                 {
  if (!host || !host->initialized || !frame) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameters");
  }
 
  if (!frame->pixels || frame->w <= 0 || frame->h <= 0 ||
      image_validate_dimensions((size_t)frame->w, (size_t)frame->h) != ASCIICHAT_OK)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid injected image");
  size_t pixel_bytes;
  if (image_calc_rgb_size((size_t)frame->w, (size_t)frame->h, &pixel_bytes) != ASCIICHAT_OK)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Injected image size is outside supported limits");
 
  mutex_lock(&host->clients_mutex);
 
  // Find memory participant
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == participant_id &&
        host->clients[i].participant_type == PARTICIPANT_TYPE_MEMORY) {
 
      if (!host->clients[i].incoming_video) {
        mutex_unlock(&host->clients_mutex);
        return SET_ERRNO(ERROR_INVALID_STATE, "Memory participant has no video buffer");
      }
 
      // Copy frame data into buffer
      image_t *dest = host->clients[i].incoming_video;
      if (dest->w != frame->w || dest->h != frame->h) {
        // Reallocate if size changed
        image_t *replacement = image_new(frame->w, frame->h);
        if (!replacement) {
          mutex_unlock(&host->clients_mutex);
          return SET_ERRNO(ERROR_MEMORY, "Failed to reallocate video buffer");
        }
        image_destroy(dest);
        dest = replacement;
        host->clients[i].incoming_video = dest;
      }
 
      // Copy pixel data
      memcpy(dest->pixels, frame->pixels, pixel_bytes);
 
      host->clients[i].video_active = true;
 
      mutex_unlock(&host->clients_mutex);
      return ASCIICHAT_OK;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return SET_ERRNO(ERROR_NOT_FOUND, "Memory participant not found");
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NOT_FOUND, image_t::h, image_calc_rgb_size(), image_destroy(), image_new(), image_validate_dimensions(), participant_id, PARTICIPANT_TYPE_MEMORY, image_t::pixels, SET_ERRNO, and image_t::w.

session_host_is_running()

bool session_host_is_running

(

session_host_t *

host

)

#include <src/common/session/host.h>

Check if host is running.

Parameters

host	Host handle (can be NULL)

Returns

true if running, false otherwise

Definition at line 1118 of file host.c.

                                                   {
  if (!host || !host->initialized) {
    return false;
  }
  return host->running;
}

session_host_remove_client()

asciichat_error_t session_host_remove_client	(	session_host_t *	host,
		uint32_t	client_id )

#include <src/common/session/host.h>

Remove a client by ID.

Parameters

host	Host handle (must not be NULL)
client_id	Client ID to remove

Returns

ASCIICHAT_OK on success, error code on failure

Disconnects and removes a client from the session.

Note

on_client_leave callback is invoked before removal.

Definition at line 1385 of file host.c.

                                                                                       {
  if (!host || !host->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid host");
  }
 
  mutex_lock(&host->clients_mutex);
 
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == client_id) {
      // Invoke callback before removing
      mutex_unlock(&host->clients_mutex);
      if (host->callbacks.on_client_leave) {
        host->callbacks.on_client_leave(host, client_id, host->user_data);
      }
      mutex_lock(&host->clients_mutex);
 
#ifndef __EMSCRIPTEN__
      if (host->clients[i].connection) {
        network_connection_request_stop(host->clients[i].connection);
        mutex_unlock(&host->clients_mutex);
        return ASCIICHAT_OK;
      }
#endif
      host_client_release_transport(&host->clients[i]);
 
      // Clean up media buffers
      if (host->clients[i].incoming_video) {
        image_destroy(host->clients[i].incoming_video);
        host->clients[i].incoming_video = NULL;
      }
      if (host->clients[i].incoming_audio) {
        ringbuffer_destroy(host->clients[i].incoming_audio);
        host->clients[i].incoming_audio = NULL;
      }
 
      host_forget_render_history(host, client_id);
      host->clients[i].active = false;
      host->client_count--;
      if (host->render_target.client_id == client_id)
        host->render_target = (session_host_render_target_t){0};
 
      mutex_unlock(&host->clients_mutex);
      return ASCIICHAT_OK;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  return SET_ERRNO(ERROR_NOT_FOUND, "Client not found: %u", client_id);
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, image_destroy(), network_connection_request_stop(), ringbuffer_destroy(), and SET_ERRNO.

session_host_send_frame()

asciichat_error_t session_host_send_frame	(	session_host_t *	host,
		uint32_t	client_id,
		const char *	frame )

#include <src/common/session/host.h>

Send ASCII frame to a specific client.

Parameters

host	Host handle (must not be NULL)
client_id	Target client ID
frame	ASCII frame data (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 1518 of file host.c.

                                                                                                       {
  if (!host || !host->initialized || !frame) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  if (!host->running) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not running");
  }
 
  // Send ASCII frame to specific client
  size_t frame_len = strlen(frame);
 
  mutex_lock(&host->clients_mutex);
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].client_id == client_id && host->clients[i].active) {
      asciichat_error_t result = host->clients[i].transport
                                     ? acip_send_ascii_frame(host->clients[i].transport, &host->frame_workspace, frame,
                                                             frame_len, 80, 24, "session-host")
                                     : SET_ERRNO(ERROR_INVALID_STATE, "Client %u has no transport", client_id);
      mutex_unlock(&host->clients_mutex);
      return result;
    }
  }
  mutex_unlock(&host->clients_mutex);
 
  return SET_ERRNO(ERROR_NOT_FOUND, "client %u not found", client_id);
}

References acip_send_ascii_frame(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NOT_FOUND, and SET_ERRNO.

session_host_set_client_transport()

asciichat_error_t session_host_set_client_transport	(	session_host_t *	host,
		uint32_t	client_id,
		acip_transport_t *	transport,
		acip_transport_ownership_t	ownership )

#include <src/common/session/host.h>

Select a transport for a specific client in the host.

Selects the transport used for this client by all send/receive operations. Detaching clears the selection; no backend-specific fallback is retained.

Parameters

host	Host handle (must not be NULL)
client_id	Client ID whose transport should be replaced
transport	Selected transport, or NULL to detach without a fallback
ownership	Responsibility for destroying the selected transport

Returns

ASCIICHAT_OK on success, ERROR_NOT_FOUND if client not found, other error on failure

Note

Replacing an owned transport destroys it. Ownership transfers only on success.

Definition at line 1703 of file host.c.

                                                                                                                       {
  if (!host || !host->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Host is NULL or not initialized");
  }
 
  if ((ownership != ACIP_TRANSPORT_BORROWED && ownership != ACIP_TRANSPORT_OWNED) ||
      (!transport && ownership == ACIP_TRANSPORT_OWNED))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport ownership");
 
  mutex_lock(&host->clients_mutex);
 
  // Find client with matching ID
  for (int i = 0; i < host->max_clients; i++) {
    if (host->clients[i].active && host->clients[i].client_id == client_id) {
      log_info("Setting transport=%p for client %u (was=%p)", transport, client_id, host->clients[i].transport);
 
      if (host->clients[i].transport == transport && host->clients[i].transport_ownership != ownership) {
        mutex_unlock(&host->clients_mutex);
        return SET_ERRNO(ERROR_INVALID_STATE, "Cannot change ownership of a registered transport");
      }
      server_state_packet_t state = {0};
      if (transport) {
        uint32_t active_count = 0;
        for (int j = 0; j < host->max_clients; j++) {
          if (host->clients[j].active) {
            active_count++;
          }
        }
        state.connected_client_count = HOST_TO_NET_U32(active_count);
        state.active_client_count = HOST_TO_NET_U32(active_count);
      }
      if (transport) {
        asciichat_error_t result = acip_send_server_state(transport, &state);
        if (result != ASCIICHAT_OK) {
          mutex_unlock(&host->clients_mutex);
          return result;
        }
      }
      if (host->clients[i].transport != transport)
        host_client_release_transport(&host->clients[i]);
      host->clients[i].transport = transport;
      host->clients[i].transport_ownership = transport ? ownership : ACIP_TRANSPORT_BORROWED;
      mutex_unlock(&host->clients_mutex);
      return ASCIICHAT_OK;
    }
  }
 
  mutex_unlock(&host->clients_mutex);
  log_warn("Client %u not found", client_id);
  return SET_ERRNO(ERROR_NOT_FOUND, "Client not found");
}

References acip_send_server_state(), ACIP_TRANSPORT_BORROWED, ACIP_TRANSPORT_OWNED, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NOT_FOUND, HOST_TO_NET_U32, log_info, log_warn, and SET_ERRNO.

session_host_set_display()

asciichat_error_t session_host_set_display	(	session_host_t *	host,
		struct session_display_ctx *	display )

#include <src/common/session/host.h>

Set a native terminal display context for local frame rendering.

Parameters

host	Host handle (must not be NULL)
display	Display context for rendering frames locally (can be NULL to disable)

Returns

ASCIICHAT_OK on success, error code on failure

Configures the host to render frames locally to the provided display context. This allows the host to see its own rendered output during testing. If display is NULL, local rendering is disabled.

Note

Can be called before or after render thread is started.

Definition at line 1614 of file host.c.

                                                                                                      {
  if (!host || !host->initialized)
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid host");
  mutex_lock(&host->clients_mutex);
  host->display_context = display;
  host->render_target = display ? (session_host_render_target_t){.get_config = native_display_config,
                                                                 .render_frame = native_display_frame,
                                                                 .context = host}
                                : (session_host_render_target_t){0};
  mutex_unlock(&host->clients_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

session_host_start()

asciichat_error_t session_host_start

(

session_host_t *

host

)

#include <src/common/session/host.h>

Start accepting client connections.

Parameters

host	Host handle (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Binds to the configured port and starts accepting connections. This function may start background threads for connection handling.

Definition at line 1037 of file host.c.

                                                           {
  if (!host || !host->initialized)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid session host");
  if (host->running)
    return ASCIICHAT_OK;
  if (host->port > UINT16_MAX)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Host port is outside the transport endpoint range");
#ifdef __EMSCRIPTEN__
  return SET_ERRNO(ERROR_NOT_SUPPORTED, "Browser hosts accept browser-managed connections");
#else
  asciichat_error_t result = ASCIICHAT_OK;
  if (host->configured_quic_listeners)
    result = session_quic_listeners_open(host->port, &host->quic_endpoint, &host->webtransport_endpoint);
  if (result != ASCIICHAT_OK)
    return result;
  network_server_config_t config = {
      .quic_endpoint = host->quic_endpoint,
      .webtransport_endpoint = host->webtransport_endpoint,
      .port = host->port,
      .ipv4_address = host->ipv4_address[0] ? host->ipv4_address : "127.0.0.1",
      .bind_ipv4 = true,
      .max_connections = host->max_clients,
      .partial_timeout_ms = 30000,
      .callbacks = {host_connection_open, host_connection_packet, host_connection_closing, host_connection_closed},
      .user_data = host};
  result = network_server_create(&config, &host->network_server);
  if (result == ASCIICHAT_OK)
    result = network_server_start(host->network_server);
  if (result == ASCIICHAT_OK)
    result = platform_thread_create(&host->network_thread, "host_network", host_network_run, host);
  if (result != ASCIICHAT_OK) {
    network_server_destroy(&host->network_server);
    return result;
  }
  host->network_thread_started = true;
  host->running = true;
  return ASCIICHAT_OK;
#endif
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, network_server_create(), network_server_destroy(), network_server_start(), session_quic_listeners_open(), and SET_ERRNO.

session_host_start_render()

asciichat_error_t session_host_start_render

(

session_host_t *

host

)

#include <src/common/session/host.h>

Start media rendering thread (video mixing and audio distribution).

Parameters

host	Host handle (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts the render thread which collects video frames from all participants, generates mixed ASCII frames, and broadcasts them to all clients. Also handles audio mixing and distribution.

Note

The host must be running before starting the render thread.

Call session_host_stop_render() to stop the thread.

Definition at line 1632 of file host.c.

                                                                  {
  if (!host || !host->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid host");
  }
 
  // Discovery mode starts the shared host renderer without passing through
  // server/main.c, which normally initializes the ASCII lookup palettes.
  ascii_simd_init();
 
  if (!host->running) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not running");
  }
 
  if (host->render_thread_running) {
    return ASCIICHAT_OK; // Already running
  }
 
  // Create audio context for mixing (host mode = true)
  if (!host->audio_ctx) {
    host->audio_ctx = session_audio_create(true);
    if (!host->audio_ctx) {
      return SET_ERRNO(ERROR_INVALID_STATE, "Failed to create audio context");
    }
  }
 
  // Spawn render thread
  host->render_thread_running = true;
  if (platform_thread_create(&host->render_thread, "render", host_render_thread, host) != 0) {
    log_error("Failed to spawn render thread");
    host->render_thread_running = false;
    return SET_ERRNO(ERROR_THREAD, "Failed to spawn render thread");
  }
 
  log_info("Host render thread started");
  return ASCIICHAT_OK;
}

References ascii_simd_init(), ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_THREAD, log_error, log_info, session_audio_create(), and SET_ERRNO.

session_host_stop()

asciichat_error_t session_host_stop

(

session_host_t *

host

)

#include <src/common/session/host.h>

Stop accepting connections and disconnect all clients.

Parameters

host	Host handle (must not be NULL)

Gracefully stops the server, disconnects all clients, and cleans up.

Definition at line 1076 of file host.c.

                                                          {
  if (!host || !host->initialized)
    return ASCIICHAT_OK;
  if (host->render_thread_running) {
    host->render_thread_running = false;
    asciichat_error_t result = thread_join(&host->render_thread, NULL);
    if (result != ASCIICHAT_OK) {
      host->render_thread_running = true;
      return result;
    }
  }
#ifndef __EMSCRIPTEN__
  network_server_request_stop(host->network_server);
  if (host->network_thread_started) {
    asciichat_error_t result = thread_join(&host->network_thread, NULL);
    if (result != ASCIICHAT_OK)
      return result;
    host->network_thread_started = false;
  }
  asciichat_error_t result = network_server_stop(host->network_server);
  if (result != ASCIICHAT_OK)
    return result;
  network_server_destroy(&host->network_server);
  result = session_quic_listeners_close(&host->quic_endpoint, &host->webtransport_endpoint);
  if (result != ASCIICHAT_OK)
    return result;
#endif
  host->running = false;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, network_server_destroy(), network_server_request_stop(), network_server_stop(), and session_quic_listeners_close().

Referenced by session_host_destroy().

session_host_stop_render()

void session_host_stop_render

(

session_host_t *

host

)

#include <src/common/session/host.h>

Stop media rendering thread.

Parameters

host	Host handle (must not be NULL)

Gracefully stops the render thread and cleans up audio resources.

Definition at line 1669 of file host.c.

                                                    {
  if (!host || !host->initialized) {
    return;
  }
 
  if (!host->render_thread_running) {
    return;
  }
 
  // Signal thread to stop
  host->render_thread_running = false;
 
  // Wait for thread to complete
  if (thread_join(&host->render_thread, NULL) != ASCIICHAT_OK) {
    host->render_thread_running = true;
    SET_ERRNO(ERROR_THREAD, "Render worker still owns host audio resources");
    return;
  }
 
  // Clean up audio resources
  if (host->audio_ctx) {
#ifndef __EMSCRIPTEN__
    session_audio_destroy(host->audio_ctx);
#endif
    host->audio_ctx = NULL;
  }
 
  log_info("Host render thread stopped");
}

References ASCIICHAT_OK, ERROR_THREAD, log_info, session_audio_destroy(), and SET_ERRNO.

session_mirror_capture_create()

session_capture_ctx_t * session_mirror_capture_create

(

const session_capture_config_t *

config

)

#include <src/common/session/capture.h>

Create a new session capture context.

Parameters

config

Capture configuration (must not be NULL)

Returns

Pointer to capture context, or NULL on failure

Creates and initializes a session capture context with the specified configuration. The media source is opened and ready for reading.

Note

Call session_capture_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Create mirror mode capture context with local media source

Creates a capture context for local media (webcam, file, URL, test pattern). Used by mirror mode and snapshot operations that need to capture video locally.

Parameters

config

Capture configuration (type, path, FPS, etc.)

Returns

Capture context with media source, or NULL on error

Note

Call session_capture_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 247 of file common/session/capture.c.

                                                                                             {
  // Mirror capture requires a config with media source info
  if (!config) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Mirror capture requires explicit config"), NULL;
  }
 
  // Delegate to the main implementation
  return session_capture_create(config);
}

References ERROR_INVALID_PARAM, session_capture_create(), and SET_ERRNO.

session_network_capture_create()

session_capture_ctx_t * session_network_capture_create

(

uint32_t

target_fps

)

#include <src/common/session/capture.h>

Create network mode capture context without media source.

Creates a minimal capture context for network modes (client, discovery) that receive video frames from the network instead of capturing locally. Only initializes keyboard and audio support; no media source is created.

Parameters

target_fps

Target FPS (0 = default 60 FPS)

Returns

Capture context without media source, or NULL on error

Note

Call session_capture_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 257 of file common/session/capture.c.

                                                                           {
  // Network modes don't capture media - create minimal context for keyboard/audio only
  session_capture_ctx_t *ctx = SAFE_CALLOC(1, sizeof(session_capture_ctx_t), session_capture_ctx_t *);
  if (!ctx) {
    return NULL;
  }
 
  // Set FPS (use provided value or default to 60)
  ctx->target_fps = target_fps > 0 ? target_fps : DEFAULT_MAX_FPS;
  ctx->resize_for_network = false;
 
  // Audio and keyboard will be set up separately by callers
  ctx->audio_enabled = false;
  ctx->source = NULL;
 
  // Initialize minimal FPS tracker (won't be used but keep structure consistent)
  char *tracker_name = SAFE_MALLOC(CAPTURE_TRACKER_NAME_BUFFER_SIZE, char *);
  if (!tracker_name) {
    SAFE_FREE(ctx);
    return NULL;
  }
  safe_snprintf(tracker_name, CAPTURE_TRACKER_NAME_BUFFER_SIZE, "NETWORK_CAPTURE");
  fps_init(&ctx->fps_tracker, 60, tracker_name);
 
  ctx->start_time_ns = time_get_ns();
  ctx->initialized = true;
  capture_sync_entries(ctx, true);
 
  log_debug("Created network capture context (no local media source)");
  return ctx;
}

References session_capture_ctx::audio_enabled, CAPTURE_TRACKER_NAME_BUFFER_SIZE, DEFAULT_MAX_FPS, fps_init(), session_capture_ctx::fps_tracker, session_capture_ctx::initialized, log_debug, session_capture_ctx::resize_for_network, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, safe_snprintf(), session_capture_ctx::source, session_capture_ctx::start_time_ns, and session_capture_ctx::target_fps.

session_participant_connect()

asciichat_error_t session_participant_connect

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Connect to session server.

Parameters

p	Participant handle (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Initiates connection to the configured server. Connection establishment is synchronous but callbacks are invoked asynchronously.

Note

on_connected callback is invoked on successful connection.

on_error callback is invoked on failure.

Definition at line 252 of file participant.c.

                                                                        {
  log_debug("p=%p", p);
 
  if (!p || !p->initialized) {
    log_debug("invalid param or not initialized");
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid participant");
  }
 
  log_debug("p->initialized=%d, p->connected=%d", p->initialized, p->connected);
 
  if (p->connected) {
    log_debug("already connected, returning OK");
    return ASCIICHAT_OK; // Already connected
  }
  if (p->port > UINT16_MAX)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Participant port is outside the transport endpoint range");
 
  asciichat_error_t result = session_connection_stop(&p->connection);
  if (result != ASCIICHAT_OK)
    return result;
  participant_connection_init(p);
  char password[PASSWORD_BUFFER_SIZE] = {0};
  SAFE_STRNCPY(password, p->password, sizeof(password));
  network_connect_config_t quic_config = {.timeout_ms = 10000,
                                          .tls_ca_file = p->tls_ca_file[0] ? p->tls_ca_file : NULL,
                                          .quic_audio_datagrams = p->quic_audio_datagrams,
                                          .quic_visual_datagrams = p->quic_visual_datagrams};
  const network_connect_config_t *connect_config = strncmp(p->address, "quic://", 7) == 0 ? &quic_config : NULL;
  result = session_connection_establish("participant", p->address, p->port, connect_config, &p->network, password,
                                        sizeof(password), participant_prepare, NULL, p);
  sodium_memzero(password, sizeof(password));
  p->transport = network_connection_transport(p->network);
  p->transport_ownership = p->network ? ACIP_TRANSPORT_OWNED : ACIP_TRANSPORT_BORROWED;
  if (result == ASCIICHAT_OK)
    result = session_connection_start(&p->connection);
  if (result != ASCIICHAT_OK) {
    asciichat_errno_scope_t cleanup = errno_scope_begin();
    session_connection_stop(&p->connection);
    errno_scope_end(cleanup, ASCIICHAT_ERRNO_HANDLED);
    return result;
  }
  log_debug("session_participant_connect: setting p->connected=true");
 
  mutex_lock(&p->settings_mutex);
  p->settings_request = 0;
  p->settings_applied_request = 0;
  p->settings.version = 0;
  mutex_unlock(&p->settings_mutex);
  p->connected = true;
  p->client_id = 0; // Will be assigned by server
 
  log_info("Connected to server at %s:%d", p->address, p->port);
 
  // Invoke callback
  if (p->callbacks.on_connected) {
    p->callbacks.on_connected(p, p->client_id, p->user_data);
  }
 
  return ASCIICHAT_OK;
}

References ACIP_TRANSPORT_BORROWED, ACIP_TRANSPORT_OWNED, session_participant::address, ASCIICHAT_ERRNO_HANDLED, ASCIICHAT_OK, session_participant::callbacks, session_participant::client_id, session_participant::connected, session_participant::connection, errno_scope_begin(), errno_scope_end(), ERROR_INVALID_PARAM, session_participant::initialized, log_debug, log_info, session_participant::network, network_connection_transport(), session_participant_callbacks_t::on_connected, session_participant::password, PASSWORD_BUFFER_SIZE, session_participant::port, session_participant::quic_audio_datagrams, session_participant::quic_visual_datagrams, SAFE_STRNCPY, session_connection_establish(), session_connection_start(), session_connection_stop(), SET_ERRNO, session_participant::settings, session_participant::settings_applied_request, session_participant::settings_mutex, session_participant::settings_request, session_participant::tls_ca_file, session_participant::transport, session_participant::transport_ownership, session_participant::user_data, and session_settings_t::version.

session_participant_create()

session_participant_t * session_participant_create

(

const session_participant_config_t *

config

)

#include <src/common/session/participant.h>

Server address, security, media, transport, and callback settings for a participant.

Create a new session participant

Parameters

config

Participant configuration (must not be NULL)

Returns

Pointer to participant handle, or NULL on failure

Creates a session participant with the specified configuration. The participant is not connected until session_participant_connect() is called.

Note

Call session_participant_destroy() to free resources when done.

On failure, sets asciichat_errno with error details.

Definition at line 156 of file participant.c.

                                                                                              {
  log_info("config=%p", config);
 
  if (!config) {
    log_error("config is NULL");
    SET_ERRNO(ERROR_INVALID_PARAM, "NULL config");
    return NULL;
  }
 
  // Allocate participant
  session_participant_t *p = SAFE_CALLOC(1, sizeof(session_participant_t), session_participant_t *);
  log_info("allocated p=%p", p);
 
  // Copy configuration
  if (config->address) {
    SAFE_STRNCPY(p->address, config->address, sizeof(p->address));
  } else {
    SAFE_STRNCPY(p->address, "127.0.0.1", sizeof(p->address));
  }
 
  p->port = config->port > 0 ? config->port : OPT_PORT_INT_DEFAULT;
  p->encryption_enabled = config->encryption_enabled;
 
  log_info("address=%s, port=%d", p->address, p->port);
 
  if (config->password) {
    SAFE_STRNCPY(p->password, config->password, sizeof(p->password));
  }
 
  if (config->server_key) {
    SAFE_STRNCPY(p->server_key, config->server_key, sizeof(p->server_key));
  }
  if (config->tls_ca_file)
    SAFE_STRNCPY(p->tls_ca_file, config->tls_ca_file, sizeof(p->tls_ca_file));
  p->quic_audio_datagrams = config->quic_audio_datagrams;
  p->quic_visual_datagrams = config->quic_visual_datagrams;
 
  p->enable_audio = config->enable_audio;
  p->enable_video = config->enable_video;
  p->callbacks = config->callbacks;
  p->user_data = config->user_data;
 
  p->transport = NULL;
  p->connected = false;
  p->client_id = 0;
 
  // Initialize settings
  session_settings_init(&p->settings);
  if (mutex_init(&p->settings_mutex, "participant_settings") != 0) {
    SAFE_FREE(p);
    return NULL;
  }
 
  participant_connection_init(p);
  p->initialized = true;
  log_info("returning p=%p (initialized=%d, connected=%d)", p, p->initialized, p->connected);
  return p;
}

References session_participant::address, session_participant_config_t::address, session_participant::callbacks, session_participant_config_t::callbacks, session_participant::client_id, session_participant::connected, session_participant::enable_audio, session_participant_config_t::enable_audio, session_participant::enable_video, session_participant_config_t::enable_video, session_participant::encryption_enabled, session_participant_config_t::encryption_enabled, ERROR_INVALID_PARAM, session_participant::initialized, log_error, log_info, OPT_PORT_INT_DEFAULT, session_participant::password, session_participant_config_t::password, session_participant::port, session_participant_config_t::port, session_participant::quic_audio_datagrams, session_participant_config_t::quic_audio_datagrams, session_participant::quic_visual_datagrams, session_participant_config_t::quic_visual_datagrams, SAFE_CALLOC, SAFE_FREE, SAFE_STRNCPY, session_participant::server_key, session_participant_config_t::server_key, session_settings_init(), SET_ERRNO, session_participant::settings, session_participant::settings_mutex, session_participant::tls_ca_file, session_participant_config_t::tls_ca_file, session_participant::transport, session_participant::user_data, and session_participant_config_t::user_data.

session_participant_destroy()

void session_participant_destroy

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Destroy session participant and free resources.

Parameters

p	Participant to destroy (can be NULL)

Disconnects if connected, stops all streams, and releases all resources. Safe to call with NULL.

Definition at line 215 of file participant.c.

                                                           {
  if (!p) {
    return;
  }
 
  session_participant_disconnect(p);
  // A failed join retains the participant and its resources for a safe retry.
  if (atomic_load_int(&p->connection.state) != SESSION_CONNECTION_STOPPED || p->video_thread_created ||
      p->audio_thread_created)
    return;
 
  // Clear sensitive data
  sodium_memzero(p->password, sizeof(p->password));
  memset(p->server_key, 0, sizeof(p->server_key));
 
  p->initialized = false;
  mutex_destroy(&p->settings_mutex);
  SAFE_FREE(p);
}

References session_participant::audio_thread_created, session_participant::connection, session_participant::initialized, session_participant::password, SAFE_FREE, session_participant::server_key, SESSION_CONNECTION_STOPPED, session_participant_disconnect(), session_participant::settings_mutex, session_connection_t::state, and session_participant::video_thread_created.

Referenced by discovery_session_apply_handoff(), and discovery_session_destroy().

session_participant_disconnect()

void session_participant_disconnect

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Disconnect from session server.

Parameters

p	Participant handle (must not be NULL)

Gracefully disconnects from the server and stops all streams.

Note

on_disconnected callback is invoked after disconnection.

Definition at line 313 of file participant.c.

                                                              {
  if (!p || !p->initialized) {
    return;
  }
 
  bool was_connected = p->connected;
  if (session_connection_stop(&p->connection) != ASCIICHAT_OK)
    return;
 
  // Invoke callback
  if (was_connected && p->callbacks.on_disconnected) {
    p->callbacks.on_disconnected(p, p->user_data);
  }
}

References ASCIICHAT_OK, session_participant::callbacks, session_participant::connected, session_participant::connection, session_participant::initialized, session_participant_callbacks_t::on_disconnected, session_connection_stop(), and session_participant::user_data.

Referenced by session_participant_destroy().

session_participant_get_client_id()

uint32_t session_participant_get_client_id

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Get assigned client ID.

Parameters

p	Participant handle (can be NULL)

Returns

Client ID if connected, 0 otherwise

Definition at line 360 of file participant.c.

                                                                     {
  if (!p || !p->initialized || !p->connected) {
    return 0;
  }
  return p->client_id;
}

References session_participant::client_id, session_participant::connected, and session_participant::initialized.

session_participant_get_settings()

asciichat_error_t session_participant_get_settings	(	session_participant_t *	p,
		session_settings_t *	settings )

#include <src/common/session/participant.h>

Get current session settings.

Parameters

p	Participant handle (must not be NULL)
settings	Output settings structure (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 383 of file participant.c.

                                                                                                           {
  if (!p || !p->initialized || !settings) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  mutex_lock(&p->settings_mutex);
  memcpy(settings, &p->settings, sizeof(session_settings_t));
  mutex_unlock(&p->settings_mutex);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, session_participant::initialized, SET_ERRNO, session_participant::settings, and session_participant::settings_mutex.

session_participant_get_transport()

acip_transport_t * session_participant_get_transport

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Get the current transport for the participant.

Returns the selected transport, regardless of its backend. This accessor does not transfer ownership. External owners must detach their transport before freeing it; the participant destroys any owned transport.

Parameters

p	Participant handle (must not be NULL)

Returns

Selected transport, or NULL when none is attached

Definition at line 799 of file participant.c.

                                                                              {
  if (!p || !p->initialized) {
    return NULL;
  }
 
  return p->transport;
}

References session_participant::initialized, and session_participant::transport.

Referenced by discovery_session_check_host_alive().

session_participant_has_transport()

bool session_participant_has_transport

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Check if participant has a selected transport.

Includes TCP, WebRTC, and WebSocket transports.

Parameters

p	Participant handle (can be NULL)

Returns

true if a transport is selected, false otherwise

Definition at line 807 of file participant.c.

                                                                 {
  if (!p) {
    return false;
  }
 
  return p->transport != NULL;
}

References session_participant::transport.

session_participant_is_audio_active()

bool session_participant_is_audio_active

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Check if audio is streaming.

Parameters

p	Participant handle (can be NULL)

Returns

true if audio is active, false otherwise

Definition at line 375 of file participant.c.

                                                                   {
  return p && p->initialized && session_av_state_is_active(&p->audio);
}

References session_participant::audio, session_participant::initialized, and session_av_state_is_active().

session_participant_is_connected()

bool session_participant_is_connected

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Check if participant is connected.

Parameters

p	Participant handle (can be NULL)

Returns

true if connected, false otherwise

Definition at line 353 of file participant.c.

                                                                {
  if (!p || !p->initialized) {
    return false;
  }
  return p->connected;
}

References session_participant::connected, and session_participant::initialized.

session_participant_is_video_active()

bool session_participant_is_video_active

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Check if video is streaming.

Parameters

p	Participant handle (can be NULL)

Returns

true if video is active, false otherwise

Definition at line 371 of file participant.c.

                                                                   {
  return p && p->initialized && session_av_state_is_active(&p->video);
}

References session_participant::initialized, session_av_state_is_active(), and session_participant::video.

session_participant_request_settings()

asciichat_error_t session_participant_request_settings	(	session_participant_t *	p,
		const session_settings_t *	settings )

#include <src/common/session/participant.h>

Request this participant's remote rendering update.

Parameters

p	Participant handle (must not be NULL)
settings	New settings to request (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Requests rendering for this participant. The host may accept or reject the request.

Note

Actual settings change is signaled via on_settings_changed callback.

Definition at line 394 of file participant.c.

                                                                                                                     {
  if (!p || !p->initialized || !settings) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameter");
  }
 
  if (!p->connected) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not connected");
  }
 
  options_t *values = SAFE_MALLOC(sizeof(*values), options_t *);
  session_settings_to_options(settings, values);
  if (values->fps == 0)
    values->fps = DEFAULT_MAX_FPS;
  if (values->color_mode == TERM_COLOR_AUTO) {
    terminal_capabilities_t caps = detect_terminal_capabilities(options_terminal_settings());
    values->color_mode = caps.detection_reliable ? caps.color_level : TERM_COLOR_NONE;
  }
  acip_render_settings_t prepared = {0};
  asciichat_error_t result = acip_render_settings_prepare(&prepared, values);
  if (result == ASCIICHAT_OK) {
    mutex_lock(&p->settings_mutex);
    uint32_t request = ++p->settings_request;
    mutex_unlock(&p->settings_mutex);
    result = acip_settings_send(p->transport, values, request, UINT32_MAX);
  }
  SAFE_FREE(values);
  return result;
}

References acip_render_settings_prepare(), acip_settings_send(), ASCIICHAT_OK, options_state::color_mode, session_participant::connected, DEFAULT_MAX_FPS, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, options_state::fps, session_participant::initialized, options_terminal_settings, SAFE_FREE, SAFE_MALLOC, session_settings_to_options(), SET_ERRNO, session_participant::settings_mutex, session_participant::settings_request, and session_participant::transport.

session_participant_set_transport()

asciichat_error_t session_participant_set_transport	(	session_participant_t *	p,
		acip_transport_t *	transport,
		acip_transport_ownership_t	ownership )

#include <src/common/session/participant.h>

Select a transport and its ownership mode for the participant.

Selects the transport used by all participant media workers. Native connections use the library connection factory; negotiated transports use this same API.

Parameters

p	Participant handle (must not be NULL)
transport	Selected transport, or NULL to detach without a fallback
ownership	Responsibility for destroying the selected transport

Returns

ASCIICHAT_OK on success, error code on failure

Note

This is used for WebRTC integration when DataChannel becomes ready

Ownership transfers only on success. Replacing an owned transport destroys it.

Media must be stopped before switching transports.

Definition at line 723 of file participant.c.

                                                                                          {
  if (!p || !p->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Participant is NULL or not initialized");
  }
 
  if (session_av_state_should_run(&p->video) || session_av_state_should_run(&p->audio) || p->video_thread_created ||
      p->audio_thread_created)
    return SET_ERRNO(ERROR_INVALID_STATE, "Stop media before replacing its transport");
 
  log_info("Setting transport=%p (was=%p)", transport, p->transport);
 
  if (ownership != ACIP_TRANSPORT_BORROWED && ownership != ACIP_TRANSPORT_OWNED)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid transport ownership");
  if (transport && transport == p->transport) {
    if (ownership != p->transport_ownership)
      return SET_ERRNO(ERROR_INVALID_STATE, "Detach before transferring transport ownership");
    return ASCIICHAT_OK;
  }
  asciichat_error_t result = session_connection_stop(&p->connection);
  if (result != ASCIICHAT_OK)
    return result;
  participant_connection_init(p);
  if (transport && ownership == ACIP_TRANSPORT_OWNED) {
    result = network_connection_adopt(transport, &p->network);
    if (result != ASCIICHAT_OK)
      return result;
  }
  p->transport = transport;
  mutex_lock(&p->settings_mutex);
  p->settings_request = 0;
  p->settings_applied_request = 0;
  p->settings.version = 0;
  mutex_unlock(&p->settings_mutex);
  p->transport_ownership = transport ? ownership : ACIP_TRANSPORT_BORROWED;
  if (transport) {
    result = session_connection_start(&p->connection);
    if (result != ASCIICHAT_OK)
      return result;
  }
  p->connected = p->transport && acip_transport_is_connected(p->transport);
 
  return ASCIICHAT_OK;
}

References ACIP_TRANSPORT_BORROWED, ACIP_TRANSPORT_OWNED, ASCIICHAT_OK, session_participant::audio, session_participant::audio_thread_created, session_participant::connected, session_participant::connection, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, session_participant::initialized, log_info, session_participant::network, network_connection_adopt(), session_av_state_should_run(), session_connection_start(), session_connection_stop(), SET_ERRNO, session_participant::settings, session_participant::settings_applied_request, session_participant::settings_mutex, session_participant::settings_request, session_participant::transport, session_participant::transport_ownership, session_settings_t::version, session_participant::video, and session_participant::video_thread_created.

Referenced by session_participant_set_connection().

session_participant_start_audio()

asciichat_error_t session_participant_start_audio

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Start audio capture and streaming.

Parameters

p	Participant handle (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts capturing audio from the microphone and streaming to the server. Also starts audio playback for receiving audio from other participants. Failure releases partially initialized capture/codec resources. Stop and disconnect join workers before releasing their resources.

Definition at line 625 of file participant.c.

                                                                            {
  if (!p || !p->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid participant");
  }
 
  if (!p->connected) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not connected");
  }
 
  if (!p->enable_audio) {
    return SET_ERRNO(ERROR_INVALID_STATE, "audio not enabled");
  }
 
  if (session_av_state_is_active(&p->audio))
    return ASCIICHAT_OK;
  uint32_t generation = session_av_state_begin(&p->audio);
  if (!generation)
    return SET_ERRNO(ERROR_INVALID_STATE, "audio is starting or stopping");
 
  // Create audio capture context if not already created
  if (!p->audio_capture) {
    asciichat_errno_scope_t checkpoint = errno_checkpoint();
    p->audio_capture = session_audio_create(false); // false = participant mode (no mixing)
    if (!p->audio_capture) {
      asciichat_error_t error = participant_startup_error(checkpoint, "Failed to create audio capture context");
      session_participant_stop_audio(p);
      return error;
    }
  }
 
  void *source = p->video_capture ? session_capture_get_media_source(p->video_capture) : NULL;
  p->audio_uses_video = source != NULL;
  session_audio_set_capture_source(p->audio_capture, source);
  session_capture_set_audio_context(p->video_capture, session_audio_get_context(p->audio_capture));
 
  // Start audio capture and playback
  asciichat_error_t err = session_audio_start_duplex(p->audio_capture);
  if (err != ASCIICHAT_OK) {
    session_participant_stop_audio(p);
    return SET_ERRNO(err, "Failed to start audio duplex");
  }
 
  // Create Opus encoder for audio compression (48kHz, VOIP mode, 24 kbps)
  if (!p->opus_encoder) {
    asciichat_errno_scope_t checkpoint = errno_checkpoint();
    client_audio_pipeline_config_t profile =
        client_audio_pipeline_config_for_source(source && media_source_has_audio(source));
    p->opus_encoder =
        opus_codec_create_encoder_channels((opus_application_t)profile.opus_application, AUDIO_SAMPLE_RATE,
                                           profile.opus_bitrate, profile.encoder_channels);
    if (!p->opus_encoder) {
      asciichat_error_t error = participant_startup_error(checkpoint, "Failed to create Opus encoder");
      session_participant_stop_audio(p);
      return error;
    }
  }
 
  // Spawn audio capture thread
  if (platform_thread_create(&p->audio_capture_thread, "audio_capture", participant_audio_capture_thread, p) != 0) {
    log_error("Failed to spawn audio capture thread");
    session_participant_stop_audio(p);
    return SET_ERRNO(ERROR_THREAD, "Failed to spawn audio capture thread");
  }
 
  p->audio_thread_created = true;
  session_av_state_complete(&p->audio, generation);
  log_info("Audio capture started");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, session_participant::audio, session_participant::audio_capture, session_participant::audio_capture_thread, AUDIO_SAMPLE_RATE, session_participant::audio_thread_created, session_participant::audio_uses_video, client_audio_pipeline_config_for_source(), session_participant::connected, session_participant::enable_audio, client_audio_pipeline_config_t::encoder_channels, errno_checkpoint(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_THREAD, session_participant::initialized, log_error, log_info, media_source_has_audio(), client_audio_pipeline_config_t::opus_application, client_audio_pipeline_config_t::opus_bitrate, opus_codec_create_encoder_channels(), session_participant::opus_encoder, session_audio_create(), session_audio_get_context(), session_audio_set_capture_source(), session_audio_start_duplex(), session_av_state_begin(), session_av_state_complete(), session_av_state_is_active(), session_capture_get_media_source(), session_capture_set_audio_context(), session_participant_stop_audio(), SET_ERRNO, source, and session_participant::video_capture.

session_participant_start_video()

asciichat_error_t session_participant_start_video

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Start video capture and streaming.

Parameters

p	Participant handle (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts the configured webcam/file source and its transmission worker. Repeated starts are idempotent. Failure releases resources and leaves video inactive. Control calls must be serialized by the owning thread.

Definition at line 541 of file participant.c.

                                                                            {
  if (!p || !p->initialized) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid participant");
  }
 
  if (!p->connected) {
    return SET_ERRNO(ERROR_INVALID_STATE, "not connected");
  }
 
  if (!p->enable_video) {
    return SET_ERRNO(ERROR_INVALID_STATE, "video not enabled");
  }
 
  if (session_av_state_is_active(&p->video))
    return ASCIICHAT_OK;
  uint32_t generation = session_av_state_begin(&p->video);
  if (!generation)
    return SET_ERRNO(ERROR_INVALID_STATE, "video is starting or stopping");
 
  // Create video capture context if not already created
  if (!p->video_capture) {
    session_capture_config_t config = {
        .type = MEDIA_SOURCE_WEBCAM,
        .path = "0", // Default device
        .target_fps = (uint32_t)GET_OPTION(fps),
        .resize_for_network = true, // Optimize for bandwidth
    };
    const char *file = GET_OPTION(media_file);
    const char *url = GET_OPTION(media_url);
    char webcam_index[SESSION_PARTICIPANT_WEBCAM_INDEX_BUFFER_SIZE];
    safe_snprintf(webcam_index, sizeof(webcam_index), "%u", GET_OPTION(webcam_index));
    config.path = webcam_index;
    if (url && url[0]) {
      config.type = MEDIA_SOURCE_FILE;
      config.path = url;
    } else if (file && file[0]) {
      config.type = strcmp(file, "-") == 0 ? MEDIA_SOURCE_STDIN : MEDIA_SOURCE_FILE;
      config.path = config.type == MEDIA_SOURCE_STDIN ? NULL : file;
    }
    config.loop = GET_OPTION(media_loop);
    asciichat_errno_scope_t checkpoint = errno_checkpoint();
    p->video_capture = session_capture_create(&config);
    if (!p->video_capture) {
      asciichat_error_t error = participant_startup_error(checkpoint, "Failed to create video capture context");
      session_participant_stop_video(p);
      return error;
    }
  }
 
  // Spawn video capture thread (media source is ready in ctx)
  if (platform_thread_create(&p->video_capture_thread, "video_capture", participant_video_capture_thread, p) != 0) {
    log_error("Failed to spawn video capture thread");
    session_participant_stop_video(p);
    return SET_ERRNO(ERROR_THREAD, "Failed to spawn video capture thread");
  }
 
  p->video_thread_created = true;
  session_av_state_complete(&p->video, generation);
  log_info("Video capture started");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, session_participant::connected, session_participant::enable_video, errno_checkpoint(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_THREAD, GET_OPTION, session_participant::initialized, log_error, log_info, session_capture_config_t::loop, MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_WEBCAM, session_capture_config_t::path, safe_snprintf(), session_av_state_begin(), session_av_state_complete(), session_av_state_is_active(), session_capture_create(), session_participant_stop_video(), SESSION_PARTICIPANT_WEBCAM_INDEX_BUFFER_SIZE, SET_ERRNO, session_capture_config_t::type, session_participant::video, session_participant::video_capture, session_participant::video_capture_thread, and session_participant::video_thread_created.

session_participant_stop_audio()

void session_participant_stop_audio

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Stop audio capture and streaming.

Parameters

p	Participant handle (must not be NULL)

Definition at line 695 of file participant.c.

                                                              {
  if (!p || !p->initialized)
    return;
  session_av_state_begin_stop(&p->audio);
  if (p->audio_thread_created) {
    if (thread_join(&p->audio_capture_thread, NULL) != 0) {
      log_error("Failed to join audio capture worker; retaining its resources");
      return;
    }
    p->audio_thread_created = false;
  }
  if (p->audio_capture) {
    session_capture_set_audio_context(p->video_capture, NULL);
    session_audio_destroy(p->audio_capture);
    p->audio_capture = NULL;
  }
  if (p->opus_encoder) {
    opus_codec_destroy(p->opus_encoder);
    p->opus_encoder = NULL;
  }
  p->audio_uses_video = false;
  session_av_state_finish_stop(&p->audio);
}

References session_participant::audio, session_participant::audio_capture, session_participant::audio_capture_thread, session_participant::audio_thread_created, session_participant::audio_uses_video, session_participant::initialized, log_error, opus_codec_destroy(), session_participant::opus_encoder, session_audio_destroy(), session_av_state_begin_stop(), session_av_state_finish_stop(), session_capture_set_audio_context(), and session_participant::video_capture.

Referenced by session_participant_start_audio(), and session_participant_stop_video().

session_participant_stop_video()

void session_participant_stop_video

(

session_participant_t *

p

)

#include <src/common/session/participant.h>

Stop and join video capture, then release its resources Also stops audio when it may borrow the video media source.

Parameters

p	Participant handle (must not be NULL)

Definition at line 603 of file participant.c.

                                                              {
  if (!p || !p->initialized)
    return;
  if (p->audio_uses_video)
    session_participant_stop_audio(p);
  if (p->audio_uses_video && p->audio_thread_created)
    return;
  session_av_state_begin_stop(&p->video);
  if (p->video_thread_created) {
    if (thread_join(&p->video_capture_thread, NULL) != 0) {
      log_error("Failed to join video capture worker; retaining its resources");
      return;
    }
    p->video_thread_created = false;
  }
  if (p->video_capture) {
    session_capture_destroy(p->video_capture);
    p->video_capture = NULL;
  }
  session_av_state_finish_stop(&p->video);
}

References session_participant::audio_thread_created, session_participant::audio_uses_video, session_participant::initialized, log_error, session_av_state_begin_stop(), session_av_state_finish_stop(), session_capture_destroy(), session_participant_stop_audio(), session_participant::video, session_participant::video_capture, session_participant::video_capture_thread, and session_participant::video_thread_created.

Referenced by session_participant_start_video().

session_render_loop()

asciichat_error_t session_render_loop	(	session_capture_ctx_t *	capture,
		session_display_ctx_t *	display,
		session_should_exit_fn	should_exit,
		session_capture_fn	capture_cb,
		session_sleep_for_frame_fn	sleep_cb,
		session_keyboard_handler_fn	keyboard_handler,
		void *	user_data )

#include <src/common/session/render.h>

Unified render loop for all display modes.

Flexible render loop that supports both synchronous and event-driven modes. Optionally integrates keyboard input handling for interactive controls.

Synchronous Mode (capture != NULL, callbacks == NULL): Handles complete render lifecycle:

• Frame rate limiting via session_capture_sleep_for_fps()
• Frame capture via session_capture_read_frame()
• ASCII conversion via session_display_convert_to_ascii()
• Terminal rendering via session_display_render_frame()
• Keyboard input polling and handling (if handler provided)
• Memory cleanup with SAFE_FREE()

Used by: mirror mode, discovery participant mode

Event-Driven Mode (capture == NULL, callbacks != NULL): Delegates all frame operations to callbacks:

• Custom frame capture via capture callback (can return NULL)
• Custom timing via sleep_for_frame callback
• ASCII conversion via session_display_convert_to_ascii()
• Terminal rendering via session_display_render_frame()
• Keyboard input polling and handling (if handler provided)
• Memory cleanup with SAFE_FREE()

Used by: client mode, async frame sources

Keyboard Support:

• If keyboard_handler is provided, initializes keyboard input at loop start
• Polls for keyboard input each frame iteration
• Calls keyboard_handler callback when keys are pressed
• Cleans up keyboard on loop exit
• Safe to pass NULL for no keyboard support (backward compatible)

Parameters

capture	Capture context for synchronous mode (NULL if using callbacks)
display	Display context (must not be NULL)
should_exit	Callback to check exit condition each iteration (must not be NULL)
capture_cb	Custom capture callback for event-driven mode (NULL if using capture context)
sleep_cb	Custom sleep callback for event-driven mode (NULL if using capture context)
keyboard_handler	Optional keyboard handler callback (NULL for no keyboard support)
user_data	Opaque pointer passed to all callbacks

Returns

ASCIICHAT_OK on success, error code on failure

Note

Either capture XOR (capture_cb && sleep_cb) must be provided, not both

Caller must free capture and display contexts after this returns

In synchronous mode, capture callback can return NULL on frame unavailability

In event-driven mode, capture callback can return NULL gracefully

keyboard_handler is optional - pass NULL to disable keyboard support

Synchronous Example (Mirror Mode)

static bool my_should_exit(void *user_data) {
  return atomic_load(&g_exit_flag);
}
 
int main(void) {
  session_capture_ctx_t *capture = session_capture_create(NULL);
  session_display_ctx_t *display = session_display_create(NULL);
 
  platform_set_console_ctrl_handler(my_ctrl_handler);
 
  asciichat_error_t result = session_render_loop(
      capture, display, my_should_exit,
      NULL, NULL,  // No custom callbacks
      NULL         // No user_data needed
  );
 
  session_display_destroy(display);
  session_capture_destroy(capture);
 
  return result == ASCIICHAT_OK ? 0 : (int)result;
}

Event-Driven Example (Client Mode)

static image_t *client_capture_frame(void *user_data) {
  client_ctx_t *ctx = (client_ctx_t *)user_data;
  return network_frame_queue_pop_nonblocking(ctx->frame_queue);
}
 
static void client_sleep_for_frame(void *user_data) {
  client_ctx_t *ctx = (client_ctx_t *)user_data;
  if (network_frame_queue_empty(ctx->frame_queue)) {
    platform_sleep_ms(10);
  }
}
 
static bool client_should_exit(void *user_data) {
  return !server_connection_is_active();
}
 
int main(void) {
  session_display_ctx_t *display = session_display_create(NULL);
  client_ctx_t client_ctx = {...};
 
  asciichat_error_t result = session_render_loop(
      NULL, display, client_should_exit,  // NULL capture = event-driven
      client_capture_frame,               // Custom capture
      client_sleep_for_frame,             // Custom sleep
      &client_ctx                         // Context for callbacks
  );
 
  session_display_destroy(display);
  return result == ASCIICHAT_OK ? 0 : (int)result;
}

Definition at line 60 of file src/common/session/render.c.

                                                       {
  // Validate required parameters
  log_debug("capture=%p, display=%p, mode=%s", (void *)capture, (void *)display,
            capture ? "SYNCHRONOUS" : "EVENT-DRIVEN");
 
  if (!display) {
    SET_ERRNO(ERROR_INVALID_PARAM, "display context is NULL");
    return ERROR_INVALID_PARAM;
  }
 
  if (!should_exit) {
    SET_ERRNO(ERROR_INVALID_PARAM, "should_exit callback is NULL");
    return ERROR_INVALID_PARAM;
  }
 
  // Validate mode: either capture context OR custom callbacks, not both
  if (!capture && !capture_cb) {
    SET_ERRNO(ERROR_INVALID_PARAM, "must provide either capture context or capture callback");
    return ERROR_INVALID_PARAM;
  }
 
  if (capture && capture_cb) {
    SET_ERRNO(ERROR_INVALID_PARAM, "cannot provide both capture context and capture callback");
    return ERROR_INVALID_PARAM;
  }
 
  // In event-driven mode, both capture_cb and sleep_cb must be provided together
  if (capture_cb && !sleep_cb) {
    SET_ERRNO(ERROR_INVALID_PARAM, "capture_cb requires sleep_cb (must provide both or neither)");
    return ERROR_INVALID_PARAM;
  }
 
  if (sleep_cb && !capture_cb) {
    SET_ERRNO(ERROR_INVALID_PARAM, "sleep_cb requires capture_cb (must provide both or neither)");
    return ERROR_INVALID_PARAM;
  }
 
  // SYNCHRONOUS MODE: Use threaded pipeline for capture + render
  if (capture != NULL) {
    log_debug("[SESSION_RENDER_LOOP_SYNCHRONOUS] Creating pipeline... (capture=%p, display=%p)", (void *)capture,
              (void *)display);
    session_pipeline_t *pipeline = NULL;
    asciichat_error_t pipeline_err = session_pipeline_create(capture, display, &pipeline);
    log_debug("[SESSION_RENDER_LOOP_SYNCHRONOUS] pipeline_create returned: %d (pipeline=%p)", pipeline_err,
              (void *)pipeline);
    if (pipeline_err != ASCIICHAT_OK) {
      log_error("[SESSION_RENDER_LOOP_SYNCHRONOUS] Pipeline creation failed %s",
                asciichat_error_format(NULL, pipeline_err));
      return pipeline_err;
    }
    log_debug("[SESSION_RENDER_LOOP_SYNCHRONOUS] Pipeline created successfully, running main loop...");
 
    // Disable logging to stdout/stderr during rendering (same as event-driven mode).
    // This prevents logs from mixing with ASCII art output. Logs still go to file.
    log_set_terminal_output(false);
    asciichat_error_t run_err = session_pipeline_run_main(pipeline, should_exit, keyboard_handler, user_data);
    log_set_terminal_output(true);
 
    asciichat_error_t drain_err = session_pipeline_destroy(pipeline);
    // The encoder no longer writes here. Use capture duration, excluding time spent draining.
    if (GET_OPTION(snapshot_mode) && display && g_snapshot_first_capture_ns > 0)
      session_display_set_snapshot_actual_duration(display, (double)g_snapshot_actual_duration_ms / 1000.0);
 
    return run_err == ASCIICHAT_OK ? drain_err : run_err;
  } else {
    log_warn("capture is NULL - will not use pipeline (capture_cb=%p)", (void *)capture_cb);
  }
 
  // Snapshot mode state tracking
  bool snapshot_mode = GET_OPTION(snapshot_mode);
  bool snapshot_done = false;
  uint64_t frames_rendered_since_first = 0; // Track frames rendered after first frame (for snapshot delay)
  // NOTE: g_snapshot_first_frame_rendered is set by display.c when first frame is rendered via platform_write_all()
 
  log_debug("display=%p capture=%p capture_cb=%p snapshot_mode=%s snapshot_delay=%.2f", (void *)display,
            (void *)capture, (void *)capture_cb, snapshot_mode ? "YES" : "NO",
            snapshot_mode ? GET_OPTION(snapshot_delay) : 0.0);
  if (should_exit(user_data)) {
    log_warn("EXIT signal already set at entry, aborting render loop");
    return ASCIICHAT_OK;
  }
 
  // Keyboard input initialization (if keyboard handler is provided)
  // Disable keyboard only in snapshot mode
  // Keyboard is pre-initialized from asciichat_shared_init()
  // Allow keyboard input in all other modes if handler provided
  bool keyboard_enabled = keyboard_handler && !snapshot_mode;
 
  // Pause mode state tracking (for pause/unpause transitions in event-driven mode)
  bool initial_paused_frame_rendered = false;
  bool is_paused = false;
  log_debug("Keyboard setup - handler=%p snapshot=%s enabled=%s", (void *)keyboard_handler,
            snapshot_mode ? "YES" : "NO", keyboard_enabled ? "YES" : "NO");
 
  // Log TTY detection status for debugging keyboard issues
  log_debug("TTY Status: stdin_tty=%d stdout_tty=%d interactive=%d keyboard_enabled=%d", terminal_is_stdin_tty(),
            terminal_is_stdout_tty(), terminal_is_interactive(), keyboard_enabled);
 
  // Frame rate timing (event-driven mode only)
  uint64_t frame_count = 0;
  uint64_t frame_start_ns = 0;
 
  // Event-driven mode: disable console logging during rendering to prevent logs from corrupting frame display
  // This must be done BEFORE the render loop to avoid repeated lock/unlock cycles that could cause deadlocks
  log_debug("[EVENT_DRIVEN_MODE] Entering render loop. snapshot_mode=%s", snapshot_mode ? "YES" : "NO");
  log_set_terminal_output(false);
 
  asciichat_error_t capture_result = ASCIICHAT_OK;
  // Main render loop
  int loop_iteration = 0;
  log_debug("[RENDER_LOOP_START] snapshot_mode=%s, snapshot_delay=%.2f", snapshot_mode ? "YES" : "NO",
            snapshot_mode ? GET_OPTION(snapshot_delay) : 0.0);
 
  // Wait for splash animation to complete before rendering first frame
  // This prevents ASCII art from mixing with splash screen output
  // But skip for immediate snapshots (snapshot-delay=0) which need to output first frame immediately
  static bool splash_wait_done = false;
  if (!splash_wait_done) {
    splash_wait_done = true;
    if (!(GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0)) {
      // Re-enable logging briefly for splash wait, then disable again
      log_set_terminal_output(true);
      splash_wait_for_animation();
      log_set_terminal_output(false);
    }
  }
 
  // In snapshot mode, we must render at least one frame before checking should_exit
  // to ensure the snapshot delay timer can start
  bool force_first_iteration = snapshot_mode && frame_count == 0;
 
  // Register display context globally so signal handlers (Ctrl+C) can access it
  // This enables Ctrl+C to close the help screen instead of quitting when help is active
  session_display_set_global_context(display);
 
  while (force_first_iteration || (!should_exit(user_data) && !(snapshot_mode && snapshot_done))) {
    force_first_iteration = false;
    loop_iteration++;
    log_debug("[LOOP_ITER] iteration=%d, snapshot_done=%s, frame_count=%lu", loop_iteration,
              snapshot_done ? "YES" : "NO", frame_count);
    if (loop_iteration % 60 == 0) {
      log_debug("iteration %d, should_exit check returning false", loop_iteration);
    }
    // Snapshot mode: exit at start of iteration if done
    // This prevents frame 2+ from being captured when snapshot_delay has elapsed
    if (snapshot_mode && snapshot_done && frame_count > 0) {
      log_debug("[SNAPSHOT_EXIT] Snapshot mode: exiting at loop iteration start (snapshot_done=true, frames=%lu)",
                frame_count);
      break;
    }
 
    log_debug_every(US_PER_SEC_INT, "frame %lu", frame_count);
    // Frame timing - measure total time to maintain target FPS
    frame_start_ns = time_get_ns();
 
    // Frame capture and timing - mode-dependent
    image_t *image = NULL;
    uint64_t capture_start_ns = 0;
    uint64_t capture_end_ns = 0;
    uint64_t pre_convert_ns = 0;
    uint64_t post_convert_ns = 0;
    uint64_t conversion_elapsed_ns = 0;
 
    // EVENT-DRIVEN MODE: Frames come from callbacks
    // Both sleep_cb and capture_cb are guaranteed non-NULL by validation above
    sleep_cb(user_data);
    ASCII_OTEL_SCOPE(PIPELINE_DISPLAY);
    asciichat_errno_scope_t frame_scope = errno_checkpoint();
    image = capture_cb(user_data);
 
    if (!image) {
      asciichat_error_context_t failure;
      if (errno_peek_since(frame_scope, &failure)) {
        capture_result = failure.code;
        break;
      }
      // No frame available - this is normal in async modes (network latency, etc.)
      // Just continue to next iteration, don't exit
      continue;
    }
 
    // Event-driven mode: increment frame count
    frame_count++;
 
    // Convert image to ASCII using display context
    // Handles all palette, terminal caps, width, height, stretch settings
    pre_convert_ns = time_get_ns();
    char *ascii_frame = session_display_convert_to_ascii_reuse(display, image);
    post_convert_ns = time_get_ns();
    conversion_elapsed_ns = post_convert_ns - pre_convert_ns;
 
    if (frame_count <= 3) {
      log_debug("RENDER_LOOP[%lu]: image=%p, ascii_frame=%p (conversion took %u ms)", frame_count, (void *)image,
                (void *)ascii_frame, (unsigned)(conversion_elapsed_ns / NS_PER_MS_INT));
    }
 
    // Declare variables that need scope beyond the if (ascii_frame) block
    bool is_paused_frame = initial_paused_frame_rendered && is_paused;
    bool output_paused_frame = snapshot_mode && is_paused_frame;
    uint64_t pre_render_ns = 0, post_render_ns = 0;
 
    if (ascii_frame) {
      log_debug_every(US_PER_SEC_INT, "ascii_frame ready (len=%zu)", strlen(ascii_frame));
 
      // Always attempt to render frames; the display context will handle filtering based on:
      // - TTY mode: render all frames with cursor control (even in snapshot mode, for animation)
      // - Piped mode: render all frames without cursor control (for continuous capture)
      // - Snapshot mode on non-TTY: only the display context renders the final frame
      // BUT: don't render if splash screen is still animating - wait for it to finish
      bool splash_running = splash_is_running();
      bool should_write = !splash_running;
      if (frame_count == 1) {
        log_dev("[RENDER_FRAME] Frame 1: splash_is_running=%s, should_write=%s", splash_running ? "YES" : "NO",
                should_write ? "YES" : "NO");
      }
      if (should_write) {
        // is_final = true when: snapshot done, or paused frame (for both snapshot and pause modes)
        // Profile: render frame
        pre_render_ns = time_get_ns();
 
        if (frame_count <= 5 || frame_count % 10 == 0) {
          log_debug("Frame %lu - calling session_display_render_frame, display=%p", (unsigned long)frame_count,
                    (void *)display);
        }
 
        // Check if SIGINT handler cancelled help mode (Ctrl+C while help is open).
        // The signal handler sets an atomic flag instead of touching state directly.
        if (display && keyboard_help_check_signal_cancel()) {
          keyboard_help_toggle(display);
          log_debug("Ctrl+C cancelled help screen - returning to ASCII art");
        }
 
        session_display_render_frame(display, ascii_frame);
 
        // Snapshot mode: increment frame counter for all displayed frames
        // Counter starts at 1 for the first displayed frame, then 2, 3, 4... for subsequent frames
        // Timer is started by display.c when g_snapshot_first_frame_rendered is set
        if (snapshot_mode && g_snapshot_first_frame_rendered) {
          frames_rendered_since_first++;
          log_debug_every(US_PER_SEC_INT, "[SNAPSHOT] Frame rendered: frames_rendered_since_first=%lu",
                          frames_rendered_since_first);
        }
      }
 
      // Keyboard input polling (if enabled) - MUST come before snapshot exit check so help screen can be toggled
      // Allow keyboard in snapshot mode too (for help screen toggle debugging)
      // Only enable keyboard if BOTH stdin AND stdout are TTYs to avoid buffering issues
      // when tcsetattr() modifies the tty line discipline
      if (keyboard_enabled && keyboard_handler) {
        uint64_t keyboard_start_ns = time_get_ns();
        keyboard_key_t key = ui_input_read_key(UI_SCREEN_MEDIA);
        double keyboard_elapsed_ns = (double)time_elapsed_ns(keyboard_start_ns, time_get_ns());
        if (keyboard_elapsed_ns >= 0.0) {
          char _duration_str[TIME_DURATION_BUFFER_SIZE];
          time_pretty((uint64_t)keyboard_elapsed_ns, -1, _duration_str, sizeof(_duration_str));
          log_dev_every(1 * NS_PER_SEC_INT, "RENDER[%lu] Keyboard read complete (key=%d) in %s",
                        (unsigned long)frame_count, key, _duration_str);
        }
        if (key != KEY_NONE) {
          log_debug("KEYBOARD: Key pressed: code=%d char='%c'", key, (key >= 32 && key < 127) ? key : '?');
          // Normal keyboard handler
          log_debug("KEYBOARD: Normal handler taking key %d", key);
          keyboard_handler(capture, key, user_data);
        }
      }
 
      // Free frame before checking exit conditions to avoid double-free
      session_display_release_ascii(display, ascii_frame);
    }
 
    // Snapshot mode: check if elapsed time has reached snapshot_delay duration (terminal render timing)
    // Separate from capture timing - both should measure their own snapshot_delay
    if (snapshot_mode && !snapshot_done) {
      if (g_snapshot_first_frame_rendered && g_snapshot_first_frame_rendered_ns > 0) {
        double snapshot_delay = GET_OPTION(snapshot_delay);
        uint64_t now_ns = time_get_ns();
        uint64_t elapsed_ns = now_ns - g_snapshot_first_frame_rendered_ns;
        double elapsed_sec = (double)elapsed_ns / (double)NS_PER_SEC_INT;
 
        if (frames_rendered_since_first == 1 || frames_rendered_since_first % 20 == 0) {
          log_debug("SNAPSHOT: RENDER_CHECK iter=%lu elapsed=%.3f target=%.2f (from first_frame_rendered)",
                    frames_rendered_since_first, elapsed_sec, snapshot_delay);
        }
 
        // snapshot_delay=0 means exit after first frame
        // snapshot_delay>0 means wait that many seconds before exiting
        // Exit is based on elapsed wall-clock time, not frame count
        bool should_exit = (snapshot_delay == 0.0) || (elapsed_sec >= snapshot_delay);
 
        if (should_exit) {
          log_debug("SNAPSHOT: RENDER_DONE at iteration %lu - elapsed=%.3f target=%.2f (setting snapshot_done=true)",
                    frames_rendered_since_first, elapsed_sec, snapshot_delay);
          // We don't end frames with newlines so the next log would print on the same line as the frame's
          // last row without an \n here. We only need this \n in stdout when interactive,
          // so piped snapshots don't have a weird newline in stdout that they don't need.
          if (terminal_is_interactive()) {
            ui_controller_printf(STDOUT_FILENO, "\n");
          }
          snapshot_done = true;
        }
      } else {
        if (frames_rendered_since_first == 0) {
          log_debug("SNAPSHOT: Waiting for first_frame_rendered (g_snapshot_first_frame_rendered=%d, "
                    "g_snapshot_first_frame_rendered_ns=%llu)",
                    g_snapshot_first_frame_rendered, (unsigned long long)g_snapshot_first_frame_rendered_ns);
        }
      }
    }
 
    // Exit conditions: snapshot mode exits after capturing the final frame or initial paused frame
    if (snapshot_mode && (snapshot_done || output_paused_frame)) {
      log_debug("SNAPSHOT: EXIT CONDITION MET - snapshot_done=%d, output_paused_frame=%d", snapshot_done,
                output_paused_frame);
 
      // Calculate elapsed time from first frame captured (for video file)
      // This is separate from render time - video should span from first capture to last capture
      double capture_elapsed_sec = 0.0;
      if (g_snapshot_first_capture_ns > 0) {
        uint64_t now_ns = time_get_ns();
        uint64_t elapsed_ns = now_ns - g_snapshot_first_capture_ns;
        capture_elapsed_sec = (double)elapsed_ns / (double)NS_PER_SEC_INT;
        log_debug("SNAPSHOT: EXIT - Capture elapsed: %.3f seconds, render elapsed: %.3f seconds, "
                  "g_snapshot_first_capture_ns=%llu",
                  capture_elapsed_sec,
                  (g_snapshot_first_frame_rendered_ns > 0)
                      ? (double)(now_ns - g_snapshot_first_frame_rendered_ns) / NS_PER_SEC_INT
                      : 0.0,
                  (unsigned long long)g_snapshot_first_capture_ns);
      } else {
        log_warn("SNAPSHOT: EXIT condition met but g_snapshot_first_capture_ns is 0!");
      }
 
      // Pass actual capture elapsed time to encoder for correct video duration
      log_debug("SNAPSHOT: About to call session_display_set_snapshot_actual_duration with duration=%.3f, display=%p",
                capture_elapsed_sec, (void *)display);
      if (display) {
        session_display_set_snapshot_actual_duration(display, capture_elapsed_sec);
      } else {
        log_warn("SNAPSHOT: display context is NULL!");
      }
 
      // Signal application to exit in snapshot mode
      APP_CALLBACK_VOID(signal_exit);
      break;
    }
 
    // Frame rendering and timing details (moved down since snapshot exit is now above it)
    if (ascii_frame) {
 
      // Measure frame completion right after rendering, BEFORE keyboard polling
      // This gives us accurate timing for just the core frame operations
      uint64_t frame_end_render_ns = time_get_ns();
 
      // Calculate each phase duration
      uint64_t prestart_ms =
          (capture_start_ns > frame_start_ns) ? (capture_start_ns - frame_start_ns) / NS_PER_MS_INT : 0;
      uint64_t capture_ms =
          (capture_end_ns > capture_start_ns) ? (capture_end_ns - capture_start_ns) / NS_PER_MS_INT : 0;
      uint64_t convert_ms = conversion_elapsed_ns / NS_PER_MS_INT;
      uint64_t render_ms =
          (post_render_ns > pre_render_ns && post_render_ns > 0) ? (post_render_ns - pre_render_ns) / NS_PER_MS_INT : 0;
      uint64_t total_ms =
          (frame_end_render_ns > frame_start_ns) ? (frame_end_render_ns - frame_start_ns) / NS_PER_MS_INT : 0;
 
      // Log phase breakdown every 5 frames
      if (frame_count % 5 == 0) {
        log_dev_every(
            2 * NS_PER_SEC_INT,
            "PHASE_BREAKDOWN[%lu]: prestart=%llu ms, capture=%llu ms, convert=%llu ms, render=%llu ms (total=%llu ms)",
            frame_count, prestart_ms, capture_ms, convert_ms, render_ms, total_ms);
      }
    } else {
      // Snapshot mode: even if frame conversion failed, check if we should exit
      // This ensures snapshot_delay is honored even if display context isn't rendering
      if (snapshot_mode && snapshot_done) {
        break;
      }
    }
 
    // In event-driven mode, frame rate limiting is handled by the sleep_cb callback
    // Synchronous mode (with capture context) uses the pipeline and returns early above
 
    // Note: Images returned by media sources are cached/reused and should NOT be destroyed
    // The image pointers are managed by the source and will be cleaned up on source shutdown
  } // while (!should_exit(user_data)) {
 
  // Re-enable console logging after rendering completes
  log_set_terminal_output(true);
  if (!snapshot_mode && terminal_is_interactive()) {
    ui_controller_printf(STDOUT_FILENO, "\n");
  }
 
  // Keyboard input cleanup (if it was initialized)
  if (keyboard_enabled) {
    ui_controller_remove(UI_SCREEN_HELP);
    ui_controller_remove(UI_SCREEN_MEDIA);
    log_debug_every(2 * NS_PER_SEC_INT, "Keyboard input disabled");
  }
 
  // Unregister global display context (for signal handlers)
  session_display_set_global_context(NULL);
 
  return capture_result;
}

References APP_CALLBACK_VOID, ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, asciichat_error_context_t::code, errno_checkpoint(), errno_peek_since(), ERROR_INVALID_PARAM, g_snapshot_actual_duration_ms, g_snapshot_first_capture_ns, g_snapshot_first_frame_rendered, g_snapshot_first_frame_rendered_ns, GET_OPTION, KEY_NONE, keyboard_help_check_signal_cancel(), keyboard_help_toggle(), log_debug, log_debug_every, log_dev, log_dev_every, log_error, log_set_terminal_output(), log_warn, NS_PER_MS_INT, NS_PER_SEC_INT, session_display_convert_to_ascii_reuse(), session_display_release_ascii(), session_display_render_frame(), session_display_set_global_context(), session_display_set_snapshot_actual_duration(), session_pipeline_create(), session_pipeline_destroy(), session_pipeline_run_main(), SET_ERRNO, should_exit(), signal_exit(), splash_is_running(), splash_wait_for_animation(), TIME_DURATION_BUFFER_SIZE, time_elapsed_ns(), time_pretty(), ui_controller_printf(), ui_controller_remove(), ui_input_read_key(), UI_SCREEN_HELP, UI_SCREEN_MEDIA, and US_PER_SEC_INT.

splash_clear_display_context()

void splash_clear_display_context

(

void

)

#include <include/ascii-chat/tui/splash.h>

Clear the cached display context to prevent use-after-free.

Must be called when the display context is being destroyed to prevent worker threads from accessing freed memory. This clears the reference stored in g_splash_state.

Note

Thread-safe (uses atomic operations)

Safe to call multiple times

Definition at line 441 of file splash.c.

                                        {
  // No-op: display context is no longer cached
}

Referenced by session_display_destroy().

splash_intro_done()

int splash_intro_done

(

void

)

#include <include/ascii-chat/tui/splash.h>

Signal that intro splash should end (first frame ready to render).

Tells the splash screen animation to stop displaying. On the next animation frame attempt, it will clear the screen and exit cleanly.

Important: Call splash_wait_for_animation() after this to ensure the animation thread has fully exited before rendering ASCII art.

Returns

ASCIICHAT_OK on success

Note

Safe to call multiple times

After calling this, next frame render should show real ASCII art

The animation thread checks this flag and exits gracefully

MUST call splash_wait_for_animation() before displaying ASCII frames

Definition at line 426 of file splash.c.

                            {
  atomic_store_u64(&g_splash_state.intro_done_time_ns, time_get_ns());
  if (discovery_splash_snapshot().enabled || (GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0))
    atomic_store_bool(&g_splash_state.should_stop, true);
  // The monitor retires the splash snapshot before clearing is_running. Keep
  // thread_created set until splash_wait_for_animation() joins that monitor.
 
  return 0;
}

References enabled, and GET_OPTION.

Referenced by display_disable_logging_for_first_frame(), session_connection_establish(), and session_display_write_ascii_frame().

splash_intro_start()

int splash_intro_start

(

session_display_ctx_t *

ctx

)

#include <include/ascii-chat/tui/splash.h>

Start animated intro screen with rainbow ASCII art (non-blocking).

Starts the splash screen animation that runs while initialization happens in the background. The animation continues until splash_intro_done() is called.

Display Requirements:

• stdin AND stdout must be TTY (platform_isatty())
• –splash-screen=false must not be set
• Not in snapshot mode (–snapshot)
• Startup layout needs 50 columns x 20 rows; discovery uses a compact layout below that.

Behavior:

• Starts animated rainbow border with "ascii-chat" logo
• Runs continuously until splash_intro_done() is called
• Animation loops with rainbow color cycling
• When splash_intro_done() called, animation stops on next frame
• Next real frame render clears screen and shows ASCII art

Parameters

ctx	Display context (can be NULL for minimal stdout-only mode)

Returns

ASCIICHAT_OK on success, error code on failure

Note

Non-blocking - returns immediately after starting animation

Call splash_intro_done() when first frame is ready to render

Uses lock-free option access via GET_OPTION() macro

Definition at line 375 of file splash.c.

                                                   {
  (void)ctx; // Not needed - display context is not actively used
 
  // Check if splash should display
  if (!splash_should_display(true)) {
    return 0;
  }
 
  discovery_splash_t discovery = discovery_splash_snapshot();
  if (discovery.enabled && (!terminal_is_interactive() || !terminal_is_stdout_tty() || GET_OPTION(snapshot_mode))) {
    return 0;
  }
  if (atomic_load_bool(&g_splash_state.thread_created))
    return 0;
 
  // Redirect splash screen to stderr when stdout is piped (not a TTY).
  // This keeps stdout clean for frame data while splash goes to stderr.
  // Uses platform_isatty() so non-desktop platforms (iOS, WASM) can override.
  if (!platform_isatty(STDOUT_FILENO)) {
    terminal_screen_set_output_fd(STDERR_FILENO);
  }
 
  // Initialize log buffer (same pattern as server_status)
  splash_log_init();
 
  // Clear log buffer for clean slate
  splash_log_clear();
 
  // Set running flag
  atomic_store_bool(&g_splash_state.is_running, true);
  atomic_store_bool(&g_splash_state.should_stop, false);
  atomic_store_u64(&g_splash_state.intro_done_time_ns, 0);
  g_splash_state.start_time_ns = time_get_ns();
 
  // Start monitor thread (only create once)
  bool expected_false = false;
  if (!atomic_cas_bool(&g_splash_state.thread_created, &expected_false, true)) {
    return 0;
  }
 
  int err = platform_thread_create(&g_splash_state.monitor_thread, "splash_monitor", splash_monitor_thread, NULL);
  if (err != ASCIICHAT_OK) {
    log_warn("Failed to create splash monitor thread: error=%d", err);
    atomic_store_bool(&g_splash_state.thread_created, false);
    atomic_store_bool(&g_splash_state.is_running, false);
    return 0;
  }
 
  return 0; // ASCIICHAT_OK
}

References ASCIICHAT_OK, ui_discovery_view_t::enabled, GET_OPTION, log_warn, splash_log_clear(), splash_log_init(), splash_should_display(), and terminal_screen_set_output_fd().

splash_is_running()

bool splash_is_running

(

void

)

#include <include/ascii-chat/tui/splash.h>

Check if splash screen animation is currently running.

Returns true if the splash animation thread is actively rendering. Used to prevent ASCII art frame rendering from overlapping with the splash.

Returns

true if splash is running, false otherwise

Note

Thread-safe (uses atomic operations)

Can be called from render loop to skip frame output during splash

Definition at line 445 of file splash.c.

                             {
  // Check if splash animation is currently rendering
  // Used to prevent ASCII art from rendering while splash is animating
  return atomic_load_bool(&g_splash_state.is_running);
}

Referenced by session_render_loop().

splash_log_append()

void splash_log_append

(

const char *

message

)

#include <include/ascii-chat/tui/splash.h>

Append message to splash log buffer.

Delegates to the standard terminal_screen log append. Called by logging system to capture messages for display.

Parameters

message

Log message to append

splash_log_clear()

void splash_log_clear

(

void

)

#include <include/ascii-chat/tui/splash.h>

Clear splash log buffer.

Delegates to the standard terminal_screen log clear. Useful when starting fresh splash animation.

Definition at line 136 of file splash.c.

                            {
  terminal_screen_log_clear();
}

References terminal_screen_log_clear().

Referenced by splash_intro_start().

splash_log_destroy()

void splash_log_destroy

(

void

)

#include <include/ascii-chat/tui/splash.h>

Destroy splash log buffer.

Delegates to the standard terminal_screen log cleanup.

Definition at line 131 of file splash.c.

                              {
  log_clear_session_log_buffer();
  terminal_screen_log_destroy();
}

References log_clear_session_log_buffer(), and terminal_screen_log_destroy().

splash_log_init()

void splash_log_init

(

void

)

#include <include/ascii-chat/tui/splash.h>

Initialize log buffer for splash animation.

Delegates to the standard terminal_screen log initialization. Call once at startup before rendering splash screen.

Definition at line 124 of file splash.c.

                           {
  session_log_buffer_t *buf = terminal_screen_log_init();
  if (buf) {
    log_set_session_log_buffer(buf);
  }
}

References log_set_session_log_buffer(), and terminal_screen_log_init().

Referenced by splash_intro_start().

splash_notify_first_frame()

void splash_notify_first_frame

(

void

)

#include <include/ascii-chat/tui/splash.h>

Notify splash that the first frame has been rendered.

Called from display_render_frame() when the first ASCII frame is rendered. This updates the splash state's atomic flag so the splash animation knows when to stop.

Important: This function does NOT access the display context pointer, making it safe to call from any thread even if the context is being freed.

Note

Thread-safe (uses atomic operations)

Safe to call multiple times

Must NOT dereference display_ctx (unlike splash_intro_done)

splash_restore_stderr()

void splash_restore_stderr

(

void

)

#include <include/ascii-chat/tui/splash.h>

Restore stderr after splash animation completes.

Restores the original stderr file descriptor that was saved when splash_intro_start() was called. This must be called after splash animation completes to allow debug logging to appear on screen again.

Note

Safe to call multiple times (idempotent)

Must only be called after splash_intro_start() was called

Definition at line 436 of file splash.c.

                                 {
  // No-op: stderr suppression is no longer used
  // Logging works naturally through session_log_buffer
}

splash_set_update_notification()

void splash_set_update_notification

(

const char *

notification

)

#include <include/ascii-chat/tui/splash.h>

Set update notification to display on splash/status screens.

Sets a notification message that will be displayed on splash screens (intro and status) to inform users about available updates.

Parameters

notification

Update notification message (can be NULL or empty to clear)

Note

This should be called before splash_intro_start()

Thread-safe via internal mutex

Definition at line 481 of file splash.c.

                                                              {
  splash_mutex_init(&g_update_notification_lifecycle, &g_update_notification_mutex, "update_notification");
  mutex_lock(&g_update_notification_mutex);
 
  if (!notification || notification[0] == '\0') {
    g_update_notification[0] = '\0';
    log_debug("Cleared update notification for splash/status screens");
  } else {
    SAFE_STRNCPY(g_update_notification, notification, sizeof(g_update_notification));
    log_debug("Set update notification for splash/status screens: %s", notification);
  }
 
  mutex_unlock(&g_update_notification_mutex);
}

References log_debug, and SAFE_STRNCPY.

splash_should_display()

bool splash_should_display

(

bool

is_intro

)

#include <include/ascii-chat/tui/splash.h>

Check if splash screen should display.

Determines if TTY checks pass and options allow splash display. Respects both TTY detection and option flags.

Parameters

is_intro

true for intro screen checks, false for status screen

Returns

true if splash should display, false if should skip

Check if splash screen should display.

Renders exactly 8 lines:

• Line 1: Top border
• Lines 2-5: ASCII logo (4 lines, centered, rainbow animated)
• Line 6: Tagline (centered)
• Line 7: Connection target (centered)
• Line 8: Bottom border

Parameters

buf	Frame buffer to write into
term_size	Current terminal dimensions
user_data	Pointer to splash_header_ctx_t

Definition at line 242 of file splash.c.

                                          {
  // Check option flags (display splash if enabled, regardless of TTY for testing)
  if (is_intro) {
    // Allow splash in snapshot mode if loading from URL/file (has loading time)
    // Skip splash only for quick webcam snapshots (unless explicitly enabled)
    bool splash_screen_opt = GET_OPTION(splash_screen);
    bool splash_explicitly_set = GET_OPTION(splash_screen_explicitly_set);
    bool is_snapshot = GET_OPTION(snapshot_mode);
    bool has_media = (GET_OPTION(media_url) && strlen(GET_OPTION(media_url)) > 0) ||
                     (GET_OPTION(media_file) && strlen(GET_OPTION(media_file)) > 0);
 
    // Show splash if enabled, but in snapshot mode only if:
    // 1. Has media file/URL, OR
    // 2. Explicitly enabled with --splash-screen=true
    bool should_display = splash_screen_opt && (!is_snapshot || has_media || splash_explicitly_set);
    // Show splash if:
    // 1. Not in snapshot mode, OR
    // 2. In snapshot mode but loading from URL/file (needs splash during load)
    return should_display;
  } else {
    return GET_OPTION(status_screen);
  }
}

References GET_OPTION.

Referenced by splash_intro_start().

splash_wait_for_animation()

void splash_wait_for_animation

(

void

)

#include <include/ascii-chat/tui/splash.h>

Wait for splash animation thread to fully exit.

Blocks until the splash animation thread has completed and exited. Must be called after splash_intro_done() and before rendering ASCII frames to prevent the splash and ASCII art from appearing simultaneously.

Note

Safe to call multiple times

On shutdown, waits at most 100ms for a blocked writer before returning. Normal frame handoff always waits for the writer to finish.

MUST be called before first display_render_frame() call

Definition at line 451 of file splash.c.

                                     {
  if (!atomic_load_bool(&g_splash_state.thread_created))
    return;
 
  // Keep terminal ownership until the writer finishes, but allow shutdown to
  // proceed if an undrained output pipe blocks the monitor thread. Polling
  // also handles shutdown requested after the normal handoff has begun, and
  // avoids platforms whose timed thread join falls back to a blocking join.
  uint64_t shutdown_started_ns = 0;
  while (atomic_load_bool(&g_splash_state.is_running)) {
    if (shutdown_is_requested()) {
      atomic_store_bool(&g_splash_state.should_stop, true);
      uint64_t now = time_get_ns();
      if (shutdown_started_ns == 0)
        shutdown_started_ns = now;
      if (now - shutdown_started_ns >= 100 * NS_PER_MS_INT)
        return;
    }
    platform_sleep_ms(10);
  }
 
  // The monitor clears is_running after retiring its presentation snapshot.
  asciichat_error_t err = thread_join(&g_splash_state.monitor_thread, NULL);
  if (err != ASCIICHAT_OK) {
    log_warn("Splash animation join failed: %s", asciichat_error_format(NULL, err));
    return;
  }
  atomic_store_bool(&g_splash_state.thread_created, false);
}

References asciichat_error_format(), ASCIICHAT_OK, log_warn, NS_PER_MS_INT, platform_sleep_ms(), and shutdown_is_requested().

Referenced by session_connection_establish(), session_display_write_ascii_frame(), and session_render_loop().

update_banner_cancel_check()

void update_banner_cancel_check

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Cancel an in-flight background startup check before joining its worker.

Definition at line 750 of file update_banner.c.

                                      {
  atomic_store(&g_update_cancel_requested, true);
}

update_banner_handle_key()

bool update_banner_handle_key

(

int

key

)

#include <include/ascii-chat/tui/update_banner.h>

Consumes F12 and overlay-local keys before mode-specific shortcut handling.

Definition at line 682 of file update_banner.c.

                                       {
  if (key == KEY_F12) {
    update_banner_toggle_overlay();
    return true;
  }
  if (!g_update_overlay)
    return false;
  bool checking = update_banner_is_checking();
  update_check_result_t result = {0};
  bool available = !checking && update_banner_copy_result(&result) && result.update_available;
  int count = update_action_count(false, checking, available);
  if (update_select_key(key, count))
    return true;
  if (key == '\r' || key == '\n') {
    int selected = atomic_load(&g_update_selected_action) % count;
    if ((available && selected == 2) || (!available && selected == 0)) {
      update_banner_toggle_overlay();
      return true;
    }
    if (checking)
      return true;
    if (available && selected == 0) {
      (void)update_banner_install_update();
      return true;
    }
    if (available && selected == 1) {
      update_banner_open_release();
      return true;
    }
    key = 'r';
  }
  if (key == KEY_ESCAPE) {
    update_banner_toggle_overlay();
    return true;
  }
  if (key == 'o' || key == 'O') {
    if (!update_banner_is_checking())
      update_banner_open_release();
    return true;
  }
  if (key == 'r' || key == 'R') {
    if (update_banner_is_checking())
      return true;
    update_banner_wait_for_check();
    update_banner_start_check_impl(true);
    return true;
  }
  return g_update_overlay;
}

References KEY_ESCAPE, KEY_F12, update_check_result_t::update_available, update_banner_install_update(), update_banner_is_checking(), update_banner_toggle_overlay(), and update_banner_wait_for_check().

Referenced by ui_input_read_key().

update_banner_has_update()

bool update_banner_has_update

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Check if an update is available (thread-safe).

Returns

true if update_banner_set_result() was called with an available update

Definition at line 110 of file update_banner.c.

                                    {
  update_check_result_t result = {0};
  return update_banner_copy_result(&result) && result.update_available;
}

References update_check_result_t::update_available.

update_banner_install_update()

bool update_banner_install_update

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Run the installation command associated with this binary and request exit on success.

Definition at line 362 of file update_banner.c.

                                        {
  update_check_result_t result = {0};
  if (!update_banner_copy_result(&result) || !result.update_available) {
    return false;
  }
  g_update_install_failed = false;
 
  install_method_t method = update_check_detect_install_method();
  int exit_code = -1;
#ifndef NDEBUG
  const char *test_command = SAFE_GETENV("ASCII_CHAT_TEST_UPDATE_COMMAND");
  if (test_command && test_command[0]) {
#ifdef _WIN32
    const char *argv[] = {"cmd", "/d", "/c", test_command, NULL};
    exit_code = platform_execute_subprocess("cmd", argv, NULL, 0, NULL, NULL);
#else
    const char *argv[] = {"/bin/sh", "-c", test_command, NULL};
    exit_code = platform_execute_subprocess("/bin/sh", argv, NULL, 0, NULL, NULL);
#endif
  } else
#endif
      if (method == INSTALL_METHOD_HOMEBREW) {
    const char *argv[] = {"brew", "upgrade", "ascii-chat", NULL};
    exit_code = platform_execute_subprocess("brew", argv, NULL, 0, NULL, NULL);
  } else if (method == INSTALL_METHOD_SCOOP) {
    // Scoop is a PowerShell script/shim, rather than a native executable.
    const char *argv[] = {"powershell", "-NoProfile", "-Command",
                          "$ErrorActionPreference = 'Stop'; scoop update ascii-chat; if (!$?) { exit 1 }", NULL};
    exit_code = platform_execute_subprocess("powershell", argv, NULL, 0, NULL, NULL);
  } else if (method == INSTALL_METHOD_ARCH_AUR) {
    const char *helper = update_check_get_aur_helper();
    if (!helper) {
      log_warn("No supported AUR helper is available");
      g_update_install_failed = true;
      ui_controller_redraw();
      return false;
    }
    const char *argv[] = {helper, "-S", "ascii-chat", NULL};
    exit_code = platform_execute_subprocess(helper, argv, NULL, 0, NULL, NULL);
  } else {
#ifdef _WIN32
    const char *argv[] = {
        "powershell", "-NoProfile", "-ExecutionPolicy",
        "Bypass",     "-Command",   "$ErrorActionPreference = 'Stop'; irm https://ascii-chat.com/install.ps1 | iex",
        NULL};
    exit_code = platform_execute_subprocess("powershell", argv, NULL, 0, NULL, NULL);
#else
    const char *argv[] = {"bash", "-o", "pipefail", "-c", "curl -fsSL https://ascii-chat.com/install.sh | bash", NULL};
    exit_code = platform_execute_subprocess("bash", argv, NULL, 0, NULL, NULL);
#endif
  }
  if (exit_code != 0) {
    log_warn("ascii-chat update command exited with status %d", exit_code);
    g_update_install_failed = true;
    ui_controller_redraw();
    return false;
  }
  update_banner_print_instructions();
  shutdown_request();
  APP_CALLBACK_VOID(signal_exit);
  return true;
}

References APP_CALLBACK_VOID, INSTALL_METHOD_ARCH_AUR, INSTALL_METHOD_HOMEBREW, INSTALL_METHOD_SCOOP, log_warn, platform_execute_subprocess(), SAFE_GETENV, shutdown_request(), signal_exit(), ui_controller_redraw(), update_check_result_t::update_available, update_banner_print_instructions(), update_check_detect_install_method(), and update_check_get_aur_helper().

Referenced by update_banner_handle_key().

update_banner_is_checking()

bool update_banner_is_checking

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

True while the shared startup or explicit update request is in flight.

Definition at line 642 of file update_banner.c.

                                     {
  if (!lifecycle_is_initialized(&g_update_result_lifecycle))
    return false;
  mutex_lock(&g_update_result_mutex);
  bool checking = g_update_checking;
  mutex_unlock(&g_update_result_mutex);
  return checking;
}

Referenced by ui_session_splash_render(), and update_banner_handle_key().

update_banner_is_overlay_open()

bool update_banner_is_overlay_open

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

True only while the F12 overlay, rather than the startup prompt, owns the update screen.

Definition at line 651 of file update_banner.c.

                                         {
  return g_update_overlay;
}

Referenced by ui_input_read_key().

update_banner_print_instructions()

void update_banner_print_instructions

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Print upgrade instructions to stdout and prepare for clean exit.

Called after update_banner_show_prompt() returns true. Prints a clear, copy-pasteable upgrade command to stdout.

Definition at line 339 of file update_banner.c.

                                            {
  mutex_lock(&g_update_result_mutex);
  update_check_result_t result;
  memcpy(&result, &g_update_result, sizeof(result));
  mutex_unlock(&g_update_result_mutex);
 
  char domain_link[TUI_UPDATE_BANNER_DOMAIN_LINK_BUFFER_SIZE],
      instructions[TUI_UPDATE_BANNER_INSTRUCTIONS_EXTENDED_BUFFER_SIZE];
  (void)terminal_format_hyperlink(domain_link, sizeof(domain_link), "https://ascii-chat.com", "ascii-chat.com",
                                  !GET_OPTION(strip_ansi));
  snprintf(instructions, sizeof(instructions), "Full instructions on %s", domain_link);
  char output[TUI_UPDATE_BANNER_OUTPUT_BUFFER_SIZE];
  int len = snprintf(output, sizeof(output),
                     "\033[0m\033[2J\033[H\033[?25h"
                     "\nUpdated ascii-chat: %s -> %s\n\nRun ascii-chat again to start the new version.\n\n"
                     "Binaries for every OS with release notes on GitHub:\n%s\n\n"
                     "%s\n\n",
                     result.current_version, result.latest_version, result.release_url,
                     colored_string(LOG_COLOR_WHITE, instructions));
  if (len > 0 && len < (int)sizeof(output))
    ui_controller_finish(STDOUT_FILENO, output, (size_t)len);
}

References colored_string(), update_check_result_t::current_version, GET_OPTION, update_check_result_t::latest_version, LOG_COLOR_WHITE, update_check_result_t::release_url, TUI_UPDATE_BANNER_DOMAIN_LINK_BUFFER_SIZE, TUI_UPDATE_BANNER_INSTRUCTIONS_EXTENDED_BUFFER_SIZE, TUI_UPDATE_BANNER_OUTPUT_BUFFER_SIZE, and ui_controller_finish().

Referenced by update_banner_install_update().

update_banner_set_result()

void update_banner_set_result

(

const update_check_result_t *

result

)

#include <include/ascii-chat/tui/update_banner.h>

Store the update check result (thread-safe).

Called from the background update check thread after a successful check that found an available update. The result is stored under mutex protection.

Parameters

result

Update check result to store (copied internally)

Definition at line 89 of file update_banner.c.

                                                                   {
  if (!result) {
    return;
  }
 
  // Resolve the command before publishing a result to the presentation thread.
  if (result->update_available && update_check_detect_install_method() == INSTALL_METHOD_ARCH_AUR)
    (void)update_check_get_aur_helper();
 
  if (lifecycle_init_once(&g_update_result_lifecycle)) {
    mutex_init(&g_update_result_mutex, "update_banner_result");
    lifecycle_init_commit(&g_update_result_lifecycle);
  }
 
  ascii_otel_ui_usage("update", result->check_succeeded ? "check_completed" : "check_failed", 0);
  mutex_lock(&g_update_result_mutex);
  memcpy(&g_update_result, result, sizeof(g_update_result));
  g_update_result_set = true;
  mutex_unlock(&g_update_result_mutex);
}

References ascii_otel_ui_usage(), update_check_result_t::check_succeeded, INSTALL_METHOD_ARCH_AUR, update_check_result_t::update_available, update_check_detect_install_method(), and update_check_get_aur_helper().

Referenced by update_banner_show_prompt().

update_banner_show_prompt()

bool update_banner_show_prompt

(

struct session_display_ctx *

ctx

)

#include <include/ascii-chat/tui/update_banner.h>

Show the update prompt screen and wait for user input.

Renders a centered box with version info, upgrade command, and release URL. Blocks until the user presses a key:

• Y/y/Enter: returns true (user wants to exit and update)
• N/n/Esc: returns false (user wants to continue)

Parameters

ctx	Display context for terminal output

Returns

true if user chose to update, false if user chose to continue

Definition at line 287 of file update_banner.c.

                                                           {
  if (!ctx || !terminal_can_prompt_user(!GET_OPTION(snapshot_mode)))
    return false;
  update_check_result_t result;
  mutex_lock(&g_update_result_mutex);
  result = g_update_result;
  mutex_unlock(&g_update_result_mutex);
  if (update_check_is_dismissed(&result)) {
    return false;
  }
  atomic_store(&g_update_selected_action, 0);
  if (ui_controller_submit(UI_SCREEN_UPDATE, STDOUT_FILENO, (terminal_size_t){.cols = 32, .rows = 23},
                           render_update_prompt, &result, sizeof(result)) != ASCIICHAT_OK)
    return false;
  bool update = false;
  while (!shutdown_is_requested()) {
    /* The update prompt is synchronous, but a failed DNS check can put the
     * error popup above it. Route keys to that modal until it is dismissed. */
    if (ui_error_popup_visible()) {
      (void)ui_input_wait_key(UI_SCREEN_ERROR, 100);
      continue;
    }
    keyboard_key_t key = ui_input_wait_key(UI_SCREEN_UPDATE, 100);
    if (g_update_overlay)
      return false;
    if (update_select_key(key, 3))
      continue;
    if (key == 'o' || key == 'O' || ((key == '\r' || key == '\n') && atomic_load(&g_update_selected_action) == 1)) {
      update_banner_open_release();
      continue;
    }
    if (key == '\r' || key == '\n') {
      update = atomic_load(&g_update_selected_action) == 0;
      break;
    }
    if (key == 'y' || key == 'Y') {
      update = true;
      break;
    }
    if (key == 'n' || key == 'N' || key == KEY_ESCAPE)
      break;
  }
  if (!g_update_overlay) {
    ui_controller_remove(UI_SCREEN_UPDATE);
  }
  if (!update && !g_update_overlay) {
    update_check_dismiss_for_a_week(&result);
    update_banner_set_result(&result);
  }
  return update;
}

References ASCIICHAT_OK, GET_OPTION, KEY_ESCAPE, shutdown_is_requested(), ui_controller_remove(), ui_controller_submit(), ui_error_popup_visible(), ui_input_wait_key(), UI_SCREEN_ERROR, UI_SCREEN_UPDATE, update_banner_set_result(), update_check_dismiss_for_a_week(), and update_check_is_dismissed().

update_banner_start_check()

void update_banner_start_check

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Start the background update check thread.

Spawns a background thread that performs the update check (DNS + HTTPS) and stores the result. The splash screen notification is also set if an update is found. Call update_banner_wait_for_check() later to join.

Definition at line 603 of file update_banner.c.

                                     {
  update_banner_start_check_impl(false);
}

Referenced by main().

update_banner_toggle_overlay()

void update_banner_toggle_overlay

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Toggle the retained update overlay. This is safe from every mode's shared input path.

Definition at line 607 of file update_banner.c.

                                        {
  if (g_update_overlay) {
    ascii_otel_ui_usage("update", "dismissed", 0);
    g_update_overlay = false;
    ui_controller_remove(UI_SCREEN_UPDATE);
    return;
  }
  ascii_otel_ui_usage("update", "opened", 0);
  g_update_overlay = true;
  atomic_store(&g_update_visible_until_ns, time_get_ns() + 2 * NS_PER_SEC_INT);
  atomic_store(&g_update_selected_action, 0);
  bool finished = false;
  if (lifecycle_is_initialized(&g_update_result_lifecycle)) {
    mutex_lock(&g_update_result_mutex);
    finished = g_update_finished;
    mutex_unlock(&g_update_result_mutex);
  }
  if (g_update_thread_started && finished)
    update_banner_wait_for_check();
  if (!g_update_thread_started)
    update_banner_start_check_impl(true);
  update_banner_present_overlay();
}

References ascii_otel_ui_usage(), NS_PER_SEC_INT, ui_controller_remove(), UI_SCREEN_UPDATE, and update_banner_wait_for_check().

Referenced by ui_input_read_key(), and update_banner_handle_key().

update_banner_wait_for_check()

void update_banner_wait_for_check

(

void

)

#include <include/ascii-chat/tui/update_banner.h>

Wait for the background update check thread to finish.

Blocks up to 5 seconds for the background check to complete. Safe to call even if no check was started.

Definition at line 732 of file update_banner.c.

                                        {
  if (!g_update_thread_started) {
    return;
  }
  // Shutdown must remain responsive after cancellation.  The worker checks
  // g_update_cancel_requested and terminates its child process, so one second
  // is sufficient for normal teardown while avoiding a multi-second Ctrl-C
  // stall when a platform/network call is slow to unwind.
  int ret = thread_join_timeout(&g_update_thread, NULL, 1LL * NS_PER_SEC_INT);
  if (ret != 0) {
    // Timeout — thread is still alive. Do a blocking join to avoid orphaning it.
    // The thread has bounded runtime (DNS + HTTP both have timeouts) so this won't hang.
    log_warn("Update check thread did not finish within 1s, waiting for completion");
    thread_join(&g_update_thread, NULL);
  }
  g_update_thread_started = false;
}

References log_warn, and NS_PER_SEC_INT.

Referenced by update_banner_handle_key(), and update_banner_toggle_overlay().