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

Data Structures
struct	ffmpeg_encoder_s

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_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.

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 337 of file ffmpeg_encoder.c.

                                                                {
  log_info("[FFMPEG_ENCODER_CREATE] START: output=%s, %dx%d @ %dfps", output_path, width_px, height_px, fps);
 
  if (!output_path || !out || width_px <= 0 || height_px <= 0)
    return SET_ERRNO(ERROR_INVALID_PARAM, "ffmpeg_encoder_create: invalid parameters");
 
  // Use default FPS if not specified (0 from config means "use default")
  if (fps <= 0) {
    fps = 60;
    log_debug("ffmpeg_encoder_create: 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;
 
  // 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("ffmpeg_encoder_create: 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("ffmpeg_encoder_create: 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("ffmpeg_encoder_create: Snapshot mode ENABLED - estimated_frame_count=%d (fps=%d * snapshot_delay=%.2f)",
             enc->estimated_frame_count, fps, snapshot_delay);
  } else {
    log_info("ffmpeg_encoder_create: Snapshot mode disabled or invalid - snapshot_mode=%d, snapshot_delay=%.2f, fps=%d",
             snapshot_mode, snapshot_delay, 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("ffmpeg_encoder_create: 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("ffmpeg_encoder_create: %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");
  }
 
  // 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) {
    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};
 
  // 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("ffmpeg_encoder: 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("ffmpeg_encoder: 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("ffmpeg_encoder: x265 preset=ultrafast crf=32");
  }
 
  // Open codec (capture libx264 startup logs)
  LOG_IO("ffmpeg", { ret = avcodec_open2(enc->codec_ctx, codec, &codec_opts); });
  av_dict_free(&codec_opts);
  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_open2 failed");
  }
 
  // 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");
  }
 
  // 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("ffmpeg_encoder_create: 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);
  }
 
  // 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");
  }
 
  // Create SWS context for RGBA → target format conversion
  LOG_IO("swscaler", {
    enc->sws_ctx = sws_getContext(width_px, height_px, 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");
  }
 
  // Initialize audio stream if supported
  encoder_init_audio_stream(enc, output_path);
 
  // Open output file or stdout
  if (!(enc->fmt_ctx->oformat->flags & AVFMT_NOFILE)) {
    // For stdout output, use "pipe:1" (FFmpeg's standard for writing to stdout)
    const char *open_path = output_path;
    if (output_path && strcmp(output_path, "-") == 0) {
      open_path = "pipe:1"; // Use pipe:1 for stdout
      log_debug("ffmpeg: Redirecting '-' to 'pipe:1' for stdout output");
    }
    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) {
    avio_closep(&enc->fmt_ctx->pb);
    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");
  }
 
  // 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("ffmpeg_encoder_create: 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);
  }
 
  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("[FFMPEG_ENCODER_CREATE] SUCCESS: encoder initialized, frame_count=0, fps=%d, dims=%dx%d", enc->fps,
           enc->width_px, enc->height_px);
  return ASCIICHAT_OK;
}

