ODR-PadEnc

From Opendigitalradio
Jump to: navigation, search

The ODR-PadEnc encodes Program Associated Data (PAD) which gets embedded into MP2/AAC audio frames. It supports the transmission of DLS texts and MOT Slideshow slides. Initially called mot-encoder, the tool was contributed by CSP [1]; further improvements were made by the OpenDigitalradio team, and it has been renamed to ODR-PadEnc.

It can be used with ODR-AudioEnc and with the legacy tools Toolame-DAB and FDK-AAC-DABplus.

Contents

Installation

Get the sources from the repository https://github.com/Opendigitalradio/ODR-PadEnc

./bootstrap
./configure
make
sudo make install

Usage

Please call odr-padenc without parameters to see all available options.

The communication between odr-padenc and the audio encoder is done via a FIFO. The FIFO needs to be created first by calling e.g.:

mkfifo /tmp/pad.fifo

Example 1: Transmission of DLS texts (file content encoded as UTF-8; after internal conversion, transmit encoded as EBU Complete Latin based repertoire) using 6 bytes PAD (short X-PAD):

odr-padenc -o /tmp/pad.fifo -t dls.txt -p 6

Example 2: Transmission of MOT Slideshow using 34 bytes PAD:

odr-padenc -o /tmp/pad.fifo -d ./slides -p 34

Example 3: Transmission of DLS texts (file content encoded as UTF-8; after internal conversion, transmit encoded as EBU Complete Latin based repertoire) and MOT Slideshow using 58 bytes PAD:

odr-padenc -o /tmp/pad.fifo -t dls.txt -d ./slides -p 58

Example 4: Transmission of DLS texts (file content encoded as UTF-8; transmit without conversion) using 6 bytes PAD (short X-PAD):

odr-padenc -o /tmp/pad.fifo -t dls.txt -p 6 -C

If you do offline encoding of a DAB programme, it makes sense to use -s 0 - otherwise odr-padenc waits (by default) 10 realtime seconds before transmitting the next DL or slide.

Supported services

Dynamic Label Segment (DLS)

DLS texts (according to ETSI EN 300 401, ch. 7.4.5.2) can be embedded into PAD and are read from a specific file. This file is read everytime before the text is prepared for transmission, therefore it can be replaced in the meantime to change the transmitted text. The specification limits the size of a DLS text to at most 128 bytes - depending on the selected charset these byte amount can be used to transmit up to 128 characters.

Dynamic Label Plus (also called DL Plus; according to ETSI TS 102 980) allows to annotate parts of a DLS text with certain tags and is supported since commit c1599cb. To enable DL Plus, the DLS text within DLS text file must be prepended by a parameter block which contains the desired settings (see below).

Using multiple DLS texts

Instead of using only one file, multiple files can be used as well (e.g. to regularly switch between artist/title and the station claim). After the specified sleep delay is over, the DLS transmission switches to the next file. To use this feature, the respective commandline option has to be specified once for every file.

MOT Slideshow (MOT SLS)

The MOT Slideshow (according to ETSI EN 301 234 and ETSI TS 101 499) allows the transmission of slides in JPEG or PNG format. The images in a specified folder are therefore transmitted one after another, until all images have been processed and the procedure repeats. If one image does not fulfill the 50 KB file size limit, has progressive coding or is larger than the recommendation of a 320x240 px resolution, it is shrinked (while keeping the aspect ratio) before transmission and converted to JPEG (since commit 5f2817a: to JPEG or PNG, whichever is smaller) to fulfill the mentioned requirements.

Optionally a slide can be accompanied by further parameters (e.g. to use a categorized Slideshow) since commit be6d1b7. This parameters reside in a separate file suffixed with .sls_params (case-sensitive). So when the image filename is test.jpg, the corresponding parameters file has to be named test.jpg.sls_params. Currently the following parameters can be used (see below):

  • CategoryID/SlideID
  • CategoryTitle
  • ClickThroughURL
  • AlternativeLocationURL

Using DLS and MOT SLS together

When both DLS and SLS are used and currently a slide is transmitted, since commit 222e277 every 50 PADs the DLS is inserted. This way a listener will get DLS much earlier after switching to a service, compared to the previous situation where the slide transmission was not interrupted for DLS insertion. Depending on the used audio encoding, DLS is inserted in the following intervals:

Codec Sample rate [kHz] Frame length [ms] Interval [ms]
MP2 48 24 1200
MP2 LSF 24 48 2400
AAC-LC 48 20 1000
AAC-LC 32 30 1500
HE-AAC 48 40 2000
HE-AAC 32 60 3000

PAD lengths

Since commit ae63fc5, the PAD length can be set to a value between 8 and 196 bytes per frame (using Variable Size X-PAD). In addition, 6 bytes per frame (using Short X-PAD) can be used. The PAD length must be set to the same value both at odr-padenc and audio encoder command line. In the future the PAD length will have to be set at a single location only.

