How do I Integrate new codecs into DVSDK

Introduction

This article is generally applicable to any codec package. However it focuses on adding and integrating an MP3 decoder into the DVSDK stack. This requires updates to: -

• [required] codec servers (aka combo)
• [optional] demo application source code - only applicable to Linux DVSDKs
• [optional] demo configuration file (cfg) - only applicable to Linux DVSDKs

The good thing is that XDM 1.x codecs (IAUDDEC1, IVIDDEC2 etc) are generally plug and play, within the same class, from a base parameters perspective so per-codec-custom-code is rarely required (again assuming base parameters).

How to Download MP3 Decoder

The TI MP3 decoder is a generic c64+ audio decoder. What this means is that it can run on any c64+ or c674+ platform i.e. the same codec can be (and is ) used on DM644x, DM646x, OMAP353x, OMAPL13x etc.

The MP3 Decoder package is available for download at the C64XPlus_Audio_Codecs Product Download Page as "MP3 Decoder".

As you will observe the package name has "c64xplus" embedded inside it i.e. it is a generic MP3 c64+ decoder. Hence you can use this link to download & integrate this codec on non-OMAP3 platforms such as DM644x, DM646x, OMAPL13x. To reiterate, it is the same codec package on both OMAP3 and Davinci DVSDK sites.

The codec can be downloaded and integrated to an existing Codec server package as described below.

Note that if you wish to use the codec-package outside of Codec Engine then check out How_to_use_a_RTSC_codec_package_in_a_non-RTSC_environment.

How to install mp3 package

On Linux hosts

1. Once you have downloaded the mp3 package c64xplus_mp3dec_1_31_001_production.bin use the following command to install the package:

   ./c64xplus_mp3dec_1_31_001_production.bin

The Binary installation will result in a tar file dm6446_mp3dec_1_31_001_production.tar(dm6446 here does not mean that it can only be used for DM6446 platform but as mentioned above this can be used for other platforms as well e.g. OMAP35xx platform.)

2. To untar dm6446_mp3dec_1_31_001_production.tar use the following command:

  tar -xvf dm6446_mp3dec_1_31_001_production.tar

On Windows hosts

1. Once you have downloaded the mp3 package c64xplus_mp3dec_1_31_001_production.exe run it to install the package. The setup program will guide you though the installation.

The installation will result in a tar file dm6446_mp3dec_1_31_001_production.tar(dm6446 here does not mean that it can only be used for DM6446 platform but as mentioned above this can be used for other platforms as well e.g. OMAP35xx platform.)

