decoder.h File Reference

HEVC/H.265 decoder for ASCII art frames using libde265. More...

Go to the source code of this file.

Macros
#define	H265_DECODER_FLAG_KEYFRAME   0x01
#define	H265_DECODER_FLAG_SIZE_CHANGE   0x02

Functions
h265_decoder_t *	h265_decoder_create (void)
void	h265_decoder_destroy (h265_decoder_t *decoder)
asciichat_error_t	h265_decode (h265_decoder_t *decoder, const uint8_t *encoded_packet, size_t packet_size, uint16_t *output_width, uint16_t *output_height, uint8_t *output_buf, size_t *output_size)
void	h265_decoder_get_stats (h265_decoder_t *decoder, uint64_t *total_frames, uint64_t *keyframes, uint16_t *last_width, uint16_t *last_height)

Detailed Description

HEVC/H.265 decoder for ASCII art frames using libde265.

Decodes x265-encoded ASCII art frames back into terminal grid data. Automatically reconfigures when frame size changes.

FRAME SIZE CHANGES: The decoder reads width/height from each packet and reconfigures as needed. No explicit API call required - handled transparently during decode.

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

Definition in file video/h265/decoder.h.

Macro Definition Documentation

H265_DECODER_FLAG_KEYFRAME

#define H265_DECODER_FLAG_KEYFRAME   0x01

Decoder flags (from packet)

Definition at line 28 of file video/h265/decoder.h.

Referenced by h265_decode().

H265_DECODER_FLAG_SIZE_CHANGE

#define H265_DECODER_FLAG_SIZE_CHANGE   0x02

Definition at line 29 of file video/h265/decoder.h.

Function Documentation

h265_decode()

asciichat_error_t h265_decode	(	h265_decoder_t *	decoder,
		const uint8_t *	encoded_packet,
		size_t	packet_size,
		uint16_t *	output_width,
		uint16_t *	output_height,
		uint8_t *	output_buf,
		size_t *	output_size )

Decode an x265-encoded ASCII frame

The decoder reads width/height from the packet and automatically reconfigures when frame dimensions change.

Parameters

decoder	Decoder handle
encoded_packet	Encoded packet (flags+width+height+x265_data)
packet_size	Size of encoded packet
output_width	Output: decoded frame width
output_height	Output: decoded frame height
output_buf	Buffer for decoded ASCII data (should be at least width×height)
output_size	Input: buffer size, Output: actual decoded size

Returns

Error code (ASCIICHAT_OK on success)

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

Call this as: uint16_t width, height; uint8_t ascii_grid[256*64]; size_t decoded_size = sizeof(ascii_grid); h265_decode(decoder, packet, packet_size, &width, &height, ascii_grid, &decoded_size);

