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
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

capture_cleanup()

void capture_cleanup

(

)

#include <capture.c>

Cleanup capture subsystem.

Cleanup capture subsystem

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

Definition at line 485 of file src/client/capture.c.

                       {
  capture_stop_thread();
 
  // Destroy capture context
  if (g_capture_capture_ctx) {
    session_capture_destroy(g_capture_capture_ctx);
    g_capture_capture_ctx = NULL;
  }
}

References capture_stop_thread(), and session_capture_destroy().

Referenced by client_crypto_handshake().

capture_init()

int capture_init

(

)

#include <capture.c>

Initialize capture subsystem.

Initialize capture subsystem

Sets up media source (webcam, file, or stdin) 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 346 of file src/client/capture.c.

                   {
  // Build capture configuration from options
  session_capture_config_t config = {0};
  const char *media_url = GET_OPTION(media_url);
  const char *media_file = GET_OPTION(media_file);
  bool media_from_stdin = GET_OPTION(media_from_stdin);
 
  if (media_url && media_url[0] != '\0') {
    // Network URL streaming (takes priority over --file)
    // Don't open webcam when streaming from URL
    config.type = MEDIA_SOURCE_FILE;
    config.path = media_url;
    config.loop = false; // Network URLs cannot be looped
    log_debug("Using network URL: %s (webcam disabled)", media_url);
  } else if (media_file && media_file[0] != '\0') {
    // File or stdin streaming - don't open webcam
    config.type = media_from_stdin ? MEDIA_SOURCE_STDIN : MEDIA_SOURCE_FILE;
    config.path = media_file;
    config.loop = GET_OPTION(media_loop) && !media_from_stdin;
    log_debug("Using media %s: %s (webcam disabled)", media_from_stdin ? "stdin" : "file", media_file);
  } else if (GET_OPTION(test_pattern)) {
    // Test pattern mode - don't open real webcam
    config.type = MEDIA_SOURCE_TEST;
    config.path = NULL;
    log_debug("Using test pattern mode");
  } else {
    // Webcam mode (default)
    static char webcam_index_str[32];
    safe_snprintf(webcam_index_str, sizeof(webcam_index_str), "%u", GET_OPTION(webcam_index));
    config.type = MEDIA_SOURCE_WEBCAM;
    config.path = webcam_index_str;
    log_debug("Using webcam device %u", GET_OPTION(webcam_index));
  }
  config.target_fps = CAPTURE_TARGET_FPS;
  config.resize_for_network = true; // Client always resizes for network transmission
 
  // Configure audio capture with fallback to microphone
  config.enable_audio = true;
  config.audio_fallback_to_mic = true;
  config.mic_audio_ctx = audio_get_context();
 
  // Add seek timestamp if specified
  config.initial_seek_timestamp = GET_OPTION(media_seek_timestamp);
 
  // Create capture context using session library
  g_capture_capture_ctx = session_capture_create(&config);
  if (!g_capture_capture_ctx) {
    // Check if there's already an error set (e.g., ERROR_WEBCAM_IN_USE)
    asciichat_error_t existing_error = GET_ERRNO();
    log_debug("session_capture_create failed, GET_ERRNO() returned: %d", existing_error);
    if (existing_error != ASCIICHAT_OK) {
      log_debug("Returning existing error code %d", existing_error);
      return existing_error;
    }
    SET_ERRNO(ERROR_MEDIA_INIT, "Failed to initialize capture source");
    return -1;
  }
 
  return 0;
}

References audio_get_context(), CAPTURE_TARGET_FPS, safe_snprintf(), and session_capture_create().

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 416 of file src/client/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_debug("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 g_client_worker_pool, 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 448 of file src/client/capture.c.

                           {
  if (!THREAD_IS_CREATED(g_capture_thread_created)) {
    return;
  }
 
  // Wait for thread to exit gracefully
  int wait_count = 0;
  while (wait_count < 20 && !atomic_load(&g_capture_thread_exited)) {
    platform_sleep_us(100 * US_PER_MS_INT); // 100ms
    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 platform_sleep_us().

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 474 of file src/client/capture.c.

                             {
  return atomic_load(&g_capture_thread_exited);
}