GSM(3)

🌸 GSM(3) — the library functions manual, but make it cute 🌸

okay bestie, sit down, hydrate, and let me tell you about GSM(3) — a whole manual page living in the Library Functions Manual section. it's giving "vintage codec lore" and honestly? we're obsessed. 🎀

---

✨ NAME ✨

gsm_create, gsm_destroy, gsm_encode, gsm_decode — GSM 06.10 lossy sound compression. that's the whole vibe. compression, but make it speech. 🗣️💅

---

✨ SYNOPSIS ✨

#include "gsm.h"

gsm gsm_create();

void gsm_encode(handle, src, dst)
gsm handle;
gsm_signal src[160];
gsm_frame dst;

int gsm_decode(handle, src, dst)
gsm handle;
gsm_frame src;
gsm_signal dst[160];

void gsm_destroy(handle)
gsm handle;

look at these little K&R-style signatures, they're so retro. no cap. 🦋

---

✨ DESCRIPTION ✨

okay so Gsm is a whole implementation of the final draft GSM 06.10 standard for full-rate speech transcoding. yes, that's a real sentence. yes, it's iconic. ✨

• gsm_create() — initializes a gsm pass and hands you back a 'gsm' object. that object is your ✨handle✨, and you'll be passing it to gsm_decode(), gsm_encode() or gsm_destroy() later. main character object, fr fr.
• gsm_encode() — takes an array of 160 13-bit samples (given as gsm_signal's, which are signed integral values of at least 16 bits) and squishes them down into a gsm_frame of 33 bytes. and btw, gsm_frame is a type defined in gsm.h as an array of 33 gsm_bytes. 💖
• gsm_decode() — the reverse bestie. decodes a gsm_frame back into an array of 160 13-bit samples (given as gsm_signals). and honestly? they sound rather like what you handed to gsm_encode() on the other side of the wire. 😭 lowkey magic.
• gsm_destroy() — finishes a gsm pass and frees all storage associated with it. say goodbye, clean up your mess, we love a responsible queen. 🫶

🎀 Sample format 🎀

here's the scaling that's assumed for input to the algorithm:

   0  1                             11 12
   S..v..v..v..v..v..v..v..v..v..v..v..v..*..*..*

so the tea is: only the top 13 bits get used as a signed input value. ⭐

and the output of gsm_decode() has the three lower bits set to zero. noted. not negotiable. 💅

---

✨ RETURN VALUE ✨

• gsm_create() returns an opaque handle object of type gsm, or 0 on error. so like, check it. please. 🙈
• gsm_decode() returns -1 if the frame you passed is invalid, else 0. simple as that. 💀

---

✨ EXAMPLE ✨

here's the whole thing in action, bestie — read it slow, it's actually so satisfying:

#include "gsm.h"

gsm handle;
gsm_frame buf;
gsm_signal sample[160];
int cc, soundfd;

play() {  /* read compressed data from standard input, write to soundfd */

     if (!(handle = gsm_create())) error...
     while (cc = read(0, (char *)buf, sizeof buf)) {
          if (cc != sizeof buf) error...
          if (gsm_decode(handle, buf, sample) < 0) error...
          if (write(soundfd, sample, sizeof sample) != sizeof sample)
               error...
     }
     gsm_destroy(handle);
}

record() {     /* read from soundfd, write compressed to standard output */

     if (!(handle = gsm_create())) error...
     while (cc = read(soundfd, sample, sizeof sample)) {
          if (cc != sizeof sample) error...
          gsm_encode(handle, sample, buf);
          if (write(1, (char *)buf, sizeof buf) != sizeof sample)
               error...
     }
     gsm_destroy(handle);
}

play() and record() are literally the duo of the century. one reads compressed data from standard input and writes to soundfd, the other reads from soundfd and writes compressed to standard output. symmetrical queens. 👑🌈

---

💀 BUGS 💀

found a bug? don't be shy. please direct bug reports to jutta@pobox.com and cabo@tzi.org. they're waiting. be nice. 🍓

---

✨ SEE ALSO ✨

• toast(1)
• gsm_print(3)
• gsm_explode(3)
• gsm_option(3)

go read those too, iykyk. 🧚

---

and that's the whole page!! this little GSM(3) manual page is filed under the Library Functions Manual section, and it's signed off at the bottom with GSM(3) — that's the manual, that's the version, that's the whole era. periodt. 💜✨