media/ffmpeg_decoder.c

Go to the documentation of this file.

 
#include <ascii-chat/media/ffmpeg_decoder.h>
#include <ascii-chat/common.h>
#include <ascii-chat/log/log.h>
#include <ascii-chat/log/io.h>
#include <ascii-chat/debug/named.h>
#include <ascii-chat/asciichat_errno.h>
#include <ascii-chat/video/rgba/image.h>
#include <ascii-chat/platform/system.h>
#include <ascii-chat/platform/thread.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/util/url.h>
#include <ascii-chat/options/options.h>
 
#include <libavformat/avformat.h>
#include <libavcodec/avcodec.h>
#include <libavutil/imgutils.h>
#include <libavutil/opt.h>
#include <libavutil/log.h>
#include <libswscale/swscale.h>
#include <libswresample/swresample.h>
#include <string.h>
#include <inttypes.h>
 
/* ============================================================================
 * FFmpeg Logging Suppression
 * ============================================================================ */
 
static void ffmpeg_silent_log_callback(void *avcl, int level, const char *fmt, va_list vl) {
  (void)avcl;  // unused
  (void)level; // unused
  (void)fmt;   // unused
  (void)vl;    // unused
  // Do nothing - silently discard all FFmpeg logs
}
 
/* ============================================================================
 * Constants
 * ============================================================================ */
 
#define TARGET_SAMPLE_RATE 48000
 
#define TARGET_CHANNELS 1
 
#define AVIO_BUFFER_SIZE (64 * 1024)
 
/* ============================================================================
 * FFmpeg Decoder Structure
 * ============================================================================ */
 
struct ffmpeg_decoder_t {
  // Format context
  AVFormatContext *format_ctx; 
 
  // Video stream
  AVCodecContext *video_codec_ctx; 
  int video_stream_idx;            
  struct SwsContext *sws_ctx;      
 
  // Audio stream
  AVCodecContext *audio_codec_ctx; 
  int audio_stream_idx;            
  struct SwrContext *swr_ctx;      
 
  // Frame and packet buffers
  AVFrame *frame;   
  AVPacket *packet; 
 
  // Decoded image cache - double-buffered for prefetching
  image_t *current_image; 
 
  // Audio sample buffer (for partial frame handling)
  float *audio_buffer;        
  size_t audio_buffer_size;   
  size_t audio_buffer_offset; 
 
  // Background thread for frame prefetching (reduces YouTube HTTP blocking)
  asciichat_thread_t prefetch_thread; 
  image_t *prefetch_image_a;          
  image_t *prefetch_image_b;          
  image_t *current_prefetch_image;    
  bool prefetch_frame_ready;          
  bool prefetch_thread_running;       
  bool prefetch_should_stop;          
  bool seeking_in_progress;           
  cond_t prefetch_cond;               
  mutex_t prefetch_mutex;             
  mutex_t read_frame_mutex;           
 
  // Track which buffer is being read by main thread
  image_t *current_read_buffer; 
  bool buffer_a_in_use;         
  bool buffer_b_in_use;         
 
  // State flags
  bool eof_reached;    
  bool is_stdin;       
  bool video_draining; 
 
  // Stdin I/O context
  AVIOContext *avio_ctx;      
  unsigned char *avio_buffer; 
 
  // Position tracking
  double last_video_pts; 
  double last_audio_pts; 
 
  // Sample-based position tracking
  uint64_t audio_samples_read; 
  int audio_sample_rate;       
 
  // Exit signal callback (for graceful shutdown during blocking I/O)
  bool (*should_exit_callback)(void *user_data); 
  void *exit_callback_user_data;                 
};
 
/* ============================================================================
 * Stdin I/O Callbacks
 * ============================================================================ */
 
/* ============================================================================
 * Memory-based AVIO for stdin buffering
 * ============================================================================ */
 
typedef struct {
  uint8_t *data; 
  size_t size;   
} stdin_buffer_t;
 
typedef struct {
  stdin_buffer_t *buffer; 
  size_t pos;             
} stdin_buffer_reader_t;
 
static int memory_read_packet(void *opaque, uint8_t *buf, int buf_size) {
  stdin_buffer_reader_t *reader = (stdin_buffer_reader_t *)opaque;
 
  if (!reader || !reader->buffer || reader->pos >= reader->buffer->size)
    return AVERROR_EOF;
 
  int to_read = buf_size;
  if (reader->pos + to_read > reader->buffer->size)
    to_read = (int)(reader->buffer->size - reader->pos);
 
  memcpy(buf, reader->buffer->data + reader->pos, to_read);
  reader->pos += to_read;
 
  return to_read;
}
 
static int64_t memory_seek_packet(void *opaque, int64_t offset, int whence) {
  stdin_buffer_reader_t *reader = (stdin_buffer_reader_t *)opaque;
 
  if (!reader || !reader->buffer)
    return -1;
 
  int64_t new_pos = 0;
  if (whence == SEEK_SET) {
    new_pos = offset;
  } else if (whence == SEEK_CUR) {
    new_pos = (int64_t)reader->pos + offset;
  } else if (whence == SEEK_END) {
    new_pos = (int64_t)reader->buffer->size + offset;
  } else {
    return -1;
  }
 
  if (new_pos < 0 || new_pos > (int64_t)reader->buffer->size)
    return -1;
 
  reader->pos = (size_t)new_pos;
  return new_pos;
}
 
static stdin_buffer_t *stdin_buffer_read_all(void) {
  stdin_buffer_t *sb = SAFE_MALLOC(sizeof(stdin_buffer_t), stdin_buffer_t *);
  if (!sb)
    return NULL;
 
  sb->data = NULL;
  sb->size = 0;
 
  // Read stdin in 64KB chunks
  const size_t chunk_size = 65536;
  uint8_t chunk_buffer[chunk_size];
  size_t total_capacity = 0;
  int chunk_count = 0;
 
  while (1) {
    size_t bytes_read = fread(chunk_buffer, 1, chunk_size, stdin);
    if (bytes_read == 0)
      break;
    chunk_count++;
 
    // Grow buffer if needed
    if (sb->size + bytes_read > total_capacity) {
      total_capacity = (sb->size + bytes_read) * 2; // Always double capacity
      uint8_t *new_data = SAFE_MALLOC(total_capacity, uint8_t *);
      if (!new_data) {
        SAFE_FREE(sb->data);
        SAFE_FREE(sb);
        return NULL;
      }
      if (sb->data) {
        memcpy(new_data, sb->data, sb->size);
        SAFE_FREE(sb->data);
      }
      sb->data = new_data;
    }
 
    // Copy chunk to buffer
    memcpy(sb->data + sb->size, chunk_buffer, bytes_read);
    sb->size += bytes_read;
  }
 
  log_info("Buffered stdin: %zu bytes in %d chunks (capacity: %zu)", sb->size, chunk_count, total_capacity);
  if (sb->size > 0) {
    log_info(
        "  First 16 bytes of stdin: %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x %02x",
        sb->data[0], sb->data[1], sb->data[2], sb->data[3], sb->data[4], sb->data[5], sb->data[6], sb->data[7],
        sb->data[8], sb->data[9], sb->data[10], sb->data[11], sb->data[12], sb->data[13], sb->data[14], sb->data[15]);
  }
  return sb;
}
 
