ODR-PadEnc - Revision history

Glokhoff: Include information about the order in which slides are included in the slideshow, as I have been wondering about this myself for quite some time...

2021-01-18T08:05:28Z

Include information about the order in which slides are included in the slideshow, as I have been wondering about this myself for quite some time...

Hb9egm: /* Communication with audio encoder */

2020-09-23T08:19:11Z

Communication with audio encoder

Hb9egm: Explain version 3

2020-09-23T08:15:12Z

Explain version 3

Andimik: /* Request DLS text file re-read */ Grammar fixed

2020-04-16T11:02:26Z

Request DLS text file re-read: Grammar fixed

Andimik: /* Request slides dir re-read */ Grammar fixed

2020-04-16T11:02:02Z

Request slides dir re-read: Grammar fixed

Andimik: /* Usage of DL Plus */ Typos and Grammar fixed

2020-04-16T11:01:19Z

Usage of DL Plus: Typos and Grammar fixed

Andimik: /* Service signalling */ Typo fixed

2020-04-16T11:00:15Z

Service signalling: Typo fixed

Andimik: /* PAD generation modes */ Grammar fix

2020-04-16T10:59:52Z

PAD generation modes: Grammar fix

Andimik: /* PAD lengths */ Grammar fix

2020-04-16T10:58:51Z

PAD lengths: Grammar fix

Andimik: /* Dynamic Label Segment (DLS) */ Grammar fixed

2020-04-16T10:57:12Z

Dynamic Label Segment (DLS): Grammar fixed

@@ Line 72: / Line 72: @@
 * ClickThroughURL
 * AlternativeLocationURL
 ==== Using DLS and MOT SLS together ====

@@ Line 184: / Line 184: @@
 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.
-== Communication with audio encoder ==
+== Communication protocol ==
-The communication of the odr-padenc with the audio encoder is currently done via a FIFO and therefore unidirectional. It has been considered to use a [[bidirectional PAD communication protocol]] to make use of flow control, to take advantage of the complete available PAD bandwidth, but later, the uniform mode has been introduced instead, for backwards compatibility reasons.
+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.
 On odr-padenc's side, each write to the FIFO consists of (padlen + 1) bytes, divided into the following components (all widths in bytes):
   +--------------+---------+-------+--------------+

@@ Line 1: / Line 1: @@
 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 [http://rd.csp.it]; 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]].
+Version 3 uses a socket to communicate, and is compatible with [[ODR-AudioEnc]] version 3 and with [[ODR-SourceCompanion]] version 1.
 == Installation ==
@@ Line 15: / Line 17: @@
 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.:
+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'
   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):
@@ Line 47: / Line 65: @@
 === 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.
+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 <code>.sls_params</code> (case-sensitive). So when the image filename is <code>test.jpg</code>, the corresponding parameters file has to be named <code>test.jpg.sls_params</code>. Currently the following parameters can be used (see below):
@@ Line 113: / Line 131: @@
 == 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.
+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.
-== PAD generation modes ==
+== PAD generation modes in version 3 ==
-ODR-PadEnc 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.
+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.
 Note: In the figures below, PAD is shown in green, audio frames in blue and overflows in red.

@@ Line 256: / Line 256: @@
 == 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 <code>d91981c</code> it is possible to request the re-read of a DLS text file.
+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 <code>d91981c</code> 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 <code>.REQUEST_DLS_REREAD</code>. When this file is present, the following happens:

@@ Line 251: / Line 251: @@
 == 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.
+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 <code>REQUEST_SLIDES_DIR_REREAD</code> into the slides dir (e.g. by executing <code>touch REQUEST_SLIDES_DIR_REREAD</code>). When this file is present, the slides dir is re-read and this file is deleted.

@@ Line 203: / Line 203: @@
   Now: Michael Jackson - Thriller
-Furthermore the values of the <code>Item Toggle</code> and <code>Item Running</code> 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.
+Furthermore, the values of the <code>Item Toggle</code> and <code>Item Running</code> 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:
@@ Line 220: / Line 220: @@
 === 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 brodcaster's web site URL), this would require to still keep also these actually static files always up-to-date.
+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:

@@ Line 162: / Line 162: @@
 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.
+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.
 == Communication with audio encoder ==

@@ Line 136: / Line 136: @@
 [[Image:PAD mapping - burst mode - overflow.svg|400px]]
-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.
+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.
 === Uniform mode (recommended) ===
@@ Line 149: / Line 149: @@
 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 indepentent from each other. It is also possible to specify how often the label is inserted.
+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.

@@ Line 116: / Line 116: @@
 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.
+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.
 == PAD generation modes ==

@@ Line 39: / Line 39: @@
 === 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.
+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 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).
+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).
 ==== Using multiple DLS texts ====