asterisk/tests/test_codec_translations.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2026, Asterisk Community
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 * \brief Codec Translation Roundtrip Tests
 *
 * \author Sebastian Jennen <sebastian.t.jennen@gmail.com>
 *
 * Tests that encoding sample frames through a codec and decoding them
 * back to slin produces output that is (almost) identical to
 * the original input. This verifies that each codec translator pair
 * (slin -> codec -> slin) does not corrupt or destroy the audio signal.
 *
 * For near-lossless codecs (alaw, ulaw) the tolerance is very tight.
 * For lossy codecs (adpcm, g726, gsm, g722, speex, ilbc, opus, g729, etc.)
 * a Signal-to-Noise Ratio (SNR) threshold is used since some degradation
 * is inherent to the compression algorithm.  Wideband codecs are tested
 * with a matching slin16/slin32/slin48 signal at the codec's native
 * sample rate.
 */

/*** MODULEINFO
	<depend>TEST_FRAMEWORK</depend>
	<support_level>extended</support_level>
 ***/

#include "asterisk.h"

#include <math.h>

#include "asterisk/module.h"
#include "asterisk/test.h"
#include "asterisk/translate.h"
#include "asterisk/format.h"
#include "asterisk/format_cap.h"
#include "asterisk/format_cache.h"
#include "asterisk/codec.h"
#include "asterisk/frame.h"
#include "asterisk/slin.h"
#include "asterisk/logger.h"
#include "asterisk/utils.h"

/*! Duration of the test signal in seconds */
#define TEST_DURATION_SECS  2

/*! Chunk duration in milliseconds to feed chunks to the coders */
#define CHUNK_MS  20

/*! Minimum acceptable SNR in dB for lossy codecs.
 *  Most telephony codecs at 8 kHz should exceed ~20 dB */
#define MIN_SNR_LOSSY_DB   15.0

/*! Maximum per-sample absolute error for near-lossless codecs (ulaw/alaw).
 *  μ-law/A-law quantisation can reach a max error of 256. */
#define MAX_SAMPLE_ERR_LOSSLESS  256

/*! Minimum fraction of input samples that must survive the roundtrip.
 *  Codec lookahead + trailing partial frame may consume some samples;
 *  require at least 90 % to call the test valid. */
#define MIN_DECODED_RATIO  0.90

/*!
 * \brief Generate a synthetic speech-like test signal in linear sample.
 *
 * a mix of a 200 Hz fundamental and an 800 Hz harmonic with a slow 4 Hz
 * amplitude-modulation envelope, loosely inspired by ITU-T P.50 artificial
 * voice.
 *
 * \param[out] buf         Buffer to fill (must hold at least \a samples int16 values)
 * \param[in]  samples     Number of samples to generate
 * \param[in]  sample_rate Sampling rate in Hz (used to scale time correctly)
 */
static void generate_speech_signal(int16_t *buf, int samples, int sample_rate)
{
	int i;
	for (i = 0; i < samples; i++) {
		double t = (double)i / sample_rate;
		double sig = 0.6 * sin(2.0 * M_PI * 200.0 * t)
		           + 0.4 * sin(2.0 * M_PI * 800.0 * t);
		/* Slow AM at 4 Hz to simulate syllable rhythm */
		sig *= 0.5 * (1.0 + sin(2.0 * M_PI * 4.0 * t));
		buf[i] = (int16_t)(sig * 16000.0);
	}
}

/*!
 * \brief Compute Signal-to-Noise Ratio between original and roundtripped signal.
 *
 * \param[in] orig       Original sample buffer
 * \param[in] roundtrip  Decoded (roundtripped) sample buffer
 * \param[in] samples    Number of samples
 *
 * \return SNR in dB
 */
