ffmpeg_encoder.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define MEDIA_FFMPEG_ENCODER_MESSAGE_BUFFER_SIZE 2048
 
/* Existing buffer budgets in bytes, including NUL for text storage. */
#define FFMPEG_STDOUT_AVIO_BUFFER_SIZE 32768
 
#include <ascii-chat/media/ffmpeg_encoder.h>
#include <ascii-chat/os/memory.h>
#include <ascii-chat/log/log.h>
#include <ascii-chat/log/io.h>
#include <ascii-chat/debug/named.h>
#include <ascii-chat/options/options.h>
#include <string.h>
#include <ascii-chat/util/stdout_writer.h>
#include <ascii-chat/util/time.h>
#include <libplatform/compiler.h>
#include <libplatform/system.h>
#include <libplatform/filesystem.h>
#include <libplatform/terminal.h>
 
#include <libavformat/avformat.h>
#include <libavcodec/avcodec.h>
#include <libavutil/opt.h>
#include <libavutil/cpu.h>
#include <libswscale/swscale.h>
#include <libswresample/swresample.h>

struct ffmpeg_encoder_s {
  // Video stream
  AVCodecContext *codec_ctx;
  AVStream *stream;
  AVFrame *frame;
  AVFrame *frame_encoded; // Frame in target pixel format for encoding
  struct SwsContext *sws_ctx;
 
  // Audio stream
  AVStream *audio_stream;
  AVCodecContext *audio_codec_ctx;
  struct SwrContext *audio_swr_ctx;
  AVFrame *audio_frame;
  int64_t audio_pts;
  int audio_frame_size;     // Codec's required samples per frame
  float *audio_partial_buf; // Accumulator for partial frames
  int audio_partial_len;
 
  // Shared
  AVFormatContext *fmt_ctx;
  AVPacket *pkt;
  int width_px;
  int height_px;
  int source_width;
  int source_height;
  bool live_timing;
  int64_t last_video_pts;
  int frame_count;
  int64_t video_pts;                 // Cumulative PTS for proper frame timestamps
  int fps;                           // Frames per second (for duration calculation)
  int is_image;                      // Single-frame format (PNG, JPG)
  enum AVPixelFormat target_pix_fmt; // RGB24 for images, YUV420P for video
  int has_audio_stream;              // Whether audio stream was created
  int is_stdout_pipe;                // Whether writing to stdout (non-seekable)
  FILE *stdout_stream;               // Retained before LOG_IO temporarily redirects stdio
  uint64_t previous_captured_ns;     // Previous frame's capture timestamp (for snapshot mode)
  double snapshot_actual_duration;   // Actual wall-clock duration in snapshot mode (seconds)
  uint64_t snapshot_elapsed_ns;      // Current elapsed time in snapshot mode for dynamic frame duration
 
  // Frame timing from capture timestamps
  uint64_t first_frame_captured_ns; // Wall-clock timestamp of first frame (0 = not set)
 
  // Snapshot mode frame distribution
  int estimated_frame_count;        // Expected frame count for snapshot mode (fps * snapshot_delay)
  int64_t estimated_frame_duration; // Duration each frame should have in stream time_base units
};
 
// Determine audio codec from file extension
static void get_audio_codec_from_extension(const char *path, const char **audio_codec, enum AVSampleFormat *sample_fmt,
                                           int *has_audio) {
  const char *dot = strrchr(path, '.');
  *has_audio = 0;
  *audio_codec = NULL;
  *sample_fmt = AV_SAMPLE_FMT_NONE;
 
  if (!dot) {
    // Use Opus for stdout (pipe/non-seekable output, part of WebM), otherwise default to AAC
    if (path && strcmp(path, "-") == 0) {
      *has_audio = 1;
      *audio_codec = "libopus";
      *sample_fmt = AV_SAMPLE_FMT_FLT;
    } else {
      *has_audio = 1;
      *audio_codec = "aac";
      *sample_fmt = AV_SAMPLE_FMT_FLTP;
    }
    return;
  }
 
  const char *ext = dot + 1;
  // Video formats with audio support
  // NOLINTNEXTLINE(bugprone-branch-clone) - Each format requires distinct codec configuration
  if (strcmp(ext, "mp4") == 0 || strcmp(ext, "mov") == 0) {
    *has_audio = 1;
    *audio_codec = "aac";
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  } else if (strcmp(ext, "mkv") == 0 || strcmp(ext, "mka") == 0) {
    *has_audio = 1;
    *audio_codec = "aac"; // Matroska supports both AAC and Opus
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  } else if (strcmp(ext, "webm") == 0) {
    *has_audio = 1;
    *audio_codec = "libopus";
    *sample_fmt = AV_SAMPLE_FMT_FLT;
  } else if (strcmp(ext, "avi") == 0) {
    *has_audio = 1;
    *audio_codec = "pcm_s16le";
    *sample_fmt = AV_SAMPLE_FMT_S16;
  } else if (strcmp(ext, "flv") == 0) {
    *has_audio = 1;
    *audio_codec = "aac";
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  } else if (strcmp(ext, "ogv") == 0 || strcmp(ext, "ogg") == 0) {
    *has_audio = 1;
    *audio_codec = "libvorbis";
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  } else if (strcmp(ext, "3gp") == 0) {
    *has_audio = 1;
    *audio_codec = "aac";
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  } else if (strcmp(ext, "gif") == 0 || strcmp(ext, "png") == 0 || strcmp(ext, "jpg") == 0 ||
             strcmp(ext, "jpeg") == 0 || strcmp(ext, "bmp") == 0 || strcmp(ext, "webp") == 0) {
    *has_audio = 0;
    *audio_codec = NULL;
    *sample_fmt = AV_SAMPLE_FMT_NONE;
  } else {
    // Default for unknown formats
    *has_audio = 1;
    *audio_codec = "aac";
    *sample_fmt = AV_SAMPLE_FMT_FLTP;
  }
}
 
// Determine codec, format, and pixel format from file extension
static void get_codec_from_extension(const char *path, const char **codec, const char **format, int *is_image,
                                     enum AVPixelFormat *pix_fmt) {
  const char *dot = strrchr(path, '.');
  *is_image = 0;
  *pix_fmt = AV_PIX_FMT_YUV420P; // Default
 
  if (!dot) {
    // Default to MP4 for any output without extension (including stdout piping)
    *codec = "libx264";
    *format = "mp4";
    return;
  }
 
  const char *ext = dot + 1;
  // Video formats
  // NOLINTNEXTLINE(bugprone-branch-clone) - Each format requires distinct codec setup
  if (strcmp(ext, "mp4") == 0 || strcmp(ext, "mov") == 0) {
    *codec = "libx264";
    *format = strcmp(ext, "mov") == 0 ? "mov" : "mp4";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } // NOLINTNEXTLINE(bugprone-branch-clone)
  else if (strcmp(ext, "mkv") == 0) {
    *codec = "libx264";
    *format = "matroska";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } // NOLINTNEXTLINE(bugprone-branch-clone)
  else if (strcmp(ext, "mka") == 0) {
    // MKA is audio-only Matroska
    *codec = "libx264";
    *format = "matroska";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "webm") == 0) {
    *codec = "libvpx-vp9";
    *format = "webm";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "avi") == 0) {
    *codec = "mpeg4";
    *format = "avi";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "flv") == 0) {
    *codec = "libx264";
    *format = "flv";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "ogv") == 0 || strcmp(ext, "ogg") == 0) {
    *codec = "libtheora";
    *format = "ogg";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "3gp") == 0) {
    *codec = "libx264";
    *format = "3gp";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "gif") == 0) {
    *codec = "gif";
    *format = "gif";
    *pix_fmt = AV_PIX_FMT_RGB8;
  } else if (strcmp(ext, "png") == 0) {
    *codec = "png";
    *format = "image2";
    *is_image = 1;
    *pix_fmt = AV_PIX_FMT_RGB24; // PNG uses RGB24
  } else if (strcmp(ext, "bmp") == 0 || strcmp(ext, "webp") == 0) {
    *codec = strcmp(ext, "bmp") == 0 ? "bmp" : "libwebp";
    *format = "image2";
    *is_image = 1;
    *pix_fmt = strcmp(ext, "bmp") == 0 ? AV_PIX_FMT_BGR24 : AV_PIX_FMT_YUV420P;
  } else if (strcmp(ext, "jpg") == 0 || strcmp(ext, "jpeg") == 0) {
    *codec = "mjpeg";
    *format = "image2";
    *is_image = 1;
    *pix_fmt = AV_PIX_FMT_YUVJ420P; // MJPEG uses YUVJ420P
  } else {
    // Default for unknown formats
    *codec = "libx264";
    *format = "mp4";
    *pix_fmt = AV_PIX_FMT_YUV420P;
  }
}
 
