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	ffmpeg_frame_status_t { FFMPEG_FRAME_READY , FFMPEG_FRAME_WAITING , FFMPEG_FRAME_EOF , FFMPEG_FRAME_FAILED }
	Decode next video frame. More...
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.
ffmpeg_frame_status_t	ffmpeg_decoder_poll_video (ffmpeg_decoder_t decoder, image_t frame, asciichat_error_context_t failure)
image_t *	ffmpeg_decoder_read_video_frame (ffmpeg_decoder_t *decoder)
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_urls (const char url, const char yt_dlp_options, char output_url, size_t output_size, char audio_url, size_t audio_size)
	For yt dlp request options, this is the live record that ties proxy_specified together. The owning code creates it, updates it while work is active, and releases its handles and pointed-to storage before freeing the record.
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_H264 \| 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_CAP_STEREO ((uint32_t)(1u << 8))
	Default audio codec capabilities (all codecs supported).
#define	VIDEO_CODEC_SUPPORTED(cap, codec)
	Check if a video codec is supported in capabilities bitmask.
#define	AUDIO_CODEC_SUPPORTED(cap, codec)
	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 interleaved stereo 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 stereo)

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 interleaved stereo float)
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)

COMMAND-LINE EXAMPLES:

# Webcam preview with a deterministic source instead of a camera
ascii-chat mirror --test-pattern --color-mode 256
 
# Play a file repeatedly, starting at one minute and thirty seconds
ascii-chat mirror --file "demo recording.mp4" --loop --seek 01:30
 
# Decode a URL through the normal FFmpeg/yt-dlp resolver
ascii-chat mirror --url "https://example.com/clip.m3u8"
 
# Feed any FFmpeg-readable format through stdin
ffmpeg -i input.mkv -f matroska - | ascii-chat mirror --file -

PROGRAMMATIC EXAMPLE:

media_source_t *source = media_source_create(MEDIA_SOURCE_FILE, "video.mp4");
if (!source) return ERROR_MEDIA;
media_source_set_loop(source, true);
 
for (;;) {
    image_t *frame = media_source_read_video(source);
    if (frame) {
        render_frame(frame);
        continue;
    }
    if (media_source_at_end(source)) break;
    // A temporary decode miss is not EOF; let the capture loop try again.
}
 
float samples[960]; // 20 ms of interleaved 48 kHz stereo float audio
size_t count = media_source_read_audio(source, samples, 960);
(void)count;
media_source_destroy(source);

Note: The CLI examples use the same media-source abstraction as the C API.

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

Date: January 2026

Macro Definition Documentation

◆ AUDIO_CAP_STEREO

#define AUDIO_CAP_STEREO ((uint32_t)(1u << 8))

#include <include/ascii-chat/media/codecs.h>

Default audio codec capabilities (all codecs supported).

Interleaved stereo PCM and stereo Opus output

Definition at line 79 of file codecs.h.

◆ AUDIO_CODEC_SUPPORTED

#define AUDIO_CODEC_SUPPORTED	(		cap,
			codec )

#include <include/ascii-chat/media/codecs.h>

Value:

(((cap) & (1 << (codec))) != 0)

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 98 of file codecs.h.

◆ VIDEO_CODEC_CAP_ALL

#define VIDEO_CODEC_CAP_ALL (VIDEO_CODEC_CAP_H264 | VIDEO_CODEC_CAP_RGBA | VIDEO_CODEC_CAP_H265 | VIDEO_CODEC_CAP_JPEG)

#include <include/ascii-chat/media/codecs.h>

Default video codec capabilities (all codecs supported).

Definition at line 52 of file codecs.h.

Referenced by session_protocol_build_capabilities().

◆ VIDEO_CODEC_SUPPORTED

#define VIDEO_CODEC_SUPPORTED	(		cap,
			codec )

#include <include/ascii-chat/media/codecs.h>

Value:

(((cap) & (1 << (codec))) != 0)

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 89 of file codecs.h.

Referenced by handle_image_frame_h265_packet(), and handle_image_frame_packet().

Typedef Documentation

◆ ffmpeg_decoder_t

typedef struct ffmpeg_decoder_t ffmpeg_decoder_t

#include <include/ascii-chat/media/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 59 of file ffmpeg_decoder.h.

◆ media_source_t

typedef struct media_source_t media_source_t

#include <include/ascii-chat/media/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 121 of file source.h.

