test_codec_translations.c File Reference

Codec Translation Roundtrip Tests. More...

#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"

Include dependency graph for test_codec_translations.c:

Go to the source code of this file.

Data Structures
struct	codec_test_entry
	Codec roundtrip entry: table of codecs to test. More...

Macros
#define	CHUNK_MS   20
#define	MAX_SAMPLE_ERR_LOSSLESS   256
#define	MIN_DECODED_RATIO   0.90
#define	MIN_SNR_LOSSY_DB   15.0
#define	TEST_DURATION_SECS   2

Functions
	AST_MODULE_INFO_STANDARD_EXTENDED (ASTERISK_GPL_KEY, "Codec Translation Roundtrip Tests")
	AST_TEST_DEFINE (codec_translate_roundtrip)
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)
	Attempt a roundtrip encode/decode for one codec format.
static int	compute_max_error (const int16_t *orig, const int16_t *roundtrip, int samples)
	Compute maximum absolute per-sample error.
static double	compute_snr (const int16_t *orig, const int16_t *roundtrip, int samples)
	Compute Signal-to-Noise Ratio between original and roundtripped signal.
static double	compute_snr_aligned (const int16_t *orig, const int16_t *decoded, int samples, int max_delay, int *delay_out)
	Compute SNR after aligning the decoded signal via cross-correlation.
static void	generate_speech_signal (int16_t *buf, int samples, int sample_rate)
	Generate a synthetic speech-like test signal in linear sample.
static int	load_module (void)
static int	unload_module (void)

Variables
static const struct codec_test_entry	codec_table []

Detailed Description

Codec Translation Roundtrip Tests.

Author

Sebastian Jennen sebas.nosp@m.tian.nosp@m..t.je.nosp@m.nnen.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

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.

Definition in file test_codec_translations.c.

Macro Definition Documentation

CHUNK_MS

#define CHUNK_MS   20

Chunk duration in milliseconds to feed chunks to the coders

Definition at line 61 of file test_codec_translations.c.

MAX_SAMPLE_ERR_LOSSLESS

#define MAX_SAMPLE_ERR_LOSSLESS   256

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

Definition at line 69 of file test_codec_translations.c.

MIN_DECODED_RATIO

#define MIN_DECODED_RATIO   0.90

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.

Definition at line 74 of file test_codec_translations.c.

MIN_SNR_LOSSY_DB

#define MIN_SNR_LOSSY_DB   15.0

Minimum acceptable SNR in dB for lossy codecs. Most telephony codecs at 8 kHz should exceed ~20 dB

Definition at line 65 of file test_codec_translations.c.

TEST_DURATION_SECS

#define TEST_DURATION_SECS   2

Duration of the test signal in seconds

Definition at line 58 of file test_codec_translations.c.

Function Documentation

AST_MODULE_INFO_STANDARD_EXTENDED()

AST_MODULE_INFO_STANDARD_EXTENDED	(	ASTERISK_GPL_KEY	,
		"Codec Translation Roundtrip Tests"
	)

AST_TEST_DEFINE()

AST_TEST_DEFINE

(

codec_translate_roundtrip

)

Definition at line 435 of file test_codec_translations.c.

{
    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;
}

References ao2_cleanup, ao2_ref, ARRAY_LEN, ast_format_cache_get, ast_format_slin, ast_format_slin16, ast_format_slin32, ast_format_slin48, ast_free, ast_malloc, AST_TEST_FAIL, AST_TEST_NOT_RUN, AST_TEST_PASS, ast_test_status_update, ast_translate_path_steps(), check_codec(), codec_table, generate_speech_signal(), MIN_SNR_LOSSY_DB, codec_test_entry::sample_rate, TEST_DURATION_SECS, TEST_EXECUTE, and TEST_INIT.

check_codec()

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  )

static

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.

Parameters