static double compute_snr(const int16_t *orig, const int16_t *roundtrip, int samples)
{
	double signal_power = 0.0;
	double noise_power  = 0.0;
	int i;

	for (i = 0; i < samples; i++) {
		double s = (double)orig[i];
		double n = (double)(orig[i] - roundtrip[i]);
		signal_power += s * s;
		noise_power  += n * n;
	}

	if (signal_power < 1.0) {
		return -100.0; /* degenerate signal */
	}
	if (noise_power < 1.0) {
		return 999.0; /* essentially perfect */
	}

	return 10.0 * log10(signal_power / noise_power);
}

/*!
 * \brief Compute SNR after aligning the decoded signal via cross-correlation.
 *
 * Some codecs (e.g. speex, opus) introduce an algorithmic lookahead delay:
 * the decoded signal is time-shifted by a fixed number of samples relative to
 * the original.  Computing SNR without compensating for this shift yields a
 * near-zero result even when the codec works perfectly.
 *
 * This function searches delays d = 0..max_delay, finds the integer shift
 * that maximises the cross-correlation sum orig[i]·decoded[i+d], then returns
 * the SNR computed at that optimal alignment.
 *
 * \param[in]  orig       Original sample buffer (must hold at least \a samples values)
 * \param[in]  decoded    Decoded sample buffer (must hold at least \a samples values)
 * \param[in]  samples    Number of samples available in each buffer
 * \param[in]  max_delay  Search range: delays 0..max_delay are tested
 * \param[out] delay_out  Receives the best-fit delay found; may be NULL
 *
 * \return SNR in dB at the best-fit alignment, or the unaligned SNR when
 *         \a samples <= \a max_delay
 */
static double compute_snr_aligned(const int16_t *orig, const int16_t *decoded,
	int samples, int max_delay, int *delay_out)
{
	double best_corr = -1e300;
	int best_delay = 0;
	int d;

	if (delay_out) {
		*delay_out = 0;
	}

	/* Need enough samples for a meaningful search */
	if (samples <= max_delay || max_delay <= 0) {
		return compute_snr(orig, decoded, samples);
	}

	for (d = 0; d <= max_delay; d++) {
		int n = samples - d;
		double corr = 0.0;
		int i;
		for (i = 0; i < n; i++) {
			corr += (double)orig[i] * (double)decoded[i + d];
		}
		if (corr > best_corr) {
			best_corr = corr;
			best_delay = d;
		}
	}

	if (delay_out) {
		*delay_out = best_delay;
	}

	/* Compute SNR at the best alignment */
	return compute_snr(orig, decoded + best_delay, samples - best_delay);
}

/*!
 * \brief Compute maximum absolute per-sample error.
 */
static int compute_max_error(const int16_t *orig, const int16_t *roundtrip, int samples)
{
	int max_err = 0;
	int i;

	for (i = 0; i < samples; i++) {
		int err = abs((int)orig[i] - (int)roundtrip[i]);
		if (err > max_err) {
			max_err = err;
		}
	}
	return max_err;
}

/*!
 * \brief Attempt a roundtrip encode/decode for one codec format.
 *
 * Feeds the original slin signal through the encoder and decoder in 20 ms
 * chunks (matching the universal VoIP frame duration), accumulates the
 * decoded output, and compares the full result against the original.
 * This naturally respects every codec's internal buffer sizes and frame
 * granularity without needing per-codec sample-count overrides.
 *
 * \param[in]  test         Test framework handle (for status messages)
 * \param[in]  slin_fmt     The slin format appropriate for the codec's sample rate
 * \param[in]  target_fmt   The codec format to test
 * \param[in]  orig_buf     Original slin sample buffer
 * \param[in]  total_samples Number of samples in orig_buf
 * \param[in]  sample_rate  Sample rate in Hz
 * \param[in]  is_lossy     If non-zero, use SNR-based comparison; otherwise use max-error
 * \param[in]  min_snr_db   Minimum acceptable SNR for lossy check (ignored when !is_lossy)
 *
 * \retval AST_TEST_PASS on success
 * \retval AST_TEST_FAIL on failure
 */