// Initialize audio stream for encoder
static asciichat_error_t encoder_init_audio_stream(ffmpeg_encoder_t *enc, const char *output_path) {
  const char *audio_codec_name = NULL;
  enum AVSampleFormat target_sample_fmt = AV_SAMPLE_FMT_NONE;
  int has_audio = 0;
 
  get_audio_codec_from_extension(output_path, &audio_codec_name, &target_sample_fmt, &has_audio);
 
  if (!has_audio) {
    log_debug("no audio for format");
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Find audio encoder
  const AVCodec *audio_codec = avcodec_find_encoder_by_name(audio_codec_name);
  if (!audio_codec) {
    log_warn("audio encoder '%s' not found, skipping audio", audio_codec_name);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Create audio stream
  enc->audio_stream = avformat_new_stream(enc->fmt_ctx, audio_codec);
  if (!enc->audio_stream) {
    log_warn("avformat_new_stream for audio failed");
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Allocate audio codec context
  enc->audio_codec_ctx = avcodec_alloc_context3(audio_codec);
  if (!enc->audio_codec_ctx) {
    log_warn("avcodec_alloc_context3 for audio failed");
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Configure audio codec context
  enc->audio_codec_ctx->sample_rate = 48000; // 48kHz (from audio pipeline)
  AVChannelLayout ch_layout = AV_CHANNEL_LAYOUT_STEREO;
  av_channel_layout_copy(&enc->audio_codec_ctx->ch_layout, &ch_layout);
  enc->audio_codec_ctx->sample_fmt = target_sample_fmt;
  enc->audio_codec_ctx->time_base = (AVRational){1, 48000};
  enc->audio_codec_ctx->bit_rate = 128000; // 128 kbps
 
  // Open audio codec (capture FFmpeg logs)
  int ret = 0;
  LOG_IO("ffmpeg", { ret = avcodec_open2(enc->audio_codec_ctx, audio_codec, NULL); });
  if (ret < 0) {
    log_warn("avcodec_open2 for audio failed");
    avcodec_free_context(&enc->audio_codec_ctx);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Copy codec parameters to stream
  ret = avcodec_parameters_from_context(enc->audio_stream->codecpar, enc->audio_codec_ctx);
  if (ret < 0) {
    log_warn("avcodec_parameters_from_context for audio failed");
    avcodec_free_context(&enc->audio_codec_ctx);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Create audio frame
  enc->audio_frame = av_frame_alloc();
  if (!enc->audio_frame) {
    log_warn("av_frame_alloc for audio failed");
    avcodec_free_context(&enc->audio_codec_ctx);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  enc->audio_frame->sample_rate = 48000;
  AVChannelLayout frame_ch_layout = AV_CHANNEL_LAYOUT_STEREO;
  av_channel_layout_copy(&enc->audio_frame->ch_layout, &frame_ch_layout);
  enc->audio_frame->format = target_sample_fmt;
 
  // Get frame size from codec (if specified)
  enc->audio_frame_size = enc->audio_codec_ctx->frame_size;
  if (enc->audio_frame_size == 0) {
    // Default frame size for codecs that don't specify
    enc->audio_frame_size = 1024;
  }
 
  // Allocate buffer for partial frames (accumulator)
  enc->audio_partial_buf = SAFE_MALLOC(enc->audio_frame_size * 2 * sizeof(float), float *);
  enc->audio_partial_len = 0;
 
  // Create resampler from input format (AV_SAMPLE_FMT_FLT interleaved stereo 48kHz) to target format
  enc->audio_swr_ctx = swr_alloc();
  if (!enc->audio_swr_ctx) {
    log_warn("swr_alloc failed");
    SAFE_FREE(enc->audio_partial_buf);
    av_frame_free(&enc->audio_frame);
    avcodec_free_context(&enc->audio_codec_ctx);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  // Set input format (interleaved stereo 48kHz float32)
  AVChannelLayout in_ch_layout = AV_CHANNEL_LAYOUT_STEREO;
  av_opt_set_chlayout(enc->audio_swr_ctx, "in_chlayout", &in_ch_layout, 0);
  av_opt_set_int(enc->audio_swr_ctx, "in_sample_rate", 48000, 0);
  av_opt_set_sample_fmt(enc->audio_swr_ctx, "in_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
 
  // Set output format
  AVChannelLayout out_ch_layout = AV_CHANNEL_LAYOUT_STEREO;
  av_opt_set_chlayout(enc->audio_swr_ctx, "out_chlayout", &out_ch_layout, 0);
  av_opt_set_int(enc->audio_swr_ctx, "out_sample_rate", 48000, 0);
  av_opt_set_sample_fmt(enc->audio_swr_ctx, "out_sample_fmt", target_sample_fmt, 0);
 
  // Initialize the resampler
  ret = swr_init(enc->audio_swr_ctx);
  if (ret < 0) {
    log_warn("swr_init failed");
    swr_free(&enc->audio_swr_ctx);
    SAFE_FREE(enc->audio_partial_buf);
    av_frame_free(&enc->audio_frame);
    avcodec_free_context(&enc->audio_codec_ctx);
    enc->has_audio_stream = 0;
    return ASCIICHAT_OK;
  }
 
  enc->audio_pts = 0;
  enc->has_audio_stream = 1;
  log_debug("audio stream initialized with codec=%s, frame_size=%d", audio_codec_name, enc->audio_frame_size);
 
  return ASCIICHAT_OK;
}
 
static void encoder_init_snapshot_timing(ffmpeg_encoder_t *enc, int fps) {
  // For snapshot mode, calculate output FPS based on input FPS and snapshot duration
  // If we capture for N seconds at input_fps, we'll get ~(N * input_fps) frames
  // Output duration should be snapshot_delay seconds
  // So output_fps = (input_fps * snapshot_delay) / snapshot_delay = input_fps
  // EXCEPT: if the input was probed, fps parameter is the actual input fps
  // Then output_fps should equal input_fps to make frame durations sum correctly
  bool snapshot_mode = GET_OPTION(snapshot_mode);
  double snapshot_delay = GET_OPTION(snapshot_delay);
  log_debug("snapshot_mode=%d, snapshot_delay=%.1f, input_fps=%d", snapshot_mode, snapshot_delay, fps);
 
  if (snapshot_mode && snapshot_delay > 0) {
    // For snapshot mode: if we capture at input_fps for snapshot_delay seconds,
    // we get approximately (input_fps * snapshot_delay) frames
    // To make output span exactly snapshot_delay seconds:
    // output_fps = frame_count / snapshot_delay = (input_fps * snapshot_delay) / snapshot_delay = input_fps
    // So we should use input_fps as output_fps!
    // Example: 30fps input for 3s → ~90 frames → output at 30fps → 90/30 = 3 seconds ✓
 
    log_info("Snapshot mode snapshot_delay=%.1f, input_fps=%d", snapshot_delay, fps);
    log_info("  → Will estimate ~%.0f frames, output FPS=%d makes durations sum to %.1f seconds", fps * snapshot_delay,
             fps, snapshot_delay);
  }
 
  enc->fps = fps;
 
  // Snapshot mode frame distribution setup
  enc->estimated_frame_count = 0;
  enc->estimated_frame_duration = 0;
  if (snapshot_mode && snapshot_delay > 0 && fps > 0) {
    // Estimate how many frames we'll capture
    enc->estimated_frame_count = (int)(fps * snapshot_delay + 0.5);
    // Each frame should have uniform duration in stream time_base (1/90000 for MP4)
    // frame_duration = total_duration / estimated_frame_count
    //                = snapshot_delay seconds * time_base.den / estimated_frame_count
    // We'll set this to stream->time_base later after it's initialized
    log_info("Snapshot mode ENABLED - estimated_frame_count=%d (fps=%d * snapshot_delay=%.2f)",
             enc->estimated_frame_count, fps, snapshot_delay);
  } else {
    log_info("Snapshot mode disabled or invalid - snapshot_mode=%d, snapshot_delay=%.2f, fps=%d", snapshot_mode,
             snapshot_delay, fps);
  }
}
 
static const AVCodec *encoder_find_video_codec(const char *codec_name) {
  // Find encoder (with fallback for FFmpeg builds without libx264)
  const AVCodec *codec = avcodec_find_encoder_by_name(codec_name);
  if (!codec && strcmp(codec_name, "libx264") == 0) {
    // libx264 not available - try built-in H.264 encoders
    static const char *h264_fallbacks[] = {"libopenh264", "h264_mf", NULL};
    for (int i = 0; h264_fallbacks[i] && !codec; i++) {
      codec = avcodec_find_encoder_by_name(h264_fallbacks[i]);
    }
    if (!codec) {
      // Last resort: ask FFmpeg for any H.264 encoder
      codec = avcodec_find_encoder(AV_CODEC_ID_H264);
    }
    if (codec) {
      log_info("ffmpeg: using fallback H.264 encoder '%s' (libx264 not available)", codec->name);
    }
  }
  if (!codec && strcmp(codec_name, "libvpx-vp9") == 0) {
    // Homebrew and distribution FFmpeg builds do not consistently expose the
    // libvpx VP9 encoder under the preferred name. Both VP9 and VP8 remain
    // valid WebM video codecs.
    static const char *webm_fallbacks[] = {"libvpx", "vp9", "libvpx-vp8", "vp8", NULL};
    for (int i = 0; webm_fallbacks[i] && !codec; ++i)
      codec = avcodec_find_encoder_by_name(webm_fallbacks[i]);
    if (codec) {
      log_info("ffmpeg: using fallback WebM encoder '%s' (libvpx-vp9 not available)", codec->name);
    }
  }
  return codec;
}
 
// On failure, setup helpers release the partially initialized encoder.
static asciichat_error_t encoder_init_video_stream(ffmpeg_encoder_t *enc, const char *codec_name) {
  int ret;
  int width_px = enc->width_px;
  int height_px = enc->height_px;
  int fps = enc->fps;
  const AVCodec *codec = encoder_find_video_codec(codec_name);
  if (!codec) {
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: encoder '%s' not found", codec_name);
  }
 
  // Create new stream
  enc->stream = avformat_new_stream(enc->fmt_ctx, codec);
  if (!enc->stream) {
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avformat_new_stream failed");
  }
 
  // Allocate codec context
  enc->codec_ctx = avcodec_alloc_context3(codec);
  if (!enc->codec_ctx) {
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avcodec_alloc_context3 failed");
  }
 
  // Set codec parameters
  enc->codec_ctx->width = width_px;
  enc->codec_ctx->height = height_px;
  enc->codec_ctx->pix_fmt = enc->target_pix_fmt;
  enc->codec_ctx->time_base = (AVRational){1, fps};
  enc->codec_ctx->framerate = (AVRational){fps, 1};
  enc->stream->time_base = enc->codec_ctx->time_base;
  enc->stream->avg_frame_rate = enc->codec_ctx->framerate;
  if (enc->fmt_ctx->oformat->flags & AVFMT_GLOBALHEADER)
    enc->codec_ctx->flags |= AV_CODEC_FLAG_GLOBAL_HEADER;
 
  // Set bitrate for high quality (music-level quality)
  // Use ~5-10 Mbps per megapixel for visually lossless quality
  int bitrate = (width_px * height_px * 10) / 1024; // higher quality estimate in kbps
  if (bitrate < 4000)
    bitrate = 4000; // Minimum 4000 kbps for quality
  if (bitrate > 50000)
    bitrate = 50000; // Cap at 50 Mbps max
  enc->codec_ctx->bit_rate = bitrate * 1000;
  log_debug("bitrate set to %d kbps for %dx%d", bitrate, width_px, height_px);
 
  // Configure codec-specific options for quality
  AVDictionary *codec_opts = NULL;
  if (strcmp(codec->name, "libx264") == 0) {
    av_dict_set(&codec_opts, "preset", "ultrafast", 0);
    av_dict_set(&codec_opts, "crf", "28", 0);
    log_debug("x264 preset=ultrafast crf=28");
  } else if (strcmp(codec->name, "libx265") == 0) {
    av_dict_set(&codec_opts, "preset", "ultrafast", 0);
    av_dict_set(&codec_opts, "crf", "32", 0);
    // x265 tag must be hvc1 for MP4 container compatibility (Apple/browser playback)
    enc->stream->codecpar->codec_tag = MKTAG('h', 'v', 'c', '1');
    log_debug("x265 preset=ultrafast crf=32");
  }
 
  // Open codec (capture encoder startup logs).
  LOG_IO("ffmpeg", { ret = avcodec_open2(enc->codec_ctx, codec, &codec_opts); });
  av_dict_free(&codec_opts);
  if (ret < 0) {
    char error_message[AV_ERROR_MAX_STRING_SIZE];
    av_strerror(ret, error_message, sizeof(error_message));
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avcodec_open2 failed for %s: %s (%d)", codec->name, error_message, ret);
  }
 
  // Copy codec parameters to stream
  ret = avcodec_parameters_from_context(enc->stream->codecpar, enc->codec_ctx);
  if (ret < 0) {
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avcodec_parameters_from_context failed");
  }
 
  return ASCIICHAT_OK;
}
 
static AVDictionary *encoder_create_muxer_options(const ffmpeg_encoder_t *enc, const char *output_path) {
  // Muxer options for proper MP4 container structure
  AVDictionary *opts = NULL;
 
  // Muxer flags configuration
  // For stdout/non-seekable output, use fragmented MP4 (frag_keyframe)
  // For regular files, use faststart (moov at front for streaming)
  bool is_stdout = (output_path && strcmp(output_path, "-") == 0);
  if (is_stdout) {
    // Use fragmented MP4 for stdout - starts a new fragment at each video keyframe
    // This allows streaming without requiring file seeking (FFmpeg docs recommended)
    av_dict_set(&opts, "movflags", "+frag_keyframe", 0);
    log_debug("Using fragmented MP4 (+frag_keyframe) for stdout output");
  } else {
    // Move moov atom to the front (faststart) - helps with streaming and player compatibility
    av_dict_set(&opts, "movflags", "faststart", 0);
  }
 
  if (enc->is_image) {
    // Use -update flag for single frame output
    av_dict_set(&opts, "update", "1", 0);
  }
 
  return opts;
}
 
static asciichat_error_t encoder_init_video_frames(ffmpeg_encoder_t *enc) {
  int ret;
  int width_px = enc->width_px;
  int height_px = enc->height_px;
  // Allocate frames
  enc->frame = av_frame_alloc();
  enc->frame_encoded = av_frame_alloc();
  enc->pkt = av_packet_alloc();
  if (!enc->frame || !enc->frame_encoded || !enc->pkt) {
    av_frame_free(&enc->frame);
    av_frame_free(&enc->frame_encoded);
    av_packet_free(&enc->pkt);
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: frame allocation failed");
  }
 
  // Set frame properties for target pixel format
  enc->frame_encoded->format = enc->target_pix_fmt;
  enc->frame_encoded->width = width_px;
  enc->frame_encoded->height = height_px;
  ret = av_frame_get_buffer(enc->frame_encoded, 32);
  if (ret < 0) {
    av_frame_free(&enc->frame);
    av_frame_free(&enc->frame_encoded);
    av_packet_free(&enc->pkt);
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: av_frame_get_buffer failed");
  }
 
  // Large recordings otherwise convert millions of pixels on one thread.
  // swscale owns its workers; small outputs avoid the synchronization cost.
  int conversion_threads = av_cpu_count();
  if (conversion_threads > 4)
    conversion_threads = 4;
  LOG_IO("swscaler", {
    if ((int64_t)width_px * height_px >= 1000000 && conversion_threads > 1) {
      struct SwsContext *context = sws_alloc_context();
      if (context) {
        int configured = av_opt_set_int(context, "srcw", enc->source_width, 0) |
                         av_opt_set_int(context, "srch", enc->source_height, 0) |
                         av_opt_set_int(context, "dstw", width_px, 0) | av_opt_set_int(context, "dsth", height_px, 0) |
                         av_opt_set_int(context, "src_format", AV_PIX_FMT_RGBA, 0) |
                         av_opt_set_int(context, "dst_format", enc->target_pix_fmt, 0) |
                         av_opt_set_int(context, "sws_flags", SWS_BICUBIC, 0) |
                         av_opt_set_int(context, "threads", conversion_threads, 0);
        if (configured >= 0 && sws_init_context(context, NULL, NULL) >= 0)
          enc->sws_ctx = context;
        else
          sws_freeContext(context);
      }
    }
    if (!enc->sws_ctx)
      enc->sws_ctx = sws_getContext(enc->source_width, enc->source_height, AV_PIX_FMT_RGBA, width_px, height_px,
                                    enc->target_pix_fmt, SWS_BICUBIC, NULL, NULL, NULL);
  });
  if (!enc->sws_ctx) {
    av_frame_free(&enc->frame);
    av_frame_free(&enc->frame_encoded);
    av_packet_free(&enc->pkt);
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: sws_getContext failed");
  }
 
  return ASCIICHAT_OK;
}
 
#if LIBAVFORMAT_VERSION_MAJOR >= 61
static int encoder_stdout_write(void *opaque, const uint8_t *data, int size) {
#else
static int encoder_stdout_write(void *opaque, uint8_t *data, int size) {
#endif
  if (size < 0)
    return AVERROR(EINVAL);
  return stdout_writer_write(opaque, data, (size_t)size) == ASCIICHAT_OK ? size : AVERROR(EIO);
}
 
static void encoder_log_callback(void *context, int level, const char *format, va_list args) {
  (void)context;
  if (level > av_log_get_level())
    return;
  char message[MEDIA_FFMPEG_ENCODER_MESSAGE_BUFFER_SIZE];
  vsnprintf(message, sizeof(message), format, args);
  if (level <= AV_LOG_ERROR)
    log_error("ffmpeg: %s", message);
  else if (level <= AV_LOG_WARNING)
    log_warn("ffmpeg: %s", message);
  else
    log_debug("ffmpeg: %s", message);
}
 
static void encoder_close_io(ffmpeg_encoder_t *enc) {
  if (!enc->fmt_ctx->pb)
    return;
  if (enc->is_stdout_pipe) {
    av_freep(&enc->fmt_ctx->pb->buffer);
    avio_context_free(&enc->fmt_ctx->pb);
    if (enc->stdout_stream) {
      fclose(enc->stdout_stream);
      enc->stdout_stream = NULL;
    }
  } else {
    avio_closep(&enc->fmt_ctx->pb);
  }
}
 
static asciichat_error_t encoder_open_output(ffmpeg_encoder_t *enc, const char *output_path, AVDictionary *opts) {
  int ret;
  // Open output file or stdout
  if (!(enc->fmt_ctx->oformat->flags & AVFMT_NOFILE)) {
    const char *open_path = output_path;
    if (enc->is_stdout_pipe) {
      int fd = platform_dup(STDOUT_FILENO);
      if (fd >= 0) {
        enc->stdout_stream = platform_fdopen("render stdout", fd, "wb");
        if (!enc->stdout_stream)
          platform_close(fd);
      }
      uint8_t *buffer = av_malloc(FFMPEG_STDOUT_AVIO_BUFFER_SIZE);
      if (buffer && enc->stdout_stream)
        enc->fmt_ctx->pb = avio_alloc_context(buffer, FFMPEG_STDOUT_AVIO_BUFFER_SIZE, 1, enc->stdout_stream, NULL,
                                              encoder_stdout_write, NULL);
      if (!enc->fmt_ctx->pb) {
        av_free(buffer);
        if (enc->stdout_stream) {
          fclose(enc->stdout_stream);
          enc->stdout_stream = NULL;
        }
      }
      ret = enc->fmt_ctx->pb ? 0 : AVERROR(ENOMEM);
      enc->fmt_ctx->flags |= AVFMT_FLAG_CUSTOM_IO;
    } else {
      ret = avio_open(&enc->fmt_ctx->pb, open_path, AVIO_FLAG_WRITE);
    }
    if (ret < 0) {
      sws_freeContext(enc->sws_ctx);
      av_frame_free(&enc->frame);
      av_frame_free(&enc->frame_encoded);
      av_packet_free(&enc->pkt);
      avcodec_free_context(&enc->codec_ctx);
      avformat_free_context(enc->fmt_ctx);
      SAFE_FREE(enc);
      return SET_ERRNO(ERROR_INIT, "ffmpeg: avio_open failed for '%s'", open_path);
    }
  }
 
  // Write header (capture FFmpeg format muxer logs)
  LOG_IO("ffmpeg", { ret = avformat_write_header(enc->fmt_ctx, &opts); });
  av_dict_free(&opts); // Free options after use
  if (ret < 0) {
    encoder_close_io(enc);
    sws_freeContext(enc->sws_ctx);
    av_frame_free(&enc->frame);
    av_frame_free(&enc->frame_encoded);
    av_packet_free(&enc->pkt);
    avcodec_free_context(&enc->codec_ctx);
    avformat_free_context(enc->fmt_ctx);
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avformat_write_header failed");
  }
 
  return ASCIICHAT_OK;
}
 
static void encoder_set_snapshot_frame_duration(ffmpeg_encoder_t *enc) {
  // Now that stream->time_base is set, calculate estimated frame duration for snapshot mode
  bool snapshot_mode_after_header = GET_OPTION(snapshot_mode);
  double snapshot_delay_after_header = GET_OPTION(snapshot_delay);
  if (snapshot_mode_after_header && enc->estimated_frame_count > 0 && snapshot_delay_after_header > 0) {
    // Each frame should span: snapshot_delay / estimated_frame_count seconds
    // In stream time_base units: (snapshot_delay * time_base.den) / estimated_frame_count
    enc->estimated_frame_duration =
        (int64_t)((snapshot_delay_after_header * (double)enc->stream->time_base.den) / enc->estimated_frame_count);
    log_debug("Calculated estimated_frame_duration=%lld time_base units "
              "for snapshot mode (snapshot_delay=%.2f, estimated_frames=%d, time_base=%d/%d)",
              (long long)enc->estimated_frame_duration, snapshot_delay_after_header, enc->estimated_frame_count,
              enc->stream->time_base.num, enc->stream->time_base.den);
  }
}
 
asciichat_error_t ffmpeg_encoder_create(const char *output_path, int width_px, int height_px, int fps,
                                        ffmpeg_encoder_t **out) {
  return ffmpeg_encoder_create_scaled(output_path, width_px, height_px, width_px, height_px, fps, out);
}
 
asciichat_error_t ffmpeg_encoder_create_scaled(const char *output_path, int source_width, int source_height,
                                               int width_px, int height_px, int fps, ffmpeg_encoder_t **out) {
  log_info("output=%s, %dx%d @ %dfps", output_path, width_px, height_px, fps);
 
  if (!output_path || !out || source_width <= 0 || source_height <= 0 || width_px <= 0 || height_px <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid parameters");
  if (strcmp(output_path, "pipe:") == 0)
    output_path = "-";
  // Codec workers can log after LOG_IO restores the process descriptors.
  // The session logger routes diagnostics to stderr when binary stdout is active.
  if (strcmp(output_path, "-") == 0)
    av_log_set_callback(encoder_log_callback);
 
  // Use default FPS if not specified (0 from config means "use default")
  if (fps <= 0) {
    fps = 60;
    log_debug("fps was 0, using default 60");
  }
 
  ffmpeg_encoder_t *enc = SAFE_CALLOC(1, sizeof(*enc), ffmpeg_encoder_t *);
  enc->width_px = width_px;
  enc->height_px = height_px;
  enc->source_width = source_width;
  enc->source_height = source_height;
 
  encoder_init_snapshot_timing(enc, fps);
 
  enc->is_stdout_pipe = (output_path && strcmp(output_path, "-") == 0) ? 1 : 0;
 
  // For codec/format detection, use output_path unless it's "-" (stdout)
  // For stdout, use "fake.mp4" to default to MP4 format
  const char *detection_path = output_path;
  if (output_path && strcmp(output_path, "-") == 0) {
    detection_path = "fake.mp4"; // Fake path for format detection when piping to stdout
    log_debug("Using MP4 format for stdout piping");
  }
 
  const char *codec_name = NULL, *format_name = NULL;
  get_codec_from_extension(detection_path, &codec_name, &format_name, &enc->is_image, &enc->target_pix_fmt);
 
  log_debug("%s (%s, %dx%d @ %dfps, %s)", output_path, codec_name, width_px, height_px, fps,
            enc->is_image ? "image" : "video");
 
  // Allocate output media context
  int ret = avformat_alloc_output_context2(&enc->fmt_ctx, NULL, format_name, output_path);
  if (ret < 0) {
    SAFE_FREE(enc);
    return SET_ERRNO(ERROR_INIT, "ffmpeg: avformat_alloc_output_context2 failed");
  }
 
  asciichat_error_t result = encoder_init_video_stream(enc, codec_name);
  if (result != ASCIICHAT_OK)
    return result;
 
  AVDictionary *opts = encoder_create_muxer_options(enc, output_path);
 
  result = encoder_init_video_frames(enc);
  if (result != ASCIICHAT_OK)
    return result;
 
  // Initialize audio stream if supported
  encoder_init_audio_stream(enc, output_path);
 
  result = encoder_open_output(enc, output_path, opts);
  if (result != ASCIICHAT_OK)
    return result;
 
  encoder_set_snapshot_frame_duration(enc);
 
  enc->frame_count = 0;
  enc->video_pts = 0;
  enc->snapshot_actual_duration = 0.0;
  enc->snapshot_elapsed_ns = 0;
  enc->first_frame_captured_ns = 0; // Initialize first frame timestamp
  *out = enc;
 
  /* Register encoder with named registry */
  NAMED_REGISTER_FFMPEG_ENCODER(enc, output_path, NULL);
 
  log_info("SUCCESS: encoder initialized, frame_count=0, fps=%d, dims=%dx%d", enc->fps, enc->width_px, enc->height_px);
  return ASCIICHAT_OK;
}
 
asciichat_error_t ffmpeg_encoder_write_frame(ffmpeg_encoder_t *enc, const uint8_t *rgb, int pitch,
                                             uint64_t captured_ns) {
  if (!enc || !rgb)
    return SET_ERRNO(ERROR_INVALID_PARAM, "NULL input");
 
  // Initialize first frame capture time on first call
  if (enc->first_frame_captured_ns == 0) {
    enc->first_frame_captured_ns = captured_ns;
    log_debug("first frame captured at %llu ns", (unsigned long long)captured_ns);
  }
 
  log_debug_every(5 * US_PER_SEC_INT, "Encoding frame %d, %dx%d", enc->frame_count, enc->width_px, enc->height_px);
 
  // Set up RGBA frame for conversion
  uint8_t *data[1] = {(uint8_t *)rgb};
  int linesize[1] = {pitch};
 
  // Encoders may retain references to earlier frames for motion or transparency detection.
  if (av_frame_make_writable(enc->frame_encoded) < 0)
    return SET_ERRNO(ERROR_MEMORY, "ffmpeg: cannot make video frame writable");
 
  // Ensure frame format is set before each sws_scale call.
  // Some FFmpeg versions reset the format field, so we set it explicitly.
  enc->frame_encoded->format = enc->target_pix_fmt;
 
  // Convert RGBA to target format
  uint64_t conversion_started_ns = time_get_ns();
  sws_scale(enc->sws_ctx, (const uint8_t *const *)data, linesize, 0, enc->source_height, enc->frame_encoded->data,
            enc->frame_encoded->linesize);
  uint64_t converted_ns = time_get_ns();
 
  // Set frame duration based on mode
  int64_t frame_duration;
  bool snapshot_mode = GET_OPTION(snapshot_mode);
 
  if (enc->frame_count == 0) {
    log_info("frame 0, snapshot_mode=%d", snapshot_mode);
  }
 
  // Use FPS-based frame duration (snapshot mode adjusts total duration in destroy())
  frame_duration = enc->codec_ctx->time_base.den / (enc->codec_ctx->time_base.num * enc->fps);
 
  enc->frame_encoded->duration = frame_duration;
 
  // Track this frame's capture timestamp for duration calculation of next frame
  if (snapshot_mode) {
    uint64_t frame_dur_ms = (enc->previous_captured_ns > 0) ? (captured_ns - enc->previous_captured_ns) / 1000000 : 0;
    if (enc->frame_count <= 2) {
      log_info("ffmpeg: frame %d SET duration=%lld units (%.3fms since last, codec_base=1/%d)", enc->frame_count,
               (long long)frame_duration, (double)frame_dur_ms, enc->codec_ctx->time_base.den);
    }
    enc->previous_captured_ns = captured_ns;
  }
 
  // Calculate PTS from actual capture timestamp
  // time_base is {1, fps}, so 1 PTS unit = 1/fps seconds
  // Convert elapsed nanoseconds to PTS units: elapsed_ns * fps / 1_000_000_000
  uint64_t elapsed_ns = captured_ns - enc->first_frame_captured_ns;
  int64_t pts_from_timestamp = (int64_t)((elapsed_ns * (uint64_t)enc->fps) / 1000000000ULL);
 
  // Normal file rendering is constant-frame-rate. Wall-clock capture timestamps
  // include scheduler jitter and can create gaps or duplicate PTS values, so use
  // the encoded frame index for exact N / FPS duration. File snapshots with
  // audio use this same timeline, excluding capture initialization delays.
  // Live sources preserve wall-clock gaps between received frames.
  if ((!snapshot_mode || enc->has_audio_stream) && !enc->live_timing) {
    pts_from_timestamp = enc->frame_count;
  }
 
  // For snapshot sources without an estimated frame count, distribute frames
  // linearly across the actual duration once the capture duration is known.
  if (snapshot_mode && !enc->has_audio_stream && !enc->live_timing && enc->estimated_frame_count == 0) {
    extern uint64_t g_snapshot_actual_duration_ms;
    extern uint64_t g_snapshot_last_capture_elapsed_ns;
    if (g_snapshot_actual_duration_ms > 0) {
      // Distribute frames linearly based on their capture timestamp relative to total duration
      // pts = (frame_elapsed_ns / total_elapsed_ns) * actual_duration_sec * fps
      // This ensures frame 0 is at 0s and last frame is at actual_duration_sec
      double actual_duration_sec = (double)g_snapshot_actual_duration_ms / 1000.0;
      double total_elapsed_sec = (double)g_snapshot_last_capture_elapsed_ns / (double)NS_PER_SEC_INT;
 
      if (total_elapsed_sec > 0.001) {
        double frame_fraction = (double)elapsed_ns / (double)g_snapshot_last_capture_elapsed_ns;
        double target_pts_sec = frame_fraction * actual_duration_sec;
        int64_t pts_before = pts_from_timestamp;
        // Convert target seconds to time_base units: pts = target_sec * time_base.den / time_base.num
        pts_from_timestamp =
            (int64_t)(target_pts_sec * (double)enc->codec_ctx->time_base.den / (double)enc->codec_ctx->time_base.num);
 
        if (enc->frame_count < 3 || enc->frame_count % 10 == 0) {
          log_debug("ffmpeg: snapshot frame %d: PTS distributed (before=%lld, after=%lld, sec=%lld->%lld, frac=%.3f)",
                    enc->frame_count, (long long)pts_before, (long long)pts_from_timestamp,
                    (long long)((double)pts_before * enc->codec_ctx->time_base.num / enc->codec_ctx->time_base.den),
                    (long long)target_pts_sec, frame_fraction);
        }
      }
    }
  }
 
  // Use timestamp-based (or scaled) PTS
  enc->frame_encoded->pts = pts_from_timestamp;
  enc->last_video_pts = pts_from_timestamp;
  enc->video_pts += frame_duration;
 
  if (!snapshot_mode) {
    log_debug_every(US_PER_SEC_INT, "PTS calculation - elapsed_ns=%llu, pts_from_timestamp=%lld, fps=%d",
                    (unsigned long long)elapsed_ns, (long long)pts_from_timestamp, enc->fps);
  }
 
  // Send frame to encoder
  int ret = avcodec_send_frame(enc->codec_ctx, enc->frame_encoded);
  uint64_t submitted_ns = time_get_ns();
  if (ret < 0) {
    return SET_ERRNO(ERROR_MEDIA_INIT, "Cannot encode recording frame: %d", ret);
  }
 
  // Receive packets from encoder and write to file
  static int write_frame_pkt_count = 0;
 
  while (ret >= 0) {
    ret = avcodec_receive_packet(enc->codec_ctx, enc->pkt);
    if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
      break;
    if (ret < 0) {
      return SET_ERRNO(ERROR_MEDIA_INIT, "ffmpeg: avcodec_receive_packet failed: %d", ret);
    }
 
    write_frame_pkt_count++;
 
    // Set packet duration in codec time base (duration of one frame at target FPS)
    // This ensures proper stream duration calculation
    if (enc->pkt->duration == 0) {
      enc->pkt->duration = enc->codec_ctx->time_base.den / (enc->codec_ctx->time_base.num * enc->fps);
    }
 
    av_packet_rescale_ts(enc->pkt, enc->codec_ctx->time_base, enc->stream->time_base);
    enc->pkt->stream_index = enc->stream->index;
 
    // In snapshot mode, apply adjusted duration if snapshot_actual_duration is set
    // This happens when we get the actual duration from the capture thread
    bool is_snapshot_mode = GET_OPTION(snapshot_mode);
    if (is_snapshot_mode && !enc->has_audio_stream && enc->snapshot_actual_duration > 0 && enc->frame_count > 0) {
      int64_t adjusted_dur = (int64_t)((enc->snapshot_actual_duration * enc->stream->time_base.den) / enc->frame_count);
      // Only apply if it's significantly different from the default
      if (adjusted_dur > enc->pkt->duration * 2) {
        enc->pkt->duration = adjusted_dur;
        log_debug("ffmpeg: write_frame packet %d duration adjusted to %lld units based on actual duration",
                  write_frame_pkt_count, (long long)enc->pkt->duration);
      }
    } else if (!is_snapshot_mode && write_frame_pkt_count < 3) {
      log_debug("ffmpeg: write_frame pkt %d, duration=%lld, snapshot_mode=%d, actual_dur=%.2f, frame_count=%d",
                write_frame_pkt_count, (long long)enc->pkt->duration, is_snapshot_mode, enc->snapshot_actual_duration,
                enc->frame_count);
    }
 
    if (write_frame_pkt_count <= 2 || write_frame_pkt_count >= 16) {
      log_debug_every(
          US_PER_SEC_INT,
          "ffmpeg: write_frame pkt %d with final duration=%lld (%.6f sec in stream time_base), total frames=%d",
          write_frame_pkt_count, (long long)enc->pkt->duration, (double)enc->pkt->duration / enc->stream->time_base.den,
          enc->frame_count);
    }
 
    ret = av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
    av_packet_unref(enc->pkt);
    if (ret < 0) {
      return SET_ERRNO(ERROR_FILE_OPERATION, "ffmpeg: av_interleaved_write_frame failed: %d", ret);
    }
 
    // Flush output buffer for stdout to ensure frames are written immediately
    if (enc->is_stdout_pipe) {
      avio_flush(enc->fmt_ctx->pb);
    }
  }
 
  uint64_t muxed_ns = time_get_ns();
  log_debug_every(US_PER_SEC_INT, "ENCODER_STAGE: convert_ms=%.2f submit_ms=%.2f packets_ms=%.2f",
                  (double)(converted_ns - conversion_started_ns) / NS_PER_MS_INT,
                  (double)(submitted_ns - converted_ns) / NS_PER_MS_INT,
                  (double)(muxed_ns - submitted_ns) / NS_PER_MS_INT);
  enc->frame_count++;
  return ASCIICHAT_OK;
}
 
static asciichat_error_t encoder_prepare_audio_frame(ffmpeg_encoder_t *enc) {
  enc->audio_frame->nb_samples = enc->audio_frame_size;
  if (!enc->audio_frame->buf[0] && av_frame_get_buffer(enc->audio_frame, 0) < 0)
    return SET_ERRNO(ERROR_MEMORY, "Cannot allocate recording audio frame");
  if (av_frame_make_writable(enc->audio_frame) < 0)
    return SET_ERRNO(ERROR_MEMORY, "Cannot make recording audio frame writable");
  const uint8_t *input[] = {(const uint8_t *)enc->audio_partial_buf};
  int converted =
      swr_convert(enc->audio_swr_ctx, enc->audio_frame->data, enc->audio_frame_size, input, enc->audio_frame_size);
  if (converted < 0)
    return SET_ERRNO(ERROR_MEDIA_INIT, "Cannot convert recording audio samples: %d", converted);
  enc->audio_frame->nb_samples = converted;
  enc->audio_frame->pts = enc->audio_pts;
  return ASCIICHAT_OK;
}
 
asciichat_error_t ffmpeg_encoder_write_audio(ffmpeg_encoder_t *enc, const float *samples, int num_samples) {
  if (!enc || !samples || num_samples <= 0)
    return ASCIICHAT_OK; // Silently ignore invalid calls
 
  // No audio stream for this format
  if (!enc->has_audio_stream)
    return ASCIICHAT_OK;
 
  // Accumulate samples into partial buffer
  int samples_to_process = num_samples;
  int samples_offset = 0;
 
  while (samples_to_process > 0) {
    // How many samples can we add to the partial buffer?
    int space_in_buffer = enc->audio_frame_size * 2 - enc->audio_partial_len;
    int samples_to_copy = (samples_to_process < space_in_buffer) ? samples_to_process : space_in_buffer;
 
    // Copy samples to partial buffer
    memcpy(&enc->audio_partial_buf[enc->audio_partial_len], &samples[samples_offset], samples_to_copy * sizeof(float));
    enc->audio_partial_len += samples_to_copy;
    samples_offset += samples_to_copy;
    samples_to_process -= samples_to_copy;
 
    // If buffer is full, encode and write frame
    if (enc->audio_partial_len >= enc->audio_frame_size * 2) {
      // Set up audio frame with accumulated samples
      asciichat_error_t prepare_result = encoder_prepare_audio_frame(enc);
      if (prepare_result != ASCIICHAT_OK)
        return prepare_result;
 
      // Send frame to encoder
      int ret = avcodec_send_frame(enc->audio_codec_ctx, enc->audio_frame);
      if (ret < 0) {
        return SET_ERRNO(ERROR_MEDIA_INIT, "Cannot encode recording audio: %d", ret);
      } else {
        // Receive and write packets
        while (ret >= 0) {
          ret = avcodec_receive_packet(enc->audio_codec_ctx, enc->pkt);
          if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
            break;
          if (ret < 0) {
            return SET_ERRNO(ERROR_MEDIA_INIT, "ffmpeg: avcodec_receive_packet for audio failed: %d", ret);
          }
 
          // Rescale timestamp and write
          av_packet_rescale_ts(enc->pkt, enc->audio_codec_ctx->time_base, enc->audio_stream->time_base);
          enc->pkt->stream_index = enc->audio_stream->index;
          ret = av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
          av_packet_unref(enc->pkt);
          if (ret < 0) {
            return SET_ERRNO(ERROR_FILE_OPERATION, "ffmpeg: av_interleaved_write_frame for audio failed: %d", ret);
          }
        }
      }
 
      // Update PTS for next frame
      enc->audio_pts += enc->audio_frame_size;
      enc->audio_partial_len = 0;
    }
  }
 
  return ASCIICHAT_OK;
}
 
void ffmpeg_encoder_set_snapshot_actual_duration(ffmpeg_encoder_t *enc, double actual_duration_sec) {
  if (!enc)
    return;
  enc->snapshot_actual_duration = actual_duration_sec;
 
  // If we already have frame count, we can calculate the adjusted packet duration now
  // This will be used for any remaining frames and during flush
  if (enc->frame_count > 0 && actual_duration_sec > 0) {
    // Calculate the packet duration that would make all frames fit in actual_duration_sec
    // packet_duration_units = (actual_duration_sec * time_base.den) / frame_count
    // This is only a starting point - the actual duration might be different if more frames are captured
    log_debug("%.3f sec with %d frames so far", actual_duration_sec, enc->frame_count);
  } else {
    log_info("Setting duration to %.3f seconds (already encoded %d frames)", actual_duration_sec, enc->frame_count);
  }
}
 
// Drain output before retrying input rejected by the encoder's backpressure.
// A NULL frame enters draining mode only after the encoder accepts it.
static asciichat_error_t finish_audio_frame(ffmpeg_encoder_t *enc, const AVFrame *frame) {
  asciichat_error_t result = ASCIICHAT_OK;
  LOG_IO("ffmpeg", {
    int send_ret;
    do {
      send_ret = avcodec_send_frame(enc->audio_codec_ctx, frame);
      if (send_ret < 0 && send_ret != AVERROR(EAGAIN) && send_ret != AVERROR_EOF) {
        result = SET_ERRNO(ERROR_MEDIA_INIT, "Cannot finalize audio frame: %d", send_ret);
        break;
      }
 
      bool received_packet = false;
      while (1) {
        int ret = avcodec_receive_packet(enc->audio_codec_ctx, enc->pkt);
        if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
          break;
        if (ret < 0) {
          result = SET_ERRNO(ERROR_MEDIA_INIT, "Cannot receive final audio packet: %d", ret);
          goto capture_done;
        }
 
        received_packet = true;
        av_packet_rescale_ts(enc->pkt, enc->audio_codec_ctx->time_base, enc->audio_stream->time_base);
        enc->pkt->stream_index = enc->audio_stream->index;
        int write_ret = av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
        if (write_ret < 0)
          result = SET_ERRNO(ERROR_FILE_OPERATION, "Cannot write final audio packet: %d", write_ret);
        av_packet_unref(enc->pkt);
      }
 
      // FFmpeg guarantees that a rejected send allows receiving output.
      if (send_ret == AVERROR(EAGAIN) && !received_packet) {
        result = SET_ERRNO(ERROR_MEDIA_INIT, "Audio encoder made no progress during finalization");
        break;
      }
    } while (send_ret == AVERROR(EAGAIN));
  capture_done:;
  });
  return result;
}
 
static void encoder_log_snapshot_duration(const ffmpeg_encoder_t *enc) {
  // In snapshot mode, calculate the FPS needed to match the target duration
  bool snapshot_mode = GET_OPTION(snapshot_mode);
  int64_t adjusted_packet_duration = 0;
  double snapshot_delay = GET_OPTION(snapshot_delay);
 
  if (snapshot_mode && !enc->has_audio_stream && !enc->live_timing && enc->frame_count > 0 && snapshot_delay > 0) {
    // Calculate output FPS that distributes frames across snapshot_delay seconds
    // output_fps = frame_count / snapshot_delay
    // packet_duration (in stream time_base) = stream_time_base.den / output_fps
    //                                        = (stream_time_base.den * snapshot_delay) / frame_count
    adjusted_packet_duration = (int64_t)((snapshot_delay * enc->stream->time_base.den) / enc->frame_count);
    log_info("Snapshot mode - adjusting packet durations for %d frames over %.2f seconds", enc->frame_count,
             snapshot_delay);
    log_debug("  Adjusted packet duration: %lld units (%.6f seconds per frame)", (long long)adjusted_packet_duration,
              (double)adjusted_packet_duration / enc->stream->time_base.den);
  }
}
 
static asciichat_error_t encoder_flush_video(ffmpeg_encoder_t *enc) {
  asciichat_error_t result = ASCIICHAT_OK;
  // Flush delayed video packets. Encoders such as VP9 may buffer every short
  // snapshot frame until this point.
  LOG_IO("ffmpeg", {
    int flush_ret = avcodec_send_frame(enc->codec_ctx, NULL);
    if (flush_ret < 0 && flush_ret != AVERROR_EOF)
      result = SET_ERRNO(ERROR_MEDIA_INIT, "Cannot flush video encoder: %d", flush_ret);
    while (1) {
      int ret = avcodec_receive_packet(enc->codec_ctx, enc->pkt);
      if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
        break;
      if (ret < 0) {
        result = SET_ERRNO(ERROR_MEDIA_INIT, "Cannot receive final video packet: %d", ret);
        break;
      }
 
      // Set packet duration in codec time base if not already set
      if (enc->pkt->duration == 0) {
        enc->pkt->duration = enc->codec_ctx->time_base.den / (enc->codec_ctx->time_base.num * enc->fps);
      }
 
      av_packet_rescale_ts(enc->pkt, enc->codec_ctx->time_base, enc->stream->time_base);
      enc->pkt->stream_index = enc->stream->index;
      int write_ret = av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
      if (write_ret < 0)
        result = SET_ERRNO(ERROR_FILE_OPERATION, "Cannot write final video packet: %d", write_ret);
      av_packet_unref(enc->pkt);
    }
  });
 
  return result;
}
 
static asciichat_error_t encoder_flush_audio(ffmpeg_encoder_t *enc) {
  asciichat_error_t result = ASCIICHAT_OK;
  // Flush audio encoder if present
  if (enc->has_audio_stream && enc->audio_codec_ctx) {
    // Write any remaining partial audio samples as padding
    if (enc->audio_partial_len > 0) {
      // Zero-pad the remaining samples
      memset(&enc->audio_partial_buf[enc->audio_partial_len], 0,
             (enc->audio_frame_size * 2 - enc->audio_partial_len) * sizeof(float));
      asciichat_error_t pad_result = encoder_prepare_audio_frame(enc);
      if (pad_result == ASCIICHAT_OK)
        pad_result = finish_audio_frame(enc, enc->audio_frame);
      if (pad_result != ASCIICHAT_OK)
        result = pad_result;
    }
 
    // Flush any remaining packets (capture FFmpeg audio codec logs)
    asciichat_error_t flush_result = finish_audio_frame(enc, NULL);
    if (flush_result != ASCIICHAT_OK)
      result = flush_result;
  }
 
  return result;
}
 
static void encoder_set_stream_duration(ffmpeg_encoder_t *enc) {
  // Set stream duration for proper metadata (must be before trailer)
  if (enc->stream && enc->frame_count > 0) {
    int64_t duration;
    bool snapshot_mode = GET_OPTION(snapshot_mode);
    if (snapshot_mode && !enc->has_audio_stream && !enc->live_timing) {
      extern uint64_t g_snapshot_actual_duration_ms;
      double snapshot_delay = GET_OPTION(snapshot_delay);
      // Use actual capture elapsed time if available, otherwise use snapshot_delay
      // This ensures frames are distributed across the correct time window
      double actual_capture_duration = g_snapshot_actual_duration_ms / 1000.0;
      double effective_duration = (actual_capture_duration > 0) ? actual_capture_duration : snapshot_delay;
 
      // In snapshot mode with wall-clock timing, the video duration should equal the actual elapsed time
      // duration_seconds = effective_duration
      // duration_time_base_units = effective_duration * time_base.den
      duration = (int64_t)(effective_duration * enc->stream->time_base.den);
 
      // Calculate what the frame durations should be to sum to effective_duration
      // This ensures FFmpeg plays the captured frames across the full effective_duration
      // effective_frame_duration = effective_duration / frame_count (seconds per frame)
      int64_t effective_frame_duration =
          (int64_t)((effective_duration / (double)enc->frame_count) * enc->stream->time_base.den);
 
      log_info("Snapshot mode - snapshot_delay=%.2f, frames=%d, output_duration=%.2f sec", snapshot_delay,
               enc->frame_count, effective_duration);
      log_debug("  Using effective_duration=%.2f seconds for output", effective_duration);
      log_debug("  stream->time_base=%d/%d, effective frame duration=%lld time_base units", enc->stream->time_base.num,
                enc->stream->time_base.den, (long long)effective_frame_duration);
      log_debug("  (each frame should span %.3f seconds to total %.2f seconds)",
                effective_duration / (double)enc->frame_count, effective_duration);
 
      log_info("Setting stream->duration=%lld (effective_duration=%.3f, time_base=%d/%d, "
               "equiv=%.3f sec)",
               (long long)duration, effective_duration, enc->stream->time_base.num, enc->stream->time_base.den,
               (double)duration * enc->stream->time_base.num / enc->stream->time_base.den);
    } else {
      // Normal mode: calculate duration from frame count and FPS
      // time_base = 1 / time_base.den seconds per unit
      // Each frame is 1/fps seconds, so duration = frame_count / fps seconds
      // In time base units: duration = (frame_count / fps) * time_base.den = frame_count * time_base.den / fps
      duration = (enc->live_timing ? enc->last_video_pts + 1 : (int64_t)enc->frame_count) * enc->stream->time_base.den /
                 enc->fps;
      log_debug("Normal mode - Set stream duration=%lld (frames=%d, fps=%d, time_base=%d/%d)", (long long)duration,
                enc->frame_count, enc->fps, 1, enc->stream->time_base.den);
    }
    enc->stream->duration = duration;
 
    // Each frame was encoded with FPS-based duration, but snapshot mode needs them distributed
    // across the actual capture duration. Since we can't change past frame durations, we extend
    // the last frame's duration to make the sum equal the desired total.
    if (snapshot_mode) {
      // Calculate sum of all frame durations (each frame currently has the same FPS-based duration)
      int64_t current_total_duration = enc->video_pts; // This is the sum of all frame durations so far
      int64_t desired_duration = duration;
 
      // The last frame needs to be extended to: desired - (sum of all other frames)
      // This ensures the video plays for exactly the snapshot_delay duration
      int64_t last_frame_extension = desired_duration - current_total_duration;
 
      if (last_frame_extension > 0) {
        // We need to extend the last frame. But we can't modify it directly after encoding.
        // Instead, the muxer will use stream->duration as the authoritative source.
        log_debug("Last frame would need extension of %lld units to reach total %lld "
                  "(currently %lld)",
                  (long long)last_frame_extension, (long long)desired_duration, (long long)current_total_duration);
      }
    }
  }
}
 
static asciichat_error_t encoder_finalize_output(ffmpeg_encoder_t *enc) {
  asciichat_error_t result = ASCIICHAT_OK;
  // Write trailer (capture FFmpeg muxer logs and final frame statistics)
  LOG_IO("ffmpeg", {
    int trailer_ret = av_write_trailer(enc->fmt_ctx);
    if (trailer_ret < 0)
      result = SET_ERRNO(ERROR_FILE_OPERATION, "Cannot finalize recording: %d", trailer_ret);
  });
 
  // Flush output buffer for stdout/pipes before closing
  if (enc->fmt_ctx && enc->fmt_ctx->pb) {
    avio_flush(enc->fmt_ctx->pb);
    if (enc->fmt_ctx->pb->error < 0)
      result = SET_ERRNO(ERROR_FILE_OPERATION, "Recording output failed: %d", enc->fmt_ctx->pb->error);
    log_debug("Flushed output buffer");
  }
 
  // Close output file
  if (enc->fmt_ctx && !(enc->fmt_ctx->oformat->flags & AVFMT_NOFILE)) {
    if (enc->is_stdout_pipe) {
      encoder_close_io(enc);
    } else {
      int close_ret = avio_closep(&enc->fmt_ctx->pb);
      if (close_ret < 0)
        result = SET_ERRNO(ERROR_FILE_OPERATION, "Cannot close recording: %d", close_ret);
    }
  }
 
  return result;
}
 
static void encoder_free(ffmpeg_encoder_t *enc) {
  // Cleanup
  sws_freeContext(enc->sws_ctx);
  av_frame_free(&enc->frame);
  av_frame_free(&enc->frame_encoded);
 
  // Cleanup audio resources (capture any remaining FFmpeg logs from codec cleanup)
  if (enc->has_audio_stream) {
    swr_free(&enc->audio_swr_ctx);
    av_frame_free(&enc->audio_frame);
    LOG_IO("ffmpeg", { avcodec_free_context(&enc->audio_codec_ctx); });
    SAFE_FREE(enc->audio_partial_buf);
  }
 
  av_packet_free(&enc->pkt);
  LOG_IO("ffmpeg", { avcodec_free_context(&enc->codec_ctx); });
  if (enc->fmt_ctx)
    avformat_free_context(enc->fmt_ctx);
 
  log_debug("wrote %d frames", enc->frame_count);
  SAFE_FREE(enc);
}
 
asciichat_error_t ffmpeg_encoder_destroy(ffmpeg_encoder_t *enc) {
  if (!enc)
    return ASCIICHAT_OK;
 
  asciichat_error_t result = ASCIICHAT_OK;
  NAMED_UNREGISTER(enc);
 
  encoder_log_snapshot_duration(enc);
 
  result = encoder_flush_video(enc);
 
  asciichat_error_t audio_result = encoder_flush_audio(enc);
  if (audio_result != ASCIICHAT_OK)
    result = audio_result;
 
  encoder_set_stream_duration(enc);
 
  asciichat_error_t output_result = encoder_finalize_output(enc);
  if (output_result != ASCIICHAT_OK)
    result = output_result;
 
  encoder_free(enc);
  return result;
}
 
void ffmpeg_encoder_set_live_timing(ffmpeg_encoder_t *enc) {
  if (enc)
    enc->live_timing = true;
}