[in]	test	Test framework handle (for status messages)
[in]	slin_fmt	The slin format appropriate for the codec's sample rate
[in]	target_fmt	The codec format to test
[in]	orig_buf	Original slin sample buffer
[in]	total_samples	Number of samples in orig_buf
[in]	sample_rate	Sample rate in Hz
[in]	is_lossy	If non-zero, use SNR-based comparison; otherwise use max-error
[in]	min_snr_db	Minimum acceptable SNR for lossy check (ignored when !is_lossy)

Return values

AST_TEST_PASS	on success
AST_TEST_FAIL	on failure

Definition at line 228 of file test_codec_translations.c.

{
    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;
}

References ast_calloc, ast_format_get_name(), AST_FRAME_VOICE, ast_free, AST_LIST_NEXT, AST_TEST_FAIL, AST_TEST_PASS, ast_test_status_update, ast_translate(), ast_translator_build_path(), ast_translator_free_path(), CHUNK_MS, cleanup(), compute_max_error(), compute_snr(), compute_snr_aligned(), copy(), ast_frame::data, ast_frame::datalen, ast_frame_subclass::format, ast_frame::frametype, ast_frame::mallocd, MAX_SAMPLE_ERR_LOSSLESS, MIN_DECODED_RATIO, NULL, ast_frame::offset, ast_frame::ptr, result, ast_frame::samples, ast_frame::src, and ast_frame::subclass.

Referenced by AST_TEST_DEFINE().

compute_max_error()

static int compute_max_error ( const int16_t *  orig, const int16_t *  roundtrip, int  samples  )

static

Compute maximum absolute per-sample error.

Definition at line 193 of file test_codec_translations.c.

{
    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;
}

References abs.

Referenced by check_codec().

compute_snr()

static double compute_snr ( const int16_t *  orig, const int16_t *  roundtrip, int  samples  )

static

Compute Signal-to-Noise Ratio between original and roundtripped signal.

Parameters

[in]	orig	Original sample buffer
[in]	roundtrip	Decoded (roundtripped) sample buffer
[in]	samples	Number of samples

Returns

SNR in dB

Definition at line 109 of file test_codec_translations.c.

{
    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);
}

Referenced by check_codec(), and compute_snr_aligned().

compute_snr_aligned()

static double compute_snr_aligned ( const int16_t *  orig, const int16_t *  decoded, int  samples, int  max_delay, int *  delay_out  )

static

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.

Parameters

[in]	orig	Original sample buffer (must hold at least samples values)
[in]	decoded	Decoded sample buffer (must hold at least samples values)
[in]	samples	Number of samples available in each buffer
[in]	max_delay	Search range: delays 0..max_delay are tested
[out]	delay_out	Receives the best-fit delay found; may be NULL

Returns

SNR in dB at the best-fit alignment, or the unaligned SNR when samples <= max_delay

Definition at line 153 of file test_codec_translations.c.

{
    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);
}

References compute_snr(), and d.

Referenced by check_codec().

generate_speech_signal()

static void generate_speech_signal ( int16_t *  buf, int  samples, int  sample_rate  )

static

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.

Parameters

[out]	buf	Buffer to fill (must hold at least samples int16 values)
[in]	samples	Number of samples to generate
[in]	sample_rate	Sampling rate in Hz (used to scale time correctly)

Definition at line 87 of file test_codec_translations.c.

{
    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);
    }
}

References buf, and M_PI.

Referenced by AST_TEST_DEFINE().

load_module()

static int load_module ( void  )

static

Definition at line 546 of file test_codec_translations.c.

{
    AST_TEST_REGISTER(codec_translate_roundtrip);
    return AST_MODULE_LOAD_SUCCESS;
}

References AST_MODULE_LOAD_SUCCESS, and AST_TEST_REGISTER.

unload_module()

static int unload_module ( void  )

static

Definition at line 540 of file test_codec_translations.c.

{
    AST_TEST_UNREGISTER(codec_translate_roundtrip);
    return 0;
}

References AST_TEST_UNREGISTER.

Variable Documentation

codec_table

const struct codec_test_entry codec_table[]

static

Table of codecs to roundtrip-test.

Definition at line 403 of file test_codec_translations.c.

                                                     {
    /* 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 },
};

Referenced by AST_TEST_DEFINE().