# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1671001499 0
# Node ID 195911f2211c3bfd172bba3f4353a446187883b2
# Parent  578fdedf432734c02b016a32c17c37694e7e9280
document PCM format conversion utilities

diff -r 578fdedf4327 -r 195911f2211c doc/PCM-file-formats
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/PCM-file-formats	Wed Dec 14 07:04:59 2022 +0000
@@ -0,0 +1,18 @@
+What file format should be used for 16-bit PCM sample recordings?  The first
+(in the order of development) group of utilities in the present package that
+need to read and write such files are gsm[e]fr-encode and gsm[e]fr-decode,
+designed to mirror amrnb-enc and amrnb-dec from opencore-amr FOSS package;
+these utilities read and write WAV files and even use WAV reading and writing
+functions copied from opencore-amrnb test code.
+
+However, as I (Mother Mychaela) keep developing more tools, my use cases become
+more diverse: in some use cases WAV is most convenient (e.g., when playing or
+recording with SoX tools), but in other use cases a raw sample file without any
+header is much more convenient.  To address this diversity of use cases, a pair
+of conversion utilities have been written:
+
+pcm16-raw2wav converts from raw format to WAV
+pcm16-wav2raw converts from WAV to raw format
+
+Both utilities take a mandatory command line argument specifying the endian
+order for the raw format - there is no default.
diff -r 578fdedf4327 -r 195911f2211c doc/Utils-overview
--- a/doc/Utils-overview	Wed Dec 14 06:45:17 2022 +0000
+++ b/doc/Utils-overview	Wed Dec 14 07:04:59 2022 +0000
@@ -40,4 +40,7 @@
 
 gsmrec-dump		See Binary-file-format article.
 
+pcm16-raw2wav		See PCM-file-formats article.
+pcm16-wav2raw
+
 rtp-gsmfr-extr		See RTP-analysis article.