encoder.h File Reference

HEVC/H.265 encoder for ASCII art frames using libx265. More...

Go to the source code of this file.

Macros
#define	H265_ENCODER_FLAG_KEYFRAME   0x01
#define	H265_ENCODER_FLAG_SIZE_CHANGE   0x02

Typedefs
typedef struct h265_encoder	h265_encoder_t

Functions
h265_encoder_t *	h265_encoder_create (uint16_t initial_width, uint16_t initial_height)
void	h265_encoder_destroy (h265_encoder_t *encoder)
asciichat_error_t	h265_encode (h265_encoder_t *encoder, uint16_t width, uint16_t height, const uint8_t *ascii_data, uint8_t *output_buf, size_t *output_size)
void	h265_encoder_request_keyframe (h265_encoder_t *encoder)
asciichat_error_t	h265_encoder_flush (h265_encoder_t *encoder, uint8_t *output_buf, size_t *output_size)
void	h265_encoder_get_stats (h265_encoder_t *encoder, uint64_t *total_frames, uint64_t *keyframes, uint32_t *avg_bitrate)

Detailed Description

HEVC/H.265 encoder for ASCII art frames using libx265.

Encodes terminal ASCII grid data using x265 for efficient compression. Handles variable-sized frames by storing dimensions in the encoded packet.

FRAME SIZE CHANGES: When terminal resize occurs (width/height change), the encoder must be reconfigured. This is handled transparently - the encoder detects size changes and reinitializes as needed.

PACKET FORMAT: [flags: u8][width: u16][height: u16][encoded_data: x265]

• flags: Encoding flags (keyframe, etc.)
• width: Frame width in characters
• height: Frame height in characters
• encoded_data: x265-encoded frame data

Definition in file encoder.h.

Macro Definition Documentation

H265_ENCODER_FLAG_KEYFRAME

#define H265_ENCODER_FLAG_KEYFRAME   0x01

Encoder flags

Definition at line 33 of file encoder.h.

H265_ENCODER_FLAG_SIZE_CHANGE

#define H265_ENCODER_FLAG_SIZE_CHANGE   0x02

Definition at line 34 of file encoder.h.

Typedef Documentation

h265_encoder_t

typedef struct h265_encoder h265_encoder_t

Definition at line 28 of file encoder.h.

Function Documentation

h265_encode()

asciichat_error_t h265_encode	(	h265_encoder_t *	encoder,
		uint16_t	width,
		uint16_t	height,
		const uint8_t *	ascii_data,
		uint8_t *	output_buf,
		size_t *	output_size
	)

Encode an ASCII art frame

The encoder automatically detects size changes and reinitializes when needed. The output packet includes frame dimensions so decoder can reconfigure.

Parameters

encoder	Encoder handle
width	Current frame width (characters)
height	Current frame height (characters)
ascii_data	Raw ASCII character grid (width × height bytes)
output_buf	Buffer for encoded output
output_size	Input: buffer size, Output: actual encoded size

Returns

Error code (ASCIICHAT_OK on success)

OUTPUT PACKET FORMAT: [flags: u8][width: u16][height: u16][x265_data...]

Definition at line 91 of file comprehensive.c.

                                                                  {
  (void)encoder;
  (void)width;
  (void)height;
  (void)pixel_data;
  (void)out_data;
  (void)out_len;
  return SET_ERRNO(ERROR_NOT_SUPPORTED, "H.265 encoding not supported in WASM");
}

References ASCIICHAT_OK, EAGAIN, ERROR_INTERNAL, ERROR_MEDIA_DECODE, ERROR_NETWORK_SIZE, ERROR_NOT_SUPPORTED, H265_ENCODER_FLAG_KEYFRAME, H265_ENCODER_FLAG_SIZE_CHANGE, log_debug, log_dev, log_error, log_info, and SET_ERRNO.

Referenced by acip_send_image_frame_h265(), h265_client_capture_and_encode(), and threaded_send_image_frame_h265().

h265_encoder_create()

h265_encoder_t * h265_encoder_create	(	uint16_t	initial_width,
		uint16_t	initial_height
	)

Create a new x265 encoder for ASCII frames

Parameters

initial_width	Initial frame width (characters)
initial_height	Initial frame height (characters)

Returns

Encoder handle, or NULL on error

