GSM(3)

💖 GSM(3) — the GSM 06.10 lossy sound compression page, but make it make sense 💖

okay bestie, welcome to GSM(3), from the Library Functions Manual. This is the girlies' guide to gsm_create, gsm_destroy, gsm_encode and gsm_decode — aka GSM 06.10 lossy sound compression. Grab a strawberry 🍓, we're doing speech transcoding.

---

✨ NAME ✨

gsm_create, gsm_destroy, gsm_encode, gsm_decode — GSM 06.10 lossy sound compression 🎀

---

🌸 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;

yes she's old-school K&R style and yes she still ate 💅

---

💜 DESCRIPTION 💜

gsm is an implementation of the final draft GSM 06.10 standard for full-rate speech transcoding. It's giving vintage, it's giving telecom royalty, it's giving exactly what it says on the tin. 👑

gsm_create() initializes a gsm pass and returns a 'gsm' object. That object is your handle — you pass it into all the subsequent calls to gsm_decode(), gsm_encode() or gsm_destroy(). She's the main character, everyone else is a supporting role. ✨

gsm_encode() encodes an array of 160 13-bit samples (given as gsm_signal's — signed integral values of at least 16 bits, no cap) into a gsm_frame of 33 bytes. For the record, gsm_frame is a type defined as an array of 33 gsm_bytes in gsm.h. So 160 in, 33 out. Compression girlies, we love a glow-down that's actually a glow-up. 🔥

gsm_decode() decodes a gsm_frame back into an array of 160 13-bit samples (given as gsm_signals), which sound rather like what you handed to gsm_encode() on the other side of the wire. it's giving "same vibe, slightly diff outfit" 🦋

gsm_destroy() finishes a gsm pass and frees all storage associated with it. Clean up after yourself, bestie. No memory leaks on this account. 🧹💖

🎀 Sample format 🎀

The following scaling is assumed for input to the algorithm:

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

Only the top 13 bits are used as a signed input value.

The output of gsm_decode() has the three lower bits set to zero. not her being like "the bottom three are staying home today" 😭

---

⭐ RETURN VALUE ⭐

• gsm_create() — returns an opaque handle object of type gsm, or 0 on error. If you get a 0, that's not a vibe, that's a problem. 🙈
• gsm_decode() — returns -1 if the passed frame is invalid, else 0.

fr fr check your return values. gsm_decode() will straight up tell you the frame is invalid and you better listen the first time. 💀

---

🌈 EXAMPLE 🌈

here's the whole thing, verbatim, because she's iconic and I refuse to paraphrase her:

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

notice how play() and record() both create a handle, loop, error-check like a responsible queen, and then gsm_destroy() on the way out. that's the whole personality of this library and honestly? slay. 💅✨

---

😭 BUGS 😭

Please direct bug reports to jutta@pobox.com and cabo@tzi.org. they're literally asking for your emails, don't be shy 🫶

---

👑 SEE ALSO 👑

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

---

and that's the GSM(3) page!! 💖 This one lives in the Library Functions Manual, the page itself is titled GSM(3) and the footer just says GSM(3) again — no version, no date, she simply doesn't date-stamp herself, lowkey mysterious of her. anyway bestie go compress some speech, you got this 🎀🦋🌸💅