================================================================================
 CodecPro Incorporated
 905-2160 Terry-Fox
 Laval (Quebec)
 Canada, H7T 3B7
 
 support@codecpro.com
 www.codecpro.com 
================================================================================
 
February 2025

================================================================================
   CodecPro EVS floating-point free trial package
================================================================================

This evaluation package includes EVS 64-bit static libraries built with Visual
Studio 2022 and Ubuntu's GCC 13.3.0.

Additionally, it provides:

- Documentation for the CodecPro EVS API.
- Source code demonstrating how to use the EVS API, which can help accelerate
  the development of an alternative host application.
- A Visual Studio 2022 sample solution for building the demo application.
- A sample Makefile for compiling the demo application.
- A set of test vectors and test commands (Bash and Batch files).
- Guidelines on decoding EVS RTP capture files using Wireshark and the CodecPro
  EVS sample demo application.

This README provides the necessary information to help you navigate the
package's folder structure— so please continue reading.

For a guide on using the EVS libraries with PJSIP, including specific
instructions on packetizing and depacketizing RTP EVS streams, please contact
CodecPro.


--------------------------------------
 How to decode PCAP and RTPDUMP files
--------------------------------------

In addition to EVS encoding and decoding functions, the CodecPro EVS libraries
provide built-in capabilities for packetizing and depacketizing RTP payloads.
With the included sample demo application, it is possible to decode EVS audio
from a captured RTP session file, such as PCAP or RTPDUMP files.

The decoder demo application supports decoding single-channel files that conform
to the RTPDUMP format. PCAP format files must first be converted into
single-channel RTPDUMP files before they can be decoded by the demo application.

To transform a PCAP file into RTPDUMP format, follow these steps:
- Open the PCAP file in Wireshark.
- For UDP streams, right-click on a packet and select "Decoded As->RTP".
- From the top menu, navigate to "Telephony->RTP->RTP Streams", select a stream,
  then click "Export". Repeat this process for other streams if necessary.

Please note that the format of the .rtp file extension used by Wireshark is
equivalent to the .rtpdump format.

For example, for a captured file named EvsRtpCapture.pcap containing two
distinct EVS RTP streams, use Wireshark to convert EvsRtpCapture.pcap into two
files named EvsRtpCaptureCh1.rtp and EvsRtpCaptureCh2.rtp.

These files can then be decoded into synthesized audio using the following
commands:


VS2022_cp_evs_dec -VOIP_hf_only=0 16 EvsRtpCaptureCh1.rtp EvsRtpCaptureCh1.syn
VS2022_cp_evs_dec -VOIP_hf_only=0 16 EvsRtpCaptureCh2.rtp EvsRtpCaptureCh2.syn

The resulting EvsRtpCaptureCh1.syn and EvsRtpCaptureCh2.syn files are raw PCM
(16-bit, 16 kHz) and can be played using any audio player. To facilitate
playback, a WAV header can be added by specifying the .WAV extension in the
output file names:

VS2022_cp_evs_dec -VOIP_hf_only=0 16 EvsRtpCaptureCh1.rtp EvsRtpCaptureCh1.wav
VS2022_cp_evs_dec -VOIP_hf_only=0 16 EvsRtpCaptureCh2.rtp EvsRtpCaptureCh2.wav

Note: The sample application's RTPDUMP depacketization process demonstrates how
to utilize the jitter buffer provided by the EVS library.


================================================================================
   Package Content
================================================================================

--------------
 .\doc folder
--------------

EVS_universalApi_10.1a.pdf:
                        document which describes the EVS library API and the
                        EVS codecs features.
26445-g00_Annex A.pdf:  Annex A only of specification 3GPP TS 26.445 version g00


---------------
 .\libs folder
---------------

3GPP Codec for Enhanced Voice Services (EVS)

.\Ubuntu_2404\lib_cpEvsOpt_10-0-4.a
                        built with gcc 13.3.0 for x64
                        (-D_REENTRANT -Wall -DFLOAT_APPROX -O3 -mfpmath=sse
                         -ffast-math -fvisibility=hidden -fsigned-char
                         -msse3 -msse4.1 -fPIC)
.\VS2022\cp_EvsOptLib_10-0-3.lib
                        built with Visual Studio 2022, x64, release


--------------
 .\src folder
--------------

encoder.c               sample program source files demonstrating the usage of
io_enc.c                the EVS encoder API.

decoder.c               sample program source files demonstrating the usage of
io_dec.c                the EVS decoder API.
dec_voip\voip_client.c
dec_voip\mime_voip.c
dec_voip\rtpdump.c      EVS payload extractor from RTP packet example source code
                        note: To transform pcap files to rtpdump files using
                              Wireshark v.4.4.5 do:
                        - open the pcap file in Wireshark
                        - for UDP streams, right click on a packet and select 
                          "Decoded As->RTP"
                        - then from the top menu select
                          "Telephony->RTP->RTP Streams", select a stream. click
                          "Export"

