Media

Files
file	ffmpeg_encoder.c
	FFmpeg video/image file encoder for render-file output.
file	renderer.c
	render_file_* — ties together font resolution, platform renderer, FFmpeg encoder
file	terminal.c
	Pixel renderer for render-file: libvterm + FreeType2 software compositor.
file	yt_dlp.c
	yt-dlp stream URL extraction implementation
file	codecs.h
	Video and audio codec definitions and capability bitmasks.
file	ffmpeg_decoder.h
	🎞️ FFmpeg-based media decoder for video and audio streams
file	ffmpeg_encoder.h
	FFmpeg video/image file encoder — codec selected from file extension.
file	renderer.h
	Terminal-to-pixel renderer and render-file output (audio + video)
file	source.h
	🎬 Unified media source abstraction for webcam, files, and stdin
file	yt_dlp.h
	yt-dlp stream URL extraction

Typedefs
typedef struct ffmpeg_decoder_t	ffmpeg_decoder_t
	Opaque FFmpeg decoder handle.
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
ffmpeg_decoder_t *	ffmpeg_decoder_create (const char *path)
	Create FFmpeg decoder from file path.
ffmpeg_decoder_t *	ffmpeg_decoder_create_stdin (void)
	Create FFmpeg decoder from stdin.
void	ffmpeg_decoder_destroy (ffmpeg_decoder_t *decoder)
	Destroy FFmpeg decoder and free resources.
asciichat_error_t	ffmpeg_decoder_start_prefetch (ffmpeg_decoder_t *decoder)
	Start background frame prefetching thread.
void	ffmpeg_decoder_stop_prefetch (ffmpeg_decoder_t *decoder)
	Stop background frame prefetching thread.
void	ffmpeg_decoder_set_exit_callback (ffmpeg_decoder_t *decoder, bool(*should_exit_callback)(void *), void *user_data)
	Set exit signal callback for graceful shutdown during I/O.
bool	ffmpeg_decoder_is_prefetch_running (ffmpeg_decoder_t *decoder)
	Check if background frame prefetching thread is running.
image_t *	ffmpeg_decoder_read_video_frame (ffmpeg_decoder_t *decoder)
	Decode next video frame.
bool	ffmpeg_decoder_has_video (ffmpeg_decoder_t *decoder)
	Check if decoder has video stream.
asciichat_error_t	ffmpeg_decoder_get_video_dimensions (ffmpeg_decoder_t *decoder, int *width, int *height)
	Get video dimensions.
double	ffmpeg_decoder_get_video_fps (ffmpeg_decoder_t *decoder)
	Get video frame rate.
size_t	ffmpeg_decoder_read_audio_samples (ffmpeg_decoder_t *decoder, float *buffer, size_t num_samples)
	Decode audio samples.
bool	ffmpeg_decoder_has_audio (ffmpeg_decoder_t *decoder)
	Check if decoder has audio stream.
asciichat_error_t	ffmpeg_decoder_rewind (ffmpeg_decoder_t *decoder)
	Seek to beginning of media.
asciichat_error_t	ffmpeg_decoder_seek_to_timestamp (ffmpeg_decoder_t *decoder, double timestamp_sec)
	Seek to specific timestamp in media.
bool	ffmpeg_decoder_at_end (ffmpeg_decoder_t *decoder)
	Check if decoder reached end of stream.
double	ffmpeg_decoder_get_duration (ffmpeg_decoder_t *decoder)
	Get media duration in seconds.
double	ffmpeg_decoder_get_position (ffmpeg_decoder_t *decoder)
	Get current playback position in seconds.
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.
asciichat_error_t	yt_dlp_extract_stream_url (const char *url, const char *yt_dlp_options, char *output_url, size_t output_size)
	Extract stream URL using yt-dlp with optional parameters.
bool	yt_dlp_is_available (void)
	Check if yt-dlp is installed and accessible.

Video Codec Bitmask Constants
Bitmasks for video codec capabilities Each codec is represented by a single bit, allowing multiple codecs to be advertised simultaneously in the codec_capabilities_video field.
#define	VIDEO_CODEC_CAP_ALL   (VIDEO_CODEC_CAP_RGBA | VIDEO_CODEC_CAP_H265 | VIDEO_CODEC_CAP_JPEG)
	Default video codec capabilities (all codecs supported)

Audio Codec Bitmask Constants
Bitmasks for audio codec capabilities Each codec is represented by a single bit, allowing multiple codecs to be advertised simultaneously in the codec_capabilities_audio field.
#define	AUDIO_CODEC_CAP_ALL   (AUDIO_CODEC_CAP_RAW | AUDIO_CODEC_CAP_OPUS)
	Default audio codec capabilities (all codecs supported)
#define	VIDEO_CODEC_SUPPORTED(cap, codec)   (((cap) & (1 << (codec))) != 0)
	Check if a video codec is supported in capabilities bitmask.
#define	AUDIO_CODEC_SUPPORTED(cap, codec)   (((cap) & (1 << (codec))) != 0)
	Check if an audio codec is supported in capabilities bitmask.

Detailed Description

This header provides FFmpeg integration for decoding various media formats. It wraps FFmpeg's complex API into a simple interface for extracting RGB video frames and float audio samples.

CORE FEATURES:

• Multi-format container support (mp4, avi, mkv, webm, etc.)
• Video decoding to RGB24 format
• Audio decoding to 48kHz mono float
• Stdin input support via custom AVIOContext
• Seeking for loop support
• Automatic stream detection

FFMPEG LIBRARIES USED:

• libavformat: Container demuxing
• libavcodec: Video/audio codec decoding
• libavutil: Utilities and error handling
• libswscale: Video format conversion (YUV -> RGB)
• libswresample: Audio resampling (any rate -> 48kHz mono)

SUPPORTED CODECS:

• Video: H.264, H.265, VP8, VP9, AV1, MPEG-4, etc.
• Audio: AAC, MP3, Opus, Vorbis, FLAC, PCM, etc.
• Containers: MP4, AVI, MKV, WebM, MOV, FLV, GIF, etc.

Author

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

Date

January 2026

This header provides a unified interface for media sources in ascii-chat, abstracting over webcams, media files, and stdin input. This allows the capture thread to work with any media source transparently.

CORE FEATURES:

• Unified API for webcam, files, and stdin
• FFmpeg-based decoding for all common formats
• Video frame extraction (RGB format)
• Audio sample extraction (48kHz float mono)
• Loop support for file playback
• Automatic format detection

SUPPORTED SOURCES:

• MEDIA_SOURCE_WEBCAM: Hardware webcam device
• MEDIA_SOURCE_FILE: Media file (mp4, avi, mkv, gif, mp3, etc.)
• MEDIA_SOURCE_STDIN: Piped or redirected media data
• MEDIA_SOURCE_TEST: Test pattern (existing)

SUPPORTED FORMATS:

• Video: mp4, avi, mkv, webm, mov, flv, wmv, gif (animated)
• Audio: mp3, aac, opus, flac, wav, ogg, m4a
• Images: gif, png, jpg (static - single frame)

USAGE:

// Create media source from file
media_source_t *source = media_source_create(MEDIA_SOURCE_FILE, "video.mp4");
media_source_set_loop(source, true);
 
// Read video frames
while (!done) {
    image_t *frame = media_source_read_video(source);
    if (!frame) {
        if (media_source_at_end(source)) break;
        continue; // Error, try next frame
    }
    // Process frame...
}
 
// Read audio samples
float buffer[480];
size_t samples = media_source_read_audio(source, buffer, 480);
 
// Cleanup
media_source_destroy(source);

Author

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

Date

January 2026

Macro Definition Documentation

AUDIO_CODEC_CAP_ALL

#define AUDIO_CODEC_CAP_ALL   (AUDIO_CODEC_CAP_RAW | AUDIO_CODEC_CAP_OPUS)

#include <codecs.h>

Default audio codec capabilities (all codecs supported)

Definition at line 77 of file codecs.h.

AUDIO_CODEC_SUPPORTED

#define AUDIO_CODEC_SUPPORTED	(		cap,
			codec
	)		(((cap) & (1 << (codec))) != 0)

#include <codecs.h>

Check if an audio codec is supported in capabilities bitmask.

Parameters

cap	Codec capabilities bitmask (AUDIO_CODEC_CAP_*)
codec	Codec type to check (audio_codec_t)

Returns

true if codec is supported, false otherwise

Definition at line 95 of file codecs.h.

VIDEO_CODEC_CAP_ALL

#define VIDEO_CODEC_CAP_ALL   (VIDEO_CODEC_CAP_RGBA | VIDEO_CODEC_CAP_H265 | VIDEO_CODEC_CAP_JPEG)

#include <codecs.h>

Default video codec capabilities (all codecs supported)

Definition at line 50 of file codecs.h.

VIDEO_CODEC_SUPPORTED

#define VIDEO_CODEC_SUPPORTED	(		cap,
			codec
	)		(((cap) & (1 << (codec))) != 0)

#include <codecs.h>

Check if a video codec is supported in capabilities bitmask.

Parameters

cap	Codec capabilities bitmask (VIDEO_CODEC_CAP_*)
codec	Codec type to check (video_codec_t)

Returns

true if codec is supported, false otherwise

Definition at line 86 of file codecs.h.

Typedef Documentation

ffmpeg_decoder_t

typedef struct ffmpeg_decoder_t ffmpeg_decoder_t

#include <ffmpeg_decoder.h>

Opaque FFmpeg decoder handle.

Forward declaration of FFmpeg decoder structure. Use ffmpeg_decoder_create() to create and ffmpeg_decoder_destroy() to cleanup.

Definition at line 58 of file ffmpeg_decoder.h.

media_source_t

typedef struct media_source_t media_source_t

#include <source.h>

Opaque media source handle.

Forward declaration of media source structure. Use media_source_create() to create and media_source_destroy() to cleanup.

THREAD SAFETY:

• media_source_read_video() and media_source_read_audio() may be called from different threads (e.g., video render thread + audio callback thread)
• Both operations access the shared FFmpeg decoder
• FFmpeg decoders are NOT thread-safe for concurrent operations
• media_source_t uses internal synchronization to protect decoder access
• Callers do NOT need external locking

Definition at line 105 of file source.h.

Enumeration Type Documentation

media_source_type_t

enum media_source_type_t

#include <source.h>

Media source type enumeration.

Identifies the type of media source being used.

Enumerator
MEDIA_SOURCE_WEBCAM	Hardware webcam device.
MEDIA_SOURCE_FILE	Media file (video/audio)
MEDIA_SOURCE_STDIN	Piped or redirected input.
MEDIA_SOURCE_TEST	Test pattern generator.

Definition at line 81 of file source.h.

             {
  MEDIA_SOURCE_WEBCAM, 
  MEDIA_SOURCE_FILE,   
  MEDIA_SOURCE_STDIN,  
  MEDIA_SOURCE_TEST    
} media_source_type_t;

Function Documentation

ffmpeg_decoder_at_end()

bool ffmpeg_decoder_at_end

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Check if decoder reached end of stream.

Parameters

decoder

Decoder (must not be NULL)

Returns

true if EOF reached, false otherwise

Definition at line 1593 of file media/ffmpeg_decoder.c.

                                                      {
  return decoder && decoder->eof_reached;
}

References ffmpeg_decoder_t::eof_reached.

Referenced by media_source_at_end(), media_source_read_audio(), and media_source_read_video().

ffmpeg_decoder_create()

ffmpeg_decoder_t * ffmpeg_decoder_create

(

const char *

path

)

#include <ffmpeg_decoder.h>

Create FFmpeg decoder from file path.

Parameters

path	File path to media file (must not be NULL)

Returns

Pointer to decoder, or NULL on failure

Creates and initializes an FFmpeg decoder for the specified file. Opens the file, detects streams, and initializes codecs.

Initialization process:

1. Open format context (avformat_open_input)
2. Find stream information (avformat_find_stream_info)
3. Detect video and audio streams
4. Open codec contexts for detected streams
5. Initialize swscale/swresample contexts

Note

Sets errno context on failure

Call ffmpeg_decoder_destroy() to cleanup