static enum ast_test_result_state check_codec(
	struct ast_test *test,
	struct ast_format *slin_fmt,
	struct ast_format *target_fmt,
	const int16_t *orig_buf,
	int total_samples,
	int sample_rate,
	int is_lossy,
	double min_snr_db)
{
	struct ast_trans_pvt *encode_path = NULL;
	struct ast_trans_pvt *decode_path = NULL;
	int16_t *decoded_buf = NULL;
	int total_decoded = 0;
	int chunk_samples = sample_rate * CHUNK_MS / 1000;
	int buf_capacity;
	int offset;
	enum ast_test_result_state result = AST_TEST_FAIL;
	const char *codec_name;

	codec_name = ast_format_get_name(target_fmt);

	/* --- Build encoder path: slin -> codec --- */
	encode_path = ast_translator_build_path(target_fmt, slin_fmt);
	if (!encode_path) {
		ast_test_status_update(test,
			"Skipping %s: no translation path from slin to %s\n",
			codec_name, codec_name);
		return AST_TEST_PASS;
	}

	/* --- Build decoder path: codec -> slin --- */
	decode_path = ast_translator_build_path(slin_fmt, target_fmt);
	if (!decode_path) {
		ast_test_status_update(test,
			"FAIL %s: found encoder but no decoder path back to slin\n",
			codec_name);
		goto cleanup;
	}

	/* Allocate output buffer with some headroom for codec expansion */
	buf_capacity = total_samples + chunk_samples;
	decoded_buf = ast_calloc(buf_capacity, sizeof(int16_t));
	if (!decoded_buf) {
		goto cleanup;
	}

	/* --- Feed audio in CHUNK_MS chunks through encode -> decode --- */
	for (offset = 0; offset < total_samples; offset += chunk_samples) {
		struct ast_frame input_frame;
		struct ast_frame *encoded;
		struct ast_frame *decoded;
		struct ast_frame *cur;
		int feed = total_samples - offset;
		if (feed > chunk_samples) {
			feed = chunk_samples;
		}

		memset(&input_frame, 0, sizeof(input_frame));
		input_frame.frametype       = AST_FRAME_VOICE;
		input_frame.subclass.format = slin_fmt;
		input_frame.datalen         = feed * sizeof(int16_t);
		input_frame.samples         = feed;
		input_frame.data.ptr        = (void *)(orig_buf + offset);
		input_frame.mallocd         = 0;
		input_frame.src             = "test_codec_translations";

		/* Encode: slin -> codec.  NULL means the encoder is buffering. */
		encoded = ast_translate(encode_path, &input_frame, 0);
		if (!encoded) {
			continue;
		}

		/* Decode: codec -> slin.  ast_translate follows the frame linked
		 * list internally, so passing the head feeds all encoded frames. */
		decoded = ast_translate(decode_path, encoded, 0);
		if (!decoded) {
			continue;
		}

		/* Copy decoded samples into our accumulation buffer.
		 * Walk the linked list in case frameout produced multiple frames. */
		for (cur = decoded; cur; cur = AST_LIST_NEXT(cur, frame_list)) {
			int copy;
			if (cur->frametype != AST_FRAME_VOICE || !cur->data.ptr
				|| cur->samples <= 0) {
				continue;
			}
			copy = cur->samples;
			if (total_decoded + copy > buf_capacity) {
				copy = buf_capacity - total_decoded;
			}
			memcpy(decoded_buf + total_decoded, cur->data.ptr,
				copy * sizeof(int16_t));
			total_decoded += copy;
		}
	}

	/* --- Verify we got enough decoded audio --- */
	if (total_decoded < (int)(total_samples * MIN_DECODED_RATIO)) {
		ast_test_status_update(test,
			"FAIL %s: decoded only %d of %d samples (%.0f%%)\n",
			codec_name, total_decoded, total_samples,
			100.0 * total_decoded / total_samples);
		goto cleanup;
	}

	/* --- Compare original vs decoded --- */
	{
		int cmp_samples = total_decoded < total_samples
			? total_decoded : total_samples;

		if (is_lossy) {
			int max_delay = sample_rate * 20 / 1000;  /* 20 ms search */
			int delay = 0;
			double snr = compute_snr_aligned(orig_buf, decoded_buf,
				cmp_samples, max_delay, &delay);

			ast_test_status_update(test,
				"  %s (lossy): SNR = %.1f dB (threshold %.1f dB)"
				" [%d/%d samples, delay=%d/%.1fms]\n",
				codec_name, snr, min_snr_db,
				cmp_samples, total_samples,
				delay, 1000.0 * delay / sample_rate);

			if (snr < min_snr_db) {
				ast_test_status_update(test,
					"FAIL %s: SNR %.1f dB is below minimum %.1f dB\n",
					codec_name, snr, min_snr_db);
				goto cleanup;
			}
		} else {
			int max_err = compute_max_error(orig_buf, decoded_buf, cmp_samples);
			double snr  = compute_snr(orig_buf, decoded_buf, cmp_samples);

			ast_test_status_update(test,
				"  %s (lossless): max_err = %d (limit %d),"
				" SNR = %.1f dB [%d/%d samples]\n",
				codec_name, max_err, MAX_SAMPLE_ERR_LOSSLESS, snr,
				cmp_samples, total_samples);

			if (max_err > MAX_SAMPLE_ERR_LOSSLESS) {
				ast_test_status_update(test,
					"FAIL %s: max sample error %d exceeds limit %d\n",
					codec_name, max_err, MAX_SAMPLE_ERR_LOSSLESS);
				goto cleanup;
			}
		}
	}

	result = AST_TEST_PASS;

cleanup:
	ast_free(decoded_buf);
	if (encode_path) {
		ast_translator_free_path(encode_path);
	}
	if (decode_path) {
		ast_translator_free_path(decode_path);
	}

	return result;
}

