src/server/render.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define SERVER_RENDER_THREAD_DISPLAY_NAME_BUFFER_SIZE 64
#define SERVER_RENDER_THREAD_NAME_BUFFER_SIZE 64
 
#include <ascii-chat/audio/limits.h>
#include <ascii-chat/otel.h>
#include <ascii-chat/stats/runtime.h>
/* Per-client video conversion and audio mixing. Render workers submit media
 * to the shared ACIP scheduler and are joined before connection destruction. */
 
#include <stdio.h>
#include <string.h>
#include <time.h>
#include <errno.h>
#include <math.h>
 
#include "render.h"
#include "connections.h"
#include "client.h"
#include "main.h"
#include "stream.h"
#include "protocol.h"
#include <ascii-chat/common.h>
#include <ascii-chat/app_callbacks.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/options/rcu.h> // For RCU-based options access
#include <libplatform/compiler.h>
#include <libplatform/system.h>
#include <libplatform/terminal.h>
#include <ascii-chat/common/sync.h>
#include <ascii-chat/network/packet/queue.h>
#include <ascii-chat/network/acip/server.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/audio/mixer.h>
#include <ascii-chat/audio/audio.h>
#include <ascii-chat/audio/opus.h>
#include <ascii-chat/util/format.h>
#include <ascii-chat/util/fps.h>
 
/* ============================================================================
 * Cross-Platform Utility Functions
 * ============================================================================
 */

 
// Removed interruptible_usleep - using regular platform_sleep_us instead
// Sleep interruption isn't needed for small delays and isn't truly possible anyway
 
/* ============================================================================
 * Per-Client Video Rendering Implementation
 * ============================================================================
 */

 
