Hi,

EDIT: To anyone reading this later on - the algorithms produce identical results bit-for-bit if done correctly. See my last reply. As a programming exercise, spot my error in the code in this reply.

I have a project (and old game) with ADPCM samples. The port has inferior ADPCM decoding.

I've tried the algorithm from DOSBox (staging) and this one. Both are miles better. Sometimes it's difficult to hear the difference but sometimes it's much more clear

(to clafify: to the inferior one from MultimediaWiki - these two are indistinguishable at least by my ear, and even if substracting the waveforms, the difference is negligible but not 0).

However, the algorithm here and in DOSBox staging is not bit perfect, or I've made a mistake. It's certainly possible. I'm decoding in C, I may have made a mistake in either one - or maybe I'm having a slightly different lookup table 😀.

Anyways, here are the algorithm I'm using. Can you spot a mistake? The sound samples "sound" good and waveforms look a lot better than with the algorithm the port used (from MediaWiki). (In case you have ADPCM data, try decvogon and adpcm4decode below to see the difference yourself - it's small but it's there).

EDIT: It seems like out a total of 57 ADPCM samples, these algorithms produce an identical results, bit-for-bit, in 30 case, but differ in 27. It's weird - but there is a difference!

EDIT2: I changed the algorithms just so that they are initialized to 0 and also decode the first ADPCM byre. Now I get IDENTICAL 41 out of 57! But still 16 differ. They always differ at the first or the second byte. I still suspect maybe some byte is leaking outside the sample data in my code. I've updated the code below accordingly.

1#include <stdlib.h>
2#include <stdint.h>
3#include <assert.h>
4#include <stdio.h>
5
6#include "adpcm_decode.h"
7
8const signed char sndsb_adpcm_4bit_scalemap[64] = {
9    0,  1,  2,  3,  4,  5,  6,  7,  0,  -1,  -2,  -3,  -4,  -5,  -6,  -7,
10    1,  3,  5,  7,  9, 11, 13, 15, -1,  -3,  -5,  -7,  -9, -11, -13, -15,
11    2,  6, 10, 14, 18, 22, 26, 30, -2,  -6, -10, -14, -18, -22, -26, -30,
12    4, 12, 20, 28, 36, 44, 52, 60, -4, -12, -20, -28, -36, -44, -52, -60
13};
14
15const signed char sndsb_adpcm_4bit_adjustmap[64] = {
16          0, 0, 0, 0, 0, 16, 16, 16,
17          0, 0, 0, 0, 0, 16, 16, 16,
18        240, 0, 0, 0, 0, 16, 16, 16,
19        240, 0, 0, 0, 0, 16, 16, 16,
20        240, 0, 0, 0, 0, 16, 16, 16,
21        240, 0, 0, 0, 0, 16, 16, 16,
22        240, 0, 0, 0, 0,  0,  0,  0,
23        240, 0, 0, 0, 0,  0,  0,  0
24};
25
26
27// /*********************************************************************************
28//  * UPDATED to adapt information from Dosbox Staging source -> */
29//  * https://github.com/dosbox-staging/dosbox-staging/blob/main/src/hardware/audio/soundblaster.cpp */
30//  *********************************************************************************/
31unsigned char *adpcm4decode(unsigned char *data, int len) {
32
33    unsigned char *new_sample = malloc (2 * (len ));
34    int byte;
35    unsigned char value;
36    int i;
37    int map_i = 31;
38    int step; //, shift; //  limit , sign;
39    step = 0;
40
41
42    byte = 0; // data[0];
43    new_sample[0] = 0;
44
45    printf("Pointer before: %p\n", new_sample);
46
47    for (int i = 0; i < len; i++) {
48      for ( int j = 1; j >= 0 ; j-- ) { // low<>high bits
49        // higher or lower 4 bits
50        value = j == 0 ? data[i] & 0x0f : ( data[i] & 0xf0 ) >> 4;
51        map_i = value + step;
52        // clamp to max_i = 63 (len-1)
53        map_i = map_i < 0 ? 0 : map_i > 63 ? 63 : map_i;
54        step = ( step + sndsb_adpcm_4bit_adjustmap[map_i]) & 0xff; // why this AND? drop >8 bits?
55        byte = ( byte + sndsb_adpcm_4bit_scalemap[map_i] );
56        // clamp to 0 ... 255
57        byte = byte < 0 ? 0 : byte > 255 ? 255 : byte;
58        new_sample[0] = byte;
59        new_sample++;
60      }

61    }
62    new_sample-=2 * ( len - 0 ) ;
63    printf("Pointer after: %p\n", new_sample);
64    return new_sample;
65
66}
67
68unsigned char *decvogon(unsigned char *data, int len) {
69    unsigned char *new_sample = malloc (2 * (len ));
70    int byte;
71    unsigned char value;
72    int i;
73        
74    int step; //, shift; //  limit , sign;
75    printf("Pointer before: %p\n", new_sample);
76    new_sample[0]=0; // data[0];
77    int lastsample = 0; // just for the first byte needed
78    for (i = 0; i < len; i++) {
79      for (int j=1; j>=0; j--) {
80        value = j == 0 ? data[i] & 0x0f : ( data[i] & 0xf0 ) >> 4;
81        new_sample[0] = DecodeADPCM4(value , lastsample);
82        lastsample=new_sample[0];
83        new_sample++;
84      }
85    }
86    new_sample-=2*(len-0);
87    printf("Pointer after: %p\n", new_sample);
88    return new_sample;
89}
90
91// /*********************************************************************************
92//  * Decoder taken from:
93//  * https://www.vogons.org/viewtopic.php?t=93707
94//  * by bananaboy
95//  *********************************************************************************/
96uint8_t DecodeADPCM4(uint8_t data, int sample)
97{
98    assert(data < 0x10);
99
100    static int accum;
101    uint8_t halfAccum = (int) accum >> 1;
102    // printf("%i", halfAccum);
103    uint8_t value = data & 7;
104    uint8_t delta = (value * accum) + halfAccum;
105
106    // int sample;
107    if (data & 8)
108    {
109      // data is negative
110      sample = sample - delta;
111      sample = sample < 0 ? 0 : sample;
112    } else { 
113      // data is positive
114      sample = sample + delta;
115      sample = sample > 255 ? 255 : sample;
116    }
117
118    if (value == 0)
119    {
120        accum = halfAccum;
121        if (accum == 0)
122            accum = 1;
123    }
124    else if (value >= 5)
125    {
126        accum <<= 1;
127        if (accum == 0x10)
128            accum = 8;
129    }
130
131    return sample;
132}
133

