source.h File Reference

🎬 Unified media source abstraction for webcam, files, and stdin More...

Go to the source code of this file.

Typedefs
typedef struct media_source_t	media_source_t
	Opaque media source handle.

Enumerations
enum	media_source_type_t { MEDIA_SOURCE_WEBCAM , MEDIA_SOURCE_FILE , MEDIA_SOURCE_STDIN , MEDIA_SOURCE_TEST }
	Media source type enumeration. More...

Functions
media_source_t *	media_source_create (media_source_type_t type, const char *path)
	Create a new media source.
void	media_source_destroy (media_source_t *source)
	Destroy media source and free resources.
image_t *	media_source_read_video (media_source_t *source)
	Read next video frame from media source.
bool	media_source_has_video (media_source_t *source)
	Check if media source has video stream.
size_t	media_source_read_audio (media_source_t *source, float *buffer, size_t num_samples)
	Read audio samples from media source.
bool	media_source_has_audio (media_source_t *source)
	Check if media source has audio stream.
void	media_source_set_loop (media_source_t *source, bool loop)
	Enable or disable looping.
void	media_source_pause (media_source_t *source)
	Pause media playback.
void	media_source_resume (media_source_t *source)
	Resume media playback after pause.
bool	media_source_is_paused (media_source_t *source)
	Check if media source is paused.
void	media_source_toggle_pause (media_source_t *source)
	Toggle pause state of media source.
bool	media_source_at_end (media_source_t *source)
	Check if media source reached end of stream.
asciichat_error_t	media_source_rewind (media_source_t *source)
	Rewind media source to beginning.
asciichat_error_t	media_source_seek (media_source_t *source, double timestamp_sec)
	Seek media source to timestamp.
media_source_type_t	media_source_get_type (media_source_t *source)
	Get media source type.
double	media_source_get_duration (media_source_t *source)
	Get media duration in seconds.
double	media_source_get_position (media_source_t *source)
	Get current playback position in seconds.
double	media_source_get_video_fps (media_source_t *source)
	Get video frame rate in frames per second.
void	media_source_set_audio_context (media_source_t *source, void *audio_ctx)
	Set audio context for playback buffer management.
void	media_source_set_exit_callback (media_source_t *source, bool(*should_exit_callback)(void *), void *user_data)
	Set exit signal callback for graceful shutdown during I/O.
bool	media_source_uses_webcam (media_source_t *source)
asciichat_error_t	media_source_start_video (media_source_t *source)
media_source_t *	media_source_create_interruptible (media_source_type_t type, const char *path, bool(*cancel)(void *), void *data)

Detailed Description

🎬 Unified media source abstraction for webcam, files, and stdin

Definition in file source.h.

Function Documentation

media_source_create_interruptible()

media_source_t * media_source_create_interruptible	(	media_source_type_t	type,
		const char *	path,
		bool(*	cancel )(void *),
		void *	data )

