Media Capture

📹 Webcam video capture and transmission to server More...

Files
file	capture.c
	📹 Client webcam capture: dedicated capture thread with frame rate limiting and network transmission
file	capture.h
	ascii-chat Client Media Capture Management Interface

Functions
	__attribute__ ((unused))
	Webcam capture thread handle.
int	capture_init ()
	Initialize capture subsystem.
int	capture_start_thread ()
	Start capture thread.
void	capture_stop_thread ()
	Stop capture thread.
bool	capture_thread_exited ()
	Check if capture thread has exited.
void	capture_cleanup ()
	Cleanup capture subsystem.

Detailed Description

📹 Webcam video capture and transmission to server

Media Capture

Overview

The media capture subsystem manages webcam video capture, frame compression, and transmission to the server. Supports platform-specific webcam backends and test pattern mode for testing without hardware.

Implementation: src/client/capture.c, src/client/capture.h

Platform Support

Webcam Backends:

• macOS: AVFoundation (lib/video/webcam/macos/webcam_avfoundation.m)
• Linux: Video4Linux2 (lib/video/webcam/linux/webcam_v4l2.c)
• Windows: Media Foundation (lib/video/webcam/windows/webcam_mediafoundation.c)

Capture Thread

static void *capture_thread_func(void *arg)
{
  (void)arg;
 
  // Calculate frame interval for target FPS
  uint64_t frame_interval_usec = 1000000 / VIDEO_CAPTURE_FPS;
  uint64_t start_time = get_monotonic_time_usec();
 
  while (!should_exit() && server_connection_is_active()) {
    // Capture frame from webcam
    video_frame_t *frame = webcam_capture();
    if (!frame) {
      platform_sleep_usec(frame_interval_usec);
      continue;
    }
 
    // Optional compression
    void *send_data = frame->data;
    size_t send_size = frame->data_size;
    void *compressed_data = NULL;
 
    if (opt_compress) {
      compressed_data = compress_frame(frame->data, frame->data_size, &send_size);
      if (compressed_data) {
        send_data = compressed_data;
      }
    }
 
    // Send frame to server
    send_packet_to_server(PACKET_TYPE_IMAGE_FRAME, send_data, send_size,
                         server_connection_get_client_id());
 
    if (compressed_data) free(compressed_data);
    if (frame->owns_data && frame->data) free(frame->data);
    free(frame);
 
    // Rate limiting
    platform_sleep_usec(frame_interval_usec);
 
    // Snapshot mode: exit after delay
    if (opt_snapshot) {
      uint64_t elapsed = (get_monotonic_time_usec() - start_time) / 1000000;
      if (elapsed >= opt_snapshot_delay) {
        signal_exit();
        break;
      }
    }
  }
 
  atomic_store(&g_capture_thread_exited, true);
  return NULL;
}

Snapshot Mode

Snapshot mode (--snapshot, --snapshot-delay <seconds>):

• Useful for testing without continuous streaming
• --snapshot: Capture single frame and exit
• --snapshot-delay N: Capture for N seconds then exit

# Single frame test
./bin/ascii-chat client --snapshot
 
# 5-second test
./bin/ascii-chat client --snapshot --snapshot-delay 5

Test Pattern Mode

Test pattern mode (--test-pattern):

• Generates synthetic video frames without webcam hardware
• Useful for testing on Windows or systems without webcam
• Uses platform-specific test pattern generation

# Use test pattern instead of webcam
./bin/ascii-chat client --test-pattern

See also

src/client/capture.c

src/client/capture.h

lib/video/webcam/webcam.h

Client Overview

Function Documentation

__attribute__()

__attribute__

(

(unused)

)

#include <capture.c>

Webcam capture thread handle.

Thread handle for the background thread that captures video frames from the webcam device. Created during connection establishment, joined during shutdown.

Definition at line 125 of file capture.c.

                                                                                                            {
  // Calculate original aspect ratio
  float img_aspect = (float)original_width / (float)original_height;
  // Check if image needs resizing
  if (original_width <= max_width && original_height <= max_height) {
    // Image is already within bounds - use as-is
    *result_width = original_width;
    *result_height = original_height;
    return;
  }
  // Determine scaling factor based on which dimension is the limiting factor
  if ((float)max_width / (float)max_height > img_aspect) {
    // Max box is wider than image aspect - scale by height
    *result_height = max_height;
    *result_width = (ssize_t)(max_height * img_aspect);
  } else {
    // Max box is taller than image aspect - scale by width
    *result_width = max_width;
    *result_height = (ssize_t)(max_width / img_aspect);
  }
}

