ODR-PadEnc

Latest revision as of 09:05, 18 January 2021

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.

Version 3 uses a socket to communicate, and is compatible with ODR-AudioEnc version 3 and with ODR-SourceCompanion version 1.

Version 2 uses a fifo and is compatible with older versions of ODR-AudioEnc and with the legacy tools Toolame-DAB and FDK-AAC-DABplus.

[edit] Installation

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

./bootstrap
./configure
make
sudo make install

[edit] Usage

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

The communication between odr-padenc and the audio encoder is done using UNIX domain sockets that are in /tmp. You do not need to prepare those beforehand. It is necessary to give the same identifier to both odr-padenc and the audio encoder so that they can communicate. In the following examples, this identifier will be 'myprogramme'

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

odr-padenc -o myprogramme -t dls.txt

Example 2: Transmission of MOT Slideshow:

odr-padenc -o myprogramme -d ./slides

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:

odr-padenc -o myprogramme -t dls.txt -d ./slides

The PAD length is specified in the audio encoder, and odr-padenc will automatically handle a possible change in PAD length if you restart the encoder with a different setting.

In previous versions (v2 and earlier), communication between odr-padenc and the audio encoder was done via a FIFO. The FIFO needs to be created first by calling e.g.:

mkfifo /tmp/pad.fifo

In this case, you need to set the same pad length for both tools

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 3a: Like example 3. However instead of the burst mode the uniform mode is used (due to the 20ms frame length, the related audio here must be AAC-LC with 48 kHz; see the respective row in this table):

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

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.

[edit] Supported services

[edit] 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 this 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 annotating 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).

[edit] 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.

[edit] 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 shrunk (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

[edit] MOT Slide order

The slides are included in the slideshow according to their filename. Therefore, it may be useful to indicate the order in the filename, e.g.

001_station_logo.jpg
002_show_promo.jpg
003_website_promo.jpg
004_station_logo.jpg
005_social_media_promo.jpg
..... etc.

[edit] 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 (Note: As the PAD generation/output currently happens as a burst, the DLS text will not be updated between two adjacent slides!). 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:

System	Codec	Sample rate [kHz]	Frame/AU length [ms]	AUs per Superframe	Interval [ms]
DAB	MP2	48	24	N/A	1200
DAB	MP2 LSF	24	48	N/A	2400
DAB+	AAC-LC (= AAC without SBR)	48	20	6	1000
DAB+	AAC-LC (= AAC without SBR)	32	30	4	1500
DAB+	HE-AAC (= AAC with SBR)	48	40	3	2000
DAB+	HE-AAC (= AAC with SBR)	32	60	2	3000

Note that regarding this table and (HE-)AAC, it doesn't matter whether PS (Parametric Stereo) is used or not. Note also that the product of the AU length and the AUs per Superframe always results in 120ms.

[edit] 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.

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 choosing the PAD length.

[edit] PAD generation modes in version 3

ODR-PadEnc version 3 removed the burst mode, and implements only a mode where PAD data is generated at each request from the audio encoder.

[edit] PAD generation modes in version 2

ODR-PadEnc version 2 supports two PAD generation modes. From the beginning the burst mode has been supported, but it has certain disadvantages. Since version 2.3.0 the uniform mode is available and the recommended mode.

Note: In the figures below, PAD is shown in green, audio frames in blue and overflows in red.

[edit] Burst mode

The burst mode pre-generates and outputs all PAD (one slide and intermittent DLS texts, or one DLS text) at once. After that, the encoder sleeps for the specified amount of time, the sleep time (e.g. 10 seconds). So the generated output looks like the following:

The sleep time has to be long enough so that the audio encoder can process all PADs before the next PAD generation burst takes place - however this way the available PAD bandwidth is not completely used (and instead given back to the audio encoder):

If the sleep time is too short, the audio encoder has not yet processed all PADs until the next PAD generation burst. Thus updated slides/DLS texts are delayed and sometime the PAD queue will overflow:

So by definition, the burst mode cannot completely utilize the available PAD bandwidth. Furthermore, it is not possible to update the DLS text between two PAD generation bursts, as the respective PADs have already been generated - but an update may be desired e.g. on a new song. Since the introduction of the uniform mode, there is no longer a reason to use the burst mode.

[edit] Uniform mode (recommended)

In the uniform mode the actual audio frame length defines the gap between two adjacent PADs:

This way there is no unused PAD bandwidth and the PAD generation also cannot overflow:

The uniform mode just requires to specify the audio frame length which can be read from the above table.

Insertion intervals for slides and labels can be set independent of each other. It is also possible to specify how often the label is inserted.

If the slides interval "0" is used, the next slide is inserted just after the previous one has been transmitted. This is useful e.g. for stations that transmit just a logo slide.

An initial burst count can be set to ensure that an audio encoder has enough PADs available e.g. in case the audio encoder encodes DAB+ Superframes at once and hence needs all related PADs.

If a slide/label is still in transmission when the transmission of the next one is scheduled, the new transmission is skipped and a warning is shown. In this case it makes sense to increase the PAD length or to instead decrease the slide size or label insertion interval (-L).

This new PAD encoder does not require any changes on the audio encoder side. Only in case of MP2, a recent revision of ODR-AudioEnc has to be used (commit ce25f2c or later), as it fixes a problem with PADs that solely consist of the F-PAD.

[edit] Service signalling

DLS does not need any explicit signalling.

MOT SLS must be explicitly 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.

[edit] Communication protocol

This describes the protocol that was in use over the fifo since commits 5c6b9fb (fdk-aac-dabplus) and 182d08c (toolame-dab) until the switchover to sockets.

The sockets-based bidirectional PAD communication protocol uses the same response format.

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.

[edit] 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)