Enumeration Type Documentation

◆ ffmpeg_frame_status_t

enum ffmpeg_frame_status_t

#include <include/ascii-chat/media/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:

Read packet from format context
Send packet to video decoder
Receive decoded frame
Convert frame to RGB24 using swscale
Wrap in image_t structure

Note: Returned frame is valid until next call or decoder destruction; Skips non-video packets automatically

Enumerator
FFMPEG_FRAME_READY
FFMPEG_FRAME_WAITING
FFMPEG_FRAME_EOF
FFMPEG_FRAME_FAILED

Definition at line 229 of file ffmpeg_decoder.h.

229{ FFMPEG_FRAME_READY, FFMPEG_FRAME_WAITING, FFMPEG_FRAME_EOF, FFMPEG_FRAME_FAILED } ffmpeg_frame_status_t;

ffmpeg_frame_status_t

Decode next video frame.

Definition ffmpeg_decoder.h:229

FFMPEG_FRAME_READY

@ FFMPEG_FRAME_READY

Definition ffmpeg_decoder.h:229

FFMPEG_FRAME_WAITING

@ FFMPEG_FRAME_WAITING

Definition ffmpeg_decoder.h:229

FFMPEG_FRAME_FAILED

@ FFMPEG_FRAME_FAILED

Definition ffmpeg_decoder.h:229

FFMPEG_FRAME_EOF

@ FFMPEG_FRAME_EOF

Definition ffmpeg_decoder.h:229

◆ media_source_type_t

enum media_source_type_t

#include <include/ascii-chat/media/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 97 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 <include/ascii-chat/media/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 1782 of file ffmpeg_decoder.c.

                                                      {
  return decoder && atomic_load_bool(&decoder->eof_reached);
}

References ffmpeg_decoder_t::eof_reached.

Referenced by ffmpeg_decoder_poll_video(), 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 <include/ascii-chat/media/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:

Open format context (avformat_open_input)
Find stream information (avformat_find_stream_info)
Detect video and audio streams
Open codec contexts for detected streams
Initialize swscale/swresample contexts

Note: Sets errno context on failure; Call ffmpeg_decoder_destroy() to cleanup

Definition at line 769 of file ffmpeg_decoder.c.

                                                          {
  return ffmpeg_decoder_create_interruptible(path, NULL, NULL);
}

References ffmpeg_decoder_create_interruptible().

◆ ffmpeg_decoder_create_stdin()

ffmpeg_decoder_t * ffmpeg_decoder_create_stdin ( void )

