view doc/Codec-utils @ 156:3f3674c27840

gsmefr-encode-r utility put together
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 15 Dec 2022 01:42:31 +0000
parents 30c7bc064218
children 04936af99fc8
line wrap: on
line source

Standalone command line utilities for FR and EFR codecs
=======================================================

The pre-existing FOSS opencore-amr package includes amrnb-enc and amrnb-dec test
programs: the first reads linear PCM from a WAV file and emits AMR encoder
output in a .amr file (RFC 4867 AMR storage format), the second reads this .amr
format and emits AMR decoder output as WAV.  Inspired by these simple test
programs, the present package offers equivalent command line utilities for GSM
FR and EFR codecs.  Here they are:

gsmfr-encode	This utility reads linear PCM from a WAV file, runs libgsm
		06.10 encoder and writes the output in the classic .gsm format
		(directly abutted FR codec frames of 33 bytes each).  We don't
		currently have a Tx-side DTX implementation (VAD etc) for GSM
		FR, hence the output from gsmfr-encode will always consist of
		good speech frames only.

gsmfr-decode	This utility reads our gsmx format (see Binary-file-format
		article), which is a superset of the classic libgsm format.
		The input to gsmfr-decode may be a pure .gsm recording as
		produced by gsmfr-encode or toast from libgsm package, or it
		can also contain SID frames and/or BFI markers.  The processing
		performed by gsmfr-decode begins with our FR1 Rx DTX handler
		preprocessor, which will be an identity transform for pure .gsm
		input but becomes important for real-world input containing SIDs
		and BFIs, and is followed by gsm_decode() from libgsm.  The
		decoded output is written as WAV.

gsmefr-encode	This utility reads linear PCM from a WAV file, runs our EFR
		encoder (Themyscira libgsmefr) and writes the output in our gsmx
		format.  There is an option to enable or disable DTX: -d enables
		DTX, otherwise it is disabled.  (This option mirrors amrnb-enc.)

gsmefr-decode	This utility reads our gsmx format (which must be EFR, not FR1)
		and feeds all frames and BFIs to our EFR decoder.  The decoded
		output is written as WAV.

WAV reading and writing functions used by the above utilities have been lifted
out of opencore-amrnb test code.

Now that we are starting to encounter use cases that involve more than feeding
a PC microphone recording to test encoders and playing decoder output on PC
speakers, many of those other use cases call for using raw format instead of WAV
for 16-bit linear PCM.  While it would be philosophically most proper to add an
option to gsm[e]fr-encode and gsm[e]fr-decode utilities to read/write raw PCM
files instead of WAV, doing so would complicate the code too much.  As a
compromise between code simplicity and functionality, we provide lossless
conversion utilities - see PCM-file-formats article.