Referenced by 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 904 of file ffmpeg_encoder.c.

                                                                {
  if (!enc)
    return ASCIICHAT_OK;
 
  NAMED_UNREGISTER(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("ffmpeg_encoder_destroy: 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);
  }
 
  // Flush delayed video packets. Encoders such as VP9 may buffer every short
  // snapshot frame until this point.
  LOG_IO("ffmpeg", {
    avcodec_send_frame(enc->codec_ctx, NULL);
    while (1) {
      int ret = avcodec_receive_packet(enc->codec_ctx, enc->pkt);
      if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
        break;
      if (ret < 0)
        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;
      av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
      av_packet_unref(enc->pkt);
    }
  });
 
  // 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 - enc->audio_partial_len) * sizeof(float));
      enc->audio_frame->data[0] = (uint8_t *)enc->audio_partial_buf;
      enc->audio_frame->linesize[0] = enc->audio_frame_size * sizeof(float);
      enc->audio_frame->nb_samples = enc->audio_frame_size;
      enc->audio_frame->pts = enc->audio_pts;
      avcodec_send_frame(enc->audio_codec_ctx, enc->audio_frame);
    }
 
    // Flush any remaining packets (capture FFmpeg audio codec logs)
    LOG_IO("ffmpeg", {
      avcodec_send_frame(enc->audio_codec_ctx, NULL);
      while (1) {
        int ret = avcodec_receive_packet(enc->audio_codec_ctx, enc->pkt);
        if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF)
          break;
        if (ret < 0)
          break;
 
        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;
        av_interleaved_write_frame(enc->fmt_ctx, enc->pkt);
        av_packet_unref(enc->pkt);
      }
    });
  }
 
  // 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("ffmpeg_encoder_destroy: 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("ffmpeg_encoder_destroy: 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("ffmpeg_encoder_destroy: 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("ffmpeg_encoder_destroy: 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);
      }
    }
  }
 
  // Write trailer (capture FFmpeg muxer logs and final frame statistics)
  LOG_IO("ffmpeg", { av_write_trailer(enc->fmt_ctx); });
 
  // Flush output buffer for stdout/pipes before closing
  if (enc->fmt_ctx && enc->fmt_ctx->pb) {
    avio_flush(enc->fmt_ctx->pb);
    log_debug("ffmpeg_encoder_destroy: Flushed output buffer");
  }
 
  // Close output file
  if (enc->fmt_ctx && !(enc->fmt_ctx->oformat->flags & AVFMT_NOFILE))
    avio_closep(&enc->fmt_ctx->pb);
 
  // 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("ffmpeg_encoder_destroy: wrote %d frames", enc->frame_count);
  SAFE_FREE(enc);
  return ASCIICHAT_OK;
}

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 1087 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 884 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("ffmpeg_encoder_set_snapshot_actual_duration: %.3f sec with %d frames so far", actual_duration_sec,
              enc->frame_count);
  } else {
    log_info(
        "ffmpeg_encoder_set_snapshot_actual_duration: 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 817 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 - 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) {
      // Set up audio frame with accumulated samples
      enc->audio_frame->data[0] = (uint8_t *)enc->audio_partial_buf;
      enc->audio_frame->linesize[0] = enc->audio_frame_size * sizeof(float);
      enc->audio_frame->nb_samples = enc->audio_frame_size;
      enc->audio_frame->pts = enc->audio_pts;
 
      // Send frame to encoder
      int ret = avcodec_send_frame(enc->audio_codec_ctx, enc->audio_frame);
      if (ret < 0) {
        log_warn_every(5 * 1000000000LL, "ffmpeg: avcodec_send_frame for audio failed");
      } 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) {
            log_warn_every(5 * 1000000000LL, "ffmpeg: avcodec_receive_packet for audio failed");
            break;
          }
 
          // 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) {
            log_warn_every(5 * 1000000000LL, "ffmpeg: av_interleaved_write_frame for audio failed");
            break;
          }
        }
      }
 
      // 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, ffmpeg_encoder_s::fmt_ctx, ffmpeg_encoder_s::has_audio_stream, log_warn_every, and ffmpeg_encoder_s::pkt.

Referenced by render_file_destroy(), and render_file_write_frame().

◆ 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 641 of file ffmpeg_encoder.c.

                                                                   {
  if (!enc || !rgb)
    return SET_ERRNO(ERROR_INVALID_PARAM, "ffmpeg_encoder_write_frame: 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("ffmpeg_encoder_write_frame: first frame captured at %llu ns", (unsigned long long)captured_ns);
  }
 
  log_info("[FFMPEG_ENCODER_WRITE] frame %d, pitch=%d, dims=%dx%d", enc->frame_count, pitch, enc->width_px,
           enc->height_px);
  log_debug("ffmpeg_encoder_write_frame: frame %d, pitch=%d, dims=%dx%d, captured_ns=%llu", enc->frame_count, pitch,
            enc->width_px, enc->height_px, (unsigned long long)captured_ns);
 
  // Set up RGBA frame for conversion
  uint8_t *data[1] = {(uint8_t *)rgb};
  int linesize[1] = {pitch};
 
  // 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
  sws_scale(enc->sws_ctx, (const uint8_t *const *)data, linesize, 0, enc->height_px, enc->frame_encoded->data,
            enc->frame_encoded->linesize);
 
  // Set frame duration based on mode
  int64_t frame_duration;
  bool snapshot_mode = GET_OPTION(snapshot_mode);
 
  if (enc->frame_count == 0) {
    log_info("ffmpeg_encoder_write_frame: 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("ffmpeg_encoder_write_frame: 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);
  if (ret < 0) {
    log_warn_every(5 * 1000000000LL, "ffmpeg: avcodec_send_frame failed");
    return ASCIICHAT_OK; // Continue anyway
  }
 
  // 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) {
      log_warn_every(5 * 1000000000LL, "ffmpeg: avcodec_receive_packet failed");
      break;
    }
 
    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("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) {
      log_warn_every(5 * 1000000000LL, "ffmpeg: av_interleaved_write_frame failed");
      break;
    }
 
    // Flush output buffer for stdout to ensure frames are written immediately
    if (enc->is_stdout_pipe) {
      avio_flush(enc->fmt_ctx->pb);
    }
  }
 
  enc->frame_count++;
  return ASCIICHAT_OK;
}

Referenced by render_file_write_frame().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ffmpeg_encoder_create()

◆ ffmpeg_encoder_destroy()

◆ ffmpeg_encoder_set_live_timing()

◆ ffmpeg_encoder_set_snapshot_actual_duration()

◆ ffmpeg_encoder_write_audio()

◆ ffmpeg_encoder_write_frame()