ffmpeg_encoder.c File Reference

FFmpeg video/image file encoder for render-file output. More...

Go to the source code of this file.

Data Structures
struct	ffmpeg_encoder_s
	This is the handoff point for ffmpeg encoder. Callers fill codec_ctx, stream, frame, frame_encoded before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do. More...

Macros
#define	MEDIA_FFMPEG_ENCODER_MESSAGE_BUFFER_SIZE   2048
#define	FFMPEG_STDOUT_AVIO_BUFFER_SIZE   32768

Functions
asciichat_error_t	ffmpeg_encoder_create (const char *output_path, int width_px, int height_px, int fps, ffmpeg_encoder_t **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)
asciichat_error_t	ffmpeg_encoder_write_frame (ffmpeg_encoder_t *enc, const uint8_t *rgb, int pitch, uint64_t captured_ns)
asciichat_error_t	ffmpeg_encoder_write_audio (ffmpeg_encoder_t *enc, const float *samples, int num_samples)
void	ffmpeg_encoder_set_snapshot_actual_duration (ffmpeg_encoder_t *enc, double actual_duration_sec)
asciichat_error_t	ffmpeg_encoder_destroy (ffmpeg_encoder_t *enc)
void	ffmpeg_encoder_set_live_timing (ffmpeg_encoder_t *enc)

Detailed Description

FFmpeg video/image file encoder for render-file output.

Definition in file ffmpeg_encoder.c.

Macro Definition Documentation

FFMPEG_STDOUT_AVIO_BUFFER_SIZE

#define FFMPEG_STDOUT_AVIO_BUFFER_SIZE   32768

Definition at line 11 of file ffmpeg_encoder.c.

MEDIA_FFMPEG_ENCODER_MESSAGE_BUFFER_SIZE

#define MEDIA_FFMPEG_ENCODER_MESSAGE_BUFFER_SIZE   2048

Definition at line 8 of file ffmpeg_encoder.c.

Function Documentation

ffmpeg_encoder_create()

asciichat_error_t ffmpeg_encoder_create	(	const char *	output_path,
		int	width_px,
		int	height_px,
		int	fps,
		ffmpeg_encoder_t **	out )

Create and initialize a video/image encoder.

The output format and codec are automatically determined from the file extension. See Supported Formats & Codecs for supported formats.

Bitrate: Automatically calculated from resolution (~1 Mbps per megapixel, clamped to 500-5000 kbps).

Color Space: Input is expected in RGBA format. Internal conversion to the appropriate output pixel format (YUV420P for video, RGB24 for PNG, YUVJ420P for JPEG) is handled automatically.

Parameters

	output_path	Path to the output file (extension determines format and codec)
	width_px	Video width in pixels (must be > 0)
	height_px	Video height in pixels (must be > 0)
	fps	Frames per second (must be > 0)
[out]	out	Pointer to encoder handle (set on success)

Returns

ASCIICHAT_OK on success, error code otherwise

Note

The encoder acquires resources (file handles, memory buffers) that must be released with ffmpeg_encoder_destroy(). Failure to do so may leak file handles and memory.

See also

ffmpeg_encoder_write_frame, ffmpeg_encoder_destroy, ffmpeg_encoder_formats

Definition at line 737 of file ffmpeg_encoder.c.

                                                                {
  return ffmpeg_encoder_create_scaled(output_path, width_px, height_px, width_px, height_px, fps, out);
}

References ffmpeg_encoder_create_scaled(), and out.

ffmpeg_encoder_create_scaled()

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 )

Create an encoder that scales RGBA input to the requested video dimensions.

Definition at line 742 of file ffmpeg_encoder.c.

                                                                                                             {
  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;
}

References ASCIICHAT_OK, ERROR_INIT, ERROR_INVALID_PARAM, ffmpeg_encoder_s::first_frame_captured_ns, ffmpeg_encoder_s::fmt_ctx, ffmpeg_encoder_s::fps, ffmpeg_encoder_s::frame_count, ffmpeg_encoder_s::height_px, ffmpeg_encoder_s::is_image, ffmpeg_encoder_s::is_stdout_pipe, log_debug, log_info, NAMED_REGISTER_FFMPEG_ENCODER, out, SAFE_CALLOC, SAFE_FREE, SET_ERRNO, ffmpeg_encoder_s::snapshot_actual_duration, ffmpeg_encoder_s::snapshot_elapsed_ns, ffmpeg_encoder_s::source_height, ffmpeg_encoder_s::source_width, ffmpeg_encoder_s::target_pix_fmt, ffmpeg_encoder_s::video_pts, and ffmpeg_encoder_s::width_px.