/*!
 * \brief Codec roundtrip entry: table of codecs to test.
 */
struct codec_test_entry {
	const char *format_name;   /*!< Name used in ast_format_cache_get() */
	int is_lossy;              /*!< 1 = lossy (use SNR check), 0 = near-lossless (use max err) */
	double min_snr_db;         /*!< Per-codec SNR floor; 0.0 = use MIN_SNR_LOSSY_DB default */
	int sample_rate;           /*!< Native slin rate: 8000/16000/32000/48000; 0 = default 8000 */
};

/*! Table of codecs to roundtrip-test.*/
static const struct codec_test_entry codec_table[] = {
	/* Near-lossless narrowband (8 kHz) — verified with max per-sample error */
	{ "ulaw",      0 },
	{ "alaw",      0 },

	/* Lossy narrowband (8 kHz) — verified with SNR threshold */
	{ "adpcm",     1 },          /* ADPCM: ~20 dB SNR, lossy by design */
	{ "g726",      1 },          /* G.726 ADPCM: ~28 dB SNR, lossy by design */
	{ "g726aal2",  1 },          /* G.726 AAL2 ADPCM: same as g726 */
	{ "gsm",       1 },
	{ "speex",     1, 7.0 },     /* speex is quite lossy */
	{ "ilbc",      1, 7.0 },     /* 30 ms frames: coarser quantisation lowers SNR floor */
	{ "codec2",    1, -2.0 },    /* vocoder: snr is really low, smoke-test only */
	{ "lpc10",     1, -2.0 },    /* vocoder: snr is really low, smoke-test only */

	/* { "g729",      1 },             UNTESTED yet */
	/* { "silk8",     1 },             UNTESTED yet */
	/* { "silk12",    1 },             UNTESTED yet */
	/* { "silk16",    1 },             UNTESTED yet */
	/* { "silk24",    1 },             UNTESTED yet */

	/* Wideband (16 kHz) — tested with slin16 signal. */
	{ "g722",      1, 0.0, 16000 },
	{ "speex16",   1, 5.0, 16000 },

	/* Ultra-wideband (32 kHz) — tested with slin32 signal */
	{ "speex32",   1, 5.0, 32000 },

	/* Opus native rate is 48 kHz */
	{ "opus",      1, 8.0, 48000 },
};

