diff doc/PCM8-conversions @ 237:e4a4bf11f37c

doc/PCM8-conversions: document command line utilities
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 08 May 2023 04:29:05 +0000
parents 4c7d0dc1eecb
children
line wrap: on
line diff
--- a/doc/PCM8-conversions	Mon May 08 03:28:40 2023 +0000
+++ b/doc/PCM8-conversions	Mon May 08 04:29:05 2023 +0000
@@ -167,4 +167,33 @@
 For production software, our (Themyscira) recommendation is to use look-up
 tables (dev/s2a-regen.out and dev/s2u-regen.out) for both A-law and mu-law
 encoding, using the upper 12 bits from 16-bit 2's complement input for A-law
-encoding and the upper 13 bits for mu-law encoding.
+encoding and the upper 13 bits for mu-law encoding.  For mu-law encoding the
+resulting mapping is different from what G.191 STL ulaw_compress() function
+produces, and many will consider that function to be canon - but our approach
+exhibits the same key properties, just mirrored around zero, and has the
+advantage of needing only the upper 13 bits.
+
+Command line utilities
+======================
+
+As usual, the present Themyscira GSM codec libraries & utilities package
+provides command line utilities for working with the subject of this article:
+conversions between 16-bit linear PCM (the format read and written by other
+tools in the present suite) and 8-bit PCM in G.711 A-law or mu-law.  The
+following utilities are provided:
+
+pcm16-to-alaw	These two utilities read 16-bit linear PCM in raw format (BE
+pcm16-to-ulaw	byte order by default, or LE with -l option) and convert the
+		recording into one byte per sample G.711 format, with each
+		program emitting its respective encoding law.  pcm16-to-alaw
+		has only one mapping, but pcm16-to-ulaw supports two possible
+		mappings: by default it applies the mapping of G.191 STL
+		ulaw_compress(), or if use specify -t option it applies the
+		same mapping that would be produced by our recommended 13-bit
+		look-up table method.
+
+pcm8-to-pcm16	This utility reads a G.711 8-bit PCM recording (alaw or ulaw
+		selected with a mandatory command line argument) from a "raw"
+		G.711 file and converts it to 16-bit linear PCM.  The output
+		byte order is BE by default, or can be changed to LE with an
+		extra command line qualifier.