Referenced by ffmpeg_encoder_create(), and render_file_create().

ffmpeg_encoder_destroy()

asciichat_error_t ffmpeg_encoder_destroy

(

ffmpeg_encoder_t *

enc

)

Close and finalize the output file, releasing all encoder resources.

This function flushes any pending frames in the encoder, writes the file trailer, and releases all allocated resources (memory buffers, file handles, codecs).

Critical: This MUST be called to properly finalize the output file. Without this call, the file may be incomplete or unplayable.

Parameters

enc	Encoder handle (created with ffmpeg_encoder_create())

Returns

ASCIICHAT_OK on success (currently always succeeds)

Note

Safe to call with NULL pointer (returns ASCIICHAT_OK).

After this call, enc must not be used again.

The output file is NOT guaranteed to be complete until this function returns.

See also

ffmpeg_encoder_create

Definition at line 1352 of file ffmpeg_encoder.c.

                                                                {
  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;
}

References ASCIICHAT_OK, and NAMED_UNREGISTER.

Referenced by render_file_create(), and render_file_destroy().

ffmpeg_encoder_set_live_timing()

void ffmpeg_encoder_set_live_timing

(

ffmpeg_encoder_t *

enc

)

Definition at line 1377 of file ffmpeg_encoder.c.

                                                           {
  if (enc)
    enc->live_timing = true;
}

References ffmpeg_encoder_s::live_timing.

Referenced by render_file_set_live_timing().

ffmpeg_encoder_set_snapshot_actual_duration()

void ffmpeg_encoder_set_snapshot_actual_duration	(	ffmpeg_encoder_t *	enc,
		double	actual_duration_sec )

Set the actual wall-clock duration for snapshot mode frame timing.

In snapshot mode, frames are captured over a wall-clock duration (e.g., 3 seconds of real time). This function should be called after all frames are captured to provide the actual elapsed time, allowing the encoder to calculate correct frame durations so the output video duration matches the actual capture time.

Parameters

enc	Encoder handle (created with ffmpeg_encoder_create())
actual_duration_sec	Actual wall-clock duration in seconds (e.g., 3.5 for 3.5 seconds)

Note

Only used in snapshot mode. In normal mode, this is ignored.

Should be called before ffmpeg_encoder_destroy() for the adjustment to take effect.

If not called, frame durations are calculated from FPS, which may not match actual wall-clock capture time.

See also

ffmpeg_encoder_create, ffmpeg_encoder_destroy

Definition at line 1089 of file ffmpeg_encoder.c.

                                                                                                    {
  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);
  }
}

References ffmpeg_encoder_s::frame_count, log_debug, log_info, and ffmpeg_encoder_s::snapshot_actual_duration.

Referenced by render_file_set_snapshot_actual_duration().

ffmpeg_encoder_write_audio()

asciichat_error_t ffmpeg_encoder_write_audio	(	ffmpeg_encoder_t *	enc,
		const float *	samples,
		int	num_samples )

Write audio samples to the output file.

Encodes and writes audio samples to the output file. Audio samples must be in 48kHz mono float32 format. The function internally buffers and accumulates samples into codec frames before encoding.

Audio Format Requirements:

• Sample rate: 48000 Hz (48 kHz)
• Channels: Mono (1 channel)
• Format: 32-bit IEEE float (AV_SAMPLE_FMT_FLT)

Notes:

• Audio is only written if the output format supports audio (MP4, WebM, AVI).
• Image formats (PNG, JPEG, GIF) ignore audio writes.
• Samples are buffered internally and encoded in chunks as needed.
• Timing is automatically synchronized with video using PTS (presentation timestamp).

Parameters

enc	Encoder handle (created with ffmpeg_encoder_create())
samples	Pointer to audio samples in float32 format (not owned, used immediately)
num_samples	Number of samples to write (must be > 0)

Returns