AST_TEST_DEFINE(codec_translate_roundtrip)
{
	int i;
	int tested = 0;
	int failed = 0;
	enum ast_test_result_state overall = AST_TEST_PASS;

	switch (cmd) {
	case TEST_INIT:
		info->name = "codec_translations";
		info->category = "/main/codec/";
		info->summary = "Roundtrip encode/decode test and quality check for various codecs referenced in this test and present in the installation";
		info->description =
			"Generates a synthetic speech-like signal (200 Hz +\n"
			"800 Hz with 4 Hz AM envelope) at the codec's native sample\n"
			"rate, feeds it through the codec and back,\n"
			"then verifies the output quality over the full duration.\n"
			"For near-lossless codecs (ulaw, alaw) it checks that the\n"
			"maximum per-sample error is within a tight bound.\n"
			"For lossy codecs it checks that the SNR exceeds a per-codec\n"
			"minimum threshold.  Vocoders use a near-zero threshold\n"
			"(smoke test).";
		return AST_TEST_NOT_RUN;
	case TEST_EXECUTE:
		break;
	}

	ast_test_status_update(test,
		"Starting codec roundtrip tests (%d codecs, %d seconds of audio)\n",
		(int)ARRAY_LEN(codec_table), TEST_DURATION_SECS);

	for (i = 0; i < (int)ARRAY_LEN(codec_table); i++) {
		struct ast_format *slin_fmt;
		struct ast_format *target_fmt;
		int16_t *orig_buf;
		enum ast_test_result_state res;
		int rate = codec_table[i].sample_rate > 0
			? codec_table[i].sample_rate : 8000;
		int total_samples = rate * TEST_DURATION_SECS;

		/* Select the slin format for this codec's native rate */
		switch (rate) {
			case 16000:
			    slin_fmt = ast_format_slin16;
			    break;
			case 32000:
			    slin_fmt = ast_format_slin32;
			    break;
			case 48000:
			    slin_fmt = ast_format_slin48;
			    break;
			default:
			    slin_fmt = ast_format_slin;
			    break;
		}

		target_fmt = ast_format_cache_get(codec_table[i].format_name);
		if (!target_fmt
			|| ast_translate_path_steps(target_fmt, slin_fmt) == -1) {
			ast_test_status_update(test,
				"  %s: no translation path available, skipping\n",
				codec_table[i].format_name);
			ao2_cleanup(target_fmt);
			continue;
		}

		orig_buf = ast_malloc(total_samples * sizeof(int16_t));
		if (!orig_buf) {
			ao2_ref(target_fmt, -1);
			overall = AST_TEST_FAIL;
			break;
		}

		generate_speech_signal(orig_buf, total_samples, rate);

		res = check_codec(
			test, slin_fmt, target_fmt, orig_buf,
			total_samples, rate,
			codec_table[i].is_lossy,
			codec_table[i].min_snr_db != 0.0
				? codec_table[i].min_snr_db : MIN_SNR_LOSSY_DB);

		ast_free(orig_buf);
		ao2_ref(target_fmt, -1);

		tested++;
		if (res == AST_TEST_FAIL) {
			failed++;
			overall = AST_TEST_FAIL;
		}
	}

	ast_test_status_update(test,
		"\nCodec roundtrip summary: %d tested, %d passed, %d failed\n",
		tested, tested - failed, failed);

	if (tested == 0) {
		ast_test_status_update(test,
			"WARNING: No codecs were available to test. "
			"Ensure codec modules are loaded.\n");
	}

	return overall;
}

static int unload_module(void)
{
	AST_TEST_UNREGISTER(codec_translate_roundtrip);
	return 0;
}

static int load_module(void)
{
	AST_TEST_REGISTER(codec_translate_roundtrip);
	return AST_MODULE_LOAD_SUCCESS;
}

AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Codec Translation Roundtrip Tests");