Note: The DLS text file must use Unix line breaks (\n), not Windows line breaks (\r\n)! To convert the latter to the former, you can use the tr command:

tr -d '\r' < input.txt > output.txt

[edit] Item Toggle/Running bits from separate file

Usually the Item Toggle bit and the Item Running bit of DL Plus are provided together in the same DLS text file as the actual label text itself. However, a user might want to use the feature of ODR-PadEnc to use more than one DLS text file. This means that the state of the two bits had also to be maintained correctly in all that DLS text files, in order to keep them constant (until they change). As some files may contain static content (e.g. the broadcaster's web site URL), this would require to still keep also these actually static files always up-to-date.

To prevent this, since commit c5d5653 a separate file can be specified that will be used to derive the state of the two mentioned bits. An example for a minimum file that contains the two bits, is the following:

##### parameters { #####
DL_PLUS_ITEM_TOGGLE=1
DL_PLUS_ITEM_RUNNING=0
##### parameters } #####

[edit] 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

[edit] Request slides dir re-read

ODR-PadEnc transmits all slides in the slides dir before that directory is scanned for slides again. However, in some cases (e.g. on a new song) it may be desired to manually request a slides dir re-read.

From version 2.3.0 on this can be done by placing a file called REQUEST_SLIDES_DIR_REREAD into the slides dir (e.g. by executing touch REQUEST_SLIDES_DIR_REREAD). When this file is present, the slides dir is re-read and this file is deleted.

[edit] Request DLS text file re-read

Similar to the slides, it may be desired to manually refresh the current DL text as e.g. the next song is played. Therefore, since commit d91981c it is possible to request the re-read of a DLS text file.

This can be achived by creating a file with the same filename as the DLS text file, suffixed by .REQUEST_DLS_REREAD. When this file is present, the following happens:

the related DLS text file is re-read
the related DLS text file is made the current DLS text file (only applies if multiple DLS text files are used)
the DL text is immediately inserted into the PAD transmission
the re-read request file is deleted

Example: Two DLS text files are used (first file for artist/title and second file for website address/phone number). A new song starts and currently the second file is the current file. Using the described mechanism, the encoder can be forced to change to the first file (which has been updated to the new artist/title) and to immediately transmit the updated DLS text.

[edit] 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
SANGEAN	DPR-36	DPR36-VP01EU	DL: one character from previous DLS beyond current DLS remains visible