ASCIICHAT_OK on success, error code otherwise

Note

Input sample data is NOT owned by the encoder. The caller must ensure the buffer remains valid throughout the call.

Safe to call on encoders without audio streams (no-op).

See also

ffmpeg_encoder_create, ffmpeg_encoder_write_frame

Definition at line 1025 of file ffmpeg_encoder.c.

                                                                                                           {
  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;
}

References ASCIICHAT_OK, ffmpeg_encoder_s::audio_codec_ctx, ffmpeg_encoder_s::audio_frame, ffmpeg_encoder_s::audio_frame_size, ffmpeg_encoder_s::audio_partial_buf, ffmpeg_encoder_s::audio_partial_len, ffmpeg_encoder_s::audio_pts, ffmpeg_encoder_s::audio_stream, EAGAIN, ERROR_FILE_OPERATION, ERROR_MEDIA_INIT, ffmpeg_encoder_s::fmt_ctx, ffmpeg_encoder_s::has_audio_stream, ffmpeg_encoder_s::pkt, and SET_ERRNO.

Referenced by render_file_destroy().

ffmpeg_encoder_write_frame()

asciichat_error_t ffmpeg_encoder_write_frame	(	ffmpeg_encoder_t *	enc,
		const uint8_t *	rgb,
		int	pitch,
		uint64_t	captured_ns )

Write a single video frame to the output file.

The frame must be in RGBA format (8-bit per channel, 32-bit per pixel). Internal color space conversion is performed automatically based on the output format (see Encoder Options & Quality Tradeoffs for details).

Pitch Parameter: The pitch parameter specifies the byte offset from one row to the next. For tightly-packed RGBA data: pitch = width_px × 4. For padded/aligned buffers: pitch must reflect the actual row size.

Timestamp Parameter: The captured_ns parameter is the wall-clock timestamp (in nanoseconds) when the frame was captured. This ensures video playback uses actual capture timing, not encoder processing time. For correct frame timing in the output video, captured_ns should be the time when the frame was acquired from the media source.

Parameters

enc	Encoder handle (created with ffmpeg_encoder_create())
rgb	Pointer to frame data in RGBA format (not copied, used immediately)
pitch	Byte offset between rows (must match actual buffer layout)
captured_ns	Wall-clock timestamp in nanoseconds when frame was captured

Returns

ASCIICHAT_OK on success, error code otherwise

Note

Input frame data is NOT owned by the encoder. The caller must ensure the buffer remains valid throughout the call.

For image-only formats (PNG, JPEG), only the last frame written is kept. Previous frames are discarded when the next frame is written.

See also

ffmpeg_encoder_create, ffmpeg_encoder_destroy

Definition at line 825 of file ffmpeg_encoder.c.

                                                                   {
  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;
}

References ASCIICHAT_OK, ffmpeg_encoder_s::codec_ctx, EAGAIN, ERROR_FILE_OPERATION, ERROR_INVALID_PARAM, ERROR_MEDIA_INIT, ERROR_MEMORY, ffmpeg_encoder_s::estimated_frame_count, ffmpeg_encoder_s::first_frame_captured_ns, ffmpeg_encoder_s::fmt_ctx, ffmpeg_encoder_s::fps, ffmpeg_encoder_s::frame_count, ffmpeg_encoder_s::frame_encoded, g_snapshot_actual_duration_ms, g_snapshot_last_capture_elapsed_ns, GET_OPTION, ffmpeg_encoder_s::has_audio_stream, ffmpeg_encoder_s::height_px, ffmpeg_encoder_s::is_stdout_pipe, ffmpeg_encoder_s::last_video_pts, ffmpeg_encoder_s::live_timing, log_debug, log_debug_every, log_info, NS_PER_MS_INT, NS_PER_SEC_INT, ffmpeg_encoder_s::pkt, ffmpeg_encoder_s::previous_captured_ns, SET_ERRNO, ffmpeg_encoder_s::snapshot_actual_duration, ffmpeg_encoder_s::source_height, ffmpeg_encoder_s::stream, ffmpeg_encoder_s::sws_ctx, ffmpeg_encoder_s::target_pix_fmt, US_PER_SEC_INT, ffmpeg_encoder_s::video_pts, and ffmpeg_encoder_s::width_px.