(It's The Last Eichhof I'm working on)

Hi,

On line 100 in the DecodeADPCM4 function the static variable is uninitialized even after your second edit, have you updated the code block? If not then depending on the compiler and flags used that variable might be initialized to a random value found in memory.

Hmm, that is true, I somehow missed that. I don't know what it should be initialised, maybe to 1, judging from the rest of the code? The OP is not clear on the matter. It is better to initialise it to *something* than let the compiler lottery 🤣

static variables are always initialized to zero by default, as part of the language specification. It should not vary by compiler.

Hmm it may still be possible accum is supposed to be 1 (rather than 0) at the beginning, since it seems to be clamped (well, floored) at one later. Also, one sample will be bit-perfectly same as with the algorithm based on lookup tables with clamp initialized to 1.

jmarsh wrote on 2026-05-07, 00:24:

static variables are always initialized to zero by default, as part of the language specification. It should not vary by compiler.

Yes you are right, for some reason I assumed that a 90s era compiler is being used by hearing the name SoundBlaster 😁 Newer compilers do initialize static arithmetic types to 0 according to the C99 standard, sorry for giving no longer correct information 🙁

Ok, I noticed my error. It was the accumulator. And a few others.

Depending on how the decoding is initialised (wrongly!), the first few bytes might have been identical just by accident. I.e. at certain values, despite the accum being initialised wrong, the output might be identical (i.e. another error cancels out another). Some implementation online incorrectly take the first byte of the ADPCM (encoded) sample as the first (decoded) sample. This is wrong (I think). The output should not be initialised to anything - Now I just initialise the decoders first value and decode every byte. The output lengths is 2 x length (of input) (not 2xlen -1 or anything like that as I've seen elsewhere).

The question is, what is the first reference value? We can not really know this. Any value could work. I just take 127, since other values tend to cause a click at the beginning. Main thing is - whatever you decide to initialise, these algorithms should be identical (when initialised at the same value).

Now, as a sidenote, sleeping is a funny thing. I went to sleep after my last reply. The first thing I thought, when I woke up, still lying in my bed, was that the accum variable is still wrong.

It needs to be initialised (to what? 1? EDIT: looking at the code, it's somewhat obvious it should be 1, otherwise first nibble would be discarded) before every decoding. In my implementation (1st reply), it used to remember what it was left when the last decoding finished. The OP has pointer to the accum, instead of handling it internally (it would work the way I've done it without pointers if everything was done in the same function and nibbles not decoded in a separate one, as then I could re-initialise it - I still do but at the outer function).

Anyways, I've updated my algorithm to initialise accum and can confirm both algorithms produce 100% identical results (at least with the samples from The Last Eichhof), if done correctly. Updated code block here (I'll leave the first one as a funny programming exercise / for reference for future readers.)

This is all C (EDIT: Cleaned up a bit unnecessary comments, more concise):

