GSM_OPTION(3)

💖 GSM_OPTION(3) — the gsm_option era 💖

okay bestie, welcome to the gsm_option(3) page from the Library Functions Manual 🌸 this is where you get to poke at all the little knobs and switches inside the gsm library that you'd literally never touch for a normal day of encoding. but when you do need them? iconic. let's go 💅

---

✨ NAME ✨

gsm_option — customizing the GSM 06.10 implementation 🎀

---

🦋 SYNOPSIS 🦋

#include "gsm.h"

int gsm_option(handle, option, valueP);
gsm handle;
int option;
int * valueP;

---

🌸 DESCRIPTION 🌸

so the gsm library is an implementation of the final draft GSM 06.10 standard for full-rate speech transcoding — that's a lossy speech compression algorithm, fyi, lossy as in it throws stuff away on purpose and that's fine, that's the whole vibe.

The gsm_option() function lets you set and query all kinds of options or flags that you do not need for regular GSM 06.10 encoding or decoding, but that might be of interest in special cases. special-case girlies, this one's for you 💜

The second argument to gsm_option tells it which parameter you wanna change or query. The third argument is either:

• a null pointer, in which case the current value of that parameter gets returned to you, or
• a pointer to an integer holding the value you want to set, in which case the previous value comes back. cute little two-way street 🫶

The following options are defined:

---

🎀 GSM_OPT_VERBOSE — verbosity level 🗣️

This one is only supported if the library was compiled with debugging turned on. It may be used by developers of compression algorithms to aid debugging. The verbosity level can be changed at any time during encoding or decoding. no cap.

---

🔥 GSM_OPT_FAST — faster compression algorithm ⚡

This implementation offers a not strictly standard-compliant, but faster compression algorithm that is compatible with the regular method and does not noticably degrade audio quality. slay.

The value passed to

gsm_option(handle, GSM_OPT_FAST, & value)

functions as a boolean flag: if it is zero, the regular algorithm will be used; if not, the faster version will be used.

the availability of this option depends on the hardware used 😭 if it is not available, gsm_option will return -1 on an attempt to set or query it. rude, but okay.

This option can be set any time during encoding or decoding.

---

✂️ GSM_OPT_LTP_CUT — enable, disable, or query the LTP cut-off optimization 💀

During encoding, the search for the long-term correlation lag forms the bottleneck of the algorithm. (it's giving main character of the slow parts.) The ltp-cut option enables an approximation that disregards most of the samples for purposes of finding that correlation, and hence speeds up the encoding at a noticable loss in quality. trade-offs, bestie, trade-offs.

The value passed to

gsm_option(handle, GSM_OPT_LTP_CUT, & value)

turns the optimization on if nonzero, and off if zero.

This option can be set any time during encoding or decoding; it will only affect the encoding pass, not the decoding. so decoding girlies, don't even worry about it 🌈

---

🎵 GSM_OPT_WAV49 — WAV-style byte ordering 🎧

A WAV file of type #49 contains GSM 06.10-encoded frames. Unfortunately, the framing and code ordering of the WAV version are incompatible with the native ones of this GSM 06.10 library. (incompatible!! the audacity.)

The GSM_OPT_WAV49 option turns on a different packing algorithm that produces alternating frames of 32 and 33 bytes (or makes it consume alternating frames of 33 and 32 bytes — note the opposite order of the two numbers, that detail matters fr fr) which, when concatenated, can be used in the body of a WAV #49 frame.

It is up to the user program to write a WAV header, if any; neither the library itself nor the toast program produce complete WAV files. so don't come for us about missing headers 💅

The value passed to

gsm_option(handle, GSM_OPT_WAV49, & value)

functions as a boolean flag: if it is zero, the library's native framing algorithm will be used; if nonzero, WAV-type packing is in effect.

This option should be used before any frames are encoded. Whether or not it is supported at all depends on a compile-time switch, WAV49.

Both the option and the compile time switch are new to the library as of patchlevel 9, and are considerably less tested than the well-worn rest of it. (new girl on the block, be gentle 😭)

Thanks to Jeff Chilton for the detective work and first free implementation of this version of the GSM 06.10 encoding. king behaviour 👑

---

🔗 GSM_OPT_FRAME_CHAIN — query or set the chaining byte ⛓️

Between the two frames of a WAV-style encoding, the GSM 06.10 library must keep track of one half-byte that is technically part of the first frame, but will be written as the first four bits of the second. half a byte. living on the edge.

This half-byte are the lowest four bits of the value returned by, and optionally set by,

gsm_option(handle, GSM_OPT_FRAME_CHAIN, & value)

This option can be queried and set at any time. whenever, wherever 🦋

---

🔢 GSM_OPT_FRAME_INDEX — query or set the current frame's index in a format's alternating list of frames 🧮

The WAV #49 framing uses two alternating types of frames. Which type the next GSM-coded frame belongs to can be queried, or, when decoding, announced, using

gsm_option(handle, GSM_OPT_FRAME_INDEX, & value)

For WAV-style framing, the value should be 0 or 1; the first frame of an encoding has an index of 0. At library initialization, the index is set to zero. 🌟

The frame index can be queried and set at any time. Used in combination with the GSM_OPT_FRAME_CHAIN option, it can be used to position on arbitrary GSM frames within a format like WAV #49 (not accounting for the lost internal GSM state). so yes you can teleport around frames, just know something gets left behind 🙈

---

⭐ RETURN VALUE ⭐

gsm_option() returns -1 if an option is not supported, and the previous value of the option otherwise. simple. elegant. periodt. 💅

---

💀 BUGS 💀

Please direct bug reports to jutta@pobox.com and cabo@tzi.org. (email era iconique, they're literally waiting for your tea 🫶)

---

🌈 SEE ALSO 🌈

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

---

and that's the whole page, bestie 💖 this came straight out of the Library Functions Manual and it's signed off as GSM_OPTION(3) — go forth, query your options, set your flags, and remember: the half-byte is real. bye 👑✨