Note: The audio encoders do not check if a chosen PAD length leaves enough remaining space for the audio itself. So this must be considered while chosing the PAD length.

Service signalling

DLS does not need any explicit signalling.

MOT SLS must be explicitely signalled within the FIC by using the FIG 0/13 (User application information). In ODR-DabMux, since v0.7.3 the parameter figtype within the mux file is used for this - please take a look at the example mux file. Note: Some receivers will display a transmitted MOT SLS even without explicit signalling.

Communication with audio encoder

The communication of the odr-padenc with the audio encoder is currently done via a FIFO and therefore unidirectional. As this does not allow flow control, the odr-padenc cannot take advantage of the complete available PAD bandwidth. There is an ongoing development to achieve bidirectional PAD communication protocol is established.

Protocol

The current protocol is in use since commits 5c6b9fb (fdk-aac-dabplus) and 182d08c (toolame-dab). On odr-padenc's side, each write to the FIFO consists of (padlen + 1) bytes, divided into the following components (all widths in bytes):

+--------------+---------+-------+--------------+
| zero padding |  X-PAD  | F-PAD | used PAD len |
+--------------+---------+-------+--------------+
|            padlen              |       1      |
               |  <used PAD len> |

X-PAD and F-PAD must already be in the reversed transmission byte order. The unused part at the beginning must be filled up with zeros and is ignored by the audio encoder. The unused PAD bytes within the audio frame result in additional bytes available to audio data.

Usage of DL Plus

To enable the transmission of DL Plus, the DLS text file has to contain a parameter block at its very beginning - the plain DL text must follow after it. Thus all parameters are surrounded by a pair of opening/closing tags. Within the parameter block, comment lines begin with an "#" and are ignored. Empty lines are skipped as well.

##### parameters { #####

# nothing happens in here; this is just a comment line

##### parameters } #####
Just a label

As in the above example, the parameters block does not contain any parameters, it has the same effect as if the DLS text file contained just the plain label.

To enable DL Plus in the first place, the setting DL_PLUS=1 is used. If this line is not present, DL Plus is disabled and all further DL Plus related parameters do not affect the odr-padenc behaviour. As no tag is specified here, one DUMMY tag is used (DL Plus transmissions must consist of at least one tag).

##### parameters { #####
DL_PLUS=1
##### parameters } #####
Just a label

To add DL Plus tags, one parameter line per tag has to be used, which contains content type, start marker and length marker - one-after-another and separated by a single space. Please note that the value of the start/length markers is specified in terms of characters - not bytes! Also note that the length marker is the length minus one, as it is defined by the spec as "the number of characters following the first character".

##### parameters { #####
DL_PLUS=1
# this tags "Michael Jackson" as ITEM.ARTIST
DL_PLUS_TAG=4 5 14
# this tags "Thriller" as ITEM.TITLE
DL_PLUS_TAG=1 23 7
##### parameters } #####
Now: Michael Jackson - Thriller

Furthermore the values of the Item Toggle and Item Running fields can be set. If there is no value for any of these two fields set, it remains 0. According to the spec, both fields being 0 means that they are not maintained at all.

The following example makes use of all available DL Plus parameters:

##### parameters { #####
DL_PLUS=1
DL_PLUS_ITEM_TOGGLE=0
DL_PLUS_ITEM_RUNNING=1
DL_PLUS_TAG=4 5 27
DL_PLUS_TAG=1 36 31
##### parameters } #####
Now: Global Deejays Feat. Rozalla - Everbody's Free (2009 Radio Mix)

Transmitting further Slideshow parameters via parameters file

See above for the filename of a file which contains additional Slideshow parameters. Comment lines begin with an "#" and are ignored. Empty lines are skipped as well.

# nothing happens in here; this is just a comment line

This file has the same effect as if the file would not exist.

A separate line for each parameter has to be used. The following example just adds data for the Categorized Slideshow (catSLS):

# this slide is in category #1 and slide #1 within this category
CategoryID/SlideID=1 1
# the used category #1 gets named
CategoryTitle=Test category

The following example makes use of all currently by odr-padenc processed Slideshow parameters:

# this slide is in category #3 and slide #2 within this category
CategoryID/SlideID=3 2
# the used category #3 gets named
CategoryTitle=Test category 3

# a URL is provided where further information can be found
ClickThroughURL=http://wiki.opendigitalradio.org/ODR-PadEnc
# provide an alternative location for this slide
AlternativeLocationURL=http://wiki.opendigitalradio.org/Tux2.png

Known receiver issues

Many older receivers only support the EBU Complete Latin based repertoire (charset 0). This is the motivation for the character set conversion from UTF-8, a modern and universal encoding, towards this widely supported character set.

In case other conversions are needed, please get in touch with the developers on the mailing list.


Brand Model Firmware version Description
SANGEAN DPR-17 DPR17-vp02D-EU5V DL: texts having exactly 128 bytes are not displayed
Personal tools