Definition at line 225 of file source.c.

                                                              {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_CREATE_INTERRUPTIBLE);
  media_source_t *source = SAFE_MALLOC(sizeof(media_source_t), media_source_t *);
  if (!source) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate media source");
    return NULL;
  }
 
  memset(source, 0, sizeof(*source));
  source->type = type;
  source->loop_enabled = false;
  atomic_store_bool(&source->is_paused, false);
 
  // Initialize mutex for protecting shared decoder access (for YouTube URLs)
  if (mutex_init(&source->decoder_mutex, "media_decoder") != 0) {
    SET_ERRNO(ERROR_MEMORY, "Failed to initialize mutex");
    SAFE_FREE(source);
    return NULL;
  }
 
  switch (type) {
  case MEDIA_SOURCE_WEBCAM: {
    // Parse webcam index from path (if provided)
    unsigned short int index = 0;
    if (path) {
      char *endptr;
      errno = 0;
      long parsed = strtol(path, &endptr, 10);
      if (*endptr == '\0' && errno == 0 && parsed >= 0 && parsed <= USHRT_MAX) {
        index = (unsigned short int)parsed;
      } else if (*endptr != '\0' || errno != 0) {
        log_error("Invalid webcam index: %s", path);
      }
    }
 
    source->webcam_index = index;
    if (GET_OPTION(waveform) || GET_OPTION(fft))
      break;
    asciichat_error_t webcam_error = webcam_init_context(&source->webcam_ctx, index);
    if (webcam_error != ASCIICHAT_OK) {
      asciichat_error_context_t webcam_context;
      bool has_webcam_context = HAS_ERRNO(&webcam_context);
      // Webcam init failed - log and cleanup
      NOTICE(WARNING, "CAMERA UNAVAILABLE", "Failed to initialize webcam device %u: %s", index,
             asciichat_error_format(has_webcam_context ? webcam_context.context_message : NULL, webcam_error));
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
 
      // Add media-level context while preserving the webcam failure as its cause.
      if (webcam_error == ERROR_WEBCAM_IN_USE) {
        SET_ERRNO(ERROR_WEBCAM_IN_USE, "Webcam device %u is in use", index);
      } else {
        SET_ERRNO(ERROR_WEBCAM, "Failed to initialize webcam device %u", index);
      }
      return NULL;
    }
 
    log_debug("Media source: Webcam device %u", index);
    break;
  }
 
  case MEDIA_SOURCE_FILE: {
    asciichat_errno_scope_t media_scope = errno_scope_begin();
    if (!path || path[0] == '\0') {
      SET_ERRNO(ERROR_INVALID_PARAM, "File path is required for FILE source");
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Resolve URL using smart FFmpeg/yt-dlp routing
    const char *effective_path = path;
    char resolved_url[MEDIA_STREAM_URL_SIZE] = {0};
    char resolved_audio_url[MEDIA_STREAM_URL_SIZE] = {0};
    yt_dlp_request_options_t video_request = {0}, audio_request = {0};
    const char *yt_dlp_options = GET_OPTION(yt_dlp_options);
 
    log_debug("Resolving URL: %s", path);
    asciichat_error_t resolve_err =
        media_source_resolve_url(path, yt_dlp_options, resolved_url, sizeof(resolved_url), resolved_audio_url,
                                 sizeof(resolved_audio_url), &video_request, &audio_request, cancel, data);
    if (resolve_err != ASCIICHAT_OK) {
      log_debug("Failed to resolve URL %s", asciichat_error_format(NULL, resolve_err));
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
    if (cancel && cancel(data)) {
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
    effective_path = resolved_url;
    log_debug("Using resolved URL for playback");
 
    // Store original URL for potential re-extraction if needed
    source->original_youtube_url = platform_strdup(path);
    if (!source->original_youtube_url) {
      log_warn("Failed to cache original URL");
    }
 
    // Cache file path for potential reopen on loop
    source->file_path = platform_strdup(effective_path);
    if (!source->file_path) {
      SET_ERRNO(ERROR_MEMORY, "Failed to duplicate file path");
      SAFE_FREE(source->original_youtube_url);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Always use separate decoders for video and audio
    // This allows independent read rates and avoids lock contention
    asciichat_errno_scope_t decoder_scope = errno_checkpoint();
    source->video_decoder = ffmpeg_decoder_create_with_request_options(
        effective_path, cancel, data, video_request.headers, video_request.cookies,
        video_request.proxy_specified ? video_request.proxy : NULL);
    if (!source->video_decoder) {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Media initialization failed: video decoder could not open input");
      if (!cancel)
        NOTICE(WARNING, "MEDIA COULD NOT BE OPENED", "Failed to open media file for video: %s: %s", effective_path,
               asciichat_error_format(NULL, ERROR_MEDIA_OPEN));
      LOG_ERRNO_IF_SET("Media initialization failed");
      SAFE_FREE(source->file_path);
      SAFE_FREE(source->original_youtube_url);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    ASSERT_NO_ERRNO_SINCE(decoder_scope);
 
    decoder_scope = errno_checkpoint();
    const char *audio_path = resolved_audio_url[0] ? resolved_audio_url : effective_path;
    const yt_dlp_request_options_t *audio_settings = resolved_audio_url[0] ? &audio_request : &video_request;
    source->audio_decoder = ffmpeg_decoder_create_with_request_options(
        audio_path, cancel, data, audio_settings->headers, audio_settings->cookies,
        audio_settings->proxy_specified ? audio_settings->proxy : NULL);
    if (!source->audio_decoder) {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Media initialization failed: audio decoder could not open input");
      LOG_ERRNO_IF_SET("Media initialization failed");
      ffmpeg_decoder_destroy(source->video_decoder);
      source->video_decoder = NULL;
      SAFE_FREE(source->file_path);
      SAFE_FREE(source->original_youtube_url);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
    source->is_shared_decoder = false;
 
    ASSERT_NO_ERRNO_SINCE(decoder_scope);
    // yt-dlp emits selected formats in selector order, which may be audio first.
    if (resolved_audio_url[0] && !ffmpeg_decoder_has_video(source->video_decoder) &&
        ffmpeg_decoder_has_video(source->audio_decoder) && ffmpeg_decoder_has_audio(source->video_decoder)) {
      ffmpeg_decoder_t *audio = source->video_decoder;
      source->video_decoder = source->audio_decoder;
      source->audio_decoder = audio;
    }
 
    // Start prefetch after choosing the decoder that actually contains video.
    asciichat_errno_scope_t prefetch_scope = errno_scope_begin();
    asciichat_error_t prefetch_err = ffmpeg_decoder_has_video(source->video_decoder)
                                         ? ffmpeg_decoder_start_prefetch(source->video_decoder)
                                         : ASCIICHAT_OK;
    if (prefetch_err != ASCIICHAT_OK) {
      log_error("Failed to start video prefetch thread: %s", asciichat_error_format(NULL, prefetch_err));
      ffmpeg_decoder_destroy(source->video_decoder);
      ffmpeg_decoder_destroy(source->audio_decoder);
      SAFE_FREE(source->file_path);
      SAFE_FREE(source->original_youtube_url);
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
    ASSERT_NO_ERRNO_SINCE(prefetch_scope);
    errno_scope_end(prefetch_scope, ASCIICHAT_ERRNO_HANDLED);
    // Both decoders succeeded: failed extraction/prefetch attempts are resolved.
    errno_scope_end(media_scope, ASCIICHAT_ERRNO_DISMISSED);
    ASSERT_NO_ERRNO_SINCE(media_scope);
    log_debug("Media source: URL resolved to stream (separate video/audio decoders)");
    break;
  }
 
  case MEDIA_SOURCE_STDIN: {
    // Create separate decoders for video and audio from stdin
    source->video_decoder = ffmpeg_decoder_create_stdin();
    if (!source->video_decoder) {
      log_error("Failed to open stdin for video input");
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Start prefetch thread for stdin video frames
    asciichat_errno_scope_t prefetch_scope = errno_scope_begin();
    asciichat_error_t prefetch_err = ffmpeg_decoder_has_video(source->video_decoder)
                                         ? ffmpeg_decoder_start_prefetch(source->video_decoder)
                                         : ASCIICHAT_OK;
    if (prefetch_err != ASCIICHAT_OK) {
      log_error("Failed to start stdin video prefetch thread: %s", asciichat_error_format(NULL, prefetch_err));
      ffmpeg_decoder_destroy(source->video_decoder);
      SAFE_FREE(source->file_path);
      SAFE_FREE(source->original_youtube_url);
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    ASSERT_NO_ERRNO_SINCE(prefetch_scope);
    errno_scope_end(prefetch_scope, ASCIICHAT_ERRNO_HANDLED);
    source->audio_decoder = ffmpeg_decoder_create_stdin();
    if (!source->audio_decoder) {
      log_error("Failed to open stdin for audio input");
      ffmpeg_decoder_destroy(source->video_decoder);
      source->video_decoder = NULL;
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    log_debug("Media source: stdin (separate video/audio decoders)");
    break;
  }
 
  case MEDIA_SOURCE_TEST: {
    // Test pattern state is encapsulated in media_source_t
    source->webcam_index = 0;
    source->webcam_ctx = NULL; // No context needed for test pattern
    source->test_pattern = NULL;
    source->test_start_ns = 0;
 
    log_debug("Media source: Test pattern");
    break;
  }
 
  default:
    SET_ERRNO(ERROR_INVALID_PARAM, "Unknown media source type: %d", type);
    // Destroy mutexes before freeing source
    mutex_destroy(&source->decoder_mutex);
    SAFE_FREE(source);
    return NULL;
  }
 
  if ((type == MEDIA_SOURCE_FILE || type == MEDIA_SOURCE_STDIN) && !ffmpeg_decoder_has_video(source->video_decoder) &&
      ffmpeg_decoder_has_audio(source->audio_decoder)) {
    source->audio_only = true;
  }
 
  /* Register media source with named registry */
  char media_type_str[MEDIA_SOURCE_MEDIA_TYPE_BUFFER_SIZE];
  switch (type) {
  case MEDIA_SOURCE_WEBCAM:
    snprintf(media_type_str, sizeof(media_type_str), "media_source:webcam");
    break;
  case MEDIA_SOURCE_FILE:
    snprintf(media_type_str, sizeof(media_type_str), "media_source:file");
    break;
  case MEDIA_SOURCE_TEST:
    snprintf(media_type_str, sizeof(media_type_str), "media_source:test");
    break;
  default:
    snprintf(media_type_str, sizeof(media_type_str), "media_source:unknown");
    break;
  }
  NAMED_REGISTER(source, media_type_str, "media_source_t", "0x%tx", NULL);
 
  /* Register media source's sync primitives with hierarchical naming */
  NAMED_REGISTER_MUTEX(&source->decoder_mutex, "decoder_mutex", (uintptr_t)(const void *)(source));
  NAMED_REGISTER_ATOMIC(&source->is_paused, "media_paused", source);
 
  return source;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_ERRNO_DISMISSED, ASCIICHAT_ERRNO_HANDLED, asciichat_error_format(), ASCIICHAT_OK, ASSERT_NO_ERRNO_SINCE, asciichat_error_context_t::context_message, yt_dlp_request_options_t::cookies, errno, errno_checkpoint(), errno_scope_begin(), errno_scope_end(), ERROR_INVALID_PARAM, ERROR_MEDIA_OPEN, ERROR_MEMORY, ERROR_WEBCAM, ERROR_WEBCAM_IN_USE, ffmpeg_decoder_create_stdin(), ffmpeg_decoder_create_with_request_options(), ffmpeg_decoder_destroy(), ffmpeg_decoder_has_audio(), ffmpeg_decoder_has_video(), ffmpeg_decoder_start_prefetch(), GET_OPTION, HAS_ERRNO, yt_dlp_request_options_t::headers, index, log_debug, LOG_ERRNO_IF_SET, log_error, log_warn, MEDIA_SOURCE_FILE, MEDIA_SOURCE_MEDIA_TYPE_BUFFER_SIZE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, MEDIA_STREAM_URL_SIZE, NAMED_REGISTER, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_MUTEX, NOTICE, yt_dlp_request_options_t::proxy, yt_dlp_request_options_t::proxy_specified, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, source, and webcam_init_context().

Referenced by media_source_create(), and session_capture_create().

media_source_start_video()

asciichat_error_t media_source_start_video

(

media_source_t *

source

)

Definition at line 571 of file source.c.

                                                                   {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_START_VIDEO);
  if (!source)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing media source");
  if ((!source->audio_only && source->type != MEDIA_SOURCE_WEBCAM) || source->webcam_ctx || GET_OPTION(test_pattern) ||
      GET_OPTION(waveform) || GET_OPTION(fft))
    return ASCIICHAT_OK;
  if (source->type != MEDIA_SOURCE_WEBCAM)
    source->webcam_index = GET_OPTION(webcam_index);
  asciichat_error_t err = webcam_init_context(&source->webcam_ctx, source->webcam_index);
  if (err != ASCIICHAT_OK)
    return SET_ERRNO(err, "Audio-only media requires webcam %u", source->webcam_index);
  log_info("Audio-only media: using webcam %u for video", source->webcam_index);
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ERROR_INVALID_PARAM, GET_OPTION, log_info, MEDIA_SOURCE_WEBCAM, SET_ERRNO, source, and webcam_init_context().

Referenced by media_source_read_video(), and session_capture_create().

media_source_uses_webcam()

bool media_source_uses_webcam

(

media_source_t *

source

)

Definition at line 587 of file source.c.

                                                      {
  return source && ((source->type == MEDIA_SOURCE_WEBCAM && !GET_OPTION(waveform) && !GET_OPTION(fft)) ||
                    (source->audio_only && !GET_OPTION(test_pattern) && !GET_OPTION(waveform) && !GET_OPTION(fft)));
}

References GET_OPTION, MEDIA_SOURCE_WEBCAM, and source.