Definition at line 108 of file video/h265/decoder.c.

                                                   {
  ASCII_OTEL_SCOPE(H265_DECODE);
  if (!decoder || !encoded_packet || !output_width || !output_height || !output_buf || !output_size) {
    return SET_ERRNO(ERROR_INTERNAL, "Invalid decoder arguments");
  }
 
  if (packet_size < 5) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Packet too small (minimum 5 bytes)");
  }
 
  // Parse header
  uint8_t flags = encoded_packet[0];
  uint16_t width = ((uint16_t)encoded_packet[1] << 8) | encoded_packet[2];
  uint16_t height = ((uint16_t)encoded_packet[3] << 8) | encoded_packet[4];
 
  if (width == 0 || height == 0) {
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid frame dimensions: %ux%u", width, height);
  }
 
  size_t required_output = width * height;
  if (*output_size < required_output) {
    *output_size = required_output;
    return SET_ERRNO(ERROR_NETWORK_SIZE, "Output buffer too small: need %zu, have %zu", required_output, *output_size);
  }
 
  // Decode HEVC data
  if (packet_size > 5) {
    const uint8_t *hevc_data = encoded_packet + 5;
    size_t hevc_size = packet_size - 5;
 
    // Send packet to decoder
    // FFmpeg owns packet storage and requires zero padding after the payload.
    // The wire buffer belongs to the caller and may be stack allocated.
    if (hevc_size > INT_MAX)
      return SET_ERRNO(ERROR_NETWORK_SIZE, "Encoded video packet exceeds FFmpeg limits");
    av_packet_unref(decoder->packet);
    if (av_new_packet(decoder->packet, (int)hevc_size) < 0)
      return SET_ERRNO(ERROR_MEMORY, "Cannot allocate decoder packet");
    memcpy(decoder->packet->data, hevc_data, hevc_size);
 
    uint64_t stats_codec_start = time_get_ns();
    int send_result = avcodec_send_packet(decoder->codec_ctx, decoder->packet);
    av_packet_unref(decoder->packet);
    if (send_result < 0) {
      return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to send packet to decoder");
    }
 
    int stats_decode_result = avcodec_receive_frame(decoder->codec_ctx, decoder->frame);
    stats_duration_record(stats_runtime_scope(), STATS_DURATION_DECODE, time_get_ns() - stats_codec_start);
    if (stats_decode_result < 0) {
      return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to receive decoded frame");
    }
  } else {
    // Empty packet - just signal a frame boundary
    if (avcodec_send_packet(decoder->codec_ctx, NULL) < 0) {
      return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to flush decoder");
    }
  }
 
  // Extract Y plane (grayscale intensity)
  uint8_t *y_plane = decoder->frame->data[0];
  int y_stride = decoder->frame->linesize[0];
  int img_width = decoder->frame->width;
  int img_height = decoder->frame->height;
 
  if (img_width != (int)width || img_height != (int)height) {
    log_warn("Image dimensions mismatch: expected %ux%u, got %dx%d", width, height, img_width, img_height);
  }
 
  // Copy Y plane to output (ASCII intensity values)
  for (int y = 0; y < img_height && y < (int)height; y++) {
    memcpy(output_buf + y * width, y_plane + y * y_stride, width);
  }
 
  *output_width = width;
  *output_height = height;
  *output_size = width * height;
 
  decoder->last_width = width;
  decoder->last_height = height;
  decoder->total_frames++;
  ASCII_OTEL_ATTR_STRING("video.codec", "h265");
  ASCII_OTEL_ATTR_INT("video.frame.width", width);
  ASCII_OTEL_ATTR_INT("video.frame.height", height);
  ASCII_OTEL_ATTR_INT("video.frame.keyframe", (flags & H265_DECODER_FLAG_KEYFRAME) != 0);
  ASCII_OTEL_ATTR_INT("video.packet.size", (int64_t)packet_size);
  ascii_otel_metric(ASCII_OTEL_METRIC_VIDEO_DECODE_BYTES, (double)packet_size);
  ascii_otel_metric(ASCII_OTEL_METRIC_VIDEO_DECODE_FRAMES, 1);
  ascii_otel_metric(ASCII_OTEL_METRIC_VIDEO_DECODE_BYTES_OUT, (double)*output_size);
  stats_counter_add(stats_runtime_scope(), STATS_COUNTER_FRAMES_DECODED, 1);
 
  if (flags & H265_DECODER_FLAG_KEYFRAME) {
    decoder->keyframes++;
  }
 
  return ASCIICHAT_OK;
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, ASCIICHAT_OK, h265_decoder::codec_ctx, ERROR_INTERNAL, ERROR_MEDIA_DECODE, ERROR_MEMORY, ERROR_NETWORK_PROTOCOL, ERROR_NETWORK_SIZE, h265_decoder::frame, H265_DECODER_FLAG_KEYFRAME, height, h265_decoder::keyframes, h265_decoder::last_height, h265_decoder::last_width, log_warn, h265_decoder::packet, SET_ERRNO, stats_counter_add(), STATS_COUNTER_FRAMES_DECODED, STATS_DURATION_DECODE, stats_duration_record(), stats_runtime_scope(), h265_decoder::total_frames, and width.

Referenced by h265_server_decode_and_convert().

h265_decoder_create()

h265_decoder_t * h265_decoder_create

(

void

)

Create a new x265 decoder for ASCII frames

Returns

Decoder handle, or NULL on error

