client_like.h File Reference

Shared initialization and teardown for client-like modes (mirror, client, discovery) More...

Go to the source code of this file.

Data Structures
struct	session_client_like_config

Typedefs
typedef struct terminal_fd_reader_s	terminal_fd_reader_t
typedef enum session_client_like_kind	session_client_like_kind_t
typedef asciichat_error_t(*	session_client_like_run_fn) (session_capture_ctx_t *capture, session_display_ctx_t *display, void *user_data)
typedef struct session_client_like_config	session_client_like_config_t

Enumerations
enum	session_client_like_kind { SESSION_CLIENT_LIKE_KIND_MIRROR = 0 , SESSION_CLIENT_LIKE_KIND_CLIENT , SESSION_CLIENT_LIKE_KIND_DISCOVERY }

Functions
terminal_fd_reader_t *	session_client_like_get_stdin_reader (void)
asciichat_error_t	session_client_like_run (const session_client_like_config_t *config)

Variables
bool(*)(void *)	session_client_like_get_render_should_exit (void)

Detailed Description

Shared initialization and teardown for client-like modes (mirror, client, discovery)

Provides a unified interface for running client-like modes that share common initialization patterns: media source selection, FPS probing, audio initialization, display creation, splash screen management, keepawake handling, and cleanup.

Each mode registers mode-specific callbacks to handle initialization, the main render loop, and keyboard input. The shared layer handles all the boilerplate.

Modes Supported

• Mirror mode: Local webcam/media playback without networking
• Client mode: Network client with per-connection initialization
• Discovery mode: P2P mode with role negotiation

Shared Responsibilities

This layer automatically handles:

• Terminal output management (stdout piping detection)
• Keepawake system (platform sleep prevention)
• Splash screen lifecycle and animation
• Media source selection and FPS probing
• Audio initialization and lifecycle
• Display context creation and management
• Render loop execution
• Proper cleanup ordering (critical for PortAudio)

Mode-Specific Responsibilities

Mode files provide:

• Main loop callback (run_fn) that calls session_render_loop() or custom loop
• Optional network interrupt callback for socket shutdown
• Optional custom exit condition for additional shutdown criteria
• Keyboard handler for interactive controls
• Terminal behavior preferences (newline on exit)

Memory and Lifecycle

All allocations (capture, display, audio) are owned and cleaned up by session_client_like_run(). Mode callbacks receive initialized, ready-to-use contexts and should not attempt to free them.

Author

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

Date

February 2026

Definition in file client_like.h.

Typedef Documentation

session_client_like_config_t

typedef struct session_client_like_config session_client_like_config_t

Configuration for session_client_like_run()

All media, display, audio, FPS, and snapshot settings are read automatically from GET_OPTION() inside the function. Callers only provide the fields below that differ per mode.

session_client_like_kind_t

typedef enum session_client_like_kind session_client_like_kind_t

session_client_like_run_fn

typedef asciichat_error_t(* session_client_like_run_fn) (session_capture_ctx_t *capture, session_display_ctx_t *display, void *user_data)

Mode-specific main loop callback

Called after all shared initialization is complete (capture opened, audio started, display ready, splash done). The mode runs its main loop here and returns when finished. The shared teardown runs after this returns.

Typical pattern:

// For mirror/discovery participant:
return session_render_loop(capture, display, exit_check_fn, NULL, NULL,
                           keyboard_handler, user_data);
 
// For client mode (protocol-driven):
while (!should_exit()) {
  // protocol loop...
}
return ASCIICHAT_OK;

Parameters

capture	Initialized capture context. Never NULL.
display	Initialized display context. Never NULL.
user_data	User data passed through from config.run_user_data

Returns

ASCIICHAT_OK, or error code to abort (cleanup still runs)

Definition at line 98 of file client_like.h.

terminal_fd_reader_t

typedef struct terminal_fd_reader_s terminal_fd_reader_t

Definition at line 59 of file client_like.h.

Enumeration Type Documentation

session_client_like_kind

enum session_client_like_kind

Enumerator
SESSION_CLIENT_LIKE_KIND_MIRROR
SESSION_CLIENT_LIKE_KIND_CLIENT
SESSION_CLIENT_LIKE_KIND_DISCOVERY

Definition at line 63 of file client_like.h.

                                      {
  SESSION_CLIENT_LIKE_KIND_MIRROR = 0,
  SESSION_CLIENT_LIKE_KIND_CLIENT,
  SESSION_CLIENT_LIKE_KIND_DISCOVERY,
} session_client_like_kind_t;

Function Documentation

session_client_like_run()

asciichat_error_t session_client_like_run

(

const session_client_like_config_t *

config

)

Run a client-like mode with fully shared initialization and teardown

This function orchestrates the complete lifecycle of client-like modes:

Initialization (automatic from GET_OPTION())

Terminal:

• Forces stderr when stdout is piped (terminal_should_force_stderr)
• Disables terminal logging during rendering, re-enables on exit
• Handles snapshot mode log visibility

Keepawake:

• Validates –keepawake / –no-keepawake mutual exclusivity
• Calls platform_enable_keepawake() unless –no-keepawake set
• Disables keepawake on exit

Splash Screen:

• Creates temporary display context
• Calls splash_intro_start() to show splash animation
• Holds splash visible during media probing and audio init
• Calls splash_intro_done() when capture and display are ready

