# HG changeset patch # User Mychaela Falconia # Date 1715365206 0 # Node ID 9bcf65088006c0ae59d6da7f8519a65ef15e6c43 # Parent 4c458145e79347c63f205544d3bd8a65e5165bca doc/AMR-EFR-philosophy: document implemented solution diff -r 4c458145e793 -r 9bcf65088006 doc/AMR-EFR-philosophy --- a/doc/AMR-EFR-philosophy Fri May 10 07:35:36 2024 +0000 +++ b/doc/AMR-EFR-philosophy Fri May 10 18:20:06 2024 +0000 @@ -48,42 +48,54 @@ I (Mother Mychaela) previously entertained the idea of creating a unified codec library that supports both AMR and EFR with common code, producing a published- source, FOSS-culture equivalent of what most proprietary vendors have done. -However, on further reflection, that idea has been rejected. The current vision -(as of 2024-04) is that libgsmefr (stable since early 2023) and libtwamr -(currently a work in progress) shall remain separate and independent libraries, -the former implementing GSM-EFR (the original bit-exact definition) and the -latter implementing AMR. My reasons for this decision are: +However, on further reflection, that idea has been rejected. The current +situation as of 2024-05 is as follows: + +* Libgsmefr is our production-oriented implementation of GSM-EFR codec. It + implements the original bit-exact definition of EFR, not the AMR-EFR hybrid + version, and it includes full support for DTX encoding and SID decoding with + comfort noise generation per GSM 06.62. -* Libgsmefr already exists, and it is already a bit of a jewel compared to the - sorry state of true GSM codec support in the world of FOSS outside Themyscira. - Giving up on this library and moving to some nebulous new one does not sound - appealing. - -* There does not exist any formal, bit-exact definition for what we informally - call "EFR version 2": the realization of EFR as implemented by post-AMR-era - proprietary vendors, some sort of AMR-EFR hybrid. As I see it, it is not my - place to try to innovate in speech codec design, instead it is my job to - provide 100% correct, bit-exact implementations of existing solid standards - - and there is no bit-exact standard to follow for "EFR version 2". +* Libtwamr is our librification of 3GPP AMR reference code. The library is + structured in such a way that libtwamr stateful encoder and decoder functions + can be combined with stateless EFR frame packing and unpacking functions from + libgsmefr, allowing AMR-EFR hybrid encoders and decoders to be built. The + decoder homing function in libtwamr can be told to trigger on EFR DHF instead + of MR122 version, and for the encoder direction there is a simple utility + function that artificially transforms MR122 DHF into EFR DHF post-encoder. + However, there is no support for AMR-EFR hybrid encoding with DTX enabled, + and the low-effort version of AMR-EFR hybrid decoder constructed in this + manner cannot grok EFR SID frames or generate CN per GSM 06.62. -* Libtwamr project: the task of turning the original AMR code from 3GPP into a - proper library, style-consistent with Themyscira libgsmfr2 and libgsmefr, - without the ugliness of opencore-amr, is already a lot of work as it is. - There is no need to make it harder by adding the task of supporting AMR-based - EFR, especially when the latter lacks formal definition. +Production implementations of GSM network elements that need to perform EFR +speech transcoding should use libgsmefr, not libtwamr. The limited support +that is provided for AMR-EFR hybrid encoding and decoding with the combination +of libtwamr and libgsmefr is intended for experimentation and reverse +engineering of other people's implementations, for times when it becomes +necessary to model, simulate or replicate bit-exact operation of someone else's +network element. -Performance issues -================== +Command line utilities for AMR-EFR hybrid +========================================= + +The present package includes a small set of command line utilities that work +with the AMR-EFR hybrid described above: -Right now the only significant downside of libgsmefr compared to -libopencore-amrnb is that our library is significantly slower: almost 7 times -slower on non-DTX encode and a little over 3 times slower on SID-free decode. -However, this performance problem will need to be solved by profiling the code -to find the slowest spots, comparing the code of individual blocks between ours -and theirs, and porting over whatever performance-optimizing strategies were -implemented in OpenCORE code base. The latter code base is a derivative work -based on 3GPP AMR source, hence the guts of the codec are largely the same -between 3GPP AMR and libopencore-amrnb; the latter has been significantly -performance-optimized, but also heavily uglified. But there is no reason why -the same performance fixes can't be applied to EFR code base - it will simply -take work. This work is currently part of our future roadmap. +amrefr-encode-r +amrefr-decode-r + + These two utilities function just like gsmefr-encode-r and + gsmefr-decode-r described in Codec-utils article, but implement the + AMR-EFR hybrid version of the codec instead of original EFR. The + no-DTX limitation applies: amrefr-encode-r lacks -d option, and the + input to amrefr-decode-r must not contain any SID frames. + +amrefr-tseq-enc +amrefr-tseq-dec + + These two utilities are AMR-EFR counterparts to gsmefr-etsi-enc and + gsmefr-etsi-dec test programs described in EFR-testing article. They + pass all tests on the non-DTX t??_efr.* sequences in ETSI's + amr122_efr.zip, but not on any of the DTX sequences included in the + same ZIP. Just like amrefr-encode-r, amrefr-tseq-enc lacks -d option, + and amrefr-tseq-dec rejects input containing SID frames.