Definition at line 38 of file video/h265/decoder.c.

                                          {
  ASCII_OTEL_SCOPE(H265_DECODER_CREATE);
  h265_decoder_t *dec = SAFE_CALLOC(1, sizeof(h265_decoder_t), h265_decoder_t *);
  if (!dec) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate decoder structure");
    return NULL;
  }
 
  defer_named(cleanup, h265_decoder_destroy(dec));
 
  // Find HEVC decoder
  const AVCodec *codec = avcodec_find_decoder(AV_CODEC_ID_HEVC);
  if (!codec) {
    SET_ERRNO(ERROR_MEDIA_INIT, "HEVC decoder not found");
    return NULL;
  }
 
  dec->codec_ctx = avcodec_alloc_context3(codec);
  if (!dec->codec_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate codec context");
    return NULL;
  }
 
  // Open decoder (capture x265 library output during initialization)
  int codec_open_result = 0;
  LOG_IO("hevc", { codec_open_result = avcodec_open2(dec->codec_ctx, codec, NULL); });
 
  if (codec_open_result < 0) {
    SET_ERRNO(ERROR_MEDIA_INIT, "Failed to open HEVC decoder");
    return NULL;
  }
 
  // Allocate frame and packet
  dec->frame = av_frame_alloc();
  dec->packet = av_packet_alloc();
  dec->parser = av_parser_init(AV_CODEC_ID_HEVC);
 
  if (!dec->frame || !dec->packet || !dec->parser) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate frame/packet/parser");
    return NULL;
  }
 
  log_info("FFmpeg HEVC decoder created");
 
  // Register decoder for debugging
  NAMED_REGISTER_H265_DECODER(dec, "h265_decoder", NULL);
 
  defer_cancel(cleanup);
  return dec;
}

References ASCII_OTEL_SCOPE, h265_decoder::codec_ctx, ERROR_MEDIA_INIT, ERROR_MEMORY, h265_decoder::frame, h265_decoder_destroy(), log_info, LOG_IO, NAMED_REGISTER_H265_DECODER, h265_decoder::packet, h265_decoder::parser, SAFE_CALLOC, and SET_ERRNO.

Referenced by h265_server_get_client_decoder().

h265_decoder_destroy()

void h265_decoder_destroy

(

h265_decoder_t *

decoder

)

Destroy an x265 decoder

Parameters

decoder

Decoder to destroy (may be NULL)

Definition at line 89 of file video/h265/decoder.c.

                                                   {
  if (!decoder)
    return;
 
  if (decoder->frame) {
    av_frame_free(&decoder->frame);
  }
  if (decoder->packet) {
    av_packet_free(&decoder->packet);
  }
  if (decoder->parser) {
    av_parser_close(decoder->parser);
  }
  if (decoder->codec_ctx) {
    avcodec_free_context(&decoder->codec_ctx);
  }
  SAFE_FREE(decoder);
}

References h265_decoder::codec_ctx, h265_decoder::frame, h265_decoder::packet, h265_decoder::parser, and SAFE_FREE.

Referenced by h265_decoder_create(), h265_server_context_destroy(), and h265_server_remove_client().

h265_decoder_get_stats()

void h265_decoder_get_stats	(	h265_decoder_t *	decoder,
		uint64_t *	total_frames,
		uint64_t *	keyframes,
		uint16_t *	last_width,
		uint16_t *	last_height )

Get decoder statistics

Parameters

decoder	Decoder handle
total_frames	Output: total frames decoded
keyframes	Output: total keyframes decoded
last_width	Output: width of last decoded frame
last_height	Output: height of last decoded frame

Definition at line 208 of file video/h265/decoder.c.

                                                   {
  if (!decoder)
    return;
 
  if (total_frames)
    *total_frames = decoder->total_frames;
  if (keyframes)
    *keyframes = decoder->keyframes;
  if (last_width)
    *last_width = decoder->last_width;
  if (last_height)
    *last_height = decoder->last_height;
}

References h265_decoder::keyframes, h265_decoder::last_height, h265_decoder::last_width, and h265_decoder::total_frames.

Referenced by h265_server_client_get_stats().