2. To untar dm6446_mp3dec_1_31_001_production.tar, use a utility such as WinZip (http://www.winzip.com/index.htm) to uncompress it.

Changes for the Codec Server

A Codec Server is designed to allow the Codec Engine to access the different codecs that are designed to run on the DSP. A Codec Server is usually packaged inside a package that contains the different codec packages being used, alongside the definitions for the server (or servers) that are defined to use these particular codecs. The packages are usually named using either of the following naming conventions: <PlatformName>_dvsdk_combos_<version> or cs<CodecServerNumber>_<PlatformName>_<version> (e.g. omap3530_dvsdk_combos_3_16 or cs1omap3530_1_00_01); the following sections cover the different elements needed in order to integrate a codec to a server of the first type.

Applying a patch to an existing codec-server (for Linux hosts)

There may exist a patch to enable support for 1+ additional codecs integrated into a given codec combo.

For example mp3dec_cs1omap3530.patch adds MP3 Decode support to the Codec Server 1 OMAP3530 package. In essence it does all the steps highlighted in How do I Integrate new codecs into DVSDK#Modifications inside the Codec Server automatically.

If no patch exists for your platform or codec it may still be of use to refer to an existing one as a guideline.

Integration of a Codec Package to a Server/Combo Package

On Linux hosts

After installing the Codec Package, you need to copy this package into the Codec Server package. The key directory for the codec package is the one that contains the XDC file for the codec (i.e. MP3DEC.xdc for a MP3 Decoder package) i.e. /<>/packages/ti/sdo/codecs/mp3dec. Use the following command for copy:

   cp -r /<>/packages/ti/sdo/codecs/mp3dec /<>/CS/packages/ti/sdo/codecs/.  

NOTE: In the above command CS is your codec server install directory.

NOTE: For a TI distributed package this can be performed by copying the packages directory of the Codec package into the Codec Server directory which has the following structure:

   packages/ti/sdo/codecs

An alternative method is to use symbolic links as shown in this article.

On Windows hosts

After installing the Codec Package, you need to copy this package into the Codec Server package. The key directory for the codec package is the one that contains the XDC file for the codec (i.e. MP3DEC.xdc for a MP3 Decoder package) i.e. /<>/packages/ti/sdo/codecs/mp3dec. Use the following command for copy:

   xcopy /E /I <path to mp3 package>/packages/ti/sdo/codecs/mp3dec <path to codec server>/packages/ti/sdo/codecs/mp3dec  

Modifications inside the Codec Server

Once the Codec Package is integrated inside the Codec Server, the server needs to be configured in order to be able to use the new codec.

First, the configuration (cfg) file that defines the server needs to be modified to add the new codec. This file is usually located under the server(s) directory inside the particular server name. (i.e. decode/decode.cfg).

NOTE: Sometimes the configuration file could be divided into two separate files to differentiate the parameters that are relative to the server or to the codecs itself named server.cfg and codec.cfg respectively. In the case the latter file contains the information that needs to be modified.

1. Declare usage of the new codec module e.g

<syntaxhighlight lang="javascript"> var MP3DEC = xdc.useModule('ti.sdo.codecs.mp3dec.ce.MP3DEC'); </syntaxhighlight>

1. The codec package might contain either an evaluation or a production version of the codec, in each case a watermark entry needs to be defined (sometimes it is defined in the codec package itself). Continuing with the same variable defined before:<syntaxhighlight lang="javascript">

MP3DEC.alg.watermark = true; /*if it is evaluation version */</syntaxhighlight> or <syntaxhighlight lang="javascript"> MP3DEC.alg.watermark = false; /*if it is production version.*/</syntaxhighlight>

3. The XDC file in the codec directory (i.e. MP3DEC.xdc) contains the different sections that are defined in the algorithm that require to be mapped to defined memory sections by the server. Usually this memory definitions are contained in the TCF file (server.tcf). For example to fulfill the requirements for the MP3 decoder algorithm, and continuing with the variable defined before, the following entries are added to the configuration file: <syntaxhighlight lang="javascript"> MP3DEC.alg.codeSection = "DDR2"; MP3DEC.alg.dataSection = "DDR2"; MP3DEC.alg.udataSection = "DDR2"; </syntaxhighlight>
4. Add the Algorithm to the server by adding a new set to the Server.algs array. For example to add the MP3 decoder algorithm, the following entry needs to be added (See 3 for notes about priority and grouping). <syntaxhighlight lang="javascript"> {name: "mp3dec", mod: MP3DEC,threadAttrs: { stackMemId: 0, priority: Server.MINPRI + 2}, groupId : 1, } </syntaxhighlight> NOTE: Ensure that Audio/Speech Codecs have the highest priority of the algorithms since they have higher framerates than video algorithms hence need to preempt video algorithms from a BIOS TSK thread perspective.
5. To minimize any errors during the building of the Server, add the codec to the validation entries in package.xs file of the server. (This file might not be defined in all servers), following the same example: <syntaxhighlight lang="javascript"> validate_one_codec( "ti.sdo.codecs.mp3dec", "MP3DEC" ); </syntaxhighlight>

Now you can rebuild the server and the new codec will be part of the server. You will need to refer to your DVSDK documentation to find out how to rebuild the server.

Demonstration applications changes (Linux DVSDKs only)

The current demo applications delivered as part of the DVSDK package are flexible enough to accommodate different codecs that are part of the Codec Server being used. However the following sections describe different possibilities that can be encountered when changing the Codec Server, either because a new server is used, or because the server was modified to add or remove codecs.

Changes in the server name

If the Codec Server name is different than the name of the previous version the following change is required:

The demo applications contain a Configuration file named application.cfg (e.g. decode.cfg), in which the information of the Engine configuration is supplied, for example:

<syntaxhighlight lang="javascript"> var demoEngine = Engine.createFromServer(

   "decode",
   "./decodeCombo.x64P",
   "ti.sdo.servers.decode"
   );

</syntaxhighlight>

See this wiki article for complete details on createFromServer usage.

• The first entry decode, refers to the internal name used by the application to specify the engine that needs to be used, and this name can remain unchanged.
• The second entry, refers to the name and path of the DSP Server binary file (with respect to the third entry). This name is also part of the Codec Server Release Notes.
• Finally, the third entry, refers to the package name. This information is part of the Release Notes.

A new codec is added to the server

In order to know if the demo application being used supports or not the file extension and/or the codec is present in the server, it can be executed using the file needed as the input parameter. If it does not support the file extension or the codec is not yet associated with any extension, the application will fail and the following errors are returned respectively (In this case decoding of an MP3 file was attempted as an example)

Unknown audio file extension: .mp3

Error: Failed to create audio decoder mp3dec

The codecs.c file contains the list of encoders or decoders supported (currently audio, video and speech codecs are supported). The Codec structure looks like this:

<syntaxhighlight lang="c"> typedef struct Codec {

   /* String name of codec for CE to locate it */
   Char    *codecName;
   /* The string to show on the UI for this codec */
   Char    *uiString;
   /* NULL terminated list of file extensions */
   Char   **fileExtensions;
   /* Params to use with codec, if NULL defaults are used */
   Void    *params;
   /* Dynamic params to use with codec, if NULL defaults are used */
   Void    *dynParams;

} Codec; </syntaxhighlight>

Therefore, if support for MP3 decoding needs to be added to the codec, the following can be added to the array group: <syntaxhighlight lang="c">

   {
       "mp3dec",
       "MP3",
       mp3Extensions,
       NULL,
       NULL
   }

</syntaxhighlight> where <syntaxhighlight lang="c"> static Char *mp3Extensions[] = { ".mp3", NULL }; </syntaxhighlight> At this point the application is ready to use the newly created server.

Integrating new files into the interface application

The interface application is used as starting point to show the capabilities of the EVM, either by using a Remote Control or Buttons in the platform to drive different demonstrations included in the DVSDK release, or a customer created application.

Note - recall that you don't need the interface application to test out the newly added codec. The demos have a keyboard interface (-k) option that serve the same purpose as the interface app in a low-touch simple, portable manner.

For the decode demo, a set of different file combinations are presented to the user in order to show different video clips and audio files using different decoders which can be selected via the Remote Control or Buttons on the platform. To include a new file that is encoded in a format used by a new codec in the Codec Server, into the interface menu, the file Dec.c in the interface directory needs to be modified:

• Increase the number of combos being used by the system as appropriately, e.g. To set the number of combinations to 6, change this definition:

<syntaxhighlight lang="c">

1. define NUM_FILE_COMBOS 6

</syntaxhighlight>

• Update the File Combo structure to add the new structure, by adding the set to the Array present in the same file. For example to add a combination of the H264 Video version of the DaVinci effect video clip with the MP3 audio source, the following set needs to be added:

<syntaxhighlight lang="c"> {

   "data/videos/davincieffect_ntsc_1.264",
   "data/sounds/davincieffect.mp3",
   "1"

} </syntaxhighlight>

Where the last entry refers to the video resolution (NTSC in this case)

DirectShow Filter changes (WinCE DVSDKs only)

The DirectShow filters delivered as part of the DVSDK package are structured to facilitate additional support for different codecs that are part of the Codec Server being used. For the MP3 codec, an MP3 decode filter is provided starting with version 1.10.00 of the filters. Refer to the DShow filters' release notes for additional information on rebuilding the TIMM library against the new server and enabling the MP3 decode filter.

For other codecs, you will need to write your own decode filter. See TI_DirectShow_Filters#Creating_a_filter_for_a_new_codec.2Falgorithm for some guidelines.

If there are changes in the server name

If the Codec Server name is different than the name of the previous version the following change is required:

The DirectShow filters' TIMM library contains a Configuration file named timm.cfg, in which the information of the Engine configuration is supplied, for example:

<syntaxhighlight lang="javascript"> var cs = Engine.createFromServer(

   "cs",
   "./bin/cs.x64P",
   "ti.sdo.server.cs"
   );

cs.server = "windows\\\\cs.x64P"; </syntaxhighlight>

See this wiki article for complete details on createFromServer usage.

• The first argument cs, refers to the internal name used by the filters to specify the engine that needs to be used, and this name can remain unchanged.
• The second argument, refers to the name and path of the DSP Server binary file (with respect to the third entry). This name is also part of the Codec Server Release Notes.
• Finally, the third argument, refers to the server package name. This information is part of the Release Notes.

cs.server designates the path to the DSP Server binary file on the target image in NK.bin.

Troubleshooting

• In rebuilding the combos if you hit this error...

gmake[1]: `.interfaces' is up to date.
======== .interfaces [packages/ti/sdo/codecs/mp3dec] ========
package.mak:17: *** target pattern contains no `%'.  Stop.
gmake: *** [packages/ti/sdo/codecs/mp3dec,.interfaces] Error 2
make: *** [.all-packages] Error 2

...then you should probably do a courtesy make clean from the top-level codec-combos directory and try make again.

• In rebuilding the combos if you hit this error...

undefined                        first referenced
 symbol                              in file
---------                        ----------------
_MP3DEC_TII_IMP3DEC              package/cfg/decodeCombo_x64P.o64P
>>   error: symbol referencing errors - 'decodeCombo.x64P' not built

...then double check that you are indeed linking in the codec properly. Scroll up the build log. If you see something like this...

will link with ti.sdo.codecs.mp3dec:null

...then you have a problem!

2 things to check in this scenario (a) ensure you got the syntax right in your cfg file with the useModule declaration. (b) make sure XDCARGS="prod" (as opposed to "eval") in the makefile for 'production' codecs. Except for some older Linux DVSDKs prior to Linux DVSDK 2.0, all TI codecs are now production codecs i.e. not watermarked.

See Also

• Configuring_Codec_Engine_in_Arm_apps_with_createFromServer
• Creating_and_Building_codec_combos_in_Windows
• RTSC_Server_Package_Wizard_FAQ#How_do_I_create_a_server_combo.3F