static stdin_buffer_t *g_stdin_buffer = NULL;
 
/* ============================================================================
 * Helper Functions
 * ============================================================================ */
 
static inline double av_q2d_safe(AVRational r) {
  return (r.den != 0) ? ((double)r.num / (double)r.den) : 0.0;
}
 
static double get_frame_pts_seconds(AVFrame *frame, AVRational time_base) {
  if (frame->pts == AV_NOPTS_VALUE) {
    return -1.0;
  }
  return (double)frame->pts * av_q2d_safe(time_base);
}
 
static int ffmpeg_interrupt_callback(void *opaque) {
  ffmpeg_decoder_t *decoder = (ffmpeg_decoder_t *)opaque;
  if (!decoder) {
    return 0;
  }
 
  // Interrupt av_read_frame() if a seek is in progress
  if (decoder->seeking_in_progress) {
    return 1;
  }
 
  // Interrupt av_read_frame() if application is shutting down
  // This allows Ctrl+C to abort blocking I/O operations like YouTube HTTP requests
  if (decoder->should_exit_callback && decoder->should_exit_callback(decoder->exit_callback_user_data)) {
    return 1;
  }
 
  return 0;
}
 
static void *ffmpeg_decoder_prefetch_thread_func(void *arg) {
  ffmpeg_decoder_t *decoder = (ffmpeg_decoder_t *)arg;
  if (!decoder || !decoder->prefetch_image_a || !decoder->prefetch_image_b) {
    return NULL;
  }
 
  log_debug("Video prefetch thread started");
  bool use_image_a = true; // Track which buffer we're using (critical for correct buffer swapping)
 
  while (true) {
    mutex_lock(&decoder->prefetch_mutex);
 
    // Check if thread should stop
    bool should_stop = decoder->prefetch_should_stop || decoder->eof_reached;
    if (should_stop) {
      mutex_unlock(&decoder->prefetch_mutex);
      break;
    }
 
    // Pause if seek is in progress - wait for signal to continue
    // cond_wait automatically releases and re-acquires mutex
    while (decoder->seeking_in_progress) {
      cond_wait(&decoder->prefetch_cond, &decoder->prefetch_mutex);
    }
 
    // Mutex is re-acquired after cond_wait - KEEP IT HELD
 
    // Keep at most one decoded frame pending. Without this check, the producer
    // can overwrite current_prefetch_image repeatedly and reach EOF before the
    // consumer has observed the intervening frames.
    if (decoder->prefetch_frame_ready) {
      mutex_unlock(&decoder->prefetch_mutex);
      platform_sleep_us(1 * US_PER_MS_INT);
      continue;
    }
 
    // Check if the buffer we want to use is still in use by the main thread
    // If so, skip this iteration and try again later
    bool buffer_in_use = use_image_a ? decoder->buffer_a_in_use : decoder->buffer_b_in_use;
    if (buffer_in_use) {
      // Can't use this buffer yet - main thread is still rendering it
      mutex_unlock(&decoder->prefetch_mutex);
      platform_sleep_us(1 * US_PER_MS_INT); // 1ms - brief sleep before retry
      continue;
    }
 
    uint64_t read_start_ns = time_get_ns();
    bool frame_decoded = false;
 
    // Release prefetch mutex but hold read_frame_mutex to prevent concurrent av_read_frame() calls from audio thread
    mutex_unlock(&decoder->prefetch_mutex);
    mutex_lock(&decoder->read_frame_mutex);
 
    // Read packets until we get a video frame - read_frame_mutex HELD
    while (true) {
      int ret;
      if (decoder->video_draining) {
        ret = avcodec_receive_frame(decoder->video_codec_ctx, decoder->frame);
        if (ret == AVERROR_EOF) {
          decoder->eof_reached = true;
          break;
        }
        if (ret < 0) {
          break;
        }
      } else {
        ret = av_read_frame(decoder->format_ctx, decoder->packet);
        if (ret < 0) {
          if (ret != AVERROR_EOF) {
            break;
          }
 
          ret = avcodec_send_packet(decoder->video_codec_ctx, NULL);
          decoder->video_draining = true;
          if (ret < 0 && ret != AVERROR_EOF) {
            break;
          }
 
          ret = avcodec_receive_frame(decoder->video_codec_ctx, decoder->frame);
          if (ret == AVERROR_EOF || ret == AVERROR(EAGAIN)) {
            decoder->eof_reached = true;
            break;
          }
          if (ret < 0) {
            break;
          }
        } else {
          // Check if this is a video packet
          if (decoder->packet->stream_index != decoder->video_stream_idx) {
            av_packet_unref(decoder->packet);
            continue;
          }
 
          // Send packet to decoder
          ret = avcodec_send_packet(decoder->video_codec_ctx, decoder->packet);
          av_packet_unref(decoder->packet);
 
          if (ret < 0) {
            continue;
          }
 
          // Receive decoded frame
          ret = avcodec_receive_frame(decoder->video_codec_ctx, decoder->frame);
          if (ret == AVERROR(EAGAIN)) {
            continue; // Need more packets
          } else if (ret < 0) {
            break;
          }
        }
      }
 
      // Frame decoded - mutex still held
      // Update position tracking
      decoder->last_video_pts =
          get_frame_pts_seconds(decoder->frame, decoder->format_ctx->streams[decoder->video_stream_idx]->time_base);
 
      // Convert frame to RGB24
      int width = decoder->video_codec_ctx->width;
      int height = decoder->video_codec_ctx->height;
 
      // Get current decode buffer based on which one we're using
      // (Buffer availability was already checked before entering the decode loop)
      image_t *decode_buffer = use_image_a ? decoder->prefetch_image_a : decoder->prefetch_image_b;
 
      // Reallocate if needed (width/height changed)
      if (decode_buffer->w != width || decode_buffer->h != height) {
        image_destroy(decode_buffer);
        decode_buffer = image_new((size_t)width, (size_t)height);
        if (!decode_buffer) {
          log_error("Failed to allocate prefetch image buffer");
          break;
        }
        // Update decoder's pointer to the reallocated buffer
        if (use_image_a) {
          decoder->prefetch_image_a = decode_buffer;
        } else {
          decoder->prefetch_image_b = decode_buffer;
        }
      }
 
      // Convert pixel format (rgb_pixel_t is 3 bytes: r, g, b)
      uint8_t *dst_data[1] = {(uint8_t *)decode_buffer->pixels};
      int dst_linesize[1] = {width * 3};
 
      static int decode_count = 0;
      if (++decode_count <= 3) {
        log_info("[FRAME_DECODE] Frame %d: width=%d, height=%d, codec_pix_fmt=%d, frame_pix_fmt=%d (is_stdin=%d)",
                 decode_count, width, height, decoder->video_codec_ctx->pix_fmt, decoder->frame->format,
                 decoder->is_stdin);
      }
 
      // For fragmented MP4 from stdin, pixel format might not be set - default to YUV420p
      // which is standard for H.264/H.265 video codecs
      int pix_fmt_to_use = decoder->video_codec_ctx->pix_fmt;
      if (pix_fmt_to_use == AV_PIX_FMT_NONE) {
        if (decoder->frame->format != AV_PIX_FMT_NONE) {
          pix_fmt_to_use = decoder->frame->format;
          log_debug("[SWSCALE_FIX] Using frame->format=%d instead of codec pix_fmt (was NONE)", decoder->frame->format);
        } else {
          // Fragmented MP4: Default to YUV420p (standard for H.264/H.265)
          pix_fmt_to_use = AV_PIX_FMT_YUV420P;
          log_debug("[SWSCALE_FIX] Fragmented format: Using hardcoded YUV420p (frame->format was also NONE)");
        }
      }
 
      // Lazy initialize swscale context if not done at startup (happens with HTTP/stdin streams)
      if (!decoder->sws_ctx) {
        log_debug("Lazy init swscale: width=%d, height=%d, pix_fmt=%d", width, height, pix_fmt_to_use);
        if (width > 0 && height > 0 && pix_fmt_to_use != AV_PIX_FMT_NONE) {
          LOG_IO("swscaler", {
            decoder->sws_ctx = sws_getContext(width, height, pix_fmt_to_use, width, height, AV_PIX_FMT_RGB24,
                                              SWS_BILINEAR, NULL, NULL, NULL);
          });
          if (!decoder->sws_ctx) {
            log_error("Failed to create swscale context: pix_fmt=%d (might be unsupported for conversion)",
                      pix_fmt_to_use);
            break;
          }
 
          // Set proper colorspace for H.264 video (BT.709)
          // sws_setColorspaceDetails(ctx, inv_table, srcRange, table, dstRange, brightness, contrast, saturation)
          const int *inv_table = sws_getCoefficients(SWS_CS_ITU709);
          const int *table = sws_getCoefficients(SWS_CS_ITU709);
          int ret_cs = sws_setColorspaceDetails(decoder->sws_ctx, inv_table, 0, table, 0, 0, 1 << 16, 1 << 16);
          if (ret_cs < 0) {
            log_warn("Failed to set BT.709 colorspace details (code=%d), continuing with defaults", ret_cs);
          } else {
            log_debug("Set BT.709 colorspace for H.264 YUV->RGB conversion");
          }
 
          log_debug("Lazy initialized swscale context with %dx%d from pix_fmt=%d", width, height, pix_fmt_to_use);
        } else {
          log_error("Cannot initialize swscale: width=%d, height=%d, pix_fmt=%d (AV_PIX_FMT_NONE=%d)", width, height,
                    pix_fmt_to_use, AV_PIX_FMT_NONE);
          break;
        }
      }
 
      if (decode_count <= 3) {
        // Log input YUV data
        uint8_t *y_data = decoder->frame->data[0];
        uint8_t *u_data = decoder->frame->data[1];
        uint8_t *v_data = decoder->frame->data[2];
        log_info("[YUV_INPUT] Frame %d: Y[0]=%u, U[0]=%u, V[0]=%u (linesize=%d,%d,%d)", decode_count,
                 y_data ? y_data[0] : 255, u_data ? u_data[0] : 255, v_data ? v_data[0] : 255,
                 decoder->frame->linesize[0], decoder->frame->linesize[1], decoder->frame->linesize[2]);
      }
 
      int ret_scale = sws_scale(decoder->sws_ctx, (const uint8_t *const *)decoder->frame->data,
                                decoder->frame->linesize, 0, height, dst_data, dst_linesize);
      if (decode_count <= 3) {
        log_info("[SWS_SCALE] Frame %d: returned %d", decode_count, ret_scale);
        rgb_pixel_t *test_px = (rgb_pixel_t *)decode_buffer->pixels;
        log_info("[SWS_RESULT] Frame %d: RGB[0]=(%u,%u,%u), RGB[100]=(%u,%u,%u)", decode_count, test_px[0].r,
                 test_px[0].g, test_px[0].b, test_px[100].r, test_px[100].g, test_px[100].b);
      }
 
      frame_decoded = true;
      break; // Exit while loop
    }
 
    // Release read_frame_mutex now that av_read_frame() is done
    mutex_unlock(&decoder->read_frame_mutex);
 
    // Re-acquire mutex to update prefetch state
    mutex_lock(&decoder->prefetch_mutex);
 
    // Mutex now held - update prefetch state
    if (frame_decoded) {
      // Update shared prefetch state while mutex is held
    }
 
    mutex_unlock(&decoder->prefetch_mutex); // Release at end of main loop iteration
 
    if (frame_decoded) {
      uint64_t read_time_ns = time_elapsed_ns(read_start_ns, time_get_ns());
 
      // Get current decode buffer
      image_t *decode_buffer = use_image_a ? decoder->prefetch_image_a : decoder->prefetch_image_b;
 
      // Update the current prefetch image (main thread will pull from this)
      mutex_lock(&decoder->prefetch_mutex);
      decoder->current_prefetch_image = decode_buffer;
      decoder->prefetch_frame_ready = true;
      mutex_unlock(&decoder->prefetch_mutex);
 
      char read_time_str[32];
      time_pretty(read_time_ns, -1, read_time_str, sizeof(read_time_str));
      log_dev_every(5 * US_PER_SEC_INT, "PREFETCH: decoded frame in %s", read_time_str);
 
      // Switch to the other buffer for next iteration (MUST use boolean flag, not pointer comparison)
      use_image_a = !use_image_a;
    } else {
      // EOF or error - exit thread
      break;
    }
  }
 
  log_debug("Video prefetch thread stopped");
  return NULL;
}
 