void *client_video_render_thread(void *arg) {
  acip_frame_workspace_t event_workspace = {0};
  client_info_t *client = (client_info_t *)arg;
  if (!client) {
    log_error("NULL client pointer in video render thread");
    return NULL;
  }
 
  // Take snapshot of client ID and socket at start to avoid race conditions
  char thread_client_id[MAX_CLIENT_ID_LEN];
  SAFE_STRNCPY(thread_client_id, client->client_id, sizeof(thread_client_id) - 1);
  bool is_webrtc = acip_transport_get_type(client->transport) == ACIP_TRANSPORT_WEBRTC;
  (void)is_webrtc; // May be unused in release builds
 
  log_debug("Video render thread: client_id=%s, webrtc=%d", thread_client_id, is_webrtc);
 
  log_debug("[VIDEO_RENDER_THREAD_START] ★★★ LOCK STATE at thread entry for client %s", thread_client_id);
  // debug_sync_print_state();  // Disabled: causes AddressSanitizer stack-use-after-return crash
 
  // Wait for client to send terminal capabilities before rendering
  // Without capabilities, convert_composite_to_ascii() will fail
  int timeout_ms = 5000;
  int waited_ms = 0;
  while (!client->has_terminal_caps && !atomic_load_bool(&g_should_exit) && !atomic_load_bool(&client->shutting_down)) {
    if (waited_ms == 0) {
      log_debug("Waiting for terminal capabilities from client %s...", thread_client_id);
    }
    APP_CALLBACK_VOID(platform_pump_events);
    platform_sleep_ms(10);
    waited_ms += 10;
    if (waited_ms >= timeout_ms) {
      log_debug("Still waiting for terminal capabilities from client %s", thread_client_id);
      waited_ms = 0;
    }
  }
  if (client->has_terminal_caps) {
    log_debug("Received terminal capabilities for client %s after %dms", thread_client_id, waited_ms);
  }
 
  // Get client's desired FPS from capabilities or use default
  int client_fps = VIDEO_RENDER_FPS; // Default to 60 FPS
  // Use snapshot pattern to avoid mutex in render thread
  bool has_caps = client->has_terminal_caps;
  int desired_fps = has_caps ? client->terminal_caps.desired_fps : 0;
  if (has_caps && desired_fps > 0) {
    client_fps = desired_fps;
    log_debug("Client %s requested FPS: %d (has_caps=%d, desired_fps=%d)", thread_client_id, client_fps, has_caps,
              desired_fps);
  } else {
    log_debug("Client %s using default FPS: %d (has_caps=%d, desired_fps=%d)", thread_client_id, client_fps, has_caps,
              desired_fps);
  }
 
  int base_frame_interval_ms = 1000 / client_fps;
  log_debug("Client %s render interval: %dms (%d FPS)", thread_client_id, base_frame_interval_ms, client_fps);
 
  // FPS tracking for video render thread
  fps_t video_fps_tracker = {0};
  fps_init(&video_fps_tracker, client_fps, "SERVER VIDEO");
 
  const uint64_t frame_interval_ns = NS_PER_SEC_INT / client_fps;
  uint64_t next_frame_ns = time_get_ns() + frame_interval_ns;
  bool last_has_sources = false;
  uint32_t frame_gen_count = 0;
  uint64_t frame_gen_start_time = 0;
  uint64_t render_rate_window_start_ns = time_get_ns();
  uint64_t rendered_frames_in_window = 0;
  uint64_t missed_deadlines_in_window = 0;
 
  log_debug("Video render loop STARTING for client %s", thread_client_id);
 
  bool should_continue = true;
  while (should_continue && !atomic_load_bool(&g_should_exit) && !atomic_load_bool(&client->shutting_down)) {
    ASCII_OTEL_SCOPE(SERVER_VIDEO);
    log_dev_every(10 * NS_PER_MS_INT, "Video render loop iteration for client %s", thread_client_id);
 
    // Check for immediate shutdown
    if (atomic_load_bool(&g_should_exit)) {
      log_debug("Video render thread stopping for client %s (g_should_exit)", thread_client_id);
      break;
    }
 
    bool video_running = atomic_load_bool(&client->video_render_thread_running);
    bool active = atomic_load_bool(&client->active);
    bool shutting_down = atomic_load_bool(&client->shutting_down);
 
    should_continue = video_running && active && !shutting_down;
 
    if (!should_continue) {
      log_debug("Video render thread stopping for client %s (should_continue=false: video_running=%d, active=%d, "
                "shutting_down=%d)",
                thread_client_id, video_running, active, shutting_down);
      break;
    }
 
    // Processing consumes part of the frame interval. Sleep only until the
    // scheduled deadline, and skip missed deadlines without a catch-up burst.
    uint64_t iter_start_ns = time_get_ns();
    if (iter_start_ns < next_frame_ns) {
      platform_sleep_ns(next_frame_ns - iter_start_ns);
    }
    uint64_t after_sleep_ns = time_get_ns();
    uint64_t elapsed_intervals =
        after_sleep_ns >= next_frame_ns ? (after_sleep_ns - next_frame_ns) / frame_interval_ns + 1 : 1;
    if (elapsed_intervals > 1) {
      missed_deadlines_in_window += elapsed_intervals - 1;
    }
    next_frame_ns += elapsed_intervals * frame_interval_ns;
 
    // Capture timestamp for FPS tracking and frame timestamps
    uint64_t current_time_ns = time_get_ns();
 
    // Check thread state again before acquiring locks (client might have been destroyed during sleep).
    should_continue = atomic_load_bool(&client->video_render_thread_running) && atomic_load_bool(&client->active) &&
                      !atomic_load_bool(&client->shutting_down);
    if (!should_continue) {
      break;
    }
 
    // Optimization: No mutex needed - all fields are atomic or stable.
    // client_id: stable string pointer
    // width/height: stable uint16_t values (set once, never modified)
    // active: atomic_t - use atomic_load for thread safety
    const char *client_id_snapshot = client->client_id;       // Stable read
    unsigned short width_snapshot = client->width;            // Stable uint16_t
    unsigned short height_snapshot = client->height;          // Stable uint16_t
    bool active_snapshot = atomic_load_bool(&client->active); // Atomic read
 
    // Check if client is still active after getting snapshot
    if (!active_snapshot) {
      break;
    }
 
    // Phase 2 IMPLEMENTED: Generate frame specifically for THIS client using snapshot data
    size_t frame_size = 0;
 
    // Check if any clients are sending video
    bool has_video_sources = any_clients_sending_video();
 
    // DIAGNOSTIC: Track when video sources become available
    if (has_video_sources != last_has_sources) {
      log_debug("Client %s video sources: %s", thread_client_id, has_video_sources ? "AVAILABLE" : "UNAVAILABLE");
      last_has_sources = has_video_sources;
    }
 
    log_debug_every(5 * NS_PER_MS_INT,
                    "Video render iteration for client %s: has_video_sources=%d, width=%u, height=%u", thread_client_id,
                    has_video_sources, width_snapshot, height_snapshot);
 
    // Use default dimensions if client dimensions not received
    if (width_snapshot == 0 || height_snapshot == 0) {
      log_dev_every(5 * NS_PER_MS_INT, "Using default dimensions for client %s (client reported: width=%u, height=%u)",
                    thread_client_id, width_snapshot, height_snapshot);
      // Use 80x25 as standard terminal size fallback for snapshot/test clients
      width_snapshot = 80;
      height_snapshot = 25;
    }
 
    // Generate frames for all clients with valid dimensions, regardless of whether other clients are sending video.
    // This ensures WebSocket snapshot clients (receive-only mode) receive frames even when no other clients are
    // sending video.
    int sources_count = 0; // Track number of video sources in this frame
 
    // DIAGNOSTIC: Track every frame generation attempt
    frame_gen_count++;
    if (frame_gen_count == 1) {
      frame_gen_start_time = current_time_ns;
    }
 
    // Log every 120 attempts (should be ~2 seconds at 60 Hz)
    if (frame_gen_count % 120 == 0) {
      uint64_t elapsed_ns = current_time_ns - frame_gen_start_time;
      double gen_fps = (120.0 / (elapsed_ns / (double)NS_PER_SEC_INT));
      log_dev("render loop: client=%s fps=%.1f", thread_client_id, gen_fps);
    }
 
    log_dev_every(5 * NS_PER_MS_INT, "About to call create_mixed_ascii_frame_for_client for client %s with dims %ux%u",
                  thread_client_id, width_snapshot, height_snapshot);
 
    // debug_sync_print_state() is too expensive to call every frame (kills FPS)
 
    uint64_t frame_create_start_ns = time_get_ns();
    acip_render_settings_t frame_rendering = {0};
    char *ascii_frame = create_mixed_ascii_frame_for_client(client_id_snapshot, width_snapshot, height_snapshot, false,
                                                            &frame_size, NULL, &sources_count, &frame_rendering);
    uint64_t frame_create_end_ns = time_get_ns();
    if (sources_count > 0) {
      stats_duration_record(stats_runtime_scope(), STATS_DURATION_ASCII_CONVERT,
                            frame_create_end_ns - frame_create_start_ns);
      stats_counter_add(stats_runtime_scope(),
                        ascii_frame ? STATS_COUNTER_FRAMES_CONVERTED : STATS_COUNTER_FRAMES_DROPPED, 1);
    }
 
    if (frame_gen_count % 120 == 0) {
      char sleep_str[TIME_DURATION_BUFFER_SIZE], create_str[TIME_DURATION_BUFFER_SIZE];
      time_pretty((uint64_t)(after_sleep_ns - iter_start_ns), -1, sleep_str, sizeof(sleep_str));
      time_pretty((uint64_t)(frame_create_end_ns - frame_create_start_ns), -1, create_str, sizeof(create_str));
      log_dev("render timing: adaptive_sleep=%s frame_create=%s", sleep_str, create_str);
    }
 
    // Always send frames at configured FPS, even if no external video sources yet
    // This ensures single-client mode (like testing) still gets continuous frames
    // The frame data (animated background or test pattern) is still valid content
 
    if (ascii_frame && frame_size > 0) {
      server_send_video(client, &event_workspace, ascii_frame, frame_size, frame_rendering.width,
                        frame_rendering.height, sources_count, &frame_rendering);
      fps_frame_ns(&video_fps_tracker, current_time_ns, "frame rendered");
      rendered_frames_in_window++;
      uint64_t render_rate_now_ns = time_get_ns();
      uint64_t render_rate_elapsed_ns = render_rate_now_ns - render_rate_window_start_ns;
      if (render_rate_elapsed_ns >= NS_PER_SEC_INT) {
        double render_fps = (double)rendered_frames_in_window * NS_PER_SEC_INT / (double)render_rate_elapsed_ns;
        if (render_fps < (double)client_fps * 0.9 || missed_deadlines_in_window > 0) {
          log_warn("Server video render lagging client=%s fps=%.1f target=%d missed_deadlines=%llu", thread_client_id,
                   render_fps, client_fps, (unsigned long long)missed_deadlines_in_window);
        } else {
          log_debug("Server video render client=%s fps=%.1f target=%d missed_deadlines=0", thread_client_id, render_fps,
                    client_fps);
        }
        render_rate_window_start_ns = render_rate_now_ns;
        rendered_frames_in_window = 0;
        missed_deadlines_in_window = 0;
      }
      SAFE_FREE(ascii_frame);
    }
 
    uint64_t iter_end_ns = time_get_ns();
    if (frame_gen_count % 120 == 0) {
      char total_str[TIME_DURATION_BUFFER_SIZE];
      time_pretty((uint64_t)(iter_end_ns - iter_start_ns), -1, total_str, sizeof(total_str));
      log_warn_every(US_PER_SEC_INT, "  TIMING: TOTAL_ITERATION=%s", total_str);
    }
    STOP_TIMER_AND_LOG(dev, 0, "render_iteration", "render_iteration completed (total)");
  }
 
#ifdef DEBUG_THREADS
  log_debug("Video render thread stopped for client %s", thread_client_id);
#endif
  acip_frame_workspace_destroy(&event_workspace);
 
  // Clean up thread-local error context before exit
 
  return NULL;
}
 
