capture.c File Reference

📹 Unified media capture implementation More...

Go to the source code of this file.

Data Structures
struct	session_capture_ctx
	Runtime state for media loading, frame timing, and source switching. More...

Macros
#define	SESSION_CAPTURE_LOAD_PATH_BUFFER_SIZE   8192
#define	SESSION_CAPTURE_LOAD_ERROR_BUFFER_SIZE   512
#define	SESSION_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE   32
#define	SESSION_CAPTURE_ERROR_BUFFER_SIZE   512
#define	SESSION_CAPTURE_PATH_BUFFER_SIZE   8192
#define	SESSION_CAPTURE_FAILURE_BUFFER_SIZE   512
#define	CAPTURE_TRACKER_NAME_BUFFER_SIZE   32
#define	SESSION_MAX_FRAME_WIDTH   320
	Maximum frame width for network transmission (bandwidth optimization).
#define	SESSION_MAX_FRAME_HEIGHT   180
	Maximum frame height for network transmission (bandwidth optimization).

Functions
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.
bool	session_capture_cancel_open (session_capture_ctx_t *ctx)
asciichat_error_t	session_capture_open_media (session_capture_ctx_t *ctx, const char *path)
asciichat_error_t	session_capture_open_playlist (session_capture_ctx_t *ctx, const char *text)
void	session_capture_skip_media (session_capture_ctx_t *ctx, int direction)
void	session_capture_lock_source (session_capture_ctx_t *ctx)
void	session_capture_unlock_source (session_capture_ctx_t *ctx)
image_t *	session_capture_read_frame (session_capture_ctx_t *ctx)
	Read the next video frame from the capture source.
asciichat_error_t	session_capture_process_for_transmission_into (session_capture_ctx_t *ctx, image_t *frame, image_t **output)
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.
void *	session_capture_get_audio_context (session_capture_ctx_t *ctx)
	Get the audio context for playback control.
void	session_capture_set_audio_updater (session_capture_ctx_t *ctx, session_capture_audio_update_fn update, void *user_data)
void	session_capture_set_audio_context (session_capture_ctx_t *ctx, void *audio_ctx)
	Set the audio context for playback control.
void	session_capture_toggle_media (session_capture_ctx_t *ctx)
bool	session_capture_media_active (session_capture_ctx_t *ctx)
void	session_capture_redraw_media (session_capture_ctx_t *ctx)
uint64_t	session_capture_source_epoch (session_capture_ctx_t *ctx)
uint64_t	session_capture_frame_serial (session_capture_ctx_t *ctx)
void	session_capture_complete_open (session_capture_ctx_t *ctx, uint64_t epoch)

Detailed Description

📹 Unified media capture implementation

Implements the session capture abstraction layer for unified media source handling across client, mirror, and discovery modes.

Author

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

Date

January 2026

Definition in file common/session/capture.c.

Macro Definition Documentation

CAPTURE_TRACKER_NAME_BUFFER_SIZE

#define CAPTURE_TRACKER_NAME_BUFFER_SIZE   32

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

Referenced by session_capture_create(), and session_network_capture_create().

SESSION_CAPTURE_ERROR_BUFFER_SIZE

#define SESSION_CAPTURE_ERROR_BUFFER_SIZE   512

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

SESSION_CAPTURE_FAILURE_BUFFER_SIZE

#define SESSION_CAPTURE_FAILURE_BUFFER_SIZE   512

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

SESSION_CAPTURE_LOAD_ERROR_BUFFER_SIZE

#define SESSION_CAPTURE_LOAD_ERROR_BUFFER_SIZE   512

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

SESSION_CAPTURE_LOAD_PATH_BUFFER_SIZE

#define SESSION_CAPTURE_LOAD_PATH_BUFFER_SIZE   8192

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

SESSION_CAPTURE_PATH_BUFFER_SIZE

#define SESSION_CAPTURE_PATH_BUFFER_SIZE   8192

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

SESSION_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE

#define SESSION_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE   32

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

Referenced by session_capture_create().

SESSION_MAX_FRAME_HEIGHT

#define SESSION_MAX_FRAME_HEIGHT   180

Maximum frame height for network transmission (bandwidth optimization).

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

Referenced by session_capture_process_for_transmission_into().

SESSION_MAX_FRAME_WIDTH

#define SESSION_MAX_FRAME_WIDTH   320

Maximum frame width for network transmission (bandwidth optimization).

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

Referenced by session_capture_process_for_transmission_into().

Function Documentation

session_capture_cancel_open()

bool session_capture_cancel_open

(

session_capture_ctx_t *

ctx

)

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

                                                             {
  if (!ctx || !ctx->media_locks_ready)
    return false;
  mutex_lock(&ctx->load_mutex);
  bool busy = ctx->loader_created;
  if (busy)
    atomic_store_bool(&ctx->load_cancel, true);
  mutex_unlock(&ctx->load_mutex);
  if (busy)
    ui_controller_remove(UI_SCREEN_RENDER_PROGRESS);
  return busy;
}