Media / Webcam (session_capture_ctx_t):

• Selects source type from options (priority order):
  1. –url → MEDIA_SOURCE_FILE (FFmpeg handles http/rtsp/rtmp)
  2. –file → MEDIA_SOURCE_FILE; "-" → MEDIA_SOURCE_STDIN
  3. –test-pattern → MEDIA_SOURCE_TEST
  4. (default) → MEDIA_SOURCE_WEBCAM
• FPS: uses GET_OPTION(fps) if > 0, otherwise probes with temporary media source
• Applies GET_OPTION(media_seek_timestamp) as initial seek
• Applies GET_OPTION(media_loop) for file looping
• Calls session_capture_create() to open webcam or media file
• Destroys capture on exit

Audio (audio_context_t):

• Skipped entirely for immediate snapshots (snapshot_mode && snapshot_delay == 0)
• Probes for audio via media_source_has_audio() on capture's source
• Allocates and initializes audio_context_t when audio available
• Links audio context to capture and media source
• Sets playback_only based on audio_should_enable_microphone()
• Disables jitter buffering for local file playback
• Calls audio_start_duplex() after splash_intro_done()
• Stops, destroys, and frees audio on exit

Display (session_display_ctx_t):

• Calls session_display_create() with snapshot and color settings
• Passes audio context if initialized
• Destroys display on exit

Mode-Specific Loop

Calls config->run_fn(capture, display, config->run_user_data) once all initialization is complete. This is where each mode calls session_render_loop() or runs its own protocol-thread-driven loop.

Cleanup (always runs, even on error)

Cleanup sequence (order is critical):

1. Re-enable terminal logging
2. audio_terminate_portaudio_final() - Free PortAudio device resources FIRST
3. audio_stop_duplex() + audio_destroy() + SAFE_FREE
4. session_display_destroy()
5. session_capture_destroy()
6. media_source_destroy() - Free capture buffers and source state
7. session_log_buffer_destroy()
8. platform_disable_keepawake()
9. Print '
   ' to STDOUT_FILENO if print_newline_on_tty_exit && TTY

Parameters

config

Mode configuration. Must not be NULL. run_fn must not be NULL.

Returns

ASCIICHAT_OK on success, or the first error code from initialization or from run_fn. Cleanup always runs regardless of return value.