/* ============================================================================
 * Per-Client Audio Rendering Implementation
 * ============================================================================
 */

 
void *client_audio_render_thread(void *arg) {
  client_info_t *client = (client_info_t *)arg;
 
  if (!client) {
    log_error("Invalid client info in audio render thread");
    return NULL;
  }
 
  // Take snapshot of client ID and display name at start to avoid race conditions
  char thread_client_id[MAX_CLIENT_ID_LEN];
  SAFE_STRNCPY(thread_client_id, client->client_id, sizeof(thread_client_id) - 1);
  char thread_display_name[SERVER_RENDER_THREAD_DISPLAY_NAME_BUFFER_SIZE];
  bool is_webrtc = acip_transport_get_type(client->transport) == ACIP_TRANSPORT_WEBRTC;
  (void)is_webrtc; // May be unused in release builds
 
  // LOCK OPTIMIZATION: Only need client_state_mutex, not global rwlock
  // We already have a stable client pointer
  mutex_lock(&client->client_state_mutex);
  SAFE_STRNCPY(thread_display_name, client->display_name, sizeof(thread_display_name));
  mutex_unlock(&client->client_state_mutex);
 
#ifdef DEBUG_THREADS
  log_debug("Audio render thread started for client %s (%s), webrtc=%d", thread_client_id, thread_display_name,
            is_webrtc);
#endif
 
  // Mix buffer: up to OPUS_FRAME_SAMPLES samples for adaptive reading
  // Normal: 480 samples = 10ms @ 48kHz
  // Catchup: OPUS_FRAME_SAMPLES samples = 20ms when buffers are filling up
  float mix_buffer[OPUS_FRAME_SAMPLES * AUDIO_CHANNELS];
 
  // Opus frame accumulation buffer (OPUS_FRAME_SAMPLES samples = 20ms @ 48kHz)
  // Opus requires minimum 480 samples, OPUS_FRAME_SAMPLES is optimal for 20ms frames
  float opus_frame_buffer[(OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)];
  int opus_frame_accumulated = 0;
 
  // Create an Opus encoder for the interleaved stereo stream.
  opus_codec_t *opus_encoder =
      opus_codec_create_encoder_channels(OPUS_APPLICATION_AUDIO, AUDIO_SAMPLE_RATE, 128000, AUDIO_CHANNELS);
  if (!opus_encoder) {
    log_error("Failed to create Opus encoder for audio render thread (client %s)", thread_client_id);
    return NULL;
  }
 
  // FPS tracking for audio render thread
  fps_t audio_fps_tracker = {0};
  fps_init(&audio_fps_tracker, AUDIO_PACKET_FPS, "SERVER AUDIO");
 
  // Per-thread counters (NOT static - each thread instance gets its own)
  int server_audio_frame_count = 0;
 
  bool should_continue = true;
  uint64_t audio_deadline = time_get_ns();
  while (should_continue && !atomic_load_bool(&g_should_exit) && !atomic_load_bool(&client->shutting_down)) {
    ASCII_OTEL_SCOPE(SERVER_AUDIO);
    log_debug_every(LOG_RATE_SLOW, "Audio render loop iteration for client %s", thread_client_id);
 
    // Check for immediate shutdown
    if (atomic_load_bool(&g_should_exit)) {
      log_debug("Audio render thread stopping for client %s (g_should_exit)", thread_client_id);
      break;
    }
 
    // Check thread state before acquiring any locks to prevent use-after-destroy.
    // If we acquire locks after client is being destroyed, we'll crash with SIGSEGV
    should_continue = (((int)atomic_load_bool(&client->audio_render_thread_running) != 0) &&
                       ((int)atomic_load_bool(&client->active) != 0) && !atomic_load_bool(&client->shutting_down));
 
    if (!should_continue) {
      log_debug("Audio render thread stopping for client %s (should_continue=false)", thread_client_id);
      break;
    }
 
    if (!g_audio_mixer) {
      log_dev_every(10 * NS_PER_MS_INT, "Audio render waiting for mixer (client %s)", thread_client_id);
      // Check shutdown flag while waiting
      if (atomic_load_bool(&g_should_exit))
        break;
      platform_sleep_ns(10 * NS_PER_MS_INT);
      continue;
    }
 
    // There is no mixed audio to send when this is the only registered
    // source. Avoid entering the mixer just to discover that exclusion; this
    // is the common single-client server case.
    if (mixer_source_count(g_audio_mixer) <= 1) {
      audio_deadline += 20 * NS_PER_MS_INT;
      uint64_t idle_now = time_get_ns();
      if (audio_deadline > idle_now)
        platform_sleep_ns(audio_deadline - idle_now);
      else
        audio_deadline = idle_now;
      continue;
    }
 
    const char *client_id_snapshot = client->client_id;
    if (!atomic_load_bool(&client->active))
      break;
 
    // Create mix excluding THIS client's audio using snapshot data
 
    // Mix one complete Opus frame per iteration. This keeps the source lock at
    // the packet cadence instead of reacquiring it twice for every 20 ms of
    // audio, while preserving the exact frame boundary required by the codec.
    int samples_to_read = OPUS_FRAME_SAMPLES * AUDIO_CHANNELS;
 
    int samples_mixed = 0;
    uint32_t client_id_hash = fnv1a_hash_string(client_id_snapshot);
    uint64_t stats_mix_start = time_get_ns();
    samples_mixed = mixer_process_excluding_source(g_audio_mixer, mix_buffer, samples_to_read, client_id_hash);
    stats_duration_record(stats_runtime_scope(), STATS_DURATION_AUDIO_MIX, time_get_ns() - stats_mix_start);
 
    log_debug_every(LOG_RATE_SLOW, "Audio render for client %s: samples_mixed=%d", client_id_snapshot, samples_mixed);
 
    // Accumulate all samples (including 0 or partial) until we have a full Opus frame
    // This maintains continuous stream without silence padding
 
    int space_available = (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) - opus_frame_accumulated;
    int samples_to_copy = (samples_mixed <= space_available) ? samples_mixed : space_available;
 
    // Only copy if we have samples, otherwise just wait for next frame
    if (samples_to_copy > 0) {
      SAFE_MEMCPY(opus_frame_buffer + opus_frame_accumulated,
                  ((OPUS_FRAME_SAMPLES * AUDIO_CHANNELS) - opus_frame_accumulated) * sizeof(float), mix_buffer,
                  samples_to_copy * sizeof(float));
      opus_frame_accumulated += samples_to_copy;
    }
 
    // Only encode and send when we have accumulated a full Opus frame
    if (opus_frame_accumulated >= (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)) {
      // Encode accumulated Opus frame (OPUS_FRAME_SAMPLES samples = 20ms @ 48kHz)
      uint8_t opus_buffer[AUDIO_OPUS_SERVER_PACKET_CAPACITY]; // Max Opus frame size
 
      int opus_size = opus_codec_encode(opus_encoder, opus_frame_buffer, OPUS_FRAME_SAMPLES * AUDIO_CHANNELS,
                                        opus_buffer, sizeof(opus_buffer));
 
      // DEBUG: Log mix buffer and encoding results to see audio levels being sent
      {
        float peak = 0.0f, rms = 0.0f;
        for (int i = 0; i < (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS); i++) {
          float abs_val = fabsf(opus_frame_buffer[i]);
          if (abs_val > peak)
            peak = abs_val;
          rms += opus_frame_buffer[i] * opus_frame_buffer[i];
        }
        rms = sqrtf(rms / (OPUS_FRAME_SAMPLES * AUDIO_CHANNELS));
        // NOTE: server_audio_frame_count is now per-thread (not static), so each client thread has its own counter
        server_audio_frame_count++;
        if (server_audio_frame_count <= 5 || server_audio_frame_count % 20 == 0) {
          // Log first 4 samples to verify they look like valid audio (not NaN/Inf/garbage)
          log_dev_every(4500 * US_PER_MS_INT,
                        "Server audio frame #%d for client %s: samples_mixed=%d, Peak=%.6f, RMS=%.6f, opus_size=%d, "
                        "first4=[%.4f,%.4f,%.4f,%.4f]",
                        server_audio_frame_count, client_id_snapshot, samples_mixed, peak, rms, opus_size,
                        opus_frame_buffer[0], opus_frame_buffer[1], opus_frame_buffer[2], opus_frame_buffer[3]);
        }
      }
 
      // Always reset accumulation buffer after attempting to encode - we've consumed these samples
      // If we don't reset, new audio samples would be dropped while stale data sits in the buffer
      opus_frame_accumulated = 0;
 
      if (opus_size <= 0) {
        log_error_every(US_PER_SEC_INT, "Failed to encode audio to Opus for client %s: opus_size=%d",
                        client_id_snapshot, opus_size);
      } else {
        // Wrap Opus data in proper batch packet format for client parsing:
        // Header: sample_rate (4B) + frame_duration (4B) + frame_count (4B)
        // Frame sizes: frame_count * 2B (one uint16 per frame with Opus data size)
        // Opus data: raw encoded audio
 
        // Fixed values for Opus encoding (standard 48kHz, OPUS_FRAME_SAMPLES samples per frame = 20ms)
        const uint32_t sample_rate = AUDIO_SAMPLE_RATE;
        const uint32_t frame_duration =
            CLIENT_AUDIO_PIPELINE_FRAME_MS; // milliseconds (OPUS_FRAME_SAMPLES samples / 48kHz = 20ms)
        const uint32_t frame_count = 1;     // one Opus frame per packet
        const uint16_t frame_size = (uint16_t)opus_size;
 
        // Calculate total packet size: 16-byte header + frame_sizes + opus data
        const size_t header_size = 16; // 4 uint32s (sample_rate, frame_duration, frame_count, reserved)
        const size_t frame_sizes_size = (size_t)frame_count * sizeof(uint16_t);
        const size_t total_packet_size = header_size + frame_sizes_size + (size_t)opus_size;
 
        // Allocate buffer for the complete packet
        uint8_t *packet_buffer = SAFE_MALLOC(total_packet_size, uint8_t *);
        if (!packet_buffer) {
          log_error("Failed to allocate Opus batch packet buffer for client %s (size=%zu)", client_id_snapshot,
                    total_packet_size);
        } else {
          // Build header in network byte order
          uint8_t *ptr = packet_buffer;
 
          // Write sample_rate (4 bytes, network byte order)
          uint32_t sr_net = htonl(sample_rate);
          memcpy(ptr, &sr_net, 4);
          ptr += 4;
 
          // Write frame_duration (4 bytes, network byte order)
          uint32_t fd_net = htonl(frame_duration);
          memcpy(ptr, &fd_net, 4);
          ptr += 4;
 
          // Write frame_count (4 bytes, network byte order)
          uint32_t fc_net = htonl(frame_count);
          memcpy(ptr, &fc_net, 4);
          ptr += 4;
 
          // Write reserved field (4 bytes, all zeros)
          uint32_t reserved = 0;
          memcpy(ptr, &reserved, 4);
          ptr += 4;
 
          // Write frame sizes (2 bytes per frame, network byte order)
          for (uint32_t i = 0; i < frame_count; i++) {
            uint16_t fs_net = htons(frame_size);
            memcpy(ptr, &fs_net, 2);
            ptr += 2;
          }
 
          // Copy Opus data
          memcpy(ptr, opus_buffer, (size_t)opus_size);
 
          // Queue the properly formatted packet
          asciichat_error_t result = server_send_audio(client, packet_buffer, total_packet_size);
 
          if (result != ASCIICHAT_OK) {
            log_debug_every(US_PER_SEC_INT, "Failed to queue Opus audio for client %s", client_id_snapshot);
          } else {
            // FPS tracking - audio packet successfully queued (handles lag detection and periodic reporting)
            fps_frame_ns(&audio_fps_tracker, time_get_ns(), "audio packet queued");
          }
 
          // Free the allocated packet buffer after queuing (packet_queue_push_copy copies data)
          SAFE_FREE(packet_buffer);
        }
      }
      // NOTE: opus_frame_accumulated is already reset at line 928 after encode attempt
    }
 
    // Audio mixing rate limiting using adaptive sleep system.
    // One complete Opus frame is mixed per 20 ms iteration.
    // Use queue_depth=0 and target_depth=0 for constant-rate audio processing
    audio_deadline += 20 * NS_PER_MS_INT;
    uint64_t now = time_get_ns();
    if (audio_deadline > now)
      platform_sleep_ns(audio_deadline - now);
    else if (now - audio_deadline > 100 * NS_PER_MS_INT)
      audio_deadline = now;
  }
 
#ifdef DEBUG_THREADS
  log_debug("Audio render thread stopped for client %s", thread_client_id);
#endif
 
  // Clean up Opus encoder
  if (opus_encoder) {
    opus_codec_destroy(opus_encoder);
  }
 
  // Clean up thread-local error context before exit
 
  return NULL;
}
 