Definition at line 627 of file media/ffmpeg_decoder.c.

                                                          {
  if (!path) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Path is NULL");
    return NULL;
  }
 
  // Suppress FFmpeg's verbose debug logging (H.264 codec warnings, etc.)
  // Only set this once, it's a global setting
  static bool ffmpeg_log_level_set = false;
  if (!ffmpeg_log_level_set) {
    av_log_set_level(AV_LOG_QUIET);                  // Suppress all FFmpeg logging
    av_log_set_callback(ffmpeg_silent_log_callback); // Install silent callback to discard all output
    ffmpeg_log_level_set = true;
  }
 
  ffmpeg_decoder_t *decoder = SAFE_MALLOC(sizeof(ffmpeg_decoder_t), ffmpeg_decoder_t *);
  if (!decoder) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate decoder");
    return NULL;
  }
 
  memset(decoder, 0, sizeof(*decoder));
  decoder->video_stream_idx = -1;
  decoder->audio_stream_idx = -1;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
 
  // Capture FFmpeg's probing output (FFmpeg may write directly to either stream)
  int ret = 0;
  LOG_IO("ffmpeg", {
    // Configure FFmpeg options for HTTP streaming performance
    AVDictionary *options = NULL;
 
    // For HTTP/HTTPS streams: enable fast probing and reconnection (validated via production-grade URL regex)
    if (path && url_is_valid(path)) {
      // Limit probing to 32KB for faster format detection
      av_dict_set(&options, "probesize", "32768", 0);
      // Analyze for 100ms max to determine streams quickly
      av_dict_set(&options, "analyzeduration", "100000", 0);
      // Enable auto-reconnection for interrupted connections
      av_dict_set(&options, "reconnect", "1", 0);
      // Allow reconnection for streamed protocols
      av_dict_set(&options, "reconnect_streamed", "1", 0);
      // Set reasonable I/O timeout (10 seconds)
      av_dict_set(&options, "rw_timeout", "10000000", 0);
      // Enable HTTP persistent connection (keep-alive) for better performance
      av_dict_set(&options, "http_persistent", "1", 0);
      // Reduce connect timeout to fail faster if server is unreachable
      av_dict_set(&options, "connect_timeout", "5000000", 0);
    }
 
    // Open input file
    ret = avformat_open_input(&decoder->format_ctx, path, NULL, &options);
    av_dict_free(&options); // Free options dictionary
 
    if (ret >= 0) {
      // Find stream info
      if (avformat_find_stream_info(decoder->format_ctx, NULL) < 0) {
        ret = -1;
      }
    }
  });
 
  if (ret < 0) {
    if (ret == -1) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to find stream info");
    } else {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to open media file: %s", path);
    }
    if (decoder->format_ctx) {
      avformat_close_input(&decoder->format_ctx);
    }
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Install interrupt callback to allow seeking to interrupt long av_read_frame() calls
  // Do this AFTER finding stream info to ensure format context is fully initialized
  if (decoder->format_ctx) {
    decoder->format_ctx->interrupt_callback.callback = ffmpeg_interrupt_callback;
    decoder->format_ctx->interrupt_callback.opaque = decoder;
  }
 
  // Open video codec
  asciichat_error_t err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_VIDEO, &decoder->video_stream_idx,
                                             &decoder->video_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_warn("Failed to open video codec (file may be audio-only)");
  }
 
  // Open audio codec - audio is enabled by default (no option needed)
  // Always try to open audio codec, don't rely on GET_OPTION(audio_enabled) which has a default issue
  err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_AUDIO, &decoder->audio_stream_idx,
                           &decoder->audio_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_debug("No audio codec found (file may be video-only or audio codec not available)");
    decoder->audio_stream_idx = -1;
    decoder->audio_codec_ctx = NULL;
  }
 
  // Require at least one stream
  if (decoder->video_stream_idx < 0 && decoder->audio_stream_idx < 0) {
    SET_ERRNO(ERROR_MEDIA_DECODE, "No video or audio streams found");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Allocate frame and packet
  decoder->frame = av_frame_alloc();
  decoder->packet = av_packet_alloc();
  if (!decoder->frame || !decoder->packet) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Initialize swscale context for video if present
  if (decoder->video_codec_ctx) {
    // Validate codec context has valid dimensions and pixel format
    // For HTTP streams, these might not be valid until first frame is read
    if (decoder->video_codec_ctx->width <= 0 || decoder->video_codec_ctx->height <= 0) {
      log_warn("Video codec has invalid dimensions (%dx%d), will initialize swscale on first frame",
               decoder->video_codec_ctx->width, decoder->video_codec_ctx->height);
      // Don't create swscale context yet - will create it lazily on first frame read
    } else if (decoder->video_codec_ctx->pix_fmt == AV_PIX_FMT_NONE) {
      log_warn("Video codec has invalid pixel format, will initialize swscale on first frame");
      // Don't create swscale context yet - will create it lazily on first frame read
    } else {
      // Create swscale context with valid parameters
      LOG_IO("swscaler", {
        decoder->sws_ctx =
            sws_getContext(decoder->video_codec_ctx->width, decoder->video_codec_ctx->height,
                           decoder->video_codec_ctx->pix_fmt, decoder->video_codec_ctx->width,
                           decoder->video_codec_ctx->height, AV_PIX_FMT_RGB24, SWS_BILINEAR, NULL, NULL, NULL);
      });
      if (!decoder->sws_ctx) {
        SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to create swscale context");
        ffmpeg_decoder_destroy(decoder);
        return NULL;
      }
    }
  }
 
  // Initialize swresample context for audio if present
  if (decoder->audio_codec_ctx) {
    // Store output sample rate for position tracking
    decoder->audio_sample_rate = TARGET_SAMPLE_RATE;
 
    // Allocate resampler context
    decoder->swr_ctx = swr_alloc();
    if (!decoder->swr_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    // Set options
    av_opt_set_chlayout(decoder->swr_ctx, "in_chlayout", &decoder->audio_codec_ctx->ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "in_sample_rate", decoder->audio_codec_ctx->sample_rate, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "in_sample_fmt", decoder->audio_codec_ctx->sample_fmt, 0);
 
    AVChannelLayout out_ch_layout = AV_CHANNEL_LAYOUT_MONO;
    av_opt_set_chlayout(decoder->swr_ctx, "out_chlayout", &out_ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "out_sample_rate", TARGET_SAMPLE_RATE, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "out_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
 
    // Initialize
    if (swr_init(decoder->swr_ctx) < 0) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to initialize swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    // Allocate audio buffer (10 seconds worth)
    decoder->audio_buffer_size = TARGET_SAMPLE_RATE * 10;
    decoder->audio_buffer = SAFE_MALLOC(decoder->audio_buffer_size * sizeof(float), float *);
    if (!decoder->audio_buffer) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio buffer");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  // Initialize video frame prefetching system (for YouTube streaming)
  if (decoder->video_stream_idx >= 0) {
    int width = decoder->video_codec_ctx->width;
    int height = decoder->video_codec_ctx->height;
 
    // Create two prefetch image buffers for double-buffering
    decoder->prefetch_image_a = image_new((size_t)width, (size_t)height);
    decoder->prefetch_image_b = image_new((size_t)width, (size_t)height);
    if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate prefetch image buffers");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->current_prefetch_image = decoder->prefetch_image_a;
    decoder->prefetch_frame_ready = false;
 
    // Initialize prefetch mutex
    if (mutex_init(&decoder->prefetch_mutex, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch mutex");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (cond_init(&decoder->prefetch_cond, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch condition variable");
      mutex_destroy(&decoder->prefetch_mutex);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (mutex_init(&decoder->read_frame_mutex, "ffmpeg_read_frame") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize read_frame mutex");
      mutex_destroy(&decoder->prefetch_mutex);
      cond_destroy(&decoder->prefetch_cond);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->prefetch_thread_running = false;
    decoder->prefetch_should_stop = false;
  }
 
  log_debug("FFmpeg decoder opened: %s (video=%s, audio=%s)", path, decoder->video_stream_idx >= 0 ? "yes" : "no",
            decoder->audio_stream_idx >= 0 ? "yes" : "no");
 
  char decoder_name[256];
  snprintf(decoder_name, sizeof(decoder_name), "%s", path);
  NAMED_REGISTER_FFMPEG_DECODER(decoder, decoder_name, NULL);
 
  return decoder;
}

References ASCIICHAT_OK, ffmpeg_decoder_t::audio_buffer, ffmpeg_decoder_t::audio_buffer_size, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::audio_sample_rate, ffmpeg_decoder_t::audio_stream_idx, cond_destroy(), cond_init(), ffmpeg_decoder_t::current_prefetch_image, ERROR_INVALID_PARAM, ERROR_MEDIA_DECODE, ERROR_MEDIA_OPEN, ERROR_MEMORY, ffmpeg_decoder_destroy(), ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::frame, image_new(), ffmpeg_decoder_t::last_audio_pts, ffmpeg_decoder_t::last_video_pts, log_debug, LOG_IO, log_warn, mutex_destroy(), mutex_init(), NAMED_REGISTER_FFMPEG_DECODER, ffmpeg_decoder_t::packet, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_mutex, ffmpeg_decoder_t::prefetch_should_stop, ffmpeg_decoder_t::prefetch_thread_running, ffmpeg_decoder_t::read_frame_mutex, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, ffmpeg_decoder_t::swr_ctx, ffmpeg_decoder_t::sws_ctx, TARGET_SAMPLE_RATE, url_is_valid(), ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_create().

ffmpeg_decoder_create_stdin()

ffmpeg_decoder_t * ffmpeg_decoder_create_stdin

(

void

)

#include <ffmpeg_decoder.h>

Create FFmpeg decoder from stdin.

Returns

Pointer to decoder, or NULL on failure

Creates an FFmpeg decoder that reads from stdin using a custom AVIOContext. This allows piping media data directly into ascii-chat.

Usage:

cat video.mp4 | ascii-chat client --file -
ffmpeg -i input.avi -f matroska - | ascii-chat client --file -

Limitations:

• Cannot seek (no loop support)
• Some formats may not work well with stdin (require seekable input)
• Recommend using formats designed for streaming (matroska, mpegts)

Note

Sets errno context on failure

Call ffmpeg_decoder_destroy() to cleanup

Definition at line 863 of file media/ffmpeg_decoder.c.

                                                    {
  // Buffer entire stdin on first call (shared between video and audio decoders)
  if (!g_stdin_buffer) {
    log_debug("Reading stdin into buffer...");
    g_stdin_buffer = stdin_buffer_read_all();
    if (!g_stdin_buffer) {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to read stdin into buffer");
      return NULL;
    }
  }
 
  ffmpeg_decoder_t *decoder = SAFE_MALLOC(sizeof(ffmpeg_decoder_t), ffmpeg_decoder_t *);
  if (!decoder) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate decoder");
    return NULL;
  }
 
  memset(decoder, 0, sizeof(*decoder));
  decoder->video_stream_idx = -1;
  decoder->audio_stream_idx = -1;
  decoder->is_stdin = true;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
 
  // Create per-decoder reader (each decoder gets independent position tracking)
  stdin_buffer_reader_t *reader = SAFE_MALLOC(sizeof(stdin_buffer_reader_t), stdin_buffer_reader_t *);
  if (!reader) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer reader");
    SAFE_FREE(decoder);
    return NULL;
  }
  reader->buffer = g_stdin_buffer;
  reader->pos = 0; // Each decoder starts from position 0
 
  // AVIO takes ownership of this buffer and may resize or free it with av_free().
  decoder->avio_buffer = av_malloc(AVIO_BUFFER_SIZE);
  if (!decoder->avio_buffer) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate AVIO buffer");
    SAFE_FREE(reader);
    SAFE_FREE(decoder);
    return NULL;
  }
 
  decoder->avio_ctx = avio_alloc_context(decoder->avio_buffer, // internal buffer for AVIO
                                         AVIO_BUFFER_SIZE,     // buffer size
                                         0,                    // write_flag
                                         reader,               // opaque (per-decoder reader)
                                         memory_read_packet,
                                         NULL,              // write_packet
                                         memory_seek_packet // seek (memory is seekable)
  );
 
  if (!decoder->avio_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to create AVIO context");
    av_free(decoder->avio_buffer);
    decoder->avio_buffer = NULL;
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Mark AVIO context as seekable (memory buffer supports seeking)
  decoder->avio_ctx->seekable = AVIO_SEEKABLE_NORMAL;
 
  // Allocate format context
  decoder->format_ctx = avformat_alloc_context();
  if (!decoder->format_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate format context");
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
    SAFE_FREE(decoder);
    return NULL;
  }
 
  decoder->format_ctx->pb = decoder->avio_ctx;
  decoder->format_ctx->flags |= AVFMT_FLAG_CUSTOM_IO; // Tell FFmpeg to use our custom AVIO context
 
  // Capture FFmpeg's probing output
  int ret = 0;
  LOG_IO("ffmpeg", {
    // Open input from buffered stdin
    ret = avformat_open_input(&decoder->format_ctx, NULL, NULL, NULL);
    if (ret >= 0) {
      // Find stream info
      if (avformat_find_stream_info(decoder->format_ctx, NULL) < 0) {
        ret = -1;
      }
    }
  });
 
  if (ret < 0) {
    if (ret == -1) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to find stream info from stdin buffer");
    } else {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to open stdin buffer");
    }
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
    if (decoder->format_ctx) {
      avformat_free_context(decoder->format_ctx);
    }
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Open codecs (same as file-based decoder)
  asciichat_error_t err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_VIDEO, &decoder->video_stream_idx,
                                             &decoder->video_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_warn("Failed to open video codec from stdin");
  }
 
  if (GET_OPTION(audio_enabled)) {
    err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_AUDIO, &decoder->audio_stream_idx,
                             &decoder->audio_codec_ctx);
    if (err != ASCIICHAT_OK) {
      log_warn("Failed to open audio codec from stdin");
    }
  } else {
    decoder->audio_stream_idx = -1;
    decoder->audio_codec_ctx = NULL;
    log_debug("Audio decoding disabled by user option");
  }
 
  if (decoder->video_stream_idx < 0 && decoder->audio_stream_idx < 0) {
    SET_ERRNO(ERROR_MEDIA_DECODE, "No video or audio streams found in stdin");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Allocate frame and packet
  decoder->frame = av_frame_alloc();
  decoder->packet = av_packet_alloc();
  if (!decoder->frame || !decoder->packet) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Initialize swscale/swresample (same as file-based)
  if (decoder->video_codec_ctx) {
    // Validate codec context has valid dimensions and pixel format
    // For stdin/HTTP streams, these might not be valid until first frame is read
    if (decoder->video_codec_ctx->width <= 0 || decoder->video_codec_ctx->height <= 0) {
      log_warn("Video codec has invalid dimensions (%dx%d), will initialize swscale on first frame",
               decoder->video_codec_ctx->width, decoder->video_codec_ctx->height);
      // Don't create swscale context yet - will create it lazily on first frame read
    } else if (decoder->video_codec_ctx->pix_fmt == AV_PIX_FMT_NONE) {
      log_warn("Video codec has invalid pixel format, will initialize swscale on first frame");
      // Don't create swscale context yet - will create it lazily on first frame read
    } else {
      // Create swscale context with valid parameters
      LOG_IO("swscaler", {
        decoder->sws_ctx =
            sws_getContext(decoder->video_codec_ctx->width, decoder->video_codec_ctx->height,
                           decoder->video_codec_ctx->pix_fmt, decoder->video_codec_ctx->width,
                           decoder->video_codec_ctx->height, AV_PIX_FMT_RGB24, SWS_BILINEAR, NULL, NULL, NULL);
      });
      if (!decoder->sws_ctx) {
        SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to create swscale context");
        ffmpeg_decoder_destroy(decoder);
        return NULL;
      }
    }
  }
 
  if (decoder->audio_codec_ctx) {
    decoder->swr_ctx = swr_alloc();
    if (!decoder->swr_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    av_opt_set_chlayout(decoder->swr_ctx, "in_chlayout", &decoder->audio_codec_ctx->ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "in_sample_rate", decoder->audio_codec_ctx->sample_rate, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "in_sample_fmt", decoder->audio_codec_ctx->sample_fmt, 0);
 
    AVChannelLayout out_ch_layout = AV_CHANNEL_LAYOUT_MONO;
    av_opt_set_chlayout(decoder->swr_ctx, "out_chlayout", &out_ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "out_sample_rate", TARGET_SAMPLE_RATE, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "out_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
 
    if (swr_init(decoder->swr_ctx) < 0) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to initialize swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->audio_buffer_size = TARGET_SAMPLE_RATE * 10;
    decoder->audio_buffer = SAFE_MALLOC(decoder->audio_buffer_size * sizeof(float), float *);
    if (!decoder->audio_buffer) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio buffer");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  // Initialize video frame prefetching system for stdin (same as file-based)
  if (decoder->video_stream_idx >= 0) {
    int width = decoder->video_codec_ctx->width;
    int height = decoder->video_codec_ctx->height;
 
    // For stdin sources, dimensions might be invalid initially (0x0)
    // Use default dimensions for prefetch buffers; they'll be resized on first frame
    if (width <= 0 || height <= 0) {
      width = 1920;  // Default width for stdin
      height = 1080; // Default height for stdin
      log_debug("stdin: Using default prefetch dimensions %dx%d (will be resized on first frame)", width, height);
    }
 
    // Create two prefetch image buffers for double-buffering
    decoder->prefetch_image_a = image_new((size_t)width, (size_t)height);
    decoder->prefetch_image_b = image_new((size_t)width, (size_t)height);
    if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate prefetch image buffers");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->current_prefetch_image = decoder->prefetch_image_a;
    decoder->prefetch_frame_ready = false;
 
    // Initialize prefetch mutex
    if (mutex_init(&decoder->prefetch_mutex, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch mutex");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (cond_init(&decoder->prefetch_cond, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch condition variable");
      mutex_destroy(&decoder->prefetch_mutex);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (mutex_init(&decoder->read_frame_mutex, "ffmpeg_read_frame") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize read_frame mutex");
      mutex_destroy(&decoder->prefetch_mutex);
      cond_destroy(&decoder->prefetch_cond);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  log_debug("FFmpeg decoder opened from stdin (video=%s, audio=%s)", decoder->video_stream_idx >= 0 ? "yes" : "no",
            decoder->audio_stream_idx >= 0 ? "yes" : "no");
 
  NAMED_REGISTER_FFMPEG_DECODER(decoder, "stdin", NULL);
 
  return decoder;
}

References ASCIICHAT_OK, ffmpeg_decoder_t::audio_buffer, ffmpeg_decoder_t::audio_buffer_size, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::audio_stream_idx, ffmpeg_decoder_t::avio_buffer, AVIO_BUFFER_SIZE, ffmpeg_decoder_t::avio_ctx, stdin_buffer_reader_t::buffer, cond_destroy(), cond_init(), ffmpeg_decoder_t::current_prefetch_image, ERROR_MEDIA_DECODE, ERROR_MEDIA_OPEN, ERROR_MEMORY, ffmpeg_decoder_destroy(), ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::frame, GET_OPTION, image_new(), ffmpeg_decoder_t::is_stdin, ffmpeg_decoder_t::last_audio_pts, ffmpeg_decoder_t::last_video_pts, log_debug, LOG_IO, log_warn, mutex_destroy(), mutex_init(), NAMED_REGISTER_FFMPEG_DECODER, ffmpeg_decoder_t::packet, stdin_buffer_reader_t::pos, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_mutex, ffmpeg_decoder_t::read_frame_mutex, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, ffmpeg_decoder_t::swr_ctx, ffmpeg_decoder_t::sws_ctx, TARGET_SAMPLE_RATE, ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_create().

ffmpeg_decoder_destroy()

void ffmpeg_decoder_destroy

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Destroy FFmpeg decoder and free resources.

Parameters

decoder

Decoder to destroy (can be NULL)

Cleans up FFmpeg decoder and releases all resources. Safe to call with NULL. Automatically stops the background prefetch thread if running.

Cleanup process:

1. Stop prefetch thread if running
2. Free video frame ringbuffer
3. Free swscale/swresample contexts
4. Close codec contexts
5. Close format context
6. Free frame and packet structures
7. Free decoder structure

Definition at line 1116 of file media/ffmpeg_decoder.c.

                                                       {
  if (!decoder) {
    return;
  }
 
  NAMED_UNREGISTER(decoder);
 
  // Stop prefetch thread (signal it to stop and wait for it to finish)
  if (decoder->prefetch_thread_running) {
    mutex_lock(&decoder->prefetch_mutex);
    decoder->prefetch_should_stop = true;
    mutex_unlock(&decoder->prefetch_mutex);
 
    // Wait for thread to finish
    asciichat_thread_join(&decoder->prefetch_thread, NULL);
    decoder->prefetch_thread_running = false;
  }
 
  // Clean up prefetch state
  cond_destroy(&decoder->prefetch_cond);
  mutex_destroy(&decoder->prefetch_mutex);
  mutex_destroy(&decoder->read_frame_mutex);
 
  // Free prefetch image buffers
  if (decoder->prefetch_image_a) {
    image_destroy(decoder->prefetch_image_a);
    decoder->prefetch_image_a = NULL;
  }
  if (decoder->prefetch_image_b) {
    image_destroy(decoder->prefetch_image_b);
    decoder->prefetch_image_b = NULL;
  }
 
  // Don't destroy current_image - it points to one of the prefetch buffers
  // which have already been destroyed above
  decoder->current_image = NULL;
 
  // Free audio buffer
  SAFE_FREE(decoder->audio_buffer);
 
  // Free swscale context
  if (decoder->sws_ctx) {
    sws_freeContext(decoder->sws_ctx);
    decoder->sws_ctx = NULL;
  }
 
  // Free swresample context
  if (decoder->swr_ctx) {
    swr_free(&decoder->swr_ctx);
  }
 
  // Free frame and packet
  if (decoder->frame) {
    av_frame_free(&decoder->frame);
  }
  if (decoder->packet) {
    av_packet_free(&decoder->packet);
  }
 
  // Free codec contexts
  if (decoder->video_codec_ctx) {
    avcodec_free_context(&decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_free_context(&decoder->audio_codec_ctx);
  }
 
  // Free format context
  if (decoder->format_ctx) {
    avformat_close_input(&decoder->format_ctx);
  }
 
  // Free AVIO context (stdin only)
  if (decoder->avio_ctx) {
    // Free the opaque reader for stdin
    if (decoder->is_stdin) {
      SAFE_FREE(decoder->avio_ctx->opaque);
    }
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
  }
 
  SAFE_FREE(decoder);
}

References asciichat_thread_join, ffmpeg_decoder_t::audio_buffer, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::avio_ctx, cond_destroy(), ffmpeg_decoder_t::current_image, ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::frame, image_destroy(), ffmpeg_decoder_t::is_stdin, mutex_destroy(), mutex_lock, mutex_unlock, NAMED_UNREGISTER, ffmpeg_decoder_t::packet, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_mutex, ffmpeg_decoder_t::prefetch_should_stop, ffmpeg_decoder_t::prefetch_thread, ffmpeg_decoder_t::prefetch_thread_running, ffmpeg_decoder_t::read_frame_mutex, SAFE_FREE, ffmpeg_decoder_t::swr_ctx, ffmpeg_decoder_t::sws_ctx, and ffmpeg_decoder_t::video_codec_ctx.

Referenced by ffmpeg_decoder_create(), ffmpeg_decoder_create_stdin(), media_source_create(), and media_source_destroy().

ffmpeg_decoder_get_duration()

double ffmpeg_decoder_get_duration

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Get media duration in seconds.

Parameters

decoder

Decoder (must not be NULL)

Returns

Duration in seconds, or -1.0 if unknown

Returns the total duration from the container metadata.

Definition at line 1597 of file media/ffmpeg_decoder.c.

                                                              {
  if (!decoder || !decoder->format_ctx) {
    return -1.0;
  }
 
  if (decoder->format_ctx->duration == AV_NOPTS_VALUE) {
    return -1.0;
  }
 
  return (double)decoder->format_ctx->duration / AV_TIME_BASE;
}

References ffmpeg_decoder_t::format_ctx.

Referenced by media_source_get_duration().

ffmpeg_decoder_get_position()

double ffmpeg_decoder_get_position

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Get current playback position in seconds.

Parameters

decoder

Decoder (must not be NULL)

Returns

Current position in seconds, or -1.0 if unknown

Returns the presentation timestamp of the last decoded frame.

Definition at line 1609 of file media/ffmpeg_decoder.c.

                                                              {
  if (!decoder) {
    return -1.0;
  }
 
  // Prefer sample-based position tracking (continuous, works before frames are decoded)
  if (decoder->audio_sample_rate > 0 && decoder->audio_samples_read >= 0) {
    return (double)decoder->audio_samples_read / (double)decoder->audio_sample_rate;
  }
 
  // Fallback to frame-based position if available
  if (decoder->last_video_pts >= 0.0) {
    return decoder->last_video_pts;
  } else if (decoder->last_audio_pts >= 0.0) {
    return decoder->last_audio_pts;
  }
 
  return -1.0;
}

References ffmpeg_decoder_t::audio_sample_rate, ffmpeg_decoder_t::audio_samples_read, ffmpeg_decoder_t::last_audio_pts, and ffmpeg_decoder_t::last_video_pts.

Referenced by media_source_get_position(), media_source_read_audio(), and media_source_seek().

ffmpeg_decoder_get_video_dimensions()

asciichat_error_t ffmpeg_decoder_get_video_dimensions	(	ffmpeg_decoder_t *	decoder,
		int *	width,
		int *	height
	)

#include <ffmpeg_decoder.h>

Get video dimensions.

Parameters

decoder	Decoder (must not be NULL)
width	Output pointer for width (can be NULL)
height	Output pointer for height (can be NULL)

Returns

ASCIICHAT_OK on success, error code if no video stream

Definition at line 1320 of file media/ffmpeg_decoder.c.

                                                                                                          {
  if (!decoder || decoder->video_stream_idx < 0) {
    return ERROR_INVALID_PARAM;
  }
 
  if (width) {
    *width = decoder->video_codec_ctx->width;
  }
  if (height) {
    *height = decoder->video_codec_ctx->height;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_stream_idx.

ffmpeg_decoder_get_video_fps()

double ffmpeg_decoder_get_video_fps

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Get video frame rate.

Parameters

decoder

Decoder (must not be NULL)

Returns

Frame rate in FPS, or -1.0 if unknown/no video

Returns the average frame rate of the video stream.

Definition at line 1335 of file media/ffmpeg_decoder.c.

                                                               {
  if (!decoder || decoder->video_stream_idx < 0) {
    return -1.0;
  }
 
  AVStream *stream = decoder->format_ctx->streams[decoder->video_stream_idx];
 
  // Try avg_frame_rate first (average frame rate from entire stream)
  double fps = av_q2d_safe(stream->avg_frame_rate);
 
  // Fallback to r_frame_rate if avg_frame_rate is invalid or zero
  // r_frame_rate is the "real" frame rate based on codec parameters
  // This is more reliable for YouTube videos and some video codecs
  if (fps <= 0.0) {
    fps = av_q2d_safe(stream->r_frame_rate);
  }
 
  return fps;
}

References ffmpeg_decoder_t::format_ctx, and ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_get_video_fps().

ffmpeg_decoder_has_audio()

bool ffmpeg_decoder_has_audio

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Check if decoder has audio stream.

Parameters

decoder

Decoder (must not be NULL)

Returns

true if audio stream exists, false otherwise

Definition at line 1481 of file media/ffmpeg_decoder.c.

                                                         {
  return decoder && decoder->audio_stream_idx >= 0;
}

References ffmpeg_decoder_t::audio_stream_idx.

Referenced by media_source_create(), and media_source_has_audio().

ffmpeg_decoder_has_video()

bool ffmpeg_decoder_has_video

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Check if decoder has video stream.

Parameters

decoder

Decoder (must not be NULL)

Returns

true if video stream exists, false otherwise

Definition at line 1316 of file media/ffmpeg_decoder.c.

                                                         {
  return decoder && decoder->video_stream_idx >= 0;
}

References ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_create(), and media_source_has_video().

ffmpeg_decoder_is_prefetch_running()

bool ffmpeg_decoder_is_prefetch_running

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Check if background frame prefetching thread is running.

Parameters

decoder

Decoder (must not be NULL)

Returns

true if prefetch thread is running, false otherwise

Utility function to check if the prefetch thread is currently active. Used during seeking to determine if thread needs to be stopped/restarted.

Definition at line 1309 of file media/ffmpeg_decoder.c.

                                                                   {
  if (!decoder) {
    return false;
  }
  return decoder->prefetch_thread_running;
}

References ffmpeg_decoder_t::prefetch_thread_running.

ffmpeg_decoder_read_audio_samples()

size_t ffmpeg_decoder_read_audio_samples	(	ffmpeg_decoder_t *	decoder,
		float *	buffer,
		size_t	num_samples
	)

#include <ffmpeg_decoder.h>

Decode audio samples.

Parameters

decoder	Decoder (must not be NULL)
buffer	Output buffer for samples (must not be NULL)
num_samples	Number of samples to read

Returns

Number of samples actually read (0 to num_samples)

Decodes audio samples from the media stream. Samples are resampled to 48kHz mono float format, compatible with ascii-chat's Opus encoding.

Audio format:

• Format: 32-bit float
• Channels: Mono (1 channel)
• Sample rate: 48000 Hz
• Range: -1.0 to 1.0

Decoding process:

1. Read packet from format context
2. Send packet to audio decoder
3. Receive decoded frame
4. Resample to 48kHz mono using swresample
5. Copy to output buffer

Note

Skips non-audio packets automatically

May return fewer samples than requested at EOF

Definition at line 1359 of file media/ffmpeg_decoder.c.

                                                                                                       {
  if (!decoder || decoder->audio_stream_idx < 0 || !buffer || num_samples == 0) {
    return 0;
  }
 
  size_t samples_written = 0;
 
  // First, drain any buffered samples
  if (decoder->audio_buffer_offset > 0) {
    size_t available = decoder->audio_buffer_offset;
    size_t to_copy = (available < num_samples) ? available : num_samples;
 
    memcpy(buffer, decoder->audio_buffer, to_copy * sizeof(float));
    samples_written += to_copy;
 
    // Shift buffer
    if (to_copy < available) {
      memmove(decoder->audio_buffer, decoder->audio_buffer + to_copy, (available - to_copy) * sizeof(float));
    }
    decoder->audio_buffer_offset -= to_copy;
 
    if (samples_written >= num_samples) {
      decoder->audio_samples_read += samples_written;
      return samples_written;
    }
  }
 
  // Read more packets to fill the request
  static uint64_t packet_count = 0;
 
  // Lock read_frame_mutex to prevent concurrent av_read_frame() calls from video prefetch thread
  mutex_lock(&decoder->read_frame_mutex);
 
  while (samples_written < num_samples) {
    int ret = av_read_frame(decoder->format_ctx, decoder->packet);
    if (ret < 0) {
      if (ret == AVERROR_EOF) {
        decoder->eof_reached = true;
      }
      break;
    }
 
    // Check if this is an audio packet
    if (decoder->packet->stream_index != decoder->audio_stream_idx) {
      av_packet_unref(decoder->packet);
      continue;
    }
 
    log_info_every(50 * US_PER_MS_INT, "Audio packet #%lu: pts=%ld dts=%ld duration=%d size=%d", packet_count++,
                   decoder->packet->pts, decoder->packet->dts, decoder->packet->duration, decoder->packet->size);
 
    // Send packet to decoder
    ret = avcodec_send_packet(decoder->audio_codec_ctx, decoder->packet);
    av_packet_unref(decoder->packet);
 
    if (ret < 0) {
      char error_message[AV_ERROR_MAX_STRING_SIZE];
      av_strerror(ret, error_message, sizeof(error_message));
      log_warn("Error sending audio packet to decoder: %s", error_message);
      continue;
    }
 
    // Receive all decoded frames from this packet
    // Important: a single packet can produce multiple frames. Must drain all before next packet.
    while (1) {
      ret = avcodec_receive_frame(decoder->audio_codec_ctx, decoder->frame);
      if (ret == AVERROR(EAGAIN)) {
        break; // No more frames from this packet, get next packet
      } else if (ret < 0) {
        log_warn("Error receiving audio frame from decoder");
        goto audio_read_done;
      }
 
      // Update position tracking
      decoder->last_audio_pts =
          get_frame_pts_seconds(decoder->frame, decoder->format_ctx->streams[decoder->audio_stream_idx]->time_base);
 
      // Resample the complete frame and retain output beyond this callback's
      // requested block. Flushing the resampler between packets would insert
      // padding into inputs whose sample rate differs from the output rate.
      uint8_t *out_ptr = (uint8_t *)decoder->audio_buffer;
      int converted = swr_convert(decoder->swr_ctx, &out_ptr, (int)decoder->audio_buffer_size,
                                  (const uint8_t **)decoder->frame->data, decoder->frame->nb_samples);
 
      if (converted > 0) {
        size_t available = (size_t)converted;
        size_t remaining = num_samples - samples_written;
        size_t to_copy = available < remaining ? available : remaining;
        memcpy(buffer + samples_written, decoder->audio_buffer, to_copy * sizeof(float));
        samples_written += to_copy;
        decoder->audio_buffer_offset = available - to_copy;
        if (decoder->audio_buffer_offset > 0)
          memmove(decoder->audio_buffer, decoder->audio_buffer + to_copy, decoder->audio_buffer_offset * sizeof(float));
      }
 
      if (samples_written >= num_samples) {
        goto audio_read_done;
      }
    }
  }
 
audio_read_done:
  // Release read_frame_mutex now that av_read_frame() is done
  mutex_unlock(&decoder->read_frame_mutex);
 
  // Flush resampler buffer if we haven't filled the full request
  // The resampler may have buffered samples that need to be output
  if (samples_written < num_samples && decoder->eof_reached) {
    int remaining_space = (int)(num_samples - samples_written);
    uint8_t *out_ptr = (uint8_t *)(buffer + samples_written);
    int flushed = swr_convert(decoder->swr_ctx, &out_ptr, remaining_space, NULL, 0);
    if (flushed > 0) {
      samples_written += (size_t)flushed;
    }
  }
 
  // Update sample-based position tracking
  decoder->audio_samples_read += samples_written;
 
  return samples_written;
}

References ffmpeg_decoder_t::audio_buffer, ffmpeg_decoder_t::audio_buffer_offset, ffmpeg_decoder_t::audio_buffer_size, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::audio_samples_read, ffmpeg_decoder_t::audio_stream_idx, EAGAIN, ffmpeg_decoder_t::eof_reached, ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::frame, ffmpeg_decoder_t::last_audio_pts, log_info_every, log_warn, mutex_lock, mutex_unlock, ffmpeg_decoder_t::packet, ffmpeg_decoder_t::read_frame_mutex, ffmpeg_decoder_t::swr_ctx, and US_PER_MS_INT.

Referenced by media_source_read_audio().

ffmpeg_decoder_read_video_frame()

image_t * ffmpeg_decoder_read_video_frame

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Decode next video frame.

Parameters

decoder

Decoder (must not be NULL)

Returns

Pointer to image_t frame, or NULL on error/EOF

Decodes the next video frame from the media stream. Returns an image_t structure in RGB24 format.

Frame format:

• Pixel format: RGB24 (8 bits per channel)
• Dimensions: Original video dimensions
• Memory: Owned by decoder (do NOT free)

Return values:

• Non-NULL: Valid frame pointer
• NULL: Error or end of stream (check ffmpeg_decoder_at_end())

Decoding process:

1. Read packet from format context
2. Send packet to video decoder
3. Receive decoded frame
4. Convert frame to RGB24 using swscale
5. Wrap in image_t structure

Note

Returned frame is valid until next call or decoder destruction

Skips non-video packets automatically

Definition at line 1205 of file media/ffmpeg_decoder.c.

                                                                    {
  if (!decoder || decoder->video_stream_idx < 0) {
    return NULL;
  }
 
  // Try to get a prefetched frame from the background thread (preferred path)
  mutex_lock(&decoder->prefetch_mutex);
  if (decoder->prefetch_frame_ready && decoder->current_prefetch_image) {
    // Release the previous buffer (rendering is now complete)
    if (decoder->current_read_buffer == decoder->prefetch_image_a) {
      decoder->buffer_a_in_use = false;
    } else if (decoder->current_read_buffer == decoder->prefetch_image_b) {
      decoder->buffer_b_in_use = false;
    }
 
    image_t *frame = decoder->current_prefetch_image;
    decoder->prefetch_frame_ready = false;
 
    // Mark the new buffer as in use (prevent prefetch thread from overwriting it during rendering)
    if (frame == decoder->prefetch_image_a) {
      decoder->buffer_a_in_use = true;
    } else if (frame == decoder->prefetch_image_b) {
      decoder->buffer_b_in_use = true;
    }
 
    decoder->current_read_buffer = frame;
    mutex_unlock(&decoder->prefetch_mutex);
 
    // Use the prefetched frame
    decoder->current_image = frame;
    log_dev_every(5 * US_PER_SEC_INT, "Using prefetched frame");
    return frame;
  }
  mutex_unlock(&decoder->prefetch_mutex);
 
  // No fallback synchronous decode - rely on background prefetch thread
  // Skipping frames when prefetch not ready allows audio timing to advance
  // This is critical for proper audio-video sync when prefetch is active
  log_dev_every(5 * US_PER_SEC_INT,
                "Prefetch frame not ready, skipping to next iteration (allow prefetch to catch up)");
  return NULL;
}

References ffmpeg_decoder_t::buffer_a_in_use, ffmpeg_decoder_t::buffer_b_in_use, ffmpeg_decoder_t::current_image, ffmpeg_decoder_t::current_prefetch_image, ffmpeg_decoder_t::current_read_buffer, frame, log_dev_every, mutex_lock, mutex_unlock, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_mutex, US_PER_SEC_INT, and ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_read_video().

ffmpeg_decoder_rewind()

asciichat_error_t ffmpeg_decoder_rewind

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Seek to beginning of media.

Parameters

decoder

Decoder (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Seeks to the beginning of the media file. Used for loop implementation.

Seek process:

1. Flush codec buffers (avcodec_flush_buffers)
2. Seek to timestamp 0 (av_seek_frame)
3. Clear decoder state

Note

Stdin decoders cannot seek (returns ERROR_NOT_SUPPORTED)

Some formats may not support seeking

Definition at line 1489 of file media/ffmpeg_decoder.c.

                                                                   {
  if (!decoder) {
    return ERROR_INVALID_PARAM;
  }
 
  if (decoder->is_stdin) {
    return ERROR_NOT_SUPPORTED; // Cannot seek stdin
  }
 
  // Flush codec buffers
  if (decoder->video_codec_ctx) {
    avcodec_flush_buffers(decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_flush_buffers(decoder->audio_codec_ctx);
  }
 
  // Seek to beginning
  if (av_seek_frame(decoder->format_ctx, -1, 0, AVSEEK_FLAG_BACKWARD) < 0) {
    return SET_ERRNO(ERROR_MEDIA_SEEK, "Failed to seek to beginning");
  }
 
  decoder->eof_reached = false;
  decoder->video_draining = false;
  decoder->audio_buffer_offset = 0;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
  decoder->audio_samples_read = 0; // Reset sample counter to 0
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ffmpeg_decoder_t::audio_buffer_offset, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::audio_samples_read, ffmpeg_decoder_t::eof_reached, ERROR_INVALID_PARAM, ERROR_MEDIA_SEEK, ERROR_NOT_SUPPORTED, ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::is_stdin, ffmpeg_decoder_t::last_audio_pts, ffmpeg_decoder_t::last_video_pts, SET_ERRNO, ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_draining.

Referenced by media_source_rewind().

ffmpeg_decoder_seek_to_timestamp()

asciichat_error_t ffmpeg_decoder_seek_to_timestamp	(	ffmpeg_decoder_t *	decoder,
		double	timestamp_sec
	)

#include <ffmpeg_decoder.h>

Seek to specific timestamp in media.

Parameters

decoder	Decoder (must not be NULL)
timestamp_sec	Seek target in seconds

Returns

ASCIICHAT_OK on success, error code on failure

Seeks to the specified timestamp in the media file. Used for audio/video synchronization in multi-decoder scenarios.

Seek process:

1. Flush codec buffers (avcodec_flush_buffers)
2. Seek to timestamp (av_seek_frame with AV_TIME_BASE conversion)
3. Clear decoder state

Note

Stdin decoders cannot seek (returns ERROR_NOT_SUPPORTED)

Some formats may not support seeking

Seeks approximately - may land before/after exact timestamp

Definition at line 1521 of file media/ffmpeg_decoder.c.

                                                                                                    {
  if (!decoder) {
    return ERROR_INVALID_PARAM;
  }
 
  if (decoder->is_stdin) {
    return ERROR_NOT_SUPPORTED; // Cannot seek stdin
  }
 
  // Hold mutex during entire seek operation to prevent race with prefetch thread
  mutex_lock(&decoder->prefetch_mutex);
 
  // Set flag to pause prefetch thread via condition variable
  decoder->seeking_in_progress = true;
 
  // Convert seconds to FFmpeg time base units (AV_TIME_BASE = 1,000,000)
  int64_t target_ts = (int64_t)(timestamp_sec * AV_TIME_BASE);
 
  // For HTTP streams, use simple keyframe seeking (faster than frame-accurate seeking)
  // HTTP seeking is expensive and can break stream state, so prefer speed over precision
  int seek_ret = av_seek_frame(decoder->format_ctx, -1, target_ts, AVSEEK_FLAG_BACKWARD);
  if (seek_ret < 0) {
    // Fallback: try without backward flag
    seek_ret = av_seek_frame(decoder->format_ctx, -1, target_ts, 0);
  }
 
  if (seek_ret < 0) {
    decoder->seeking_in_progress = false;
    cond_signal(&decoder->prefetch_cond);
    mutex_unlock(&decoder->prefetch_mutex);
    return SET_ERRNO(ERROR_MEDIA_SEEK, "Failed to seek to timestamp %.2f seconds", timestamp_sec);
  }
 
  // Flush codec buffers AFTER seeking
  if (decoder->video_codec_ctx) {
    avcodec_flush_buffers(decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_flush_buffers(decoder->audio_codec_ctx);
  }
 
  // Reset state
  decoder->eof_reached = false;
  decoder->video_draining = false;
  decoder->audio_buffer_offset = 0;
  // Clear any stale audio data in buffer
  if (decoder->audio_buffer) {
    memset(decoder->audio_buffer, 0, decoder->audio_buffer_size * sizeof(float));
  }
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
  decoder->prefetch_frame_ready = false;
  // Set audio_samples_read to match the seek target so position tracking works correctly
  decoder->audio_samples_read = (uint64_t)(timestamp_sec * decoder->audio_sample_rate);
 
  // Reset current_read_buffer and mark both buffers as not in use
  // After seeking, the prefetch thread may reallocate buffers, so current_read_buffer
  // could point to freed memory. Clear it so the next read doesn't try to release stale pointers.
  decoder->current_read_buffer = NULL;
  decoder->buffer_a_in_use = false;
  decoder->buffer_b_in_use = false;
 
  // Resume prefetch thread
  decoder->seeking_in_progress = false;
  cond_signal(&decoder->prefetch_cond);
 
  // Release mutex - prefetch thread can resume
  mutex_unlock(&decoder->prefetch_mutex);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ffmpeg_decoder_t::audio_buffer, ffmpeg_decoder_t::audio_buffer_offset, ffmpeg_decoder_t::audio_buffer_size, ffmpeg_decoder_t::audio_codec_ctx, ffmpeg_decoder_t::audio_sample_rate, ffmpeg_decoder_t::audio_samples_read, ffmpeg_decoder_t::buffer_a_in_use, ffmpeg_decoder_t::buffer_b_in_use, cond_signal(), ffmpeg_decoder_t::current_read_buffer, ffmpeg_decoder_t::eof_reached, ERROR_INVALID_PARAM, ERROR_MEDIA_SEEK, ERROR_NOT_SUPPORTED, ffmpeg_decoder_t::format_ctx, ffmpeg_decoder_t::is_stdin, ffmpeg_decoder_t::last_audio_pts, ffmpeg_decoder_t::last_video_pts, mutex_lock, mutex_unlock, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_mutex, ffmpeg_decoder_t::seeking_in_progress, SET_ERRNO, ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_draining.

Referenced by media_source_seek().

ffmpeg_decoder_set_exit_callback()

void ffmpeg_decoder_set_exit_callback	(	ffmpeg_decoder_t *	decoder,
		bool(*)(void *)	should_exit_callback,
		void *	user_data
	)

#include <ffmpeg_decoder.h>

Set exit signal callback for graceful shutdown during I/O.

Parameters

decoder	Decoder (must not be NULL)
callback	Function that returns true if app should exit (can be NULL)
user_data	User data to pass to callback (can be NULL)

Sets a callback that allows the decoder's background prefetch thread to gracefully abort blocking I/O operations (like YouTube HTTP requests) when the application is shutting down (e.g., when user presses Ctrl+C).

When the callback returns true, the FFmpeg interrupt handler will abort any blocking av_read_frame() call, allowing the prefetch thread to exit cleanly rather than hanging indefinitely.

Note

Called automatically from media_source layer (no need to call manually)

Definition at line 1300 of file media/ffmpeg_decoder.c.

                                                       {
  if (!decoder) {
    return;
  }
  decoder->should_exit_callback = should_exit_callback;
  decoder->exit_callback_user_data = user_data;
}

References ffmpeg_decoder_t::exit_callback_user_data, and ffmpeg_decoder_t::should_exit_callback.

Referenced by media_source_set_exit_callback().

ffmpeg_decoder_start_prefetch()

asciichat_error_t ffmpeg_decoder_start_prefetch

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Start background frame prefetching thread.

Parameters

decoder

Decoder (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Starts a background thread that continuously reads and decodes video frames, storing them in an internal ringbuffer. The render loop then pulls pre-decoded frames from this buffer without blocking on network I/O.

Purpose: Solves YouTube HTTP streaming performance issues by decoupling the blocking av_read_frame() calls from the render loop. Without this, frames take 93ms to arrive instead of the expected 41.7ms at 24 FPS.

Note

Should be called after decoder creation for FILE/HTTP sources

Automatically called when media source is created

Thread is stopped in ffmpeg_decoder_destroy()

Start background frame prefetching thread.

Starts a background thread that continuously reads and decodes video frames, storing them in double-buffer structures. The render loop pulls frames from these buffers. This prevents the render thread from blocking on YouTube HTTP requests.

Definition at line 1255 of file media/ffmpeg_decoder.c.

                                                                           {
  if (!decoder || decoder->video_stream_idx < 0) {
    return ERROR_INVALID_PARAM;
  }
 
  if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
    return ERROR_INVALID_PARAM;
  }
 
  // Already running
  if (decoder->prefetch_thread_running) {
    return ASCIICHAT_OK;
  }
 
  // Reset stop flag and create thread
  decoder->prefetch_should_stop = false;
 
  int thread_err = asciichat_thread_create(&decoder->prefetch_thread, "ffmpeg_prefetch",
                                           ffmpeg_decoder_prefetch_thread_func, decoder);
  if (thread_err != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to create video prefetch thread");
  }
 
  decoder->prefetch_thread_running = true;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asciichat_thread_create, ERROR_INVALID_PARAM, ERROR_THREAD, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_should_stop, ffmpeg_decoder_t::prefetch_thread, ffmpeg_decoder_t::prefetch_thread_running, SET_ERRNO, and ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_create().

ffmpeg_decoder_stop_prefetch()

void ffmpeg_decoder_stop_prefetch

(

ffmpeg_decoder_t *

decoder

)

#include <ffmpeg_decoder.h>

Stop background frame prefetching thread.

Parameters

decoder

Decoder (must not be NULL)

Stops the background prefetch thread. Automatically called by ffmpeg_decoder_destroy(). Safe to call even if thread isn't running.

Stop background frame prefetching thread.

Definition at line 1285 of file media/ffmpeg_decoder.c.

                                                             {
  if (!decoder || !decoder->prefetch_thread_running) {
    return;
  }
 
  decoder->prefetch_should_stop = true;
  // Wait up to 2 seconds for thread to stop
  // The interrupt callback should cause av_read_frame to abort quickly
  asciichat_thread_join_timeout(&decoder->prefetch_thread, NULL, 2000 * NS_PER_MS_INT);
 
  // Mark thread as stopped regardless of join result
  // (if join succeeded: cleanup was done; if timeout: will be cleaned up on restart)
  decoder->prefetch_thread_running = false;
}

References asciichat_thread_join_timeout(), NS_PER_MS_INT, ffmpeg_decoder_t::prefetch_should_stop, ffmpeg_decoder_t::prefetch_thread, and ffmpeg_decoder_t::prefetch_thread_running.

media_source_at_end()

bool media_source_at_end

(

media_source_t *

source

)

#include <source.h>

Check if media source reached end of stream.

Parameters

source

Media source (must not be NULL)

Returns

true if end reached, false otherwise

Determines if the media source has reached end of stream. This distinguishes between read errors and legitimate EOF conditions.

Return values:

• true: End of stream reached (no more data)
• false: More data available or error occurred

Note

WEBCAM/TEST sources never reach end (always return false)

FILE/STDIN sources return true when all packets consumed

If loop is enabled, this returns false (EOF triggers rewind)

Definition at line 772 of file source.c.

                                                 {
  if (!source) {
    return true;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return false; // Webcam never ends
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    if (!source->video_decoder) {
      return true;
    }
    // If loop is enabled, we never truly reach end
    if (source->loop_enabled && source->type == MEDIA_SOURCE_FILE) {
      return false;
    }
    if (source->audio_only)
      return source->audio_decoder && ffmpeg_decoder_at_end(source->audio_decoder);
    return ffmpeg_decoder_at_end(source->video_decoder);
 
  default:
    return true;
  }
}

References media_source_t::audio_decoder, media_source_t::audio_only, ffmpeg_decoder_at_end(), media_source_t::loop_enabled, MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, media_source_t::type, and media_source_t::video_decoder.

Referenced by media_source_read_video(), and session_capture_at_end().

media_source_create()

media_source_t * media_source_create	(	media_source_type_t	type,
		const char *	path
	)

#include <source.h>

Create a new media source.

Parameters

type	Media source type
path	File path (for FILE type), device index string (for WEBCAM), or NULL

Returns

Pointer to media source, or NULL on failure

Creates and initializes a media source of the specified type.

Path parameter usage:

• MEDIA_SOURCE_FILE: File path (e.g., "video.mp4")
• MEDIA_SOURCE_STDIN: Use "-" or NULL
• MEDIA_SOURCE_WEBCAM: Device index as string (e.g., "0") or NULL for default
• MEDIA_SOURCE_TEST: Ignored (use NULL)

Note

For WEBCAM type, delegates to webcam_init_context()

For FILE/STDIN types, uses FFmpeg decoder

Call media_source_destroy() to cleanup

Definition at line 187 of file source.c.

                                                                                {
  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;
  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;
  }
 
  // Initialize mutex for protecting pause state (accessed from keyboard and video threads)
  if (mutex_init(&source->pause_mutex, "media_pause") != 0) {
    SET_ERRNO(ERROR_MEMORY, "Failed to initialize pause mutex");
    mutex_destroy(&source->decoder_mutex);
    SAFE_FREE(source);
    return NULL;
  }
 
  // Initialize mutex for protecting decoder access during seeks (prevents race conditions)
  if (mutex_init(&source->seek_access_mutex, "media_seek") != 0) {
    SET_ERRNO(ERROR_MEMORY, "Failed to initialize seek access mutex");
    mutex_destroy(&source->decoder_mutex);
    mutex_destroy(&source->pause_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("media_source_create: Invalid webcam index: %s", path);
      }
    }
 
    source->webcam_index = index;
    asciichat_error_t webcam_error = webcam_init_context(&source->webcam_ctx, index);
    if (webcam_error != ASCIICHAT_OK) {
      // Webcam init failed - log and cleanup
      log_error("Failed to initialize webcam device %u (error code: %d)", index, webcam_error);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
 
      // Explicitly re-set errno to preserve the specific error code for the caller
      // (log_error or other calls may have cleared the thread-local errno)
      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: {
    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);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Resolve URL using smart FFmpeg/yt-dlp routing
    const char *effective_path = path;
    char resolved_url[BUFFER_SIZE_XLARGE] = {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));
    if (resolve_err != ASCIICHAT_OK) {
      log_debug("Failed to resolve URL (error: %d)", resolve_err);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_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);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Always use separate decoders for video and audio
    // This allows independent read rates and avoids lock contention
    source->video_decoder = ffmpeg_decoder_create(effective_path);
    if (!source->video_decoder) {
      log_error("Failed to open media file for video: %s", effective_path);
      SAFE_FREE(source->file_path);
      SAFE_FREE(source->original_youtube_url);
      // Destroy mutexes before freeing source
      mutex_destroy(&source->decoder_mutex);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Start prefetch only when a video stream exists.
    // This thread continuously reads frames into a buffer so the render loop never blocks
    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_string(prefetch_err));
      // Don't fail on prefetch error - continue with frame skipping as fallback
    }
 
    source->audio_decoder = ffmpeg_decoder_create(effective_path);
    if (!source->audio_decoder) {
      log_error("Failed to open media file for audio: %s", effective_path);
      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);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
      return NULL;
    }
    source->is_shared_decoder = false;
 
    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);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_mutex);
      SAFE_FREE(source);
      return NULL;
    }
 
    // Start prefetch thread for stdin video frames
    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_string(prefetch_err));
      // Don't fail on prefetch error - continue with frame skipping as fallback
    }
 
    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);
      mutex_destroy(&source->pause_mutex);
      mutex_destroy(&source->seek_access_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_frame = NULL; // Allocated lazily on first read
    source->test_frame_counter = 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);
    mutex_destroy(&source->pause_mutex);
    mutex_destroy(&source->seek_access_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[64];
  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_MUTEX(&source->pause_mutex, "pause_mutex", (uintptr_t)(const void *)(source));
  NAMED_REGISTER_MUTEX(&source->seek_access_mutex, "seek_access_mutex", (uintptr_t)(const void *)(source));
 
  return source;
}

References ASCIICHAT_OK, media_source_t::audio_decoder, media_source_t::audio_only, BUFFER_SIZE_XLARGE, media_source_t::decoder_mutex, errno, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_WEBCAM, ERROR_WEBCAM_IN_USE, ffmpeg_decoder_create(), ffmpeg_decoder_create_stdin(), ffmpeg_decoder_destroy(), ffmpeg_decoder_has_audio(), ffmpeg_decoder_has_video(), ffmpeg_decoder_start_prefetch(), media_source_t::file_path, GET_OPTION, media_source_t::is_paused, media_source_t::is_shared_decoder, log_debug, log_error, log_warn, media_source_t::loop_enabled, MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, mutex_destroy(), mutex_init(), NAMED_REGISTER, NAMED_REGISTER_MUTEX, media_source_t::original_youtube_url, media_source_t::pause_mutex, platform_strdup(), SAFE_FREE, SAFE_MALLOC, media_source_t::seek_access_mutex, SET_ERRNO, media_source_t::test_frame_counter, media_source_t::test_pattern_frame, media_source_t::type, media_source_t::video_decoder, media_source_t::webcam_ctx, media_source_t::webcam_index, and webcam_init_context().

Referenced by session_capture_create(), and session_client_like_run().

media_source_destroy()

void media_source_destroy

(

media_source_t *

source

)

#include <source.h>

Destroy media source and free resources.

Parameters

source

Media source to destroy (can be NULL)

Cleans up media source and releases all resources. Safe to call with NULL.

Note

For WEBCAM type, calls webcam_cleanup_context()

For FILE/STDIN types, closes FFmpeg decoder

Definition at line 448 of file source.c.

                                                  {
  if (!source) {
    return;
  }
 
  // Cleanup based on type
  if (source->webcam_ctx) {
    webcam_cleanup_context(source->webcam_ctx);
    source->webcam_ctx = NULL;
  }
 
  // For YouTube (shared decoder), only destroy once
  // For local files (separate decoders), destroy both
  if (source->video_decoder) {
    ffmpeg_decoder_destroy(source->video_decoder);
    source->video_decoder = NULL;
  }
 
  if (source->audio_decoder) {
    // Don't double-free if audio and video share the same decoder
    if (!source->is_shared_decoder) {
      ffmpeg_decoder_destroy(source->audio_decoder);
    }
    source->audio_decoder = NULL;
  }
 
  SAFE_FREE(source->file_path);
  SAFE_FREE(source->original_youtube_url);
 
  // Clean up test pattern frame
  if (source->test_pattern_frame) {
    image_destroy(source->test_pattern_frame);
    source->test_pattern_frame = NULL;
  }
 
  // Destroy mutexes
  mutex_destroy(&source->decoder_mutex);
  mutex_destroy(&source->pause_mutex);
  mutex_destroy(&source->seek_access_mutex);
 
  SAFE_FREE(source);
}

References media_source_t::audio_decoder, media_source_t::decoder_mutex, ffmpeg_decoder_destroy(), media_source_t::file_path, image_destroy(), media_source_t::is_shared_decoder, mutex_destroy(), media_source_t::original_youtube_url, media_source_t::pause_mutex, SAFE_FREE, media_source_t::seek_access_mutex, media_source_t::test_pattern_frame, media_source_t::video_decoder, webcam_cleanup_context(), and media_source_t::webcam_ctx.

Referenced by session_capture_create(), session_capture_destroy(), and session_client_like_run().

media_source_get_duration()

double media_source_get_duration

(

media_source_t *

source

)

#include <source.h>

Get media duration in seconds.

Parameters

source

Media source (must not be NULL)

Returns

Duration in seconds, or -1.0 if unknown/infinite

Returns the total duration of the media. Useful for progress display.

Return values:

• Positive value: Duration in seconds (e.g., 120.5 for 2 minutes)
• -1.0: Duration unknown (stdin, live streams) or infinite (webcam)

Note

WEBCAM/TEST sources return -1.0 (infinite)

FILE sources return actual duration from container

STDIN sources return -1.0 (cannot determine duration)

Definition at line 934 of file source.c.

                                                         {
  if (!source) {
    return -1.0;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return -1.0; // Infinite
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    if (!source->video_decoder) {
      return -1.0;
    }
    return ffmpeg_decoder_get_duration(source->video_decoder);
 
  default:
    return -1.0;
  }
}

References ffmpeg_decoder_get_duration(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, media_source_t::type, and media_source_t::video_decoder.

Referenced by session_handle_keyboard_input().

media_source_get_position()

double media_source_get_position

(

media_source_t *

source

)

#include <source.h>

Get current playback position in seconds.

Parameters

source

Media source (must not be NULL)

Returns

Current position in seconds, or -1.0 if unknown

Returns the current playback position. Useful for progress display.

Return values:

• Positive value: Position in seconds (e.g., 45.2)
• -1.0: Position unknown or not applicable

Note

WEBCAM/TEST sources return -1.0 (no position concept)

FILE sources return position based on last decoded frame PTS

Definition at line 956 of file source.c.

                                                         {
  if (!source) {
    return -1.0;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return -1.0; // No position concept
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    if (!source->video_decoder) {
      return -1.0;
    }
    return ffmpeg_decoder_get_position(source->audio_only ? source->audio_decoder : source->video_decoder);
 
  default:
    return -1.0;
  }
}

References media_source_t::audio_decoder, media_source_t::audio_only, ffmpeg_decoder_get_position(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, media_source_t::type, and media_source_t::video_decoder.

Referenced by session_handle_keyboard_input().

media_source_get_type()

media_source_type_t media_source_get_type

(

media_source_t *

source

)

#include <source.h>

Get media source type.

Parameters

source

Media source (must not be NULL)

Returns

Media source type

Returns the type of the media source.

Definition at line 930 of file source.c.

                                                                  {
  return source ? source->type : MEDIA_SOURCE_TEST;
}

References MEDIA_SOURCE_TEST, and media_source_t::type.

Referenced by session_capture_sleep_for_fps(), session_handle_keyboard_input(), and session_pipeline_create().

media_source_get_video_fps()

double media_source_get_video_fps

(

media_source_t *

source

)

#include <source.h>

Get video frame rate in frames per second.

Parameters

source

Media source (must not be NULL)

Returns

Frame rate in FPS, or 0.0 if unknown

Returns the native frame rate of the video stream.

Return values:

• Positive value: Frame rate in FPS (e.g., 30.0, 60.0)
• 0.0: Frame rate unknown or not applicable

Note

WEBCAM sources return 0.0 (variable rate)

TEST sources return 0.0

FILE/STDIN sources return the video stream's fps from FFmpeg

Definition at line 978 of file source.c.

                                                          {
  if (!source) {
    return 0.0;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return 0.0; // Variable rate, no fixed FPS
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    if (!source->video_decoder) {
      return 0.0;
    }
    return ffmpeg_decoder_get_video_fps(source->video_decoder);
 
  default:
    return 0.0;
  }
}

References ffmpeg_decoder_get_video_fps(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, media_source_t::type, and media_source_t::video_decoder.

Referenced by session_client_like_run().

media_source_has_audio()

bool media_source_has_audio

(

media_source_t *

source

)

#include <source.h>

Check if media source has audio stream.

Parameters

source

Media source (must not be NULL)

Returns

true if source has audio, false otherwise

Determines if the media source provides audio samples.

Note

WEBCAM and TEST sources return false (no audio)

FILE/STDIN sources return true if audio stream detected

Definition at line 737 of file source.c.

                                                    {
  if (!source) {
    return false;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return false; // Webcam/test don't have audio
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    return source->audio_decoder && ffmpeg_decoder_has_audio(source->audio_decoder);
 
  default:
    return false;
  }
}

References media_source_t::audio_decoder, ffmpeg_decoder_has_audio(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and media_source_t::type.

Referenced by audio_start_duplex(), session_capture_create(), and session_client_like_run().

media_source_has_video()

bool media_source_has_video

(

media_source_t *

source

)

#include <source.h>

Check if media source has video stream.

Parameters

source

Media source (must not be NULL)

Returns

true if source has video, false otherwise

Determines if the media source provides video frames.

Note

WEBCAM and TEST sources always return true

FILE/STDIN sources return true if video stream detected

Definition at line 629 of file source.c.

                                                    {
  if (!source) {
    return false;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return true; // Webcam/test always has video
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN:
    return source->audio_only || (source->video_decoder && ffmpeg_decoder_has_video(source->video_decoder));
 
  default:
    return false;
  }
}

References media_source_t::audio_only, ffmpeg_decoder_has_video(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, media_source_t::type, and media_source_t::video_decoder.

media_source_is_paused()

bool media_source_is_paused

(

media_source_t *

source

)

#include <source.h>

Check if media source is paused.

Parameters

source

Media source (must not be NULL)

Returns

true if paused, false if playing

Determines if the media source is currently paused.

Definition at line 1022 of file source.c.

                                                    {
  if (!source) {
    return false;
  }
  mutex_lock(&source->pause_mutex);
  bool paused = source->is_paused;
  mutex_unlock(&source->pause_mutex);
  return paused;
}

References media_source_t::is_paused, mutex_lock, mutex_unlock, and media_source_t::pause_mutex.

Referenced by session_handle_keyboard_input().

media_source_pause()

void media_source_pause

(

media_source_t *

source

)

#include <source.h>

Pause media playback.

Parameters

source

Media source (must not be NULL)

Pauses the media source. When paused, read_video and read_audio return no new data (NULL/silence) while maintaining the current playback position. Resume with media_source_resume() to continue from the paused position.

Behavior:

• media_source_read_video() returns NULL when paused
• media_source_read_audio() returns 0 (silence) when paused
• Playback position is preserved (no seeking occurs)

Note

All source types support pause (has no effect for WEBCAM/TEST)

Pausing is instantaneous (next read will return no data)

Definition at line 1004 of file source.c.

                                                {
  if (!source) {
    return;
  }
  mutex_lock(&source->pause_mutex);
  source->is_paused = true;
  mutex_unlock(&source->pause_mutex);
}

References media_source_t::is_paused, mutex_lock, mutex_unlock, and media_source_t::pause_mutex.

Referenced by session_capture_read_frame().

media_source_read_audio()

size_t media_source_read_audio	(	media_source_t *	source,
		float *	buffer,
		size_t	num_samples
	)

#include <source.h>

Read audio samples from media source.

Parameters

source	Media source (must not be NULL)
buffer	Output buffer for audio samples (must not be NULL)
num_samples	Number of samples to read

Returns

Number of samples actually read (may be less than requested)

Reads audio samples from the media source. Samples are in 32-bit float format, mono channel, 48kHz sample rate (compatible with Opus encoding).

Audio format:

• Format: 32-bit float
• Channels: Mono (1 channel)
• Sample rate: 48000 Hz
• Range: -1.0 to 1.0

Return value:

• Returns actual number of samples read (0 to num_samples)
• Returns 0 on error or end of stream
• Check media_source_at_end() to distinguish error from EOF

Note

WEBCAM type does NOT provide audio (returns 0)

FILE/STDIN types decode audio via FFmpeg if stream exists

Audio is resampled to 48kHz mono automatically

Definition at line 652 of file source.c.

                                                                                          {
  if (!source || !buffer || num_samples == 0) {
    return 0;
  }
 
  static uint64_t call_count = 0;
  call_count++;
  if (call_count <= 5 || call_count % 1000 == 0) {
    log_info("media_source_read_audio #%lu: source_type=%d num_samples=%zu", call_count, source->type, num_samples);
  }
 
  // Check pause state (thread-safe)
  mutex_lock(&source->pause_mutex);
  bool is_paused = source->is_paused;
  mutex_unlock(&source->pause_mutex);
 
  // Return silence immediately if paused (maintaining position)
  if (is_paused) {
    memset(buffer, 0, num_samples * sizeof(float));
    return num_samples;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    // Webcam/test pattern don't provide audio
    return 0;
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN: {
    if (!source->audio_decoder) {
      log_warn("media_source_read_audio: audio_decoder is NULL!");
      return 0;
    }
 
    // Lock seek_access_mutex to prevent audio callback from reading during seek
    mutex_lock(&source->seek_access_mutex);
 
    // Lock shared decoder if YouTube URL (protect against concurrent video thread access)
    if (source->is_shared_decoder) {
      mutex_lock(&source->decoder_mutex);
    }
 
    double audio_pos_before_read = ffmpeg_decoder_get_position(source->audio_decoder);
    size_t samples_read = ffmpeg_decoder_read_audio_samples(source->audio_decoder, buffer, num_samples);
    double audio_pos_after_read = ffmpeg_decoder_get_position(source->audio_decoder);
 
    static double last_audio_pos = 0;
    if (audio_pos_after_read >= 0 && last_audio_pos >= 0 && audio_pos_after_read < last_audio_pos) {
      log_warn("AUDIO POSITION WENT BACKWARD: %.2f → %.2f (LOOPING!)", last_audio_pos, audio_pos_after_read);
    }
    if (audio_pos_after_read >= 0) {
      last_audio_pos = audio_pos_after_read;
    }
 
    log_info_every(100 * US_PER_MS_INT, "Audio: read %zu samples, pos %.2f → %.2f", samples_read,
                   audio_pos_before_read, audio_pos_after_read);
 
    // Handle EOF with loop
    if (samples_read == 0 && ffmpeg_decoder_at_end(source->audio_decoder)) {
      if (source->loop_enabled && source->type == MEDIA_SOURCE_FILE) {
        log_debug("End of file reached (audio), rewinding for loop");
        if (media_source_rewind(source) == ASCIICHAT_OK) {
          // Try reading again after rewind
          samples_read = ffmpeg_decoder_read_audio_samples(source->audio_decoder, buffer, num_samples);
        }
      }
    }
 
    // Unlock shared decoder
    if (source->is_shared_decoder) {
      mutex_unlock(&source->decoder_mutex);
    }
 
    // Release seek_access_mutex
    mutex_unlock(&source->seek_access_mutex);
 
    return samples_read;
  }
 
  default:
    return 0;
  }
}

References ASCIICHAT_OK, media_source_t::audio_decoder, media_source_t::decoder_mutex, ffmpeg_decoder_at_end(), ffmpeg_decoder_get_position(), ffmpeg_decoder_read_audio_samples(), media_source_t::is_paused, media_source_t::is_shared_decoder, log_debug, log_info, log_info_every, log_warn, media_source_t::loop_enabled, MEDIA_SOURCE_FILE, media_source_rewind(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, mutex_lock, mutex_unlock, media_source_t::pause_mutex, media_source_t::seek_access_mutex, media_source_t::type, and US_PER_MS_INT.

Referenced by session_capture_read_audio().

media_source_read_video()

image_t * media_source_read_video

(

media_source_t *

source

)

#include <source.h>

Read next video frame from media source.

Parameters

source

Media source (must not be NULL)

Returns

Pointer to image_t frame, or NULL on error/end

Reads the next video frame from the media source. Returns an image_t structure in RGB format, compatible with existing ascii-chat pipeline.

Return values:

• Non-NULL: Valid frame pointer (do NOT free - internal buffer)
• NULL: Error or end of stream (check media_source_at_end())

Frame ownership:

• Returned frame is owned by media source
• Do NOT free the returned frame
• Frame is valid until next call or source destruction

Note

For WEBCAM type, calls webcam_read_context()

For FILE/STDIN types, decodes next video frame via FFmpeg

Frame timing is handled by caller (capture thread)

Definition at line 523 of file source.c.

                                                         {
  if (!source) {
    return NULL;
  }
 
  // Check pause state (thread-safe)
  mutex_lock(&source->pause_mutex);
  bool is_paused = source->is_paused;
  mutex_unlock(&source->pause_mutex);
 
  // Return NULL immediately if paused (maintaining position)
  if (is_paused) {
    return NULL;
  }
 
  if (source->audio_only && media_source_at_end(source))
    return NULL;
  if (source->audio_only && GET_OPTION(test_pattern))
    return read_test_pattern(source);
  if (source->audio_only && !source->webcam_ctx) {
    if (media_source_start_video(source) != ASCIICHAT_OK)
      return NULL;
  }
  if (source->webcam_ctx)
    return webcam_read_context(source->webcam_ctx);
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
    // Read from webcam
    if (source->webcam_ctx) {
      return webcam_read_context(source->webcam_ctx);
    }
    return NULL;
 
  case MEDIA_SOURCE_TEST: {
    return read_test_pattern(source);
  }
 
  case MEDIA_SOURCE_FILE:
  case MEDIA_SOURCE_STDIN: {
    if (!source->video_decoder) {
      return NULL;
    }
 
    // Lock shared decoder if YouTube URL (protect against concurrent audio thread access)
    if (source->is_shared_decoder) {
      mutex_lock(&source->decoder_mutex);
    }
 
    uint64_t frame_read_start_ns = time_get_ns();
    image_t *frame = ffmpeg_decoder_read_video_frame(source->video_decoder);
    uint64_t frame_read_ns = time_elapsed_ns(frame_read_start_ns, time_get_ns());
 
    // Track frame reading statistics for FPS diagnosis
    static uint64_t total_attempts = 0;
    static uint64_t successful_frames = 0;
    static uint64_t null_frame_count = 0;
    static uint64_t total_read_time_ns = 0;
    static uint64_t max_read_time_ns = 0;
 
    total_attempts++;
    if (frame) {
      successful_frames++;
      total_read_time_ns += frame_read_ns;
      if (frame_read_ns > max_read_time_ns) {
        max_read_time_ns = frame_read_ns;
      }
 
      // Log statistics every 30 successful frames
      if (successful_frames % 30 == 0) {
        double avg_read_ms = (double)total_read_time_ns / (double)successful_frames / NS_PER_MS;
        double max_read_ms = (double)max_read_time_ns / NS_PER_MS;
        double null_rate = (double)null_frame_count * 100.0 / (double)total_attempts;
        log_info_every(3 * US_PER_SEC_INT,
                       "FRAME_STATS[%lu]: avg_read=%.2f ms, max_read=%.2f ms, null_rate=%.1f%% "
                       "(%lu null/%lu attempts)",
                       successful_frames, avg_read_ms, max_read_ms, null_rate, null_frame_count, total_attempts);
      }
    } else {
      null_frame_count++;
    }
 
    // Handle EOF with loop
    if (!frame && ffmpeg_decoder_at_end(source->video_decoder)) {
      if (source->loop_enabled && source->type == MEDIA_SOURCE_FILE) {
        log_debug("End of file reached, rewinding for loop");
        if (media_source_rewind(source) == ASCIICHAT_OK) {
          // Try reading again after rewind
          frame = ffmpeg_decoder_read_video_frame(source->video_decoder);
        }
      }
    }
 
    // Unlock shared decoder
    if (source->is_shared_decoder) {
      mutex_unlock(&source->decoder_mutex);
    }
 
    return frame;
  }
 
  default:
    return NULL;
  }
}

References ASCIICHAT_OK, media_source_t::audio_only, media_source_t::decoder_mutex, ffmpeg_decoder_at_end(), ffmpeg_decoder_read_video_frame(), frame, GET_OPTION, media_source_t::is_paused, media_source_t::is_shared_decoder, log_debug, log_info_every, media_source_t::loop_enabled, media_source_at_end(), MEDIA_SOURCE_FILE, media_source_rewind(), media_source_start_video(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, mutex_lock, mutex_unlock, NS_PER_MS, media_source_t::pause_mutex, time_elapsed_ns(), time_get_ns(), media_source_t::type, US_PER_SEC_INT, media_source_t::video_decoder, media_source_t::webcam_ctx, and webcam_read_context().

Referenced by session_capture_read_frame().

media_source_resume()

void media_source_resume

(

media_source_t *

source

)

#include <source.h>

Resume media playback after pause.

Parameters

source

Media source (must not be NULL)

Resumes playback from where it was paused. Continues reading frames and audio samples from the current position.

Note

Safe to call if not paused (no-op)

Resume is instantaneous (next read will return new data)

Definition at line 1013 of file source.c.

                                                 {
  if (!source) {
    return;
  }
  mutex_lock(&source->pause_mutex);
  source->is_paused = false;
  mutex_unlock(&source->pause_mutex);
}

References media_source_t::is_paused, mutex_lock, mutex_unlock, and media_source_t::pause_mutex.

media_source_rewind()

asciichat_error_t media_source_rewind

(

media_source_t *

source

)

#include <source.h>

Rewind media source to beginning.

Parameters

source

Media source (must not be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Seeks to the beginning of the media source. Used for loop implementation.

Behavior:

• FILE sources: Seek to timestamp 0 (if seekable)
• STDIN sources: ERROR_NOT_SUPPORTED (cannot seek stdin)
• WEBCAM/TEST sources: No-op (always returns OK)

Note

Called automatically by read functions if loop enabled

Can be called manually to restart playback

Definition at line 800 of file source.c.

                                                              {
  if (!source) {
    return ERROR_INVALID_PARAM;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
  case MEDIA_SOURCE_TEST:
    return ASCIICHAT_OK; // No-op for webcam
 
  case MEDIA_SOURCE_FILE:
    if (!source->video_decoder || !source->audio_decoder) {
      return ERROR_INVALID_PARAM;
    }
 
    // Lock shared decoder if YouTube URL (protect against concurrent thread access)
    if (source->is_shared_decoder) {
      mutex_lock(&source->decoder_mutex);
    }
 
    // Rewind video decoder
    asciichat_error_t video_result = ffmpeg_decoder_rewind(source->video_decoder);
    if (video_result != ASCIICHAT_OK) {
      if (source->is_shared_decoder) {
        mutex_unlock(&source->decoder_mutex);
      }
      return video_result;
    }
 
    // For YouTube (shared decoder), don't rewind audio separately
    // For local files (separate decoders), rewind audio too
    asciichat_error_t result = ASCIICHAT_OK;
    if (!source->is_shared_decoder) {
      result = ffmpeg_decoder_rewind(source->audio_decoder);
    }
 
    // Unlock shared decoder
    if (source->is_shared_decoder) {
      mutex_unlock(&source->decoder_mutex);
    }
 
    return result;
 
  case MEDIA_SOURCE_STDIN:
    return ERROR_NOT_SUPPORTED; // Cannot seek stdin
 
  default:
    return ERROR_INVALID_PARAM;
  }
}

References ASCIICHAT_OK, media_source_t::audio_decoder, media_source_t::decoder_mutex, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, ffmpeg_decoder_rewind(), media_source_t::is_shared_decoder, MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, mutex_lock, mutex_unlock, media_source_t::type, and media_source_t::video_decoder.

Referenced by media_source_read_audio(), and media_source_read_video().

media_source_seek()

asciichat_error_t media_source_seek	(	media_source_t *	source,
		double	timestamp_sec
	)

#include <source.h>

Seek media source to timestamp.

Parameters

source	Media source (must not be NULL)
timestamp_sec	Timestamp in seconds

Returns

ASCIICHAT_OK on success, error code on failure

Seeks both video and audio decoders to the specified timestamp. Handles shared decoder locking for YouTube URLs.

Behavior:

• FILE sources: Seek to timestamp (if seekable)
• STDIN sources: ERROR_NOT_SUPPORTED (cannot seek stdin)
• WEBCAM/TEST sources: No-op (always returns OK)

Thread safety:

• For YouTube URLs with shared decoder, automatically locks during seek
• Safe to call from any thread

Note

FILE sources only (returns OK for others)

STDIN sources: ERROR_NOT_SUPPORTED (cannot seek stdin)

Negative timestamps are rejected

Seeks are approximate (may land before requested timestamp)

Definition at line 851 of file source.c.

                                                                                  {
  if (!source) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Media source is NULL");
    return ERROR_INVALID_PARAM;
  }
 
  if (timestamp_sec < 0.0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timestamp must be >= 0.0");
    return ERROR_INVALID_PARAM;
  }
 
  // WEBCAM and TEST sources: no-op (always return OK)
  if (source->type == MEDIA_SOURCE_WEBCAM || source->type == MEDIA_SOURCE_TEST) {
    return ASCIICHAT_OK;
  }
 
  // STDIN: not supported
  if (source->type == MEDIA_SOURCE_STDIN) {
    SET_ERRNO(ERROR_NOT_SUPPORTED, "Cannot seek stdin");
    return ERROR_NOT_SUPPORTED;
  }
 
  asciichat_error_t result = ASCIICHAT_OK;
 
  // Clear audio playback buffer BEFORE seeking to prevent old audio from being queued
  // This ensures fresh audio starts playing immediately after seek completes
  if (source->audio_ctx) {
    audio_context_t *audio_ctx = (audio_context_t *)source->audio_ctx;
    if (audio_ctx->playback_buffer) {
      audio_ring_buffer_clear(audio_ctx->playback_buffer);
    }
  }
 
  // The seeking_in_progress flag in decoders blocks prefetch thread
  // seeking_in_progress coordinates with audio callback via condition variable
 
  uint64_t seek_start_ns = time_get_ns();
  if (source->video_decoder) {
    double video_pos_before = ffmpeg_decoder_get_position(source->video_decoder);
    asciichat_error_t video_err = ffmpeg_decoder_seek_to_timestamp(source->video_decoder, timestamp_sec);
    double video_pos_after = ffmpeg_decoder_get_position(source->video_decoder);
    uint64_t video_seek_ns = time_elapsed_ns(seek_start_ns, time_get_ns());
    char video_seek_str[32];
    time_pretty(video_seek_ns, -1, video_seek_str, sizeof(video_seek_str));
    if (video_err != ASCIICHAT_OK) {
      log_warn("Video seek to %.2f failed: error code %d (took %s)", timestamp_sec, video_err, video_seek_str);
      result = video_err;
    } else {
      log_info("Video SEEK: %.2f → %.2f sec (target %.2f, took %s)", video_pos_before, video_pos_after,
               timestamp_sec, video_seek_str);
    }
  }
 
  // Seek audio decoder (if separate from video)
  if (source->audio_decoder && !source->is_shared_decoder) {
    log_info("=== Starting audio seek to %.2f sec ===", timestamp_sec);
    uint64_t audio_seek_start_ns = time_get_ns();
    double audio_pos_before = ffmpeg_decoder_get_position(source->audio_decoder);
    log_info("Audio position before seek: %.2f", audio_pos_before);
    asciichat_error_t audio_err = ffmpeg_decoder_seek_to_timestamp(source->audio_decoder, timestamp_sec);
    double audio_pos_after = ffmpeg_decoder_get_position(source->audio_decoder);
    uint64_t audio_seek_ns = time_elapsed_ns(audio_seek_start_ns, time_get_ns());
    log_info("Audio position after seek: %.2f", audio_pos_after);
    char audio_seek_str[32];
    time_pretty(audio_seek_ns, -1, audio_seek_str, sizeof(audio_seek_str));
    if (audio_err != ASCIICHAT_OK) {
      log_warn("Audio seek to %.2f failed: error code %d (took %s)", timestamp_sec, audio_err, audio_seek_str);
      result = audio_err;
    } else {
      log_info("Audio SEEK COMPLETE: %.2f → %.2f sec (target %.2f, took %s)", audio_pos_before, audio_pos_after,
               timestamp_sec, audio_seek_str);
    }
  }
 
  // Prefetch thread automatically resumes when seeking_in_progress is cleared and signaled
 
  return result;
}

References ASCIICHAT_OK, media_source_t::audio_ctx, media_source_t::audio_decoder, audio_ring_buffer_clear(), ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, ffmpeg_decoder_get_position(), ffmpeg_decoder_seek_to_timestamp(), media_source_t::is_shared_decoder, log_info, log_warn, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, audio_context_t::playback_buffer, SET_ERRNO, time_elapsed_ns(), time_get_ns(), time_pretty(), media_source_t::type, and media_source_t::video_decoder.

Referenced by session_capture_create(), and session_handle_keyboard_input().

media_source_set_audio_context()

void media_source_set_audio_context	(	media_source_t *	source,
		void *	audio_ctx
	)

#include <source.h>

Set audio context for playback buffer management.

Parameters

source	Media source (must not be NULL)
audio_ctx	Audio context pointer (opaque, may be NULL)

Associates an audio context with the media source. Used to clear playback buffers during seeking to prevent audio lag.

Definition at line 1041 of file source.c.

                                                                             {
  if (source) {
    source->audio_ctx = audio_ctx;
  }
}

References media_source_t::audio_ctx.

Referenced by session_client_like_run().

media_source_set_exit_callback()

void media_source_set_exit_callback	(	media_source_t *	source,
		bool(*)(void *)	should_exit_callback,
		void *	user_data
	)

#include <source.h>

Set exit signal callback for graceful shutdown during I/O.

Parameters

source	Media source (must not be NULL)
callback	Function that returns true if app should exit (can be NULL)
user_data	User data to pass to callback (can be NULL)

Sets a callback on the underlying decoders that allows graceful shutdown when the application is shutting down (e.g., Ctrl+C). This is particularly important for file/HTTP sources where av_read_frame() might block indefinitely.

Purpose: When the user presses Ctrl+C, the signal handler sets the app's exit flag. This callback is polled by FFmpeg's interrupt handler to abort blocking I/O operations, allowing the prefetch thread to exit cleanly instead of hanging indefinitely.

Note

Called automatically from session_capture_create (no need to call manually)

Definition at line 1047 of file source.c.

                                                                                                                   {
  if (!source) {
    return;
  }
 
  // Set exit callback on video decoder if present
  if (source->video_decoder) {
    ffmpeg_decoder_set_exit_callback(source->video_decoder, should_exit_callback, user_data);
  }
 
  // Set exit callback on audio decoder if present (only if different from video decoder)
  if (source->audio_decoder && source->audio_decoder != source->video_decoder) {
    ffmpeg_decoder_set_exit_callback(source->audio_decoder, should_exit_callback, user_data);
  }
}

References media_source_t::audio_decoder, ffmpeg_decoder_set_exit_callback(), and media_source_t::video_decoder.

Referenced by session_capture_create().

media_source_set_loop()

void media_source_set_loop	(	media_source_t *	source,
		bool	loop
	)

#include <source.h>

Enable or disable looping.

Parameters

source	Media source (must not be NULL)
loop	true to enable looping, false to disable

Enables loop mode for media files. When looping is enabled, the media source will automatically seek to the beginning when EOF is reached.

Behavior:

• FILE sources: Seek to beginning on EOF (if seekable)
• STDIN sources: Looping NOT supported (cannot seek stdin)
• WEBCAM/TEST sources: Ignored (infinite by nature)

Note

For stdin, loop flag is silently ignored

Looping works for both video and audio streams

Definition at line 760 of file source.c.

                                                              {
  if (!source) {
    return;
  }
 
  source->loop_enabled = loop;
 
  if (loop && source->type == MEDIA_SOURCE_STDIN) {
    log_warn("Loop mode not supported for stdin input (cannot seek)");
  }
}

References log_warn, media_source_t::loop_enabled, MEDIA_SOURCE_STDIN, and media_source_t::type.

Referenced by session_capture_create().

media_source_toggle_pause()

void media_source_toggle_pause

(

media_source_t *

source

)

#include <source.h>

Toggle pause state of media source.

Parameters

source

Media source (must not be NULL)

Toggles between paused and playing states. If paused, resumes playback. If playing, pauses playback.

Definition at line 1032 of file source.c.

                                                       {
  if (!source) {
    return;
  }
  mutex_lock(&source->pause_mutex);
  source->is_paused = !source->is_paused;
  mutex_unlock(&source->pause_mutex);
}

References media_source_t::is_paused, mutex_lock, mutex_unlock, and media_source_t::pause_mutex.

Referenced by session_handle_keyboard_input().

yt_dlp_extract_stream_url()

asciichat_error_t yt_dlp_extract_stream_url	(	const char *	url,
		const char *	yt_dlp_options,
		char *	output_url,
		size_t	output_size
	)

#include <yt_dlp.h>

Extract stream URL using yt-dlp with optional parameters.

Calls yt-dlp subprocess with –dump-json to extract direct stream URL. Results are cached for 30 seconds.

Parameters

url	Input URL (YouTube, Twitch, direct streams, etc.)
yt_dlp_options	Arbitrary yt-dlp options string e.g., "--cookies-from-browser=chrome --no-warnings" Pass NULL or "" for no extra options
output_url	Output buffer for extracted stream URL
output_size	Size of output buffer (recommend 8192+ bytes)

Returns

ASCIICHAT_OK on success, error code on failure

Note

On failure, logs error context via log_error()

Results are cached to avoid redundant yt-dlp calls

Thread-safe: Uses centralized cache with proper locking

Definition at line 150 of file yt_dlp.c.

                                                                {
  if (!url || !output_url || output_size < 256) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters for yt-dlp URL extraction");
    return ERROR_INVALID_PARAM;
  }
 
  // Check if yt-dlp is available
  if (!yt_dlp_is_available()) {
    SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "yt-dlp is not installed. Please install it with: "
                                            "pip install yt-dlp (or: brew install yt-dlp on macOS)");
    return ERROR_YOUTUBE_EXTRACT_FAILED;
  }
 
  // Check if we have a cached extraction for this URL+options combination
  char cached_url[8192] = {0};
  if (yt_dlp_cache_get(url, yt_dlp_options, cached_url, sizeof(cached_url))) {
    if (cached_url[0] != '\0') {
      // Cached success - return the URL
      SAFE_STRNCPY(output_url, cached_url, output_size - 1);
      output_url[output_size - 1] = '\0';
      return ASCIICHAT_OK;
    } else {
      // Cached failure - return error without logging again
      return ERROR_YOUTUBE_EXTRACT_FAILED;
    }
  }
 
  // Build yt-dlp command
  char command[4096];
  const char *opts = yt_dlp_options ? yt_dlp_options : "";
 
  int cmd_ret;
  if (opts[0] != '\0') {
    // User provided custom options
    cmd_ret = safe_snprintf(command, sizeof(command),
                            "yt-dlp --quiet --no-warnings "
                            "--user-agent 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
                            "AppleWebKit/537.36' "
                            "%s "
                            "-f 'b' -O '%%(url)s' '%s' 2>&1",
                            opts, url);
  } else {
    // No custom options, use default
    cmd_ret = safe_snprintf(command, sizeof(command),
                            "yt-dlp --quiet --no-warnings "
                            "--user-agent 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
                            "AppleWebKit/537.36' "
                            "-f 'b' -O '%%(url)s' '%s' 2>&1",
                            url);
  }
 
  if (cmd_ret < 0 || cmd_ret >= (int)sizeof(command)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "URL or yt-dlp options too long");
    return ERROR_INVALID_PARAM;
  }
 
  log_debug("Executing yt-dlp: %s", command);
 
  // Execute yt-dlp and capture output
  FILE *pipe = NULL;
  if (platform_popen("yt_dlp_extract", command, "r", &pipe) != ASCIICHAT_OK || !pipe) {
    SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "Failed to execute yt-dlp subprocess");
    return ERROR_YOUTUBE_EXTRACT_FAILED;
  }
 
  // Read output looking for stream URL (should be last line starting with http)
  char url_buffer[8192] = {0};
  char full_output[16384] = {0};
  size_t ytdlp_output_len = 0;
  size_t url_size = 0;
  int c;
 
  while ((c = fgetc(pipe)) != EOF && ytdlp_output_len < sizeof(full_output) - 1) {
    full_output[ytdlp_output_len++] = (char)c;
 
    // Track current line - looking for http:// or https:// stream URL
    if ((url_size == 0 && c == 'h') || (url_size > 0 && c != '\n' && url_size < sizeof(url_buffer) - 1)) {
      url_buffer[url_size++] = (char)c;
    } else if (c == '\n') {
      if (url_size > 0) {
        url_buffer[url_size] = '\0';
        if (url_is_valid(url_buffer)) {
          break; // Found valid URL
        }
      }
      url_size = 0; // Reset for next line
    }
  }
  full_output[ytdlp_output_len] = '\0';
  url_buffer[url_size] = '\0';
 
  int pclose_ret = (platform_pclose(&pipe) == ASCIICHAT_OK) ? 0 : -1;
  if (pclose_ret != 0) {
    yt_dlp_cache_set(url, yt_dlp_options, NULL); // Cache failure
 
    log_debug("yt-dlp exited with code %d", pclose_ret);
    if (ytdlp_output_len > 0) {
      log_error("yt-dlp output:\n%s", full_output);
      SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "yt-dlp failed to extract stream: %s", full_output);
    } else {
      SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "yt-dlp failed to extract stream");
    }
    return ERROR_YOUTUBE_EXTRACT_FAILED;
  }
 
  if (url_size == 0 || (url_size == 2 && strncmp(url_buffer, "NA", 2) == 0)) {
    yt_dlp_cache_set(url, yt_dlp_options, NULL);
    log_error("yt-dlp returned empty output for URL: %s", url);
    SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "yt-dlp returned no playable formats");
    return ERROR_YOUTUBE_EXTRACT_FAILED;
  }
 
  if (url_buffer[0] != 'h' || strncmp(url_buffer, "http", 4) != 0) {
    yt_dlp_cache_set(url, yt_dlp_options, NULL);
    log_error("Invalid URL from yt-dlp: %s (full output: %s)", url_buffer, full_output);
    SET_ERRNO(ERROR_YOUTUBE_EXTRACT_FAILED, "yt-dlp returned invalid URL");
    return ERROR_YOUTUBE_EXTRACT_FAILED;
  }
 
  if (url_size >= output_size) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Stream URL too long for output buffer (%zu bytes, max %zu)", url_size, output_size);
    return ERROR_INVALID_PARAM;
  }
 
  SAFE_STRNCPY(output_url, url_buffer, output_size - 1);
  output_url[output_size - 1] = '\0';
 
  // Cache successful result
  yt_dlp_cache_set(url, yt_dlp_options, output_url);
 
  log_debug("yt-dlp successfully extracted stream URL (%zu bytes)", url_size);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_YOUTUBE_EXTRACT_FAILED, log_debug, log_error, platform_pclose(), platform_popen(), safe_snprintf(), SAFE_STRNCPY, SET_ERRNO, url_is_valid(), and yt_dlp_is_available().

yt_dlp_is_available()

bool yt_dlp_is_available

(

void

)

#include <yt_dlp.h>

Check if yt-dlp is installed and accessible.

Runs yt-dlp --version to verify yt-dlp is available in PATH.

Returns

true if yt-dlp –version succeeds, false otherwise

Note

Thread-safe: No static state

Definition at line 143 of file yt_dlp.c.

                               {
  const char *argv[] = {"yt-dlp", "--version", NULL};
  int ret = 0;
  LOG_IO("yt-dlp", { ret = platform_execute_subprocess("yt-dlp", argv, NULL, 0); });
  return (ret == 0);
}

References LOG_IO, and platform_execute_subprocess().

Referenced by yt_dlp_extract_stream_url().