static asciichat_error_t open_codec_context(AVFormatContext *fmt_ctx, enum AVMediaType type, int *stream_idx,
                                            AVCodecContext **codec_ctx) {
  int ret = av_find_best_stream(fmt_ctx, type, -1, -1, NULL, 0);
  if (ret < 0) {
    // Stream not found - not an error, just means no stream of this type
    *stream_idx = -1;
    *codec_ctx = NULL;
    return ASCIICHAT_OK;
  }
 
  *stream_idx = ret;
  AVStream *stream = fmt_ctx->streams[ret];
 
  // Find decoder
  const AVCodec *codec = avcodec_find_decoder(stream->codecpar->codec_id);
  if (!codec) {
    return SET_ERRNO(ERROR_MEDIA_DECODE, "Codec not found for stream %d", ret);
  }
 
  // Allocate codec context
  *codec_ctx = avcodec_alloc_context3(codec);
  if (!*codec_ctx) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate codec context");
  }
 
  // Copy codec parameters
  if (avcodec_parameters_to_context(*codec_ctx, stream->codecpar) < 0) {
    avcodec_free_context(codec_ctx);
    return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to copy codec parameters");
  }
 
  // Open codec
  if (avcodec_open2(*codec_ctx, codec, NULL) < 0) {
    avcodec_free_context(codec_ctx);
    return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to open codec");
  }
 
  return ASCIICHAT_OK;
}
 