Definition at line 55 of file encoder.c.

                                                                                     {
  if (initial_width == 0 || initial_height == 0) {
    SET_ERRNO(ERROR_MEDIA_INIT, "Frame dimensions must be non-zero");
    return NULL;
  }
 
  h265_encoder_t *enc = SAFE_CALLOC(1, sizeof(h265_encoder_t), h265_encoder_t *);
  if (!enc) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate encoder structure");
    return NULL;
  }
 
  // Find best available HEVC encoder (try by ID first, then by name for specific implementations)
  const AVCodec *codec = avcodec_find_encoder(AV_CODEC_ID_HEVC);
 
  // If generic HEVC encoder not found, try specific implementations by name
  if (!codec) {
    codec = avcodec_find_encoder_by_name("libx265");
  }
  if (!codec) {
    codec = avcodec_find_encoder_by_name("hevc_vaapi");
  }
  if (!codec) {
    codec = avcodec_find_encoder_by_name("hevc_videotoolbox");
  }
  if (!codec) {
    codec = avcodec_find_encoder_by_name("hevc_nvenc");
  }
  if (!codec) {
    codec = avcodec_find_encoder_by_name("hevc_qsv");
  }
 
  if (!codec) {
    SET_ERRNO(ERROR_MEDIA_INIT, "HEVC encoder not found");
    SAFE_FREE(enc);
    return NULL;
  }
 
  enc->codec_ctx = avcodec_alloc_context3(codec);
  if (!enc->codec_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate codec context");
    SAFE_FREE(enc);
    return NULL;
  }
 
  // Configure codec context
  enc->codec_ctx->width = initial_width;
  enc->codec_ctx->height = initial_height;
  enc->codec_ctx->pix_fmt = AV_PIX_FMT_YUV420P;
  enc->codec_ctx->time_base = (AVRational){1, 30};
  enc->codec_ctx->framerate = (AVRational){30, 1};
 
  // Set ultrafast preset for low-latency encoding
  if (av_opt_set(enc->codec_ctx->priv_data, "preset", "ultrafast", 0) < 0) {
    log_warn("Failed to set preset to ultrafast, using default");
  }
  if (av_opt_set(enc->codec_ctx->priv_data, "tune", "zerolatency", 0) < 0) {
    log_warn("Failed to set tune to zerolatency, using default");
  }
 
  enc->codec_ctx->thread_count = h265_thread_count();
 
  // Defer avcodec_open2 to first encode call. The initial resolution (800x600) is
  // usually wrong — the actual frame resolution is only known when the first capture
  // arrives. Opening the codec here would create an x265 thread pool (~1s) that gets
  // immediately discarded on reconfigure, wasting startup time.
  enc->codec_opened = false;
 
  // Allocate frame and packet
  enc->frame = av_frame_alloc();
  enc->packet = av_packet_alloc();
 
  if (!enc->frame || !enc->packet) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet");
    if (enc->frame)
      av_frame_free(&enc->frame);
    if (enc->packet)
      av_packet_free(&enc->packet);
    avcodec_free_context(&enc->codec_ctx);
    SAFE_FREE(enc);
    return NULL;
  }
 
  enc->current_width = initial_width;
  enc->current_height = initial_height;
 
  // Allocate YUV420P buffer (Y plane + U/V planes)
  size_t stride = initial_width;
  enc->yuv_buf_size = stride * initial_height * 3 / 2;
  enc->yuv_buf = SAFE_MALLOC(enc->yuv_buf_size, uint8_t *);
  if (!enc->yuv_buf) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate YUV buffer");
    av_frame_free(&enc->frame);
    av_packet_free(&enc->packet);
    avcodec_free_context(&enc->codec_ctx);
    SAFE_FREE(enc);
    return NULL;
  }
 
  log_info("FFmpeg HEVC encoder created: %ux%u (codec: %s)", initial_width, initial_height, codec->name);
 
  // Register encoder for debugging
  NAMED_REGISTER_H265_ENCODER(enc, "h265_encoder", NULL);
 
  return enc;
}

References ERROR_MEDIA_INIT, ERROR_MEMORY, log_info, log_warn, NAMED_REGISTER_H265_ENCODER, SAFE_CALLOC, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

h265_encoder_destroy()

void h265_encoder_destroy

(

h265_encoder_t *

encoder

)

Destroy an x265 encoder

Parameters

encoder

Encoder to destroy (may be NULL)

Definition at line 102 of file comprehensive.c.

                                                   {
  (void)encoder;
}

References LOG_IO, and SAFE_FREE.

Referenced by h265_client_context_create(), and h265_client_context_destroy().

h265_encoder_flush()

asciichat_error_t h265_encoder_flush	(	h265_encoder_t *	encoder,
		uint8_t *	output_buf,
		size_t *	output_size
	)

Flush remaining buffered frames from encoder

Sends a NULL frame to the encoder to flush all buffered frames. This should be called before destroying the encoder or when you need to ensure all encoded data is retrieved.

Parameters

encoder	Encoder handle
output_buf	Buffer for encoded output
output_size	Input: buffer size, Output: actual encoded size

Returns

Error code (ASCIICHAT_OK on success, ASCIICHAT_OK with size=0 when no more data)

USAGE: // After final h265_encode() call, flush remaining frames while (size > 0) { size = max_size; h265_encoder_flush(encoder, buf, &size); if (size > 0) { // Send the flushed frame... } }

Definition at line 106 of file comprehensive.c.

                                                                                                  {
  (void)encoder;
  (void)out_data;
  (void)out_len;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, EAGAIN, ERROR_INTERNAL, ERROR_MEDIA_DECODE, ERROR_NETWORK_SIZE, H265_ENCODER_FLAG_KEYFRAME, log_debug, log_dev, log_error, and SET_ERRNO.

Referenced by protocol_stop_connection().

h265_encoder_get_stats()

void h265_encoder_get_stats	(	h265_encoder_t *	encoder,
		uint64_t *	total_frames,
		uint64_t *	keyframes,
		uint32_t *	avg_bitrate
	)

Get encoder statistics

Parameters

encoder	Encoder handle
total_frames	Output: total frames encoded
keyframes	Output: total keyframes encoded
avg_bitrate	Output: average bitrate in bits per second

Definition at line 464 of file encoder.c.

                                                   {
  if (!encoder)
    return;
 
  if (total_frames)
    *total_frames = encoder->total_frames;
  if (keyframes)
    *keyframes = encoder->keyframes;
  if (avg_bitrate)
    *avg_bitrate = encoder->avg_bitrate;
}

Referenced by h265_client_get_stats().

h265_encoder_request_keyframe()

void h265_encoder_request_keyframe

(

h265_encoder_t *

encoder

)

Request a keyframe on the next encode

Forces the encoder to produce an I-frame (keyframe) on the next call to h265_encoder_encode(). Useful for error recovery or stream synchronization.

Parameters

encoder

Encoder handle

Definition at line 113 of file comprehensive.c.

                                                            {
  (void)encoder;
}

Referenced by h265_client_request_keyframe().