#include <include/ascii-chat/media/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 1043 of file ffmpeg_decoder.c.

                                                    {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_CREATE_STDIN);
  // 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 = traced_format_open(&decoder->format_ctx, NULL, NULL, NULL);
    if (ret >= 0) {
      // Find stream info
      if (traced_format_probe(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_optional_codec_context(decoder->format_ctx, AVMEDIA_TYPE_VIDEO,
                                                      &decoder->video_stream_idx, &decoder->video_codec_ctx);
  if (err != ASCIICHAT_OK) {
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  if (GET_OPTION(audio_enabled)) {
    err = open_optional_codec_context(decoder->format_ctx, AVMEDIA_TYPE_AUDIO, &decoder->audio_stream_idx,
                                      &decoder->audio_codec_ctx);
    if (err != ASCIICHAT_OK) {
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  } 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_STEREO;
    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 (decoder->audio_codec_ctx->ch_layout.nb_channels == 1) {
      const double matrix[] = {1.0, 1.0};
      swr_set_matrix(decoder->swr_ctx, matrix, 1);
    }
 
    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 * TARGET_CHANNELS * 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);
  NAMED_REGISTER_ATOMIC(&decoder->eof_reached, "ffmpeg_eof", decoder);
 
  return decoder;
}

Referenced by media_source_create_interruptible().

◆ ffmpeg_decoder_destroy()

void ffmpeg_decoder_destroy ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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:

Stop prefetch thread if running
Free video frame ringbuffer
Free swscale/swresample contexts
Close codec contexts
Close format context
Free frame and packet structures
Free decoder structure

Definition at line 1304 of file ffmpeg_decoder.c.

                                                       {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_DESTROY);
  if (!decoder) {
    return;
  }
 
  NAMED_UNREGISTER(&decoder->eof_reached);
  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;
    cond_signal(&decoder->prefetch_cond);
    mutex_unlock(&decoder->prefetch_mutex);
 
    // Wait for thread to finish
    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);
}

Referenced by ffmpeg_decoder_create_stdin(), ffmpeg_decoder_create_with_request_options(), http_renderer_render_file(), media_source_create_interruptible(), and media_source_destroy().

◆ ffmpeg_decoder_get_duration()

double ffmpeg_decoder_get_duration ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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 1786 of file 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 <include/ascii-chat/media/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 1798 of file 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 <include/ascii-chat/media/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 1529 of file ffmpeg_decoder.c.

                                                                                                          {
  if (!decoder || decoder->video_stream_idx < 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Decoder has no video stream");
  }
 
  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, height, SET_ERRNO, ffmpeg_decoder_t::video_codec_ctx, ffmpeg_decoder_t::video_stream_idx, and width.

◆ ffmpeg_decoder_get_video_fps()

double ffmpeg_decoder_get_video_fps ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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 1544 of file 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 <include/ascii-chat/media/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 1692 of file ffmpeg_decoder.c.

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

References ffmpeg_decoder_t::audio_stream_idx.

Referenced by media_source_create_interruptible(), and media_source_has_audio().

◆ ffmpeg_decoder_has_video()

bool ffmpeg_decoder_has_video ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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 1525 of file ffmpeg_decoder.c.

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

References ffmpeg_decoder_t::video_stream_idx.

Referenced by media_source_create_interruptible(), and media_source_has_video().

◆ ffmpeg_decoder_is_prefetch_running()

bool ffmpeg_decoder_is_prefetch_running ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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 1518 of file ffmpeg_decoder.c.

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

References ffmpeg_decoder_t::prefetch_thread_running.

◆ ffmpeg_decoder_poll_video()

ffmpeg_frame_status_t ffmpeg_decoder_poll_video	(	ffmpeg_decoder_t *	decoder,
		image_t **	frame,
		asciichat_error_context_t *	failure )

#include <include/ascii-chat/media/ffmpeg_decoder.h>

Failure is an owned snapshot; no worker stack or thread lifetime dependency.

Definition at line 1396 of file ffmpeg_decoder.c.

                                                                                    {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_POLL_VIDEO);
  if (frame)
    *frame = NULL;
  if (failure)
    memset(failure, 0, sizeof(*failure));
  if (!decoder || !frame || !failure) {
    asciichat_errno_scope_t scope = errno_checkpoint();
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid video poll outputs");
    if (failure && !errno_peek_since(scope, failure))
      failure->code = ERROR_INVALID_PARAM;
    return FFMPEG_FRAME_FAILED;
  }
  // Empty polls need no protected state. EOF and errors still confirm under
  // the mutex so a final pending frame takes precedence over termination.
  if (!atomic_load_explicit(&decoder->prefetch_frame_ready, memory_order_acquire) &&
      !atomic_load_explicit(&decoder->prefetch_failed, memory_order_acquire) && !ffmpeg_decoder_at_end(decoder))
    return FFMPEG_FRAME_WAITING;
 
  mutex_lock(&decoder->prefetch_mutex);
  if (decoder->prefetch_frame_ready && decoder->current_prefetch_image) {
    // Taking the next image releases the previous reader-owned buffer.
    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;
    *frame = decoder->current_prefetch_image;
    decoder->prefetch_frame_ready = false;
    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;
    decoder->current_image = *frame;
    cond_signal(&decoder->prefetch_cond);
    mutex_unlock(&decoder->prefetch_mutex);
    return FFMPEG_FRAME_READY;
  }
  *failure = decoder->prefetch_failure;
  bool eof = ffmpeg_decoder_at_end(decoder);
  mutex_unlock(&decoder->prefetch_mutex);
  if (failure->code != ASCIICHAT_OK)
    return FFMPEG_FRAME_FAILED;
  return eof ? FFMPEG_FRAME_EOF : FFMPEG_FRAME_WAITING;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ffmpeg_decoder_t::buffer_a_in_use, ffmpeg_decoder_t::buffer_b_in_use, asciichat_error_context_t::code, ffmpeg_decoder_t::current_image, ffmpeg_decoder_t::current_prefetch_image, ffmpeg_decoder_t::current_read_buffer, errno_checkpoint(), errno_peek_since(), ERROR_INVALID_PARAM, ffmpeg_decoder_at_end(), FFMPEG_FRAME_EOF, FFMPEG_FRAME_FAILED, FFMPEG_FRAME_READY, FFMPEG_FRAME_WAITING, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_failed, ffmpeg_decoder_t::prefetch_failure, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_image_a, ffmpeg_decoder_t::prefetch_image_b, ffmpeg_decoder_t::prefetch_mutex, and SET_ERRNO.

Referenced by ffmpeg_decoder_read_video_frame(), and http_renderer_render_file().

◆ ffmpeg_decoder_read_audio_samples()

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

#include <include/ascii-chat/media/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 interleaved stereo float format, compatible with ascii-chat's Opus encoding.

Audio format:

Format: 32-bit float
Channels: Stereo (2 channels); sample counts include both channels
Sample rate: 48000 Hz
Range: -1.0 to 1.0

Decoding process:

Read packet from format context
Send packet to audio decoder
Receive decoded frame
Resample to 48kHz stereo using swresample
Copy to output buffer

Note: Skips non-audio packets automatically; May return fewer samples than requested at EOF

Definition at line 1568 of file ffmpeg_decoder.c.

                                                                                                       {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_READ_AUDIO_SAMPLES);
  // Keep channels and the playback clock aligned even with odd caller capacity.
  num_samples -= num_samples % TARGET_CHANNELS;
  if (!decoder || decoder->audio_stream_idx < 0 || !buffer || num_samples == 0) {
    return 0;
  }
 
  mutex_lock(&decoder->read_frame_mutex);
  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 / TARGET_CHANNELS;
      mutex_unlock(&decoder->read_frame_mutex);
      return samples_written;
    }
  }
 
  // Read more packets to fill the request
  static uint64_t packet_count = 0;
 
  while (samples_written < num_samples) {
    int ret = traced_packet_read(decoder->format_ctx, decoder->packet);
    if (ret < 0) {
      if (ret == AVERROR_EOF) {
        atomic_store_bool(&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;
    }
 
    packet_count++;
    log_debug_every(US_PER_SEC_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 = traced_packet_send(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_every(US_PER_SEC_INT, "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 = traced_frame_receive(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_every(US_PER_SEC_INT, "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 =
          traced_audio_resample(decoder->swr_ctx, &out_ptr, (int)(decoder->audio_buffer_size / TARGET_CHANNELS),
                                (const uint8_t **)decoder->frame->data, decoder->frame->nb_samples);
 
      if (converted > 0) {
        size_t available = (size_t)converted * TARGET_CHANNELS;
        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:
  // 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 && atomic_load_bool(&decoder->eof_reached)) {
    int remaining_space = (int)((num_samples - samples_written) / TARGET_CHANNELS);
    uint8_t *out_ptr = (uint8_t *)(buffer + samples_written);
    int flushed = traced_audio_resample(decoder->swr_ctx, &out_ptr, remaining_space, NULL, 0);
    if (flushed > 0) {
      samples_written += (size_t)flushed * TARGET_CHANNELS;
    }
  }
 
  // Update sample-based position tracking
  decoder->audio_samples_read += samples_written / TARGET_CHANNELS;
  mutex_unlock(&decoder->read_frame_mutex);
 
  return samples_written;
}

Referenced by media_source_read_audio().

◆ ffmpeg_decoder_read_video_frame()

image_t * ffmpeg_decoder_read_video_frame ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/ffmpeg_decoder.h>

Definition at line 1443 of file ffmpeg_decoder.c.

                                                                    {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_READ_VIDEO_FRAME);
  image_t *frame = NULL;
  asciichat_error_context_t failure = {0};
  if (ffmpeg_decoder_poll_video(decoder, &frame, &failure) == FFMPEG_FRAME_FAILED)
    errno_import(&failure);
  return frame;
}

References ASCII_OTEL_SCOPE, errno_import(), ffmpeg_decoder_poll_video(), and FFMPEG_FRAME_FAILED.

Referenced by media_source_read_video().

◆ ffmpeg_decoder_rewind()

asciichat_error_t ffmpeg_decoder_rewind ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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:

Flush codec buffers (avcodec_flush_buffers)
Seek to timestamp 0 (av_seek_frame)
Clear decoder state

Note: Stdin decoders cannot seek (returns ERROR_NOT_SUPPORTED); Some formats may not support seeking

Definition at line 1700 of file ffmpeg_decoder.c.

                                                                   {
  return ffmpeg_decoder_seek_to_timestamp(decoder, 0);
}

References ffmpeg_decoder_seek_to_timestamp().

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 <include/ascii-chat/media/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:

Flush codec buffers (avcodec_flush_buffers)
Seek to timestamp (av_seek_frame with AV_TIME_BASE conversion)
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 1704 of file ffmpeg_decoder.c.

                                                                                                    {
  ASCII_OTEL_SCOPE(FFMPEG_DECODER_SEEK_TO_TIMESTAMP);
  if (!decoder) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing decoder for seek");
  }
 
  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;
  ++decoder->seek_generation;
  // Serialize codec and partial-audio state with the existing packet reader.
  mutex_lock(&decoder->read_frame_mutex);
  // The old reader has stopped. Holding both guards prevents another read;
  // the seek must not cancel its own I/O through the interrupt callback.
  decoder->seeking_in_progress = false;
  if (decoder->format_ctx->pb && decoder->format_ctx->pb->error == AVERROR_EXIT)
    decoder->format_ctx->pb->error = 0;
 
  // 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;
    mutex_unlock(&decoder->read_frame_mutex);
    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
  atomic_store_bool(&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);
 
  // The consumer retains its image across seeks until it takes a replacement.
 
  // Resume prefetch thread
  decoder->seeking_in_progress = false;
  mutex_unlock(&decoder->read_frame_mutex);
  cond_signal(&decoder->prefetch_cond);
 
  // Release mutex - prefetch thread can resume
  mutex_unlock(&decoder->prefetch_mutex);
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, 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::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, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_frame_ready, ffmpeg_decoder_t::prefetch_mutex, ffmpeg_decoder_t::read_frame_mutex, ffmpeg_decoder_t::seek_generation, ffmpeg_decoder_t::seeking_in_progress, SET_ERRNO, ffmpeg_decoder_t::video_codec_ctx, and ffmpeg_decoder_t::video_draining.

Referenced by ffmpeg_decoder_rewind(), and media_source_seek().

◆ ffmpeg_decoder_set_exit_callback()

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

#include <include/ascii-chat/media/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 1509 of file ffmpeg_decoder.c.

                                                       {
  if (!decoder) {
    return;
  }
  atomic_ptr_store(&decoder->exit_callback_user_data, user_data);
  atomic_ptr_store(&decoder->should_exit_callback, (void *)should_exit_callback);
}

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 <include/ascii-chat/media/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 1459 of file ffmpeg_decoder.c.

                                                                           {
  if (!decoder || decoder->video_stream_idx < 0) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Decoder has no initialized video prefetch buffers");
  }
 
  if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Decoder has no initialized video prefetch buffers");
  }
 
  // Already running
  if (decoder->prefetch_thread_running) {
    return ASCIICHAT_OK;
  }
 
  // Reset stop flag and create thread
  decoder->prefetch_should_stop = false;
  memset(&decoder->prefetch_failure, 0, sizeof(decoder->prefetch_failure));
  atomic_store(&decoder->prefetch_failed, false);
 
  int thread_err = platform_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, ERROR_INVALID_PARAM, ERROR_THREAD, ffmpeg_decoder_t::prefetch_failed, ffmpeg_decoder_t::prefetch_failure, 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 http_renderer_render_file(), and media_source_create_interruptible().

◆ ffmpeg_decoder_stop_prefetch()

void ffmpeg_decoder_stop_prefetch ( ffmpeg_decoder_t * decoder )

#include <include/ascii-chat/media/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 1491 of file ffmpeg_decoder.c.

                                                             {
  if (!decoder || !decoder->prefetch_thread_running) {
    return;
  }
 
  mutex_lock(&decoder->prefetch_mutex);
  decoder->prefetch_should_stop = true;
  cond_signal(&decoder->prefetch_cond);
  mutex_unlock(&decoder->prefetch_mutex);
  // Wait up to 2 seconds for thread to stop
  // The interrupt callback should cause av_read_frame to abort quickly
  if (thread_join_timeout(&decoder->prefetch_thread, NULL, 2000 * NS_PER_MS_INT) == ASCIICHAT_OK)
    decoder->prefetch_thread_running = false;
  // A timed-out worker remains owned and must be joined by decoder destruction.
  else
    log_warn("Video prefetch thread is still stopping");
}

References ASCIICHAT_OK, log_warn, NS_PER_MS_INT, ffmpeg_decoder_t::prefetch_cond, ffmpeg_decoder_t::prefetch_mutex, 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 <include/ascii-chat/media/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 836 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 ffmpeg_decoder_at_end(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and source.

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 <include/ascii-chat/media/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 221 of file source.c.

                                                                                {
  return media_source_create_interruptible(type, path, NULL, NULL);
}

References media_source_create_interruptible().

◆ media_source_destroy()

void media_source_destroy ( media_source_t * source )

#include <include/ascii-chat/media/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 508 of file source.c.

                                                  {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_DESTROY);
  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
  test_pattern_destroy(source->test_pattern);
  source->test_pattern = NULL;
 
  NAMED_UNREGISTER(&source->is_paused);
 
  // Destroy mutexes
  mutex_destroy(&source->decoder_mutex);
 
  SAFE_FREE(source);
}

References ASCII_OTEL_SCOPE, ffmpeg_decoder_destroy(), NAMED_UNREGISTER, SAFE_FREE, source, test_pattern_destroy(), and webcam_cleanup_context().

Referenced by session_capture_create(), and session_capture_destroy().

◆ media_source_get_duration()

double media_source_get_duration ( media_source_t * source )

#include <include/ascii-chat/media/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 1003 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, and source.

◆ media_source_get_position()

double media_source_get_position ( media_source_t * source )

#include <include/ascii-chat/media/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 1025 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 ffmpeg_decoder_get_position(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and source.

◆ media_source_get_type()

media_source_type_t media_source_get_type ( media_source_t * source )

#include <include/ascii-chat/media/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 999 of file source.c.

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

References MEDIA_SOURCE_TEST, and source.

Referenced by session_capture_at_end(), session_capture_toggle_media(), and session_pipeline_create().

◆ media_source_get_video_fps()

double media_source_get_video_fps ( media_source_t * source )

#include <include/ascii-chat/media/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 the negotiated capture rate when available; TEST sources return 0.0; FILE/STDIN sources return the video stream's fps from FFmpeg

Definition at line 1047 of file source.c.

                                                          {
  if (!source) {
    return 0.0;
  }
 
  switch (source->type) {
  case MEDIA_SOURCE_WEBCAM:
    return source->webcam_ctx ? webcam_get_fps(source->webcam_ctx) : 0.0;
  case MEDIA_SOURCE_TEST:
    return 0.0;
 
  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, source, and webcam_get_fps().

Referenced by session_capture_create().

◆ media_source_has_audio()

bool media_source_has_audio ( media_source_t * source )

#include <include/ascii-chat/media/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 801 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 ffmpeg_decoder_has_audio(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and source.

Referenced by audio_connection_init(), audio_start_duplex(), session_audio_start_duplex(), session_capture_create(), and session_participant_start_audio().

◆ media_source_has_video()

bool media_source_has_video ( media_source_t * source )

#include <include/ascii-chat/media/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 699 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 ffmpeg_decoder_has_video(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and source.

◆ media_source_is_paused()

bool media_source_is_paused ( media_source_t * source )

#include <include/ascii-chat/media/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 1088 of file source.c.

                                                    {
  if (!source) {
    return false;
  }
  return atomic_load_bool(&source->is_paused);
}

References source.

◆ media_source_pause()

void media_source_pause ( media_source_t * source )

#include <include/ascii-chat/media/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 1074 of file source.c.

                                                {
  if (!source) {
    return;
  }
  atomic_store_bool(&source->is_paused, true);
}

References source.

◆ media_source_read_audio()

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

#include <include/ascii-chat/media/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, interleaved stereo, 48kHz sample rate (compatible with Opus encoding).

Audio format:

Format: 32-bit float
Channels: Stereo (2 channels); sample counts include both channels
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 stereo automatically

Definition at line 722 of file source.c.

                                                                                          {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_READ_AUDIO);
  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_debug("#%lu: source_type=%d num_samples=%zu", call_count, source->type, num_samples);
  }
 
  // Check pause state (thread-safe)
  bool is_paused = atomic_load_bool(&source->is_paused);
 
  // 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_every(US_PER_SEC_INT, "audio_decoder is NULL!");
      return 0;
    }
 
    // 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_debug_every(US_PER_SEC_INT, "Audio position moved 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_debug_every(US_PER_SEC_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);
    }
 
    return samples_read;
  }
 
  default:
    return 0;
  }
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ffmpeg_decoder_at_end(), ffmpeg_decoder_get_position(), ffmpeg_decoder_read_audio_samples(), log_debug, log_debug_every, log_warn_every, MEDIA_SOURCE_FILE, media_source_rewind(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, source, and US_PER_SEC_INT.

◆ media_source_read_video()

image_t * media_source_read_video ( media_source_t * source )

#include <include/ascii-chat/media/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 592 of file source.c.

                                                         {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_READ_VIDEO);
  if (!source) {
    return NULL;
  }
 
  // Check pause state (thread-safe)
  bool is_paused = atomic_load_bool(&source->is_paused);
 
  // Return NULL immediately if paused (maintaining position)
  if (is_paused) {
    return NULL;
  }
 
  if (source->audio_only && media_source_at_end(source))
    return NULL;
  // Audio visualizations replace the image at display time and need only a frame clock.
  if ((source->audio_only && GET_OPTION(test_pattern)) ||
      ((source->audio_only || source->type == MEDIA_SOURCE_WEBCAM) && (GET_OPTION(waveform) || GET_OPTION(fft))))
    return read_test_pattern(source);
  if ((source->audio_only || source->type == MEDIA_SOURCE_WEBCAM) && !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_debug_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 ASCII_OTEL_SCOPE, ASCIICHAT_OK, ffmpeg_decoder_at_end(), ffmpeg_decoder_read_video_frame(), GET_OPTION, log_debug, log_debug_every, media_source_at_end(), MEDIA_SOURCE_FILE, media_source_rewind(), media_source_start_video(), MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, NS_PER_MS, source, time_elapsed_ns(), US_PER_SEC_INT, and webcam_read_context().

◆ media_source_resume()

void media_source_resume ( media_source_t * source )

#include <include/ascii-chat/media/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 1081 of file source.c.

                                                 {
  if (!source) {
    return;
  }
  atomic_store_bool(&source->is_paused, false);
}

References source.

◆ media_source_rewind()

asciichat_error_t media_source_rewind ( media_source_t * source )

#include <include/ascii-chat/media/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 864 of file source.c.

                                                              {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_REWIND);
  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 =
        source->video_decoder ? ffmpeg_decoder_rewind(source->video_decoder) : ASCIICHAT_OK;
    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 && source->audio_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 ASCII_OTEL_SCOPE, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, ffmpeg_decoder_rewind(), MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, and source.

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 <include/ascii-chat/media/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 917 of file source.c.

                                                                                  {
  ASCII_OTEL_SCOPE(MEDIA_SOURCE_SEEK);
  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[TIME_DURATION_BUFFER_SIZE];
    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 %s (took %s)", timestamp_sec, asciichat_error_format(NULL, video_err),
               video_seek_str);
      result = video_err;
    } else {
      log_debug("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_debug("=== 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_debug("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_debug("Audio position after seek: %.2f", audio_pos_after);
    char audio_seek_str[TIME_DURATION_BUFFER_SIZE];
    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 %s (took %s)", timestamp_sec, asciichat_error_format(NULL, audio_err),
               audio_seek_str);
      result = audio_err;
    } else {
      log_debug("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 ASCII_OTEL_SCOPE, asciichat_error_format(), ASCIICHAT_OK, audio_ring_buffer_clear(), ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, ffmpeg_decoder_get_position(), ffmpeg_decoder_seek_to_timestamp(), log_debug, log_warn, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, audio_context_t::playback_buffer, SET_ERRNO, source, TIME_DURATION_BUFFER_SIZE, time_elapsed_ns(), and time_pretty().

Referenced by session_capture_create().

◆ media_source_set_audio_context()

void media_source_set_audio_context	(	media_source_t *	source,
		void *	audio_ctx )

#include <include/ascii-chat/media/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 1104 of file source.c.

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

References source.

◆ media_source_set_exit_callback()

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

#include <include/ascii-chat/media/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 1110 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 ffmpeg_decoder_set_exit_callback(), and source.

Referenced by session_capture_create().

◆ media_source_set_loop()

void media_source_set_loop	(	media_source_t *	source,
		bool	loop )

#include <include/ascii-chat/media/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 824 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_STDIN, and source.

Referenced by session_capture_create().

◆ media_source_toggle_pause()

void media_source_toggle_pause ( media_source_t * source )

#include <include/ascii-chat/media/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 1095 of file source.c.

                                                       {
  if (!source) {
    return;
  }
  bool paused = atomic_load_bool(&source->is_paused);
  while (!atomic_cas_bool(&source->is_paused, &paused, !paused)) {
  }
}

References source.

◆ yt_dlp_extract_stream_urls()

asciichat_error_t yt_dlp_extract_stream_urls	(	const char *	url,
		const char *	yt_dlp_options,
		char *	output_url,
		size_t	output_size,
		char *	audio_url,
		size_t	audio_size )

#include <include/ascii-chat/media/yt_dlp.h>

For yt dlp request options, this is the live record that ties proxy_specified together. The owning code creates it, updates it while work is active, and releases its handles and pointed-to storage before freeing the record.

Extract stream URL using yt-dlp with optional parameters

Prefers a combined stream, falling back to separate video and audio streams. 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" Quotes group arguments; no shell expansion is performed. Pass NULL or "" for no extra options.
output_url	Output buffer for extracted stream URL
output_size	Size of output buffer (recommend 8192+ bytes)
audio_url	Output buffer for a separate audio URL, or an empty string when the first URL contains both streams
audio_size	Size of the audio URL buffer

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

Definition at line 552 of file yt_dlp.c.

                                                                                                     {
  return yt_dlp_extract_stream_urls_interruptible(url, yt_dlp_options, output_url, output_size, audio_url, audio_size,
                                                  NULL, NULL);
}

References yt_dlp_extract_stream_urls_interruptible().

Referenced by yt_dlp_extract_stream_url().

◆ yt_dlp_is_available()

bool yt_dlp_is_available ( void )

#include <include/ascii-chat/media/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 178 of file yt_dlp.c.

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

References ASCII_OTEL_ATTR_STRING, ASCII_OTEL_SCOPE, LOG_IO, and platform_execute_subprocess().

Files

Typedefs

Enumerations

Functions

Video Codec Bitmask Constants

Audio Codec Bitmask Constants

Detailed Description

CORE FEATURES:

FFMPEG LIBRARIES USED:

SUPPORTED CODECS:

CORE FEATURES:

SUPPORTED SOURCES:

SUPPORTED FORMATS:

COMMAND-LINE EXAMPLES:

PROGRAMMATIC EXAMPLE:

Macro Definition Documentation

◆ AUDIO_CAP_STEREO

◆ AUDIO_CODEC_SUPPORTED

◆ VIDEO_CODEC_CAP_ALL

◆ VIDEO_CODEC_SUPPORTED

Typedef Documentation

◆ ffmpeg_decoder_t

◆ media_source_t

THREAD SAFETY:

Enumeration Type Documentation

◆ ffmpeg_frame_status_t

◆ media_source_type_t

Function Documentation

◆ ffmpeg_decoder_at_end()

◆ ffmpeg_decoder_create()

◆ ffmpeg_decoder_create_stdin()

◆ ffmpeg_decoder_destroy()

◆ ffmpeg_decoder_get_duration()

◆ ffmpeg_decoder_get_position()

◆ ffmpeg_decoder_get_video_dimensions()

◆ ffmpeg_decoder_get_video_fps()

◆ ffmpeg_decoder_has_audio()

◆ ffmpeg_decoder_has_video()

◆ ffmpeg_decoder_is_prefetch_running()

◆ ffmpeg_decoder_poll_video()

◆ ffmpeg_decoder_read_audio_samples()

◆ ffmpeg_decoder_read_video_frame()

◆ ffmpeg_decoder_rewind()

◆ ffmpeg_decoder_seek_to_timestamp()

◆ ffmpeg_decoder_set_exit_callback()

◆ ffmpeg_decoder_start_prefetch()

◆ ffmpeg_decoder_stop_prefetch()

◆ media_source_at_end()

◆ media_source_create()

◆ media_source_destroy()

◆ media_source_get_duration()

◆ media_source_get_position()

◆ media_source_get_type()

◆ media_source_get_video_fps()

◆ media_source_has_audio()

◆ media_source_has_video()

◆ media_source_is_paused()

◆ media_source_pause()

◆ media_source_read_audio()

◆ media_source_read_video()

◆ media_source_resume()

◆ media_source_rewind()

◆ media_source_seek()

◆ media_source_set_audio_context()

◆ media_source_set_exit_callback()

◆ media_source_set_loop()

◆ media_source_toggle_pause()

◆ yt_dlp_extract_stream_urls()

◆ yt_dlp_is_available()