capture_cleanup()

void capture_cleanup

(

)

#include <capture.c>

Cleanup capture subsystem.

Cleanup capture subsystem

Stops capture thread and cleans up webcam resources. Called during client shutdown.

Definition at line 526 of file capture.c.

                       {
  capture_stop_thread();
  webcam_cleanup();
}

References capture_stop_thread(), and webcam_cleanup().

Referenced by client_crypto_handshake().

capture_init()

int capture_init

(

)

#include <capture.c>

Initialize capture subsystem.

Initialize capture subsystem

Sets up webcam device and prepares capture system for operation. Must be called once during client initialization.

Returns

0 on success, negative on error

0 on success, negative on error

Definition at line 428 of file capture.c.

                   {
  // Initialize webcam capture
  int webcam_index = GET_OPTION(webcam_index);
  int result = webcam_init(webcam_index);
  if (result != 0) {
    SET_ERRNO(ERROR_WEBCAM, "Failed to initialize webcam (error code: %d)", result);
    // Preserve specific error code (e.g., WEBCAM vs WEBCAM_IN_USE)
    return result;
  }
  return 0;
}

References ERROR_WEBCAM, GET_OPTION, SET_ERRNO, and webcam_init().

capture_start_thread()

int capture_start_thread

(

)

#include <capture.c>

Start capture thread.

Start capture thread

Creates and starts the webcam capture thread. Also sends stream start notification to server.

Returns

0 on success, negative on error

0 on success, negative on error

Definition at line 449 of file capture.c.

                           {
  if (THREAD_IS_CREATED(g_capture_thread_created)) {
    log_warn("Capture thread already created");
    return 0;
  }
 
  // Start webcam capture thread
  atomic_store(&g_capture_thread_exited, false);
  if (thread_pool_spawn(g_client_worker_pool, webcam_capture_thread_func, NULL, 2, "webcam_capture") != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_THREAD, "Webcam capture thread creation failed");
    LOG_ERRNO_IF_SET("Webcam capture thread creation failed");
    return -1;
  }
 
  g_capture_thread_created = true;
  log_info("Webcam capture thread created successfully");
 
  // Notify server we're starting to send video
  if (threaded_send_stream_start_packet(STREAM_TYPE_VIDEO) < 0) {
    LOG_ERRNO_IF_SET("Failed to send stream start packet");
  }
 
  return 0;
}

References ASCIICHAT_OK, ERROR_THREAD, g_client_worker_pool, LOG_ERRNO_IF_SET, log_info, log_warn, SET_ERRNO, STREAM_TYPE_VIDEO, THREAD_IS_CREATED, thread_pool_spawn(), and threaded_send_stream_start_packet().

Referenced by protocol_start_connection().

capture_stop_thread()

void capture_stop_thread

(

)

#include <capture.c>

Stop capture thread.

Stop capture thread

Gracefully stops the capture thread and cleans up resources. Safe to call multiple times.

Definition at line 481 of file capture.c.

                           {
  if (!THREAD_IS_CREATED(g_capture_thread_created)) {
    return;
  }
 
  // Flush webcam to interrupt any blocking ReadSample operations
  // This allows the capture thread to notice should_exit() and exit cleanly
  webcam_flush();
 
  // Wait for thread to exit gracefully
  int wait_count = 0;
  while (wait_count < 20 && !atomic_load(&g_capture_thread_exited)) {
    platform_sleep_usec(100000); // 100ms
    // Keep flushing in case the thread went back into a blocking read
    if (wait_count % 5 == 0) {
      webcam_flush();
    }
    wait_count++;
  }
 
  if (!atomic_load(&g_capture_thread_exited)) {
    log_warn("Capture thread not responding after 2 seconds - will be joined by thread pool");
  }
 
  // Thread will be joined by thread_pool_stop_all() in protocol_stop_connection()
  g_capture_thread_created = false;
}

References log_warn, platform_sleep_usec(), THREAD_IS_CREATED, and webcam_flush().

Referenced by capture_cleanup(), and protocol_stop_connection().

capture_thread_exited()

bool capture_thread_exited

(

)

#include <capture.c>

Check if capture thread has exited.

Check if capture thread has exited

Returns

true if thread has exited, false otherwise

true if thread exited, false otherwise

Definition at line 515 of file capture.c.

                             {
  return atomic_load(&g_capture_thread_exited);
}