/* ============================================================================
 * Decoder Lifecycle
 * ============================================================================ */
 
ffmpeg_decoder_t *ffmpeg_decoder_create(const char *path) {
  if (!path) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Path is NULL");
    return NULL;
  }
 
  // Suppress FFmpeg's verbose debug logging (H.264 codec warnings, etc.)
  // Only set this once, it's a global setting
  static bool ffmpeg_log_level_set = false;
  if (!ffmpeg_log_level_set) {
    av_log_set_level(AV_LOG_QUIET);                  // Suppress all FFmpeg logging
    av_log_set_callback(ffmpeg_silent_log_callback); // Install silent callback to discard all output
    ffmpeg_log_level_set = true;
  }
 
  ffmpeg_decoder_t *decoder = SAFE_MALLOC(sizeof(ffmpeg_decoder_t), ffmpeg_decoder_t *);
  if (!decoder) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate decoder");
    return NULL;
  }
 
  memset(decoder, 0, sizeof(*decoder));
  decoder->video_stream_idx = -1;
  decoder->audio_stream_idx = -1;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
 
  // Capture FFmpeg's probing output (FFmpeg may write directly to either stream)
  int ret = 0;
  LOG_IO("ffmpeg", {
    // Configure FFmpeg options for HTTP streaming performance
    AVDictionary *options = NULL;
 
    // For HTTP/HTTPS streams: enable fast probing and reconnection (validated via production-grade URL regex)
    if (path && url_is_valid(path)) {
      // Limit probing to 32KB for faster format detection
      av_dict_set(&options, "probesize", "32768", 0);
      // Analyze for 100ms max to determine streams quickly
      av_dict_set(&options, "analyzeduration", "100000", 0);
      // Enable auto-reconnection for interrupted connections
      av_dict_set(&options, "reconnect", "1", 0);
      // Allow reconnection for streamed protocols
      av_dict_set(&options, "reconnect_streamed", "1", 0);
      // Set reasonable I/O timeout (10 seconds)
      av_dict_set(&options, "rw_timeout", "10000000", 0);
      // Enable HTTP persistent connection (keep-alive) for better performance
      av_dict_set(&options, "http_persistent", "1", 0);
      // Reduce connect timeout to fail faster if server is unreachable
      av_dict_set(&options, "connect_timeout", "5000000", 0);
    }
 
    // Open input file
    ret = avformat_open_input(&decoder->format_ctx, path, NULL, &options);
    av_dict_free(&options); // Free options dictionary
 
    if (ret >= 0) {
      // Find stream info
      if (avformat_find_stream_info(decoder->format_ctx, NULL) < 0) {
        ret = -1;
      }
    }
  });
 
  if (ret < 0) {
    if (ret == -1) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to find stream info");
    } else {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to open media file: %s", path);
    }
    if (decoder->format_ctx) {
      avformat_close_input(&decoder->format_ctx);
    }
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Install interrupt callback to allow seeking to interrupt long av_read_frame() calls
  // Do this AFTER finding stream info to ensure format context is fully initialized
  if (decoder->format_ctx) {
    decoder->format_ctx->interrupt_callback.callback = ffmpeg_interrupt_callback;
    decoder->format_ctx->interrupt_callback.opaque = decoder;
  }
 
  // Open video codec
  asciichat_error_t err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_VIDEO, &decoder->video_stream_idx,
                                             &decoder->video_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_warn("Failed to open video codec (file may be audio-only)");
  }
 
  // Open audio codec - audio is enabled by default (no option needed)
  // Always try to open audio codec, don't rely on GET_OPTION(audio_enabled) which has a default issue
  err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_AUDIO, &decoder->audio_stream_idx,
                           &decoder->audio_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_debug("No audio codec found (file may be video-only or audio codec not available)");
    decoder->audio_stream_idx = -1;
    decoder->audio_codec_ctx = NULL;
  }
 
  // Require at least one stream
  if (decoder->video_stream_idx < 0 && decoder->audio_stream_idx < 0) {
    SET_ERRNO(ERROR_MEDIA_DECODE, "No video or audio streams found");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Allocate frame and packet
  decoder->frame = av_frame_alloc();
  decoder->packet = av_packet_alloc();
  if (!decoder->frame || !decoder->packet) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Initialize swscale context for video if present
  if (decoder->video_codec_ctx) {
    // Validate codec context has valid dimensions and pixel format
    // For HTTP streams, these might not be valid until first frame is read
    if (decoder->video_codec_ctx->width <= 0 || decoder->video_codec_ctx->height <= 0) {
      log_warn("Video codec has invalid dimensions (%dx%d), will initialize swscale on first frame",
               decoder->video_codec_ctx->width, decoder->video_codec_ctx->height);
      // Don't create swscale context yet - will create it lazily on first frame read
    } else if (decoder->video_codec_ctx->pix_fmt == AV_PIX_FMT_NONE) {
      log_warn("Video codec has invalid pixel format, will initialize swscale on first frame");
      // Don't create swscale context yet - will create it lazily on first frame read
    } else {
      // Create swscale context with valid parameters
      LOG_IO("swscaler", {
        decoder->sws_ctx =
            sws_getContext(decoder->video_codec_ctx->width, decoder->video_codec_ctx->height,
                           decoder->video_codec_ctx->pix_fmt, decoder->video_codec_ctx->width,
                           decoder->video_codec_ctx->height, AV_PIX_FMT_RGB24, SWS_BILINEAR, NULL, NULL, NULL);
      });
      if (!decoder->sws_ctx) {
        SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to create swscale context");
        ffmpeg_decoder_destroy(decoder);
        return NULL;
      }
    }
  }
 
  // Initialize swresample context for audio if present
  if (decoder->audio_codec_ctx) {
    // Store output sample rate for position tracking
    decoder->audio_sample_rate = TARGET_SAMPLE_RATE;
 
    // Allocate resampler context
    decoder->swr_ctx = swr_alloc();
    if (!decoder->swr_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    // Set options
    av_opt_set_chlayout(decoder->swr_ctx, "in_chlayout", &decoder->audio_codec_ctx->ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "in_sample_rate", decoder->audio_codec_ctx->sample_rate, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "in_sample_fmt", decoder->audio_codec_ctx->sample_fmt, 0);
 
    AVChannelLayout out_ch_layout = AV_CHANNEL_LAYOUT_MONO;
    av_opt_set_chlayout(decoder->swr_ctx, "out_chlayout", &out_ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "out_sample_rate", TARGET_SAMPLE_RATE, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "out_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
 
    // Initialize
    if (swr_init(decoder->swr_ctx) < 0) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to initialize swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    // Allocate audio buffer (10 seconds worth)
    decoder->audio_buffer_size = TARGET_SAMPLE_RATE * 10;
    decoder->audio_buffer = SAFE_MALLOC(decoder->audio_buffer_size * sizeof(float), float *);
    if (!decoder->audio_buffer) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio buffer");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  // Initialize video frame prefetching system (for YouTube streaming)
  if (decoder->video_stream_idx >= 0) {
    int width = decoder->video_codec_ctx->width;
    int height = decoder->video_codec_ctx->height;
 
    // Create two prefetch image buffers for double-buffering
    decoder->prefetch_image_a = image_new((size_t)width, (size_t)height);
    decoder->prefetch_image_b = image_new((size_t)width, (size_t)height);
    if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate prefetch image buffers");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->current_prefetch_image = decoder->prefetch_image_a;
    decoder->prefetch_frame_ready = false;
 
    // Initialize prefetch mutex
    if (mutex_init(&decoder->prefetch_mutex, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch mutex");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (cond_init(&decoder->prefetch_cond, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch condition variable");
      mutex_destroy(&decoder->prefetch_mutex);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (mutex_init(&decoder->read_frame_mutex, "ffmpeg_read_frame") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize read_frame mutex");
      mutex_destroy(&decoder->prefetch_mutex);
      cond_destroy(&decoder->prefetch_cond);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->prefetch_thread_running = false;
    decoder->prefetch_should_stop = false;
  }
 
  log_debug("FFmpeg decoder opened: %s (video=%s, audio=%s)", path, decoder->video_stream_idx >= 0 ? "yes" : "no",
            decoder->audio_stream_idx >= 0 ? "yes" : "no");
 
  char decoder_name[256];
  snprintf(decoder_name, sizeof(decoder_name), "%s", path);
  NAMED_REGISTER_FFMPEG_DECODER(decoder, decoder_name, NULL);
 
  return decoder;
}
 
ffmpeg_decoder_t *ffmpeg_decoder_create_stdin(void) {
  // Buffer entire stdin on first call (shared between video and audio decoders)
  if (!g_stdin_buffer) {
    log_debug("Reading stdin into buffer...");
    g_stdin_buffer = stdin_buffer_read_all();
    if (!g_stdin_buffer) {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to read stdin into buffer");
      return NULL;
    }
  }
 
  ffmpeg_decoder_t *decoder = SAFE_MALLOC(sizeof(ffmpeg_decoder_t), ffmpeg_decoder_t *);
  if (!decoder) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate decoder");
    return NULL;
  }
 
  memset(decoder, 0, sizeof(*decoder));
  decoder->video_stream_idx = -1;
  decoder->audio_stream_idx = -1;
  decoder->is_stdin = true;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
 
  // Create per-decoder reader (each decoder gets independent position tracking)
  stdin_buffer_reader_t *reader = SAFE_MALLOC(sizeof(stdin_buffer_reader_t), stdin_buffer_reader_t *);
  if (!reader) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer reader");
    SAFE_FREE(decoder);
    return NULL;
  }
  reader->buffer = g_stdin_buffer;
  reader->pos = 0; // Each decoder starts from position 0
 
  // AVIO takes ownership of this buffer and may resize or free it with av_free().
  decoder->avio_buffer = av_malloc(AVIO_BUFFER_SIZE);
  if (!decoder->avio_buffer) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate AVIO buffer");
    SAFE_FREE(reader);
    SAFE_FREE(decoder);
    return NULL;
  }
 
  decoder->avio_ctx = avio_alloc_context(decoder->avio_buffer, // internal buffer for AVIO
                                         AVIO_BUFFER_SIZE,     // buffer size
                                         0,                    // write_flag
                                         reader,               // opaque (per-decoder reader)
                                         memory_read_packet,
                                         NULL,              // write_packet
                                         memory_seek_packet // seek (memory is seekable)
  );
 
  if (!decoder->avio_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to create AVIO context");
    av_free(decoder->avio_buffer);
    decoder->avio_buffer = NULL;
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Mark AVIO context as seekable (memory buffer supports seeking)
  decoder->avio_ctx->seekable = AVIO_SEEKABLE_NORMAL;
 
  // Allocate format context
  decoder->format_ctx = avformat_alloc_context();
  if (!decoder->format_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate format context");
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
    SAFE_FREE(decoder);
    return NULL;
  }
 
  decoder->format_ctx->pb = decoder->avio_ctx;
  decoder->format_ctx->flags |= AVFMT_FLAG_CUSTOM_IO; // Tell FFmpeg to use our custom AVIO context
 
  // Capture FFmpeg's probing output
  int ret = 0;
  LOG_IO("ffmpeg", {
    // Open input from buffered stdin
    ret = avformat_open_input(&decoder->format_ctx, NULL, NULL, NULL);
    if (ret >= 0) {
      // Find stream info
      if (avformat_find_stream_info(decoder->format_ctx, NULL) < 0) {
        ret = -1;
      }
    }
  });
 
  if (ret < 0) {
    if (ret == -1) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to find stream info from stdin buffer");
    } else {
      SET_ERRNO(ERROR_MEDIA_OPEN, "Failed to open stdin buffer");
    }
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
    if (decoder->format_ctx) {
      avformat_free_context(decoder->format_ctx);
    }
    SAFE_FREE(decoder);
    return NULL;
  }
 
  // Open codecs (same as file-based decoder)
  asciichat_error_t err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_VIDEO, &decoder->video_stream_idx,
                                             &decoder->video_codec_ctx);
  if (err != ASCIICHAT_OK) {
    log_warn("Failed to open video codec from stdin");
  }
 
  if (GET_OPTION(audio_enabled)) {
    err = open_codec_context(decoder->format_ctx, AVMEDIA_TYPE_AUDIO, &decoder->audio_stream_idx,
                             &decoder->audio_codec_ctx);
    if (err != ASCIICHAT_OK) {
      log_warn("Failed to open audio codec from stdin");
    }
  } else {
    decoder->audio_stream_idx = -1;
    decoder->audio_codec_ctx = NULL;
    log_debug("Audio decoding disabled by user option");
  }
 
  if (decoder->video_stream_idx < 0 && decoder->audio_stream_idx < 0) {
    SET_ERRNO(ERROR_MEDIA_DECODE, "No video or audio streams found in stdin");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Allocate frame and packet
  decoder->frame = av_frame_alloc();
  decoder->packet = av_packet_alloc();
  if (!decoder->frame || !decoder->packet) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet");
    ffmpeg_decoder_destroy(decoder);
    return NULL;
  }
 
  // Initialize swscale/swresample (same as file-based)
  if (decoder->video_codec_ctx) {
    // Validate codec context has valid dimensions and pixel format
    // For stdin/HTTP streams, these might not be valid until first frame is read
    if (decoder->video_codec_ctx->width <= 0 || decoder->video_codec_ctx->height <= 0) {
      log_warn("Video codec has invalid dimensions (%dx%d), will initialize swscale on first frame",
               decoder->video_codec_ctx->width, decoder->video_codec_ctx->height);
      // Don't create swscale context yet - will create it lazily on first frame read
    } else if (decoder->video_codec_ctx->pix_fmt == AV_PIX_FMT_NONE) {
      log_warn("Video codec has invalid pixel format, will initialize swscale on first frame");
      // Don't create swscale context yet - will create it lazily on first frame read
    } else {
      // Create swscale context with valid parameters
      LOG_IO("swscaler", {
        decoder->sws_ctx =
            sws_getContext(decoder->video_codec_ctx->width, decoder->video_codec_ctx->height,
                           decoder->video_codec_ctx->pix_fmt, decoder->video_codec_ctx->width,
                           decoder->video_codec_ctx->height, AV_PIX_FMT_RGB24, SWS_BILINEAR, NULL, NULL, NULL);
      });
      if (!decoder->sws_ctx) {
        SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to create swscale context");
        ffmpeg_decoder_destroy(decoder);
        return NULL;
      }
    }
  }
 
  if (decoder->audio_codec_ctx) {
    decoder->swr_ctx = swr_alloc();
    if (!decoder->swr_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    av_opt_set_chlayout(decoder->swr_ctx, "in_chlayout", &decoder->audio_codec_ctx->ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "in_sample_rate", decoder->audio_codec_ctx->sample_rate, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "in_sample_fmt", decoder->audio_codec_ctx->sample_fmt, 0);
 
    AVChannelLayout out_ch_layout = AV_CHANNEL_LAYOUT_MONO;
    av_opt_set_chlayout(decoder->swr_ctx, "out_chlayout", &out_ch_layout, 0);
    av_opt_set_int(decoder->swr_ctx, "out_sample_rate", TARGET_SAMPLE_RATE, 0);
    av_opt_set_sample_fmt(decoder->swr_ctx, "out_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
 
    if (swr_init(decoder->swr_ctx) < 0) {
      SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to initialize swresample context");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->audio_buffer_size = TARGET_SAMPLE_RATE * 10;
    decoder->audio_buffer = SAFE_MALLOC(decoder->audio_buffer_size * sizeof(float), float *);
    if (!decoder->audio_buffer) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate audio buffer");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  // Initialize video frame prefetching system for stdin (same as file-based)
  if (decoder->video_stream_idx >= 0) {
    int width = decoder->video_codec_ctx->width;
    int height = decoder->video_codec_ctx->height;
 
    // For stdin sources, dimensions might be invalid initially (0x0)
    // Use default dimensions for prefetch buffers; they'll be resized on first frame
    if (width <= 0 || height <= 0) {
      width = 1920;  // Default width for stdin
      height = 1080; // Default height for stdin
      log_debug("stdin: Using default prefetch dimensions %dx%d (will be resized on first frame)", width, height);
    }
 
    // Create two prefetch image buffers for double-buffering
    decoder->prefetch_image_a = image_new((size_t)width, (size_t)height);
    decoder->prefetch_image_b = image_new((size_t)width, (size_t)height);
    if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate prefetch image buffers");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    decoder->current_prefetch_image = decoder->prefetch_image_a;
    decoder->prefetch_frame_ready = false;
 
    // Initialize prefetch mutex
    if (mutex_init(&decoder->prefetch_mutex, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch mutex");
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (cond_init(&decoder->prefetch_cond, "ffmpeg_prefetch") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize prefetch condition variable");
      mutex_destroy(&decoder->prefetch_mutex);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
 
    if (mutex_init(&decoder->read_frame_mutex, "ffmpeg_read_frame") != 0) {
      SET_ERRNO(ERROR_MEMORY, "Failed to initialize read_frame mutex");
      mutex_destroy(&decoder->prefetch_mutex);
      cond_destroy(&decoder->prefetch_cond);
      ffmpeg_decoder_destroy(decoder);
      return NULL;
    }
  }
 
  log_debug("FFmpeg decoder opened from stdin (video=%s, audio=%s)", decoder->video_stream_idx >= 0 ? "yes" : "no",
            decoder->audio_stream_idx >= 0 ? "yes" : "no");
 
  NAMED_REGISTER_FFMPEG_DECODER(decoder, "stdin", NULL);
 
  return decoder;
}
 
void ffmpeg_decoder_destroy(ffmpeg_decoder_t *decoder) {
  if (!decoder) {
    return;
  }
 
  NAMED_UNREGISTER(decoder);
 
  // Stop prefetch thread (signal it to stop and wait for it to finish)
  if (decoder->prefetch_thread_running) {
    mutex_lock(&decoder->prefetch_mutex);
    decoder->prefetch_should_stop = true;
    mutex_unlock(&decoder->prefetch_mutex);
 
    // Wait for thread to finish
    asciichat_thread_join(&decoder->prefetch_thread, NULL);
    decoder->prefetch_thread_running = false;
  }
 
  // Clean up prefetch state
  cond_destroy(&decoder->prefetch_cond);
  mutex_destroy(&decoder->prefetch_mutex);
  mutex_destroy(&decoder->read_frame_mutex);
 
  // Free prefetch image buffers
  if (decoder->prefetch_image_a) {
    image_destroy(decoder->prefetch_image_a);
    decoder->prefetch_image_a = NULL;
  }
  if (decoder->prefetch_image_b) {
    image_destroy(decoder->prefetch_image_b);
    decoder->prefetch_image_b = NULL;
  }
 
  // Don't destroy current_image - it points to one of the prefetch buffers
  // which have already been destroyed above
  decoder->current_image = NULL;
 
  // Free audio buffer
  SAFE_FREE(decoder->audio_buffer);
 
  // Free swscale context
  if (decoder->sws_ctx) {
    sws_freeContext(decoder->sws_ctx);
    decoder->sws_ctx = NULL;
  }
 
  // Free swresample context
  if (decoder->swr_ctx) {
    swr_free(&decoder->swr_ctx);
  }
 
  // Free frame and packet
  if (decoder->frame) {
    av_frame_free(&decoder->frame);
  }
  if (decoder->packet) {
    av_packet_free(&decoder->packet);
  }
 
  // Free codec contexts
  if (decoder->video_codec_ctx) {
    avcodec_free_context(&decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_free_context(&decoder->audio_codec_ctx);
  }
 
  // Free format context
  if (decoder->format_ctx) {
    avformat_close_input(&decoder->format_ctx);
  }
 
  // Free AVIO context (stdin only)
  if (decoder->avio_ctx) {
    // Free the opaque reader for stdin
    if (decoder->is_stdin) {
      SAFE_FREE(decoder->avio_ctx->opaque);
    }
    av_freep(&decoder->avio_ctx->buffer);
    avio_context_free(&decoder->avio_ctx);
  }
 
  SAFE_FREE(decoder);
}
 
/* ============================================================================
 * Video Operations
 * ============================================================================ */
 
image_t *ffmpeg_decoder_read_video_frame(ffmpeg_decoder_t *decoder) {
  if (!decoder || decoder->video_stream_idx < 0) {
    return NULL;
  }
 
  // Try to get a prefetched frame from the background thread (preferred path)
  mutex_lock(&decoder->prefetch_mutex);
  if (decoder->prefetch_frame_ready && decoder->current_prefetch_image) {
    // Release the previous buffer (rendering is now complete)
    if (decoder->current_read_buffer == decoder->prefetch_image_a) {
      decoder->buffer_a_in_use = false;
    } else if (decoder->current_read_buffer == decoder->prefetch_image_b) {
      decoder->buffer_b_in_use = false;
    }
 
    image_t *frame = decoder->current_prefetch_image;
    decoder->prefetch_frame_ready = false;
 
    // Mark the new buffer as in use (prevent prefetch thread from overwriting it during rendering)
    if (frame == decoder->prefetch_image_a) {
      decoder->buffer_a_in_use = true;
    } else if (frame == decoder->prefetch_image_b) {
      decoder->buffer_b_in_use = true;
    }
 
    decoder->current_read_buffer = frame;
    mutex_unlock(&decoder->prefetch_mutex);
 
    // Use the prefetched frame
    decoder->current_image = frame;
    log_dev_every(5 * US_PER_SEC_INT, "Using prefetched frame");
    return frame;
  }
  mutex_unlock(&decoder->prefetch_mutex);
 
  // No fallback synchronous decode - rely on background prefetch thread
  // Skipping frames when prefetch not ready allows audio timing to advance
  // This is critical for proper audio-video sync when prefetch is active
  log_dev_every(5 * US_PER_SEC_INT,
                "Prefetch frame not ready, skipping to next iteration (allow prefetch to catch up)");
  return NULL;
}
 
asciichat_error_t ffmpeg_decoder_start_prefetch(ffmpeg_decoder_t *decoder) {
  if (!decoder || decoder->video_stream_idx < 0) {
    return ERROR_INVALID_PARAM;
  }
 
  if (!decoder->prefetch_image_a || !decoder->prefetch_image_b) {
    return ERROR_INVALID_PARAM;
  }
 
  // Already running
  if (decoder->prefetch_thread_running) {
    return ASCIICHAT_OK;
  }
 
  // Reset stop flag and create thread
  decoder->prefetch_should_stop = false;
 
  int thread_err = asciichat_thread_create(&decoder->prefetch_thread, "ffmpeg_prefetch",
                                           ffmpeg_decoder_prefetch_thread_func, decoder);
  if (thread_err != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to create video prefetch thread");
  }
 
  decoder->prefetch_thread_running = true;
  return ASCIICHAT_OK;
}
 
void ffmpeg_decoder_stop_prefetch(ffmpeg_decoder_t *decoder) {
  if (!decoder || !decoder->prefetch_thread_running) {
    return;
  }
 
  decoder->prefetch_should_stop = true;
  // Wait up to 2 seconds for thread to stop
  // The interrupt callback should cause av_read_frame to abort quickly
  asciichat_thread_join_timeout(&decoder->prefetch_thread, NULL, 2000 * NS_PER_MS_INT);
 
  // Mark thread as stopped regardless of join result
  // (if join succeeded: cleanup was done; if timeout: will be cleaned up on restart)
  decoder->prefetch_thread_running = false;
}
 
void ffmpeg_decoder_set_exit_callback(ffmpeg_decoder_t *decoder, bool (*should_exit_callback)(void *),
                                      void *user_data) {
  if (!decoder) {
    return;
  }
  decoder->should_exit_callback = should_exit_callback;
  decoder->exit_callback_user_data = user_data;
}
 
bool ffmpeg_decoder_is_prefetch_running(ffmpeg_decoder_t *decoder) {
  if (!decoder) {
    return false;
  }
  return decoder->prefetch_thread_running;
}
 
bool ffmpeg_decoder_has_video(ffmpeg_decoder_t *decoder) {
  return decoder && decoder->video_stream_idx >= 0;
}
 
asciichat_error_t ffmpeg_decoder_get_video_dimensions(ffmpeg_decoder_t *decoder, int *width, int *height) {
  if (!decoder || decoder->video_stream_idx < 0) {
    return ERROR_INVALID_PARAM;
  }
 
  if (width) {
    *width = decoder->video_codec_ctx->width;
  }
  if (height) {
    *height = decoder->video_codec_ctx->height;
  }
 
  return ASCIICHAT_OK;
}
 
double ffmpeg_decoder_get_video_fps(ffmpeg_decoder_t *decoder) {
  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;
}
 
/* ============================================================================
 * Audio Operations
 * ============================================================================ */
 
size_t ffmpeg_decoder_read_audio_samples(ffmpeg_decoder_t *decoder, float *buffer, size_t num_samples) {
  if (!decoder || decoder->audio_stream_idx < 0 || !buffer || num_samples == 0) {
    return 0;
  }
 
  size_t samples_written = 0;
 
  // First, drain any buffered samples
  if (decoder->audio_buffer_offset > 0) {
    size_t available = decoder->audio_buffer_offset;
    size_t to_copy = (available < num_samples) ? available : num_samples;
 
    memcpy(buffer, decoder->audio_buffer, to_copy * sizeof(float));
    samples_written += to_copy;
 
    // Shift buffer
    if (to_copy < available) {
      memmove(decoder->audio_buffer, decoder->audio_buffer + to_copy, (available - to_copy) * sizeof(float));
    }
    decoder->audio_buffer_offset -= to_copy;
 
    if (samples_written >= num_samples) {
      decoder->audio_samples_read += samples_written;
      return samples_written;
    }
  }
 
  // Read more packets to fill the request
  static uint64_t packet_count = 0;
 
  // Lock read_frame_mutex to prevent concurrent av_read_frame() calls from video prefetch thread
  mutex_lock(&decoder->read_frame_mutex);
 
  while (samples_written < num_samples) {
    int ret = av_read_frame(decoder->format_ctx, decoder->packet);
    if (ret < 0) {
      if (ret == AVERROR_EOF) {
        decoder->eof_reached = true;
      }
      break;
    }
 
    // Check if this is an audio packet
    if (decoder->packet->stream_index != decoder->audio_stream_idx) {
      av_packet_unref(decoder->packet);
      continue;
    }
 
    log_info_every(50 * US_PER_MS_INT, "Audio packet #%lu: pts=%ld dts=%ld duration=%d size=%d", packet_count++,
                   decoder->packet->pts, decoder->packet->dts, decoder->packet->duration, decoder->packet->size);
 
    // Send packet to decoder
    ret = avcodec_send_packet(decoder->audio_codec_ctx, decoder->packet);
    av_packet_unref(decoder->packet);
 
    if (ret < 0) {
      char error_message[AV_ERROR_MAX_STRING_SIZE];
      av_strerror(ret, error_message, sizeof(error_message));
      log_warn("Error sending audio packet to decoder: %s", error_message);
      continue;
    }
 
    // Receive all decoded frames from this packet
    // Important: a single packet can produce multiple frames. Must drain all before next packet.
    while (1) {
      ret = avcodec_receive_frame(decoder->audio_codec_ctx, decoder->frame);
      if (ret == AVERROR(EAGAIN)) {
        break; // No more frames from this packet, get next packet
      } else if (ret < 0) {
        log_warn("Error receiving audio frame from decoder");
        goto audio_read_done;
      }
 
      // Update position tracking
      decoder->last_audio_pts =
          get_frame_pts_seconds(decoder->frame, decoder->format_ctx->streams[decoder->audio_stream_idx]->time_base);
 
      // Resample the complete frame and retain output beyond this callback's
      // requested block. Flushing the resampler between packets would insert
      // padding into inputs whose sample rate differs from the output rate.
      uint8_t *out_ptr = (uint8_t *)decoder->audio_buffer;
      int converted = swr_convert(decoder->swr_ctx, &out_ptr, (int)decoder->audio_buffer_size,
                                  (const uint8_t **)decoder->frame->data, decoder->frame->nb_samples);
 
      if (converted > 0) {
        size_t available = (size_t)converted;
        size_t remaining = num_samples - samples_written;
        size_t to_copy = available < remaining ? available : remaining;
        memcpy(buffer + samples_written, decoder->audio_buffer, to_copy * sizeof(float));
        samples_written += to_copy;
        decoder->audio_buffer_offset = available - to_copy;
        if (decoder->audio_buffer_offset > 0)
          memmove(decoder->audio_buffer, decoder->audio_buffer + to_copy, decoder->audio_buffer_offset * sizeof(float));
      }
 
      if (samples_written >= num_samples) {
        goto audio_read_done;
      }
    }
  }
 
audio_read_done:
  // Release read_frame_mutex now that av_read_frame() is done
  mutex_unlock(&decoder->read_frame_mutex);
 
  // Flush resampler buffer if we haven't filled the full request
  // The resampler may have buffered samples that need to be output
  if (samples_written < num_samples && decoder->eof_reached) {
    int remaining_space = (int)(num_samples - samples_written);
    uint8_t *out_ptr = (uint8_t *)(buffer + samples_written);
    int flushed = swr_convert(decoder->swr_ctx, &out_ptr, remaining_space, NULL, 0);
    if (flushed > 0) {
      samples_written += (size_t)flushed;
    }
  }
 
  // Update sample-based position tracking
  decoder->audio_samples_read += samples_written;
 
  return samples_written;
}
 
bool ffmpeg_decoder_has_audio(ffmpeg_decoder_t *decoder) {
  return decoder && decoder->audio_stream_idx >= 0;
}
 
/* ============================================================================
 * Playback Control
 * ============================================================================ */
 
asciichat_error_t ffmpeg_decoder_rewind(ffmpeg_decoder_t *decoder) {
  if (!decoder) {
    return ERROR_INVALID_PARAM;
  }
 
  if (decoder->is_stdin) {
    return ERROR_NOT_SUPPORTED; // Cannot seek stdin
  }
 
  // Flush codec buffers
  if (decoder->video_codec_ctx) {
    avcodec_flush_buffers(decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_flush_buffers(decoder->audio_codec_ctx);
  }
 
  // Seek to beginning
  if (av_seek_frame(decoder->format_ctx, -1, 0, AVSEEK_FLAG_BACKWARD) < 0) {
    return SET_ERRNO(ERROR_MEDIA_SEEK, "Failed to seek to beginning");
  }
 
  decoder->eof_reached = false;
  decoder->video_draining = false;
  decoder->audio_buffer_offset = 0;
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
  decoder->audio_samples_read = 0; // Reset sample counter to 0
 
  return ASCIICHAT_OK;
}
 
asciichat_error_t ffmpeg_decoder_seek_to_timestamp(ffmpeg_decoder_t *decoder, double timestamp_sec) {
  if (!decoder) {
    return ERROR_INVALID_PARAM;
  }
 
  if (decoder->is_stdin) {
    return ERROR_NOT_SUPPORTED; // Cannot seek stdin
  }
 
  // Hold mutex during entire seek operation to prevent race with prefetch thread
  mutex_lock(&decoder->prefetch_mutex);
 
  // Set flag to pause prefetch thread via condition variable
  decoder->seeking_in_progress = true;
 
  // Convert seconds to FFmpeg time base units (AV_TIME_BASE = 1,000,000)
  int64_t target_ts = (int64_t)(timestamp_sec * AV_TIME_BASE);
 
  // For HTTP streams, use simple keyframe seeking (faster than frame-accurate seeking)
  // HTTP seeking is expensive and can break stream state, so prefer speed over precision
  int seek_ret = av_seek_frame(decoder->format_ctx, -1, target_ts, AVSEEK_FLAG_BACKWARD);
  if (seek_ret < 0) {
    // Fallback: try without backward flag
    seek_ret = av_seek_frame(decoder->format_ctx, -1, target_ts, 0);
  }
 
  if (seek_ret < 0) {
    decoder->seeking_in_progress = false;
    cond_signal(&decoder->prefetch_cond);
    mutex_unlock(&decoder->prefetch_mutex);
    return SET_ERRNO(ERROR_MEDIA_SEEK, "Failed to seek to timestamp %.2f seconds", timestamp_sec);
  }
 
  // Flush codec buffers AFTER seeking
  if (decoder->video_codec_ctx) {
    avcodec_flush_buffers(decoder->video_codec_ctx);
  }
  if (decoder->audio_codec_ctx) {
    avcodec_flush_buffers(decoder->audio_codec_ctx);
  }
 
  // Reset state
  decoder->eof_reached = false;
  decoder->video_draining = false;
  decoder->audio_buffer_offset = 0;
  // Clear any stale audio data in buffer
  if (decoder->audio_buffer) {
    memset(decoder->audio_buffer, 0, decoder->audio_buffer_size * sizeof(float));
  }
  decoder->last_video_pts = -1.0;
  decoder->last_audio_pts = -1.0;
  decoder->prefetch_frame_ready = false;
  // Set audio_samples_read to match the seek target so position tracking works correctly
  decoder->audio_samples_read = (uint64_t)(timestamp_sec * decoder->audio_sample_rate);
 
  // Reset current_read_buffer and mark both buffers as not in use
  // After seeking, the prefetch thread may reallocate buffers, so current_read_buffer
  // could point to freed memory. Clear it so the next read doesn't try to release stale pointers.
  decoder->current_read_buffer = NULL;
  decoder->buffer_a_in_use = false;
  decoder->buffer_b_in_use = false;
 
  // Resume prefetch thread
  decoder->seeking_in_progress = false;
  cond_signal(&decoder->prefetch_cond);
 
  // Release mutex - prefetch thread can resume
  mutex_unlock(&decoder->prefetch_mutex);
 
  return ASCIICHAT_OK;
}
 
bool ffmpeg_decoder_at_end(ffmpeg_decoder_t *decoder) {
  return decoder && decoder->eof_reached;
}
 
double ffmpeg_decoder_get_duration(ffmpeg_decoder_t *decoder) {
  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;
}
 
double ffmpeg_decoder_get_position(ffmpeg_decoder_t *decoder) {
  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;
}