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

Typedefs
typedef struct h265_decoder	h265_decoder_t

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 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 decoder.h.

H265_DECODER_FLAG_SIZE_CHANGE

#define H265_DECODER_FLAG_SIZE_CHANGE   0x02

Definition at line 29 of file decoder.h.

Typedef Documentation

h265_decoder_t

typedef struct h265_decoder h265_decoder_t

Definition at line 23 of file 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 109 of file decoder.c.

                                                   {
  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
    av_packet_from_data(decoder->packet, (uint8_t *)hevc_data, hevc_size);
 
    if (avcodec_send_packet(decoder->codec_ctx, decoder->packet) < 0) {
      return SET_ERRNO(ERROR_MEDIA_DECODE, "Failed to send packet to decoder");
    }
 
    if (avcodec_receive_frame(decoder->codec_ctx, decoder->frame) < 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++;
 
  if (flags & H265_DECODER_FLAG_KEYFRAME) {
    decoder->keyframes++;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, h265_decoder::codec_ctx, ERROR_INTERNAL, ERROR_MEDIA_DECODE, ERROR_NETWORK_PROTOCOL, ERROR_NETWORK_SIZE, h265_decoder::frame, H265_DECODER_FLAG_KEYFRAME, h265_decoder::keyframes, h265_decoder::last_height, h265_decoder::last_width, log_warn, h265_decoder::packet, SET_ERRNO, and h265_decoder::total_frames.

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 31 of file decoder.c.

                                          {
  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;
  }
 
  // Find HEVC decoder
  const AVCodec *codec = avcodec_find_decoder(AV_CODEC_ID_HEVC);
  if (!codec) {
    SET_ERRNO(ERROR_MEDIA_INIT, "HEVC decoder not found");
    SAFE_FREE(dec);
    return NULL;
  }
 
  dec->codec_ctx = avcodec_alloc_context3(codec);
  if (!dec->codec_ctx) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate codec context");
    SAFE_FREE(dec);
    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");
    avcodec_free_context(&dec->codec_ctx);
    SAFE_FREE(dec);
    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");
    if (dec->frame)
      av_frame_free(&dec->frame);
    if (dec->packet)
      av_packet_free(&dec->packet);
    if (dec->parser)
      av_parser_close(dec->parser);
    avcodec_free_context(&dec->codec_ctx);
    SAFE_FREE(dec);
    return NULL;
  }
 
  log_info("FFmpeg HEVC decoder created");
 
  // Register decoder for debugging
  NAMED_REGISTER_H265_DECODER(dec, "h265_decoder", NULL);
 
  return dec;
}

References h265_decoder::codec_ctx, ERROR_MEDIA_INIT, ERROR_MEMORY, h265_decoder::frame, log_info, LOG_IO, NAMED_REGISTER_H265_DECODER, h265_decoder::packet, h265_decoder::parser, SAFE_CALLOC, SAFE_FREE, 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 90 of file 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_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 187 of file 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().