1const signed char sndsb_adpcm_4bit_scalemap[64] = {
2    0,  1,  2,  3,  4,  5,  6,  7,  0,  -1,  -2,  -3,  -4,  -5,  -6,  -7,
3    1,  3,  5,  7,  9, 11, 13, 15, -1,  -3,  -5,  -7,  -9, -11, -13, -15,
4    2,  6, 10, 14, 18, 22, 26, 30, -2,  -6, -10, -14, -18, -22, -26, -30,
5    4, 12, 20, 28, 36, 44, 52, 60, -4, -12, -20, -28, -36, -44, -52, -60
6};
7
8const signed char sndsb_adpcm_4bit_adjustmap[64] = {
9          0, 0, 0, 0, 0, 16, 16, 16,
10          0, 0, 0, 0, 0, 16, 16, 16,
11        240, 0, 0, 0, 0, 16, 16, 16,
12        240, 0, 0, 0, 0, 16, 16, 16,
13        240, 0, 0, 0, 0, 16, 16, 16,
14        240, 0, 0, 0, 0, 16, 16, 16,
15        240, 0, 0, 0, 0,  0,  0,  0,
16        240, 0, 0, 0, 0,  0,  0,  0
17};
18
19#define ADPCM_INIT 0x7f // value to init to. Could be anything
20                        // I've noticed 127 produces least clicks
21                        // ADPCM samples tend to have end/start clicks anyways
22
23  /* This is something called 8 to 4 bit ADPCM */
24  /* Originally, the decoding algorithm was taken from */
25  /* http://wiki.multimedia.cx/index.php?title=Creative_8_bits_ADPCM */
26
27// /*********************************************************************************
28//  * UPDATED to adapt information from Dosbox Staging source -> */
29//  * https://github.com/dosbox-staging/dosbox-staging/blob/main/src/hardware/audio/soundblaster.cpp */
30//  *********************************************************************************/
31unsigned char *adpcm4decode_dbs(unsigned char *data, int len) {
32
33  unsigned char *new_sample = malloc (2 * (len ));
34  int byte = ADPCM_INIT;
35  unsigned char value;
36  int map_i;
37  int step = 0;
38
39  for (int i = 0; i < len; i++) {
40    for ( int j = 1; j >= 0 ; j-- ) { // low<>high bits
41      // higher or lower 4 bits
42      value = j == 0 ? data[i] & 0x0f : ( data[i] & 0xf0 ) >> 4;
43      map_i = value + step;
44      // clamp to max_i = 63 (len-1)
45      map_i = map_i < 0 ? 0 : map_i > 63 ? 63 : map_i;
46      step = ( step + sndsb_adpcm_4bit_adjustmap[map_i]) & 0xff; // why this AND? drop >8 bits?
47      byte = ( byte + sndsb_adpcm_4bit_scalemap[map_i] );
48      // clamp to 0 ... 255
49      byte = byte < 0 ? 0 : byte > 255 ? 255 : byte;
50      new_sample[0] = byte;
51      new_sample++;
52    }
53  }
54  new_sample-=2 * ( len - 0 ) ;
55  return new_sample;
56}
57
58unsigned char *adpcm4decode_ban(unsigned char *data, int len) {
59
60  unsigned char *new_sample = malloc (2*len);

61  int accum = 1;
62  int lastsample = ADPCM_INIT;
63
64  for (int i = 0; i < len; i++) {
65    for (int j=1; j>=0; j--) {
66      unsigned char value = j == 0 ? data[i] & 0x0f : ( data[i] & 0xf0 ) >> 4;
67      new_sample[0] = DecodeADPCM4(value , lastsample, &accum);
68      lastsample=new_sample[0];
69      new_sample++;
70    }
71  }
72  new_sample-=2*len;
73  return new_sample;
74}
75
76// /*********************************************************************************
77//  * Decoder adapted from:
78//  * https://www.vogons.org/viewtopic.php?t=93707
79//  * by bananaboy
80//  *********************************************************************************/
81uint8_t DecodeADPCM4(uint8_t data, int sample, int *accum) {
82
83  uint8_t halfAccum = (int) *accum >> 1;
84  uint8_t value = data & 7;
85  uint8_t delta = (value * (*accum)) + halfAccum;
86
87  if (data & 8) {
88    // data is negative
89    sample = sample - delta;
90  } else {
91    // data is positive
92    sample = sample + delta;
93  }
94
95  // Clamp to 0...255
96  sample = sample < 0 ? 0 : sample > 255 ? 255 : sample;
97
98  if (value == 0) {
99    *accum = halfAccum;
100    if (*accum == 0) *accum = 1;
101  }
102
103  else if (value >= 5) {
104    *accum <<= 1;
105    if (*accum == 0x10) *accum = 8;
106  }
107
108  return sample;
109}

Hey nice I'm glad you found this useful. Sorry for my original post causing so much confusion! I checked my notes and implementation and you're right, `accum` should be initialised to 1. Great to hear you've solved your issue!

Cheers,
Sam

Hi Sam,

No problems!

This decoding algorithm is in-use in my fork of the Allegro4 port of The Last Eichoff, which can be found in gitea.com.