References session_capture_ctx::load_cancel, session_capture_ctx::load_mutex, session_capture_ctx::loader_created, session_capture_ctx::media_locks_ready, ui_controller_remove(), and UI_SCREEN_RENDER_PROGRESS.

Referenced by session_handle_keyboard_input().

session_capture_complete_open()

void session_capture_complete_open	(	session_capture_ctx_t *	ctx,
		uint64_t	epoch )

Reveal the committed source after its first frame has been published or transmitted.

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

                                                                               {
  if (!ctx || !atomic_load_bool(&ctx->awaiting_presentation))
    return;
  mutex_lock(&ctx->load_mutex);
  if (epoch == session_capture_source_epoch(ctx) && atomic_exchange_bool(&ctx->awaiting_presentation, false))
    ui_controller_remove(UI_SCREEN_RENDER_PROGRESS);
  mutex_unlock(&ctx->load_mutex);
}

References session_capture_ctx::awaiting_presentation, session_capture_ctx::load_mutex, session_capture_source_epoch(), ui_controller_remove(), and UI_SCREEN_RENDER_PROGRESS.

Referenced by session_pipeline_run_main().

session_capture_frame_serial()

uint64_t session_capture_frame_serial

(

session_capture_ctx_t *

ctx

)

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

                                                                  {
  return ctx ? atomic_load_u64(&ctx->frame_serial) : 0;
}

References session_capture_ctx::frame_serial.

session_capture_get_audio_context()

void * session_capture_get_audio_context

(

session_capture_ctx_t *

ctx

)

Get the audio context for playback control.

Parameters

ctx	Capture context

Returns

Audio context pointer (borrowed, not owned) or NULL

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

                                                                    {
  if (!ctx || !ctx->initialized) {
    return NULL;
  }
  return atomic_ptr_load(&ctx->audio_ctx);
}

References session_capture_ctx::audio_ctx, and session_capture_ctx::initialized.

session_capture_lock_source()

void session_capture_lock_source

(

session_capture_ctx_t *

ctx

)

Serialize decoder controls with capture-owner replacement.

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

                                                             {
  if (ctx && ctx->media_locks_ready)
    mutex_lock(&ctx->source_mutex);
}

References session_capture_ctx::media_locks_ready, and session_capture_ctx::source_mutex.

Referenced by session_capture_read_audio(), session_capture_read_frame(), session_capture_set_audio_context(), and session_handle_keyboard_input().

session_capture_media_active()

bool session_capture_media_active

(

session_capture_ctx_t *

ctx

)

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

                                                              {
  return ctx && !atomic_load_bool(&ctx->non_media_active);
}

References session_capture_ctx::non_media_active.

session_capture_open_media()

asciichat_error_t session_capture_open_media	(	session_capture_ctx_t *	ctx,
		const char *	path )

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

                                                                                           {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_OPEN_MEDIA);
  media_playlist_t list = {0};
  asciichat_error_t result = media_playlist_append(&list, path, path && strstr(path, "://") != NULL);
  return result == ASCIICHAT_OK ? capture_load_playlist(ctx, &list, 0, false) : result;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, and media_playlist_append().

session_capture_open_playlist()

asciichat_error_t session_capture_open_playlist	(	session_capture_ctx_t *	ctx,
		const char *	text )

Replace the current playlist with quoted paths or URLs.

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

                                                                                              {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_OPEN_PLAYLIST);
  media_playlist_t list = {0};
  asciichat_error_t result = media_playlist_parse(text, &list);
  return result == ASCIICHAT_OK ? capture_load_playlist(ctx, &list, 0, false) : result;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, and media_playlist_parse().

Referenced by session_handle_keyboard_input().

session_capture_process_for_transmission_into()

asciichat_error_t session_capture_process_for_transmission_into	(	session_capture_ctx_t *	ctx,
		image_t *	frame,
		image_t **	output )

Reuse capture-worker-owned storage; preserves it on allocation failure. The caller destroys *output after capture joins. Input may equal *output.

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

                                                                                  {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_PROCESS_FOR_TRANSMISSION_INTO);
  if (!ctx || !frame || !output)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing transmission frame or workspace");
  ssize_t width = frame->w, height = frame->h;
  if (ctx->resize_for_network)
    calculate_optimal_dimensions(frame->w, frame->h, SESSION_MAX_FRAME_WIDTH, SESSION_MAX_FRAME_HEIGHT, &width,
                                 &height);
  if (!*output || (*output)->w != width || (*output)->h != height) {
    image_t *replacement = image_new(width, height);
    if (!replacement)
      return SET_ERRNO(ERROR_MEMORY, "Cannot reserve transmission image workspace");
    image_destroy(*output);
    *output = replacement;
  }
  if (frame != *output) {
    if (frame->w == width && frame->h == height)
      memcpy((*output)->pixels, frame->pixels, (size_t)width * (size_t)height * sizeof(rgb_pixel_t));
    else
      image_resize(frame, *output);
  }
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_MEMORY, image_t::h, height, image_destroy(), image_new(), image_resize(), image_t::pixels, session_capture_ctx::resize_for_network, SESSION_MAX_FRAME_HEIGHT, SESSION_MAX_FRAME_WIDTH, SET_ERRNO, image_t::w, and width.