header files:
        - evs_if.h
        - io_dec.h
        - io_enc.h
        - OS_depend_func.h
        - typedef.h
        - dec_voip\mime_voip.h
        - dec_voip\rtpdump.h
        - dec_voip\evs_rtp_payload.h


-----------------------------
 .\Ubuntu_24_04_LTS\makefile
-----------------------------
                     
Sample makefile to build the EVS demo apps.
   
                        
---------------------------------------------
 .\VS2022_cp_evs_demo\VS2022_cp_evs_demo.sln 
---------------------------------------------
                     
Sample Visual Studio 2022 solution to build the EVS demo apps.
   
                        
================================================================================
 Usage of the EVS sample demo application
================================================================================

***
** EVS ENCODER:
***

VS2022_cp_evs_enc [Options] R Fs input_file bitstream_file


Mandatory parameters:
---------------------
R                : Bitrate in bps,
                   for EVS native modes R = (5900*, 7200, 8000, 9600, 13200, 16400,
                                             24400, 32000, 48000, 64000, 96000, 128000)
                                             *VBR mode (average bitrate),
                   for AMR-WB IO modes R =  (6600, 8850, 12650, 14250, 15850, 18250,
                                             19850, 23050, 23850)
                   Alternatively, R can be a bitrate switching file which consist of R values
                   indicating the bitrate for each frame in bit/s. These values are stored in
                   binary format using 4 bytes per value
Fs               : Input sampling rate in kHz, Fs = (8, 16, 32 or 48)
input_file       : Input signal filename
bitstream_file   : Output bitstream filename

Options:
--------
-q               : Quiet mode, no frame counters
                 : default is deactivated
-dtx D           : Activate DTX mode, D = (0, 3-100) is the SID update rate
                   where 0 = adaptive, 3-100 = fixed in number of frames,
                   default is deactivated
-dtx             : Activate DTX mode with a SID update rate of 8 frames
-rf p o          : Activate channel-aware mode for WB and SWB signal at 13.2kbps,
                   where FEC indicator, p: LO or HI, and FEC offset, o: 2, 3, 5, or 7 in number of frames.
                   Alternatively p and o can be replaced by a rf configuration file with each line
                   contains the values of p and o separated by a space,
                   default is deactivated
-max_band B      : Activate bandwidth limitation, B = (NB, WB, SWB or FB)
                   alternatively, B can be a text file where each line contains
                   "nb_frames B"
-no_delay_cmp    : Turn off delay compensation
                   The encoder produces TS26.445 Annex.2.6 Mime Storage Format, (not RFC4867 Mime Format).

sample command lines (when in testVector folder):
  >> ./VS2022_cp_evs_enc 13200 16 sample16.pcm out/sample16.evs_13k2

***
** EVS DECODER:
***

VS2022_cp_evs_dec [Options] Fs bitstream_file output_file

Mandatory parameters:
---------------------
Fs                  : Output sampling rate in kHz (8, 16, 32 or 48)
bitstream_file      : Input bitstream filename or RTP packet filename (in VOIP mode)
output_file         : Output speech filename

Options:
--------
                   : Mime bitstream file format when no VOIP option 
                     The decoder is able to read both TS26.445 Annex A.2.6 and RFC4867 Mime Storage
                     Format files, the magic word in the mime file is used to determine
                     which of the two supported formats is in use.
                     default bitstream file format is MIME - TS26.445 Annex 2.6
-VOIP              : VoIP mode: RTP in MIME
-VOIP_hf_only=0    : VoIP mode: EVS RTP Payload Format hf_only=0 in rtpdump
-VOIP_hf_only=1    : VoIP mode: EVS RTP Payload Format hf_only=1 in rtpdump
                     The decoder may read rtpdump files containing TS26.445 Annex A.2.2
                     EVS RTP Payload Format. The SDP parameter hf_only is required.
                     Reading RFC4867 AMR/AMR-WB RTP payload format is not supported.
-no_delay_cmp      : Turn off delay compensation
-q                 : Quiet mode, no frame counter
                     default is OFF

sample command lines (when in testVector folder):
  >> ..\VS2022_cp_evs_dec 16 ref/sample16.evs_13k2 out\sample16.evs_13k2.syn
  >> ..\VS2022_cp_evs_dec -VOIP_hf_only=0 16 evs_float_b24_4m_dtx_swb_cbr_hfOnly0_cmr1_ptime60.rtpdump out\evs_float_b24_4m_dtx_swb_cbr_hfOnly0_cmr1_ptime60.rtpdump.syn

  Bash file runEncDecTests.sh or batch file runEncDecTests.bat can be used to run the demo
  apps on the test vectors.

================================================================================
 This is a free trial version. A 250ms beep is periodically inserted into the
 encoded and decoded signals. Please contact CodecPro for a licensed version.
================================================================================