/* ============================================================================
 * Thread Lifecycle Management Functions
 * ============================================================================
 */

 
int create_client_render_threads(server_context_t *server_ctx, client_info_t *client) {
  log_debug("client_id=%s", client ? client->client_id : "NULL");
 
  if (!server_ctx || !client) {
    log_error("Cannot create render threads: NULL %s", !server_ctx ? "server_ctx" : "client");
    return -1;
  }
 
#ifdef DEBUG_THREADS
  log_debug("Creating render threads for client %s", client->client_id);
#endif
 
  // NOTE: Mutexes are already initialized in add_client() before any threads start
  // This prevents race conditions where receive thread tries to use uninitialized mutexes
 
  // Initialize render thread control flags
  // IMPORTANT: Set to true BEFORE creating thread to avoid race condition
  // where thread starts and immediately exits because flag is false
  atomic_store_bool(&client->video_render_thread_running, true);
  atomic_store_bool(&client->audio_render_thread_running, true);
 
  // Create video rendering thread (stop_id=2, stop after receive thread)
  char thread_name[SERVER_RENDER_THREAD_NAME_BUFFER_SIZE];
  safe_snprintf(thread_name, sizeof(thread_name), "video_render_%s", client->client_id);
  asciichat_error_t video_result;
 
  video_result = platform_thread_create(&client->video_render_thread, thread_name, client_video_render_thread, client);
 
  if (video_result != ASCIICHAT_OK) {
    // Reset flag since thread creation failed
    atomic_store_bool(&client->video_render_thread_running, false);
    atomic_store_bool(&client->audio_render_thread_running, false);
    // Mutexes will be destroyed by remove_client() which called us
    return -1;
  }
 
  // Create audio rendering thread (stop_id=2, same priority as video)
  safe_snprintf(thread_name, sizeof(thread_name), "audio_render_%s", client->client_id);
  asciichat_error_t audio_result;
 
  audio_result = platform_thread_create(&client->audio_render_thread, thread_name, client_audio_render_thread, client);
  if (audio_result != ASCIICHAT_OK) {
    // Clean up video thread (atomic operation, no mutex needed)
    atomic_store_bool(&client->video_render_thread_running, false);
    // Reset audio flag since thread creation failed
    atomic_store_bool(&client->audio_render_thread_running, false);
    // stop_client_render_threads() will be called by remove_client()
    // to clean up the video thread we just created
    // Mutexes will be destroyed by remove_client() which called us
    return -1;
  }
 
#ifdef DEBUG_THREADS
  log_debug("Created render threads for client %s", client->client_id);
#endif
 
  return 0;
}

asciichat_error_t stop_client_render_threads(client_info_t *client) {
  if (!client)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing render client");
  atomic_store_bool(&client->video_render_thread_running, false);
  atomic_store_bool(&client->audio_render_thread_running, false);
  if (thread_is_initialized(&client->video_render_thread)) {
    asciichat_error_t result = thread_join(&client->video_render_thread, NULL);
    if (result != ASCIICHAT_OK)
      return result;
    thread_init(&client->video_render_thread);
  }
  if (thread_is_initialized(&client->audio_render_thread)) {
    asciichat_error_t result = thread_join(&client->audio_render_thread, NULL);
    if (result != ASCIICHAT_OK)
      return result;
    thread_init(&client->audio_render_thread);
  }
  return ASCIICHAT_OK;
}