Referenced by session_capture_process_for_transmission().

session_capture_redraw_media()

void session_capture_redraw_media

(

session_capture_ctx_t *

ctx

)

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

                                                              {
  if (ctx)
    atomic_store_bool(&ctx->redraw_media, true);
}

References session_capture_ctx::redraw_media.

session_capture_set_audio_context()

void session_capture_set_audio_context	(	session_capture_ctx_t *	ctx,
		void *	audio_ctx )

Set the audio context for playback control.

Parameters

ctx	Capture context (must not be NULL)
audio_ctx	Audio context pointer (borrowed, not owned)

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

                                                                                    {
  if (ctx) {
    session_capture_lock_source(ctx);
    atomic_ptr_store(&ctx->audio_ctx, audio_ctx);
    session_capture_unlock_source(ctx);
  }
}

References session_capture_ctx::audio_ctx, session_capture_lock_source(), and session_capture_unlock_source().

Referenced by client_protocol_start(), session_participant_start_audio(), and session_participant_stop_audio().

session_capture_set_audio_updater()

void session_capture_set_audio_updater	(	session_capture_ctx_t *	ctx,
		session_capture_audio_update_fn	update,
		void *	user_data )

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

                                                        {
  if (ctx) {
    ctx->audio_update = update;
    ctx->audio_update_data = user_data;
  }
}

References session_capture_ctx::audio_update, and session_capture_ctx::audio_update_data.

session_capture_skip_media()

void session_capture_skip_media	(	session_capture_ctx_t *	ctx,
		int	direction )

Queue a relative playlist change on the capture owner.

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

                                                                           {
  ASCII_OTEL_SCOPE(SESSION_CAPTURE_SKIP_MEDIA);
  if (ctx && (direction == -1 || direction == 1))
    atomic_store_u64(&ctx->playlist_skip, direction > 0 ? 1 : 2);
}

References ASCII_OTEL_SCOPE, and session_capture_ctx::playlist_skip.

Referenced by session_handle_keyboard_input().

session_capture_source_epoch()

uint64_t session_capture_source_epoch

(

session_capture_ctx_t *

ctx

)

Source identity and successful acquisition count; retained redraws do not advance the serial.

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

                                                                  {
  return ctx ? atomic_load_u64(&ctx->source_epoch) : 0;
}

References session_capture_ctx::source_epoch.

Referenced by session_capture_complete_open(), and session_pipeline_run_main().

session_capture_toggle_media()

void session_capture_toggle_media

(

session_capture_ctx_t *

ctx

)

Request a source change on the capture thread.

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

                                                              {
  if (!ctx || !ctx->source || media_source_get_type(ctx->source) != MEDIA_SOURCE_FILE)
    return;
  // Swap UI preferences in input order so a following animation key applies to
  // the newly selected mode even before the capture thread switches devices.
  ctx->non_media_requested = !ctx->non_media_requested;
  options_set_bool("media_input", !ctx->non_media_requested);
  if (ctx->non_media_requested) {
    options_set_bool("matrix_rain", ctx->saved_matrix);
    options_set_bool("waveform", ctx->saved_waveform);
    options_set_bool("fft", ctx->saved_fft);
  } else {
    ctx->saved_matrix = GET_OPTION(matrix_rain);
    ctx->saved_waveform = GET_OPTION(waveform);
    ctx->saved_fft = GET_OPTION(fft);
    options_set_bool("matrix_rain", false);
    options_set_bool("waveform", false);
    options_set_bool("fft", false);
  }
  atomic_fetch_add_u64(&ctx->toggle_media, 1);
}

References GET_OPTION, MEDIA_SOURCE_FILE, media_source_get_type(), session_capture_ctx::non_media_requested, options_set_bool(), session_capture_ctx::saved_fft, session_capture_ctx::saved_matrix, session_capture_ctx::saved_waveform, session_capture_ctx::source, and session_capture_ctx::toggle_media.

session_capture_unlock_source()

void session_capture_unlock_source

(

session_capture_ctx_t *

ctx

)

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

                                                               {
  if (ctx && ctx->media_locks_ready)
    mutex_unlock(&ctx->source_mutex);
}

References session_capture_ctx::media_locks_ready, and session_capture_ctx::source_mutex.

Referenced by session_capture_read_audio(), session_capture_read_frame(), session_capture_set_audio_context(), and session_handle_keyboard_input().