Definition at line 135 of file client_like.c.

                                                                                      {
  log_info("session_client_like_run: ENTRY");
  if (!config || !config->run_fn) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "config or run_fn is NULL");
  }
  log_info("session_client_like_run: config validated");
 
  // Store config globally for adapter callbacks
  g_current_config = config;
 
  // Store the render should_exit adapter globally so mode-specific run_fn can access it
  g_render_should_exit = display_should_exit_adapter;
 
  asciichat_error_t result = ASCIICHAT_OK;
 
  // Keep track of what's been initialized for cleanup
  session_capture_ctx_t *capture = NULL;
  session_display_ctx_t *display = NULL;
  audio_context_t *audio_ctx = NULL;
  media_source_t *probe_source = NULL;
  bool audio_available = false;
 
  // ============================================================================
  // SETUP: Terminal and Logging
  // ============================================================================
 
  log_debug("session_client_like_run(): Setting up terminal and logging");
 
  // Force stderr when stdout is piped (prevents ASCII corruption in output stream)
  bool should_force_stderr = terminal_should_force_stderr();
  log_debug("terminal_should_force_stderr()=%d", should_force_stderr);
 
  if (should_force_stderr) {
    // Redirect logs to stderr to prevent corruption of stdout (for pipes)
    // But keep terminal output enabled so we can see initialization errors
    log_set_force_stderr(true);
  }
 
  // Note: Force all logging to stderr if encoding to pipe to prevent corrupting binary video output
  // (implemented via should_force_stderr check above)
  const char *render_file_early = GET_OPTION(render_file);
  log_info("[CLIENT_LIKE_RUN] render_file_early=%s (ptr=%p)", render_file_early ? render_file_early : "(null)",
           (void *)render_file_early);
  if (render_file_early && render_file_early[0] != '\0' &&
      (strcmp(render_file_early, "-") == 0 || strcmp(render_file_early, "pipe:") == 0)) {
    log_info("--render-file=- will output binary video to stdout, logging sent to stderr");
  }
 
  // ============================================================================
  // SETUP: Keepawake System
  // ============================================================================
 
  log_debug("session_client_like_run(): Validating keepawake options");
 
  // Validate mutual exclusivity
  bool enable_ka = GET_OPTION(enable_keepawake);
  bool disable_ka = GET_OPTION(disable_keepawake);
  log_debug("enable_keepawake=%d, disable_keepawake=%d", enable_ka, disable_ka);
 
  if (enable_ka && disable_ka) {
    result = SET_ERRNO(ERROR_INVALID_PARAM, "--keepawake and --no-keepawake are mutually exclusive");
    goto cleanup;
  }
 
  log_debug("session_client_like_run(): Enabling keepawake if needed");
 
  // Enable keepawake unless explicitly disabled
  if (!disable_ka) {
    (void)platform_enable_keepawake();
  }
 
  log_debug("session_client_like_run(): Keepawake setup complete");
 
  result = validate_mirror_webcam_selection(config);
  if (result != ASCIICHAT_OK) {
    goto cleanup;
  }
 
  // ============================================================================
  // SETUP: Display Context (before splash for unified TTY initialization)
  // ============================================================================
 
  // Create display context early to share TTY initialization between splash and rendering
  // This prevents double TTY init which was corrupting the terminal state
  session_display_config_t display_config = {0};
  display_config.snapshot_mode = GET_OPTION(snapshot_mode);
  display_config.palette_type = GET_OPTION(palette_type);
  display_config.custom_palette = GET_OPTION(palette_custom_set) ? GET_OPTION(palette_custom) : NULL;
  display_config.color_mode = TERM_COLOR_AUTO;
  display_config.should_exit_callback = display_should_exit_adapter;
  display_config.callback_data = NULL;
  display_config.defer_render_file = true;
 
  log_debug("[SETUP_DISPLAY_EARLY] Creating display context (before splash)");
  display = session_display_create(&display_config);
  if (!display) {
    log_debug("[SETUP_DISPLAY_EARLY] session_display_create() returned NULL");
    log_fatal("Failed to initialize display context");
    result = ERROR_DISPLAY;
    goto cleanup;
  }
  log_debug("[SETUP_DISPLAY_EARLY] Display context created, will use for splash");
 
  // Register global display context for signal handlers (Ctrl+C help screen closure)
  // This makes the context available to signal handlers for the entire app lifetime
  session_display_set_global_context(display);
 
  // ============================================================================
  // SETUP: Splash Screen (using unified display context)
  // ============================================================================
 
  log_debug("session_client_like_run(): Starting splash with display context");
 
  // Use the display context we just created for splash animation
  splash_intro_start(display);
  log_debug("session_client_like_run(): splash_intro_start() returned");
  if (splash_is_running()) {
    log_set_terminal_output(false);
  }
 
  // Detect if we're using media vs webcam (needed for splash timing)
  const char *media_url = GET_OPTION(media_url);
  const char *media_file = GET_OPTION(media_file);
  bool has_media = (media_url && strlen(media_url) > 0) || (media_file && strlen(media_file) > 0);
 
  // Show splash briefly for webcam, but skip sleep for media (which takes time anyway)
  if (!has_media && !GET_OPTION(snapshot_mode)) {
    APP_CALLBACK_VOID(platform_pump_events);
    APP_CALLBACK_VOID_UINT(platform_sleep_ms, 250);
  }
  log_debug("session_client_like_run(): After splash sleep");
 
  // Restore stderr now that splash animation and post-splash logging are done
  // This allows logs to appear on screen again after this point
  splash_restore_stderr();
 
  // Wait for background update check to finish and show prompt if update available
  update_banner_wait_for_check();
  if (update_banner_has_update() && !GET_OPTION(snapshot_mode)) {
    bool wants_update = update_banner_show_prompt(display);
    if (wants_update) {
      update_banner_print_instructions();
      return ASCIICHAT_OK;
    }
    terminal_clear_screen();
  }
 
  // ============================================================================
  // SETUP: Terminal Logging in Snapshot Mode
  // ============================================================================
 
  log_debug("session_client_like_run(): About to disable terminal logging (snapshot=%d, discovery=%d)",
            GET_OPTION(snapshot_mode), config->discovery != NULL);
  // For discovery mode, skip disabling logging initially - we'll handle it after role is determined
  // Discovery participants should show logs, only hosts should have logs disabled for rendering
  bool should_disable_logging = !GET_OPTION(snapshot_mode) && (config->discovery == NULL);
  if (should_disable_logging) {
    log_debug("session_client_like_run(): Calling log_set_terminal_output(false)...");
    log_set_terminal_output(false);
    log_debug("session_client_like_run(): RETURNED from log_set_terminal_output(false)");
  } else {
    log_debug("session_client_like_run(): Skipping log disable (snapshot=%d or discovery=%d)",
              GET_OPTION(snapshot_mode), config->discovery != NULL);
  }
  log_debug("session_client_like_run(): Terminal logging setup complete, starting media source setup");
 
  // ============================================================================
  // SETUP: Media Source Selection and FPS Probing
  // ============================================================================
 
  log_debug("session_client_like_run(): Initializing capture config");
  session_capture_config_t capture_config = {0};
  capture_config.resize_for_network = config->kind == SESSION_CLIENT_LIKE_KIND_DISCOVERY;
  capture_config.should_exit_callback = capture_should_exit_adapter;
  capture_config.callback_data = NULL;
 
  // Determine FPS explicitly set by user
  log_debug("session_client_like_run(): Getting FPS option");
  int user_fps = GET_OPTION(fps);
  bool fps_explicitly_set = GET_OPTION(fps_explicitly_set);
  log_debug("session_client_like_run(): FPS=%d (explicitly_set=%d)", user_fps, fps_explicitly_set);
 
  // Select media source based on options (priority order)
  log_debug("session_client_like_run(): Getting media_url option");
  const char *media_url_val = GET_OPTION(media_url);
  log_debug("session_client_like_run(): Getting media_file option");
  const char *media_file_val = GET_OPTION(media_file);
  log_debug("session_client_like_run(): media_url=%s, media_file=%s", media_url_val ? media_url_val : "(null)",
            media_file_val ? media_file_val : "(null)");
 
  if (media_url_val && strlen(media_url_val) > 0) {
    // Network URL takes priority
    log_info("Using network URL: %s (webcam disabled)", media_url_val);
    capture_config.type = MEDIA_SOURCE_FILE;
    capture_config.path = media_url_val;
    capture_config.loop = false; // Network URLs cannot be looped
 
    if (fps_explicitly_set) {
      capture_config.target_fps = (uint32_t)user_fps;
      log_info("Using user-specified FPS: %u", capture_config.target_fps);
    } else {
      // Always probe FPS for HTTP URLs, even in snapshot mode
      // (snapshot mode needs correct FPS to capture right number of frames during snapshot_delay window)
      log_debug("Probing FPS for HTTP URL");
      probe_source = media_source_create(MEDIA_SOURCE_FILE, media_url_val);
      if (probe_source) {
        double url_fps = media_source_get_video_fps(probe_source);
        log_info("Detected HTTP stream video FPS: %.1f", url_fps);
        if (url_fps > 0.0) {
          capture_config.target_fps = (uint32_t)(url_fps + 0.5);
        } else {
          log_warn("FPS detection failed for HTTP stream, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      } else {
        log_warn("Failed to create probe source for HTTP stream, using default 60 FPS");
        capture_config.target_fps = 60;
      }
    }
  } else if (media_file_val && strlen(media_file_val) > 0) {
    // Local file or stdin
    log_info("DEBUG: media_file_val='%s', strcmp result=%d", media_file_val, strcmp(media_file_val, "-"));
    if (strcmp(media_file_val, "-") == 0) {
      log_info("Using stdin for media streaming (webcam disabled)");
      capture_config.type = MEDIA_SOURCE_STDIN;
      capture_config.path = NULL;
      capture_config.loop = false;
      if (fps_explicitly_set) {
        capture_config.target_fps = (uint32_t)user_fps;
      } else {
        log_debug("Probing FPS from buffered stdin media");
        probe_source = media_source_create(MEDIA_SOURCE_STDIN, NULL);
        if (probe_source) {
          double stdin_fps = media_source_get_video_fps(probe_source);
          log_info("Detected stdin video FPS: %.1f", stdin_fps);
          capture_config.target_fps = stdin_fps > 0.0 ? (uint32_t)(stdin_fps + 0.5) : 60;
        } else {
          log_warn("Failed to probe stdin FPS, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      }
    } else {
      log_info("Using media file: %s (webcam disabled)", media_file_val);
      capture_config.type = MEDIA_SOURCE_FILE;
      capture_config.path = media_file_val;
      capture_config.loop = GET_OPTION(media_loop);
 
      if (fps_explicitly_set) {
        capture_config.target_fps = (uint32_t)user_fps;
        log_info("Using user-specified FPS: %u", capture_config.target_fps);
      } else {
        // Always probe FPS for local files, even in snapshot mode
        // (snapshot mode needs correct FPS to capture right number of frames during snapshot_delay window)
        log_debug("Probing FPS for local file");
        probe_source = media_source_create(MEDIA_SOURCE_FILE, media_file_val);
        if (probe_source) {
          double file_fps = media_source_get_video_fps(probe_source);
          log_info("Detected file video FPS: %.1f", file_fps);
          if (file_fps > 0.0) {
            capture_config.target_fps = (uint32_t)(file_fps + 0.5);
          } else {
            log_warn("FPS detection failed, using default 60 FPS");
            capture_config.target_fps = 60;
          }
        } else {
          log_warn("Failed to create probe source for FPS detection, using default 60 FPS");
          capture_config.target_fps = 60;
        }
      }
    }
  } else if (GET_OPTION(test_pattern)) {
    // Test pattern
    log_debug("session_client_like_run(): Using test pattern");
    log_info("Using test pattern");
    capture_config.type = MEDIA_SOURCE_TEST;
    capture_config.path = NULL;
    capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
    capture_config.loop = false;
  } else {
    // Default: Try webcam if stdout is a TTY, otherwise use test pattern
    // (webcam + piped output often fails, test pattern is reliable fallback)
    bool stdout_is_tty = terminal_is_stdout_tty();
    if (stdout_is_tty) {
      // Normal terminal mode: use webcam
      log_debug("session_client_like_run(): Stdout is TTY, using local webcam");
      log_info("Using local webcam");
      capture_config.type = MEDIA_SOURCE_WEBCAM;
      static char webcam_index_str[32];
      safe_snprintf(webcam_index_str, sizeof(webcam_index_str), "%u", GET_OPTION(webcam_index));
      capture_config.path = webcam_index_str;
      log_info("Using webcam device index %u", GET_OPTION(webcam_index));
      capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
      capture_config.loop = false;
    } else {
      // Piped output mode: use test pattern (webcam + pipes often fails)
      log_debug("session_client_like_run(): Stdout is piped, defaulting to test pattern for reliability");
      log_info("Stdout is piped - using test pattern instead of webcam");
      capture_config.type = MEDIA_SOURCE_TEST;
      capture_config.path = NULL;
      capture_config.target_fps = fps_explicitly_set ? (uint32_t)user_fps : 60;
      capture_config.loop = false;
    }
  }
 
  // Apply initial seek if specified
  log_debug("session_client_like_run(): Getting media_seek_timestamp option");
  capture_config.initial_seek_timestamp = GET_OPTION(media_seek_timestamp);
  log_debug("session_client_like_run(): Media seek timestamp set");
 
  // Clean up probe source (don't reuse for actual capture)
  if (probe_source) {
    log_debug("session_client_like_run(): Destroying probe source");
    media_source_destroy(probe_source);
    probe_source = NULL;
    log_debug("session_client_like_run(): Probe source destroyed");
  } else {
    log_debug("session_client_like_run(): No probe source to destroy");
  }
 
  // Pass probed FPS to display context for correct render-file duration
  if (capture_config.target_fps > 0) {
    session_display_set_render_fps(display, capture_config.target_fps);
    log_debug("session_client_like_run(): Set display render FPS to %u for correct video encoding duration",
              capture_config.target_fps);
  }
 
  asciichat_error_t render_init_result = session_display_init_render_file(display, capture_config.target_fps);
  if (render_init_result != ASCIICHAT_OK) {
    result = render_init_result;
    goto cleanup;
  }
 
  // ============================================================================
  // SETUP: Network Transports (TCP/WebSocket)
  // ============================================================================
 
  log_debug("session_client_like_run(): Setting up network transports");
 
  bool networked_mode = session_client_like_is_networked(config->kind);
 
  switch (config->kind) {
  case SESSION_CLIENT_LIKE_KIND_MIRROR:
    log_debug("Mirror mode detected - will use local capture with media source");
    break;
  case SESSION_CLIENT_LIKE_KIND_CLIENT:
    log_debug("Client/Network mode detected - will use network capture without local media source");
    break;
  case SESSION_CLIENT_LIKE_KIND_DISCOVERY:
    log_debug("Discovery mode detected - discovery session will manage networking");
    break;
  }
 
  // ============================================================================
  // SETUP: Capture Context
  // ============================================================================
 
  // Check for stdin render mode: read ASCII frames from stdin, render to video
  // Only enable stdin render mode if:
  // 1. render-file is "-" (output to stdout)
  // 2. stdin is not a TTY
  // 3. --height is explicitly specified (user must opt-in to stdin render mode)
  // 4. NO media source is being used (not reading from file/URL/test-pattern)
  // This prevents accidental activation when piping to other processes or using mirror mode
  const char *render_file_opt = GET_OPTION(render_file);
  int frame_height = GET_OPTION(height);
  bool height_explicitly_set = (frame_height != OPT_HEIGHT_DEFAULT);
  bool has_media_source = (media_url_val && strlen(media_url_val) > 0) ||
                          (media_file_val && strlen(media_file_val) > 0) || GET_OPTION(test_pattern);
 
  // Enable audio capture if render-file is active and media source exists
  if (render_file_opt && strlen(render_file_opt) > 0 && has_media_source) {
    capture_config.enable_audio = true;
    log_debug("Audio capture enabled for render-file encoding");
  }
 
  bool stdin_render_mode =
      (render_file_opt && strcmp(render_file_opt, "-") == 0 && !terminal_is_stdin_tty() && height_explicitly_set &&
       !has_media_source && config->kind != SESSION_CLIENT_LIKE_KIND_MIRROR);
 
  if (stdin_render_mode) {
    // Stdin render mode: read ASCII frames from stdin, output video to stdout
    log_info("Stdin render mode enabled: reading ASCII frames from stdin, output to stdout");
 
    // Get frame dimensions (--height must be explicitly set to reach here)
    int frame_width = GET_OPTION(width);
 
    // Validate stdin render mode constraints (--height is already validated above since height_explicitly_set is true)
    bool width_was_explicitly_set = (frame_width != OPT_WIDTH_DEFAULT);
 
    if (width_was_explicitly_set) {
      result = SET_ERRNO(ERROR_USAGE, "Stdin render mode does not accept --width (auto-detected from frames).\n"
                                      "Only specify: --height <rows>");
      goto cleanup;
    }
 
    asciichat_error_t stdin_err = terminal_fd_reader_create(STDIN_FILENO, frame_height, &g_stdin_reader);
    if (stdin_err != ASCIICHAT_OK) {
      log_fatal("Failed to initialize stdin frame reader: %s", asciichat_error_string(stdin_err));
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
 
    // For stdin render mode, create a minimal capture context for compatibility
    int fps = GET_OPTION(fps);
    capture = session_network_capture_create((uint32_t)(fps > 0 ? fps : 60));
    if (!capture) {
      log_fatal("Failed to initialize capture context for stdin rendering");
      terminal_fd_reader_destroy(g_stdin_reader);
      g_stdin_reader = NULL;
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
 
    log_info("stdin render mode: reading %d-line frames from stdin, auto-detecting width", frame_height);
  }
 
  // Choose capture type based on mode determined earlier:
  // - Mirror mode: needs to capture local media (webcam, file, test pattern)
  // - Network modes (client/discovery): receive frames from network, no local capture
  // Discovery peers may use a local media source (for example the synthetic
  // test pattern used by headless WebRTC tests) as their outgoing stream.
  // Keep the network-only capture for ordinary client mode, but do not discard
  // an explicitly requested source before the discovery transport is active.
  bool discovery_has_local_source = config->kind == SESSION_CLIENT_LIKE_KIND_DISCOVERY;
  if (!stdin_render_mode && networked_mode && !discovery_has_local_source) {
    // Network mode: create minimal capture context without media source
    log_debug("Network mode detected - using network capture (no local media source)");
    int fps = GET_OPTION(fps);
    uint64_t net_cap_start = time_get_ns();
    capture = session_network_capture_create((uint32_t)(fps > 0 ? fps : 60));
    double net_cap_ms = time_ns_to_ms(time_elapsed_ns(net_cap_start, time_get_ns()));
    log_info("★ INIT_CHECKPOINT: Network capture created in %.1f ms", net_cap_ms);
    if (!capture) {
      log_fatal("Failed to initialize network capture context");
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
    if (fps > 0) {
      log_debug("Network capture FPS set to %d from options", fps);
    }
  }
 
  // ============================================================================
  // SETUP: Audio Context
  // ============================================================================
 
  // Skip audio for immediate snapshots
  bool should_init_audio = GET_OPTION(audio_enabled);
  if (GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0) {
    should_init_audio = false;
    log_debug("Skipping audio initialization for immediate snapshot");
  }
 
  // Pass stdin_reader to display if in stdin render mode
  if (stdin_render_mode && g_stdin_reader) {
    session_display_set_stdin_reader(display, g_stdin_reader);
    log_debug("stdin_reader passed to display context");
  }
 
  // ============================================================================
  // SETUP: End Splash Screen
  // ============================================================================
  log_debug("[SETUP_SPLASH] About to end splash screen");
 
  // The splash screen will display during initialization and exit when done.
  // The initialization process (media probing, display setup, etc.) naturally
  // takes time, keeping the splash visible. The splash is kept alive during
  // connection attempts (TCP and WebSocket) to prevent a blank screen during
  // network operations. splash_intro_done() is called only after a successful
  // connection is established.
 
  log_debug("[SETUP_SPLASH] Splash will remain visible during connection attempts");
 
  // Exit early if shutdown was requested (e.g., user pressed Ctrl-C)
  if (APP_CALLBACK_BOOL(should_exit)) {
    log_debug("[SETUP] Shutdown requested, exiting early");
    log_debug("[SETUP_SPLASH] Ending splash due to early shutdown request");
    splash_intro_done();
    splash_wait_for_animation();
    result = ASCIICHAT_OK;
    goto cleanup;
  }
 
  // Wait for splash animation to finish before proceeding to render loop
  // (splash_anim thread uses the display, must not be disrupted before cleanup)
  // But skip for immediate snapshots (snapshot-delay=0) which need to output first frame immediately
  // For discovery mode, keep the splash running - it stays visible while waiting for peers
  if (config->discovery == NULL) {
    splash_intro_done();
    if (!(GET_OPTION(snapshot_mode) && GET_OPTION(snapshot_delay) == 0.0)) {
      splash_wait_for_animation();
    }
  } else {
    log_debug("[SETUP_SPLASH] Discovery mode: keeping splash visible while waiting for peers");
  }
 
  // ============================================================================
  // SETUP: Create Mirror Capture (after splash screen finishes)
  // ============================================================================
 
  log_info("[MIRROR_CHECK] stdin_render_mode=%d, capture=%p", stdin_render_mode, (void *)capture);
  if (!stdin_render_mode && !capture) {
    // Mirror mode: create capture context with local media source (NOW, after splash finishes)
    log_info("Mirror mode detected - creating mirror capture after splash screen");
    uint64_t mirror_cap_start = time_get_ns();
    capture = session_mirror_capture_create(&capture_config);
    double mirror_cap_ms = time_ns_to_ms(time_elapsed_ns(mirror_cap_start, time_get_ns()));
    log_info("★ INIT_CHECKPOINT: Mirror capture created in %.1f ms (after splash)", mirror_cap_ms);
    if (!capture) {
      log_fatal("Failed to initialize mirror capture source");
      result = ERROR_MEDIA_INIT;
      goto cleanup;
    }
  }
 
  if (should_init_audio && config->kind == SESSION_CLIENT_LIKE_KIND_MIRROR) {
    media_source_t *source = session_capture_get_media_source(capture);
    bool file_audio = media_source_has_audio(source);
    bool record_mic = render_file_opt && render_file_opt[0] && !file_audio;
    if (file_audio || record_mic) {
      audio_ctx = SAFE_CALLOC(1, sizeof(*audio_ctx), audio_context_t *);
      if (audio_init(audio_ctx) == ASCIICHAT_OK) {
        audio_available = true;
        if (file_audio && GET_OPTION(audio_capture_source) != AUDIO_CAPTURE_SOURCE_MIC)
          audio_ctx->capture_media_source = source;
        audio_ctx->monitor_local_media = true;
        audio_ctx->playback_only = !audio_should_enable_microphone(GET_OPTION(audio_capture_source), file_audio);
        session_capture_set_audio_context(capture, audio_ctx);
        media_source_set_audio_context(source, audio_ctx);
      } else {
        SAFE_FREE(audio_ctx);
      }
    }
  }
 
  // ============================================================================
  // SETUP: Start Audio Playback
  // ============================================================================
 
  log_debug("[SETUP_AUDIO] About to check audio context for duplex");
  if (audio_ctx && audio_available) {
    log_debug("[SETUP_AUDIO] Starting audio duplex");
    if (audio_start_duplex(audio_ctx) == ASCIICHAT_OK) {
      log_info("Audio playback started");
    } else {
      log_warn("Failed to start audio duplex");
      session_capture_set_audio_context(capture, NULL);
      media_source_set_audio_context(session_capture_get_media_source(capture), NULL);
      audio_destroy(audio_ctx);
      SAFE_FREE(audio_ctx);
      audio_ctx = NULL;
      audio_available = false;
    }
  }
 
  log_info("[MARKER] Audio setup complete at line 614");
  log_info("[SETUP_COMPLETE] All setup complete, about to start connection loop");
 
  // ============================================================================
  // RUN: Mode-Specific Main Loop with Reconnection
  // ============================================================================
 
  // Connection/attempt loop - wraps run_fn with reconnection logic
  int attempt = 0;
  int max_attempts = config->max_reconnect_attempts;
 
  log_info("[CLIENT_LIKE_LOOP] Starting connection loop, max_attempts=%d", max_attempts);
 
  while (true) {
    attempt++;
 
    result = config->run_fn(capture, display, config->run_user_data);
 
    // Exit immediately if run_fn succeeded
    if (result == ASCIICHAT_OK) {
      // Connection succeeded - splash screen cleanup now happens when first frame renders
      // This ensures the splash stays visible during TCP/WebSocket/datachannel connection attempts
 
      break;
    }
 
    // Check if we should attempt reconnection
    bool should_retry = false;
 
    if (max_attempts != 0) { // max_attempts == 0 means no retries
      // Check custom reconnect logic if provided
      if (config->should_reconnect_callback) {
        should_retry = config->should_reconnect_callback(result, attempt, config->reconnect_user_data);
      } else {
        should_retry = true; // Default: always retry
      }
 
      // Check retry limits if still planning to retry
      if (should_retry && max_attempts > 0 && attempt >= max_attempts) {
        log_debug("Reached maximum reconnection attempts (%d), giving up", max_attempts);
        should_retry = false;
      }
    }
 
    // If not retrying or shutdown requested, exit loop
    if (!should_retry || APP_CALLBACK_BOOL(should_exit)) {
      break;
    }
 
    // Reconnection will happen - show splash screen during reconnection attempt
    // Reset first_frame flag so splash cleanup runs on next successful connection
    session_display_reset_first_frame(display);
 
    // splash_intro_start() handles all the logic:
    // - If splash should display: shows splash and disables console logging
    // - If splash shouldn't display: restores stderr and returns without changing logging state
    splash_intro_start(display);
 
    // Log reconnection message
    if (max_attempts == -1) {
      log_info("Connection failed, retrying...");
    } else if (max_attempts > 0) {
      log_info("Connection failed, retrying (attempt %d/%d)...", attempt + 1, max_attempts);
    }
 
    // Apply reconnection delay if configured
    // Check APP_CALLBACK_BOOL(should_exit) frequently during sleep so SIGTERM can interrupt reconnection attempts
    if (config->reconnect_delay_ms > 0) {
      unsigned int remaining_ms = config->reconnect_delay_ms;
      const unsigned int check_interval_ms = 100; // Check exit flag every 100ms
 
      while (remaining_ms > 0 && !APP_CALLBACK_BOOL(should_exit)) {
        unsigned int sleep_ms = (remaining_ms < check_interval_ms) ? remaining_ms : check_interval_ms;
        APP_CALLBACK_VOID(platform_pump_events);
        APP_CALLBACK_VOID_UINT(platform_sleep_ms, sleep_ms);
        remaining_ms -= sleep_ms;
      }
    }
 
    // Continue loop to retry
  }
 
  // ============================================================================
  // CLEANUP (always runs, even on error)
  // ============================================================================
 
cleanup:
  // Re-enable terminal output for shutdown logs
  log_set_terminal_output(true);
 
  g_current_config = NULL;
  g_render_should_exit = NULL;
 
#ifndef NDEBUG
  // Join the registry inspector before freeing the session's synchronization objects.
  debug_sync_cleanup_thread();
#endif
 
  // Stop audio thread before destroying audio context to prevent use-after-free
  // The audio worker thread may still be logging when we destroy the buffer
  APP_CALLBACK_VOID(audio_stop_thread);
 
  // Stop streams before releasing the local media source.
  if (audio_ctx) {
    audio_stop_duplex(audio_ctx);
    audio_destroy(audio_ctx);
    SAFE_FREE(audio_ctx);
    audio_ctx = NULL;
  }
 
  // Destroy display (check global context to see if discovery mode already destroyed it)
  // Discovery participant mode may destroy the display early and clear the global context
  session_display_ctx_t *current_global = session_display_get_global_context();
  if (display && display == current_global) {
    // Display is still valid (not destroyed by discovery mode)
    session_display_destroy(display);
    display = NULL;
  } else if (display && display != current_global) {
    // Display was already destroyed (by discovery participant mode)
    // Just NULL it out, don't call destroy again
    log_debug("[CLEANUP] Display was already destroyed by discovery mode, skipping destroy");
    display = NULL;
  }
 
  // Destroy capture
  if (capture) {
    session_capture_destroy(capture);
    capture = NULL;
  }
 
  // Destroy stdin reader if active (stdin render mode)
  if (g_stdin_reader) {
    terminal_fd_reader_destroy(g_stdin_reader);
    g_stdin_reader = NULL;
  }
 
  // Clean up probe source if still allocated (shouldn't happen, but be safe)
  if (probe_source) {
    media_source_destroy(probe_source);
    probe_source = NULL;
  }
 
  // Stop splash animation and enforce minimum display time (even on error path)
  // But skip completely if shutting down - don't interact with splash at all during shutdown
  // The animation thread will exit on its own when it detects shutdown_is_requested()
  // For discovery mode, keep the splash running - it stays visible while waiting for peers
  if (config->discovery != NULL) {
    log_debug("[CLEANUP] Discovery mode: keeping splash alive for peer waiting UI");
  } else if (!APP_CALLBACK_BOOL(should_exit)) {
    log_debug("[CLEANUP] About to call splash_intro_done()");
    splash_intro_done();
    log_debug("[CLEANUP] splash_intro_done() returned");
 
    // Wait for animation thread to exit before cleanup
    log_debug("[CLEANUP] About to call splash_wait_for_animation()");
    splash_wait_for_animation();
    log_debug("[CLEANUP] splash_wait_for_animation() returned");
  } else {
    log_debug("[CLEANUP] Skipping all splash operations (shutdown in progress)");
    // During shutdown, don't interact with splash - let animation thread exit naturally
    // and don't wait for it (prevents blocking on signals)
  }
 
  // Disable keepawake (re-allow OS to sleep)
  log_debug("[CLEANUP] Disabling keepawake");
  platform_disable_keepawake();
  log_debug("[CLEANUP] keepawake disabled");
 
  // Write newline to separate final frame from prompt (if configured)
  log_debug("About to check print_newline_on_tty_exit");
  if (config->print_newline_on_tty_exit && terminal_is_stdout_tty()) {
    log_debug("Writing newline");
    const char newline = '\n';
    (void)platform_write_all(STDOUT_FILENO, &newline, 1);
  }
 
  log_set_terminal_output(false);
 
  return result;
}

References APP_CALLBACK_BOOL, APP_CALLBACK_VOID, APP_CALLBACK_VOID_UINT, ASCIICHAT_OK, AUDIO_CAPTURE_SOURCE_MIC, audio_destroy(), audio_init(), audio_should_enable_microphone(), audio_start_duplex(), audio_stop_duplex(), audio_stop_thread(), session_capture_config_t::callback_data, session_display_config_t::callback_data, audio_context_t::capture_media_source, session_display_config_t::color_mode, session_display_config_t::custom_palette, debug_sync_cleanup_thread(), session_display_config_t::defer_render_file, session_client_like_config::discovery, session_capture_config_t::enable_audio, ERROR_DISPLAY, ERROR_INVALID_PARAM, ERROR_MEDIA_INIT, ERROR_USAGE, GET_OPTION, session_capture_config_t::initial_seek_timestamp, session_client_like_config::kind, log_debug, log_fatal, log_info, log_set_force_stderr(), log_set_terminal_output(), log_warn, session_capture_config_t::loop, session_client_like_config::max_reconnect_attempts, media_source_create(), media_source_destroy(), MEDIA_SOURCE_FILE, media_source_get_video_fps(), media_source_has_audio(), media_source_set_audio_context(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, audio_context_t::monitor_local_media, OPT_HEIGHT_DEFAULT, OPT_WIDTH_DEFAULT, session_display_config_t::palette_type, session_capture_config_t::path, platform_disable_keepawake(), platform_enable_keepawake(), platform_sleep_ms(), platform_write_all(), audio_context_t::playback_only, session_client_like_config::print_newline_on_tty_exit, session_client_like_config::reconnect_delay_ms, session_client_like_config::reconnect_user_data, session_capture_config_t::resize_for_network, session_client_like_config::run_fn, session_client_like_config::run_user_data, SAFE_CALLOC, SAFE_FREE, safe_snprintf(), session_capture_destroy(), session_capture_get_media_source(), session_capture_set_audio_context(), SESSION_CLIENT_LIKE_KIND_CLIENT, SESSION_CLIENT_LIKE_KIND_DISCOVERY, SESSION_CLIENT_LIKE_KIND_MIRROR, session_display_create(), session_display_destroy(), session_display_get_global_context(), session_display_init_render_file(), session_display_reset_first_frame(), session_display_set_global_context(), session_display_set_render_fps(), session_display_set_stdin_reader(), session_mirror_capture_create(), session_network_capture_create(), SET_ERRNO, should_exit(), session_capture_config_t::should_exit_callback, session_display_config_t::should_exit_callback, session_client_like_config::should_reconnect_callback, session_display_config_t::snapshot_mode, splash_intro_done(), splash_intro_start(), splash_is_running(), splash_restore_stderr(), splash_wait_for_animation(), session_capture_config_t::target_fps, TERM_COLOR_AUTO, terminal_clear_screen(), terminal_fd_reader_create(), terminal_fd_reader_destroy(), terminal_is_stdin_tty(), terminal_is_stdout_tty(), terminal_should_force_stderr(), time_elapsed_ns(), time_get_ns(), session_capture_config_t::type, update_banner_has_update(), update_banner_print_instructions(), update_banner_show_prompt(), and update_banner_wait_for_check().

Referenced by client_main(), discovery_main(), and mirror_main().

Variable Documentation

session_client_like_get_render_should_exit

bool(*)(void *) session_client_like_get_render_should_exit(void)

(

void

)

Get the render loop should_exit callback set by session_client_like_run().

This is used by mode-specific run_fn callbacks to obtain the proper should_exit callback for passing to session_render_loop(). The callback checks both the global should_exit() flag and any mode-specific custom_should_exit condition.

Returns

Function pointer to the render should_exit callback, or NULL if session_client_like_run() has not been called yet.

Definition at line 245 of file client_like.h.