summaryrefslogtreecommitdiffstats
path: root/doc/example.mux
blob: 76d68289ce733d4f5a48a00c0fa1507337a9fbf9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
; This is an example configuration file that illustrates
; the structure of the configuration.
; It doesn't show all possible options. A more detailed example
; is available in doc/advanced.mux
;
; It contains two services, one DAB and one DAB+, and also shows
; both the file input useful for offline processing, and the
; ZeroMQ input useful in a 24/7 scenario.

; More information about the usage of the tools is available
; in the guide, which can be found on the
; www.opendigitalradio.org website.
;
; As you can see, comments are defined by semicolons.
;
; It consists of six mandatory sections, whose relative order in this
; file are of no importance.

; The general section defines global multiplex parameters.
general {
    ; the DAB Transmission mode (values 1-4 accepted)
    dabmode 1

    ; the number of ETI frames to generate (set to 0 to get an unlimited number)
    nbframes 10

    ; boolean fields can accept either false or true as values:

    ; Set to true to enable logging to syslog
    syslog false

    ; Enable timestamp definition necessary for SFN
    ; This also enables time encoding using the MNSC.
    ;
    ; When TIST is enabled, and either EDI or a ZMQ output with metadata is used,
    ; ODR-DabMux will download leap-second information from the IETF website,
    ; and cache it locally in /var/tmp. It will refresh the data by itself
    ; before it expires.
    ;
    ; If it cannot load this information, ODR-DabMux cannot start up!
    ;
    ; If your system doesn't have access to internet, you have to take care
    ; to create the file before ODR-DabMux startup. Get it from
    ; http://www.ietf.org/timezones/data/leap-seconds.list
    ; and save it to
    ; /var/tmp/odr-dabmux-leap-seconds.cache
    ; Refresh the file before expiry otherwise ODR-DabMux will abort!
    ;
    ; Use the RC interface 'get clocktai expiry' command to check how long
    ; your file is still valid.
    tist false

    ; The URLs used to fetch the TAI bulletin can be overridden if needed.
    ; URLs are given as a pipe-separated list, and the default value is:
    ;tai_clock_bulletins "https://www.ietf.org/timezones/data/leap-seconds.list|https://raw.githubusercontent.com/eggert/tz/master/leap-seconds.list"
    ;
    ; You may also use a file:// URL if you take care of updating the file
    ; yourself and store it locally.

    ; The management server is a simple TCP server that can present
    ; statistics data (buffers, overruns, underruns, etc)
    ; which can then be graphed a tool like Munin
    ; The doc/stats_dabmux_multi.py tool is a suitable
    ; plugin for that.
    ; If the port is zero, or the line commented, the server
    ; is not started.
    managementport 12720
}

remotecontrol {
    ; enable the telnet remote control server on the given port
    ; This server allows you to read and define parameters that
    ; some features export. It is only accessible from localhost.
    ; Set the port to 0 to disable the server
    telnetport 12721

    ; The remote control is also accessible through a ZMQ REQ/REP socket,
    ; and is useful for machine-triggered interactions. It supports the
    ; same commands as the telnet RC.
    ; The example code in doc/zmq_remote.py illustrates how to use this rc.
    ; To disable the zeromq endpoint, remove the zmqendpoint line.
    ; By specifying "lo" in the URL, we make the server only accessible
    ; from localhost. You can write tcp://*:12722 to make it accessible
    ; on all interfaces.
    zmqendpoint tcp://lo:12722

    ; the remote control server makes use of the unique identifiers
    ; for the subchannels, services and components. Make sure you
    ; chose them so that you can identify them.
}

; Some ensemble parameters
ensemble {
    ; A unique 16-bit id is allocated to the ensemble and allows unambiguous
    ; identification of the ensemble when associated with the ensemble ECC.
    ; The id normally starts with the coutry id. (See ETSI TS 101 756)

    ; Example for Switzerland, with country id=4 and ECC=E1
    id 0x4fff ; you can also use decimal if you want
    ecc 0xe1 ; Extended Country Code

    local-time-offset auto  ; autmatically calculate from system local time
                            ; or
    ;local-time-offset 1    ; in hours, supports half-hour offsets

    ; If you want to run your machine in UTC time, but still take advantage of the
    ; automatic calculation of the local time offset, set the environment variable TZ
    ; to your timezone (e.g. TZ=Europe/Rome) before you launch ODR-DabMux

    ; FIG1 labels are given with the 'label' and 'shortlabel' keys.
    ;
    ; All labels are maximum 16 characters in length.
    ; Labels that are valid utf-8 will be converted to EBU Latin Character set
    ; as defined in ETSI TS 101 756, in Annex C. If it's not valid utf-8, the
    ; label is taken as-is, byte per byte. Characters that cannot be
    ; represented in EBU Latin will be replaced by a space character.
    label "OpenDigitalRadio"

    ; The short label is built from the label by erasing letters, and cannot
    ; be longer than 8 characters. If omitted, it will be truncated from the
    ; label
    shortlabel "ODR"

    ; The FIG2 label can be up to 16 characters long, and is in UTF-8.
    ;fig2_label "ÓpêñÐigıtålRadiō"

    ; FIG2 labels can either be sent with a character field (old spec)
    ; or with a text control (new draftETSI TS 103 176 v2.2.1).
    ; If unspecified, defaults to setting the text control with the values
    ; shown in the example below.
    ;
    ;fig2_label_character_flag "0xFF00"
    ;
    ;fig2_label_text_control {
    ; bidi false
    ; base_direction "LTR"
    ; contextual false
    ; combining false
    ;}
}

; Definition of DAB services
services {
    ; Each service has it's own unique identifier, that is
    ; used throughout the configuration file and for the RC.
    srv-fu {
        id 0x4daa
        label "Fünk"
        ; You can define a shortlabel and a fig2_label too.
    }
    srv-ri {
        ; If your ensemble contains a service from another country,
        ; specify its ECC here. Example is for Italy, country id=5, ECC=E0
        id 0x5dab
        ecc 0xe0
        label "Rick"
    }
}

subchannels {
    sub-fu {
        ; This is our DAB programme, using a file input
        type audio
        inputfile "funk.mp2"
        bitrate 128
        id 10
        protection 3
    }
    sub-ri {
        ; This is our DAB+ programme, using a ZeroMQ
        type dabplus
        ; Accepts connections to port 9000 from any interface.
        ; Use ODR-AudioEnc as encoder
        inputfile "tcp://*:9000"
        bitrate 96
        id 1
        protection 3

        ; ZMQ specific options, mandatory:

        ; Maximum size of input buffer, in AAC frames (24ms)
        ; when this buffer size is reached, some frames will be
        ; discarded to get the size again below this value.
        ; As the present implementation discards entire AAC superframes,
        ; (5 frames = 120ms) the effect will clearly be audible.
        zmq-buffer 40

        ; At startup or after an underrun, the buffer is filled to this
        ; amount of AAC frames before streaming starts.
        zmq-prebuffering 20

        ; In an ideal scenario, where the input rate exactly corresponds
        ; to the rate at which the frames are consumed by dabmux, you
        ; see the buffer level staying around the zmq-prebuffering value.
        ; Network latency jitter can make it temporarily go lower or higher.
        ; Encoder clock drift will make the buffer either slowly fill or
        ; empty, which will create intermittent glitches.
    }
}

; In our simple example, each component links one service to one subchannel
components {
    ; the component unique identifiers are used for the RC.
    comp-fu {
        ; According to specification, you should not define component labels if
        ; the service is only used in one component. The service label is sufficient
        ; in that case.
        service srv-fu
        subchannel sub-fu
    }

    comp-ri {
        service srv-ri
        subchannel sub-ri
    }
}

; A list of outputs
outputs {
    ; The unique-id can be used by the remote control or the statistics server
    ; to identify the output

    ; Output RAW ETI NI to standard output
    stdout "fifo:///dev/stdout?type=raw"

    ; ZeroMQ output example, new configuration format. Several
    ; zeromq blocks can be added here.
    ; This output does not back-pressure the multiplexer.
    zeromq {
        ; Listen on all interfaces, on port 9100
        endpoint "tcp://*:9100"

        ; Transmit backward compatible metadata containing
        ; EDI time and UTC offset when TIST is enabled.
        ;
        ; If TIST is enabled, requires leap-second information (see example.mux)
        ;
        ; WARNING! requires ODR-DabMux to be compiled with
        ; EDI output, and this will enable leap second download
        ; as for the EDI output!
        allowmetadata true
    }

    ; Output ETI-over-TCP. This is like piping a RAW ETI NI data stream
    ; into a TCP socket, except that the output can handle simultaneous
    ; connections.
    ; 0.0.0.0 means "listen on all interfaces"
    ; This output does not back-pressure the multiplexer.
    ;tcp "tcp://0.0.0.0:9200"

    ; Throttle output to real-time (one ETI frame every 24ms)
    ;throttle "simul://"

    ; Important! For real-time operation, you need to have exactly one
    ; output that applies back-pressure to ODR-DabMux, otherwise it will run
    ; at the highest possible rate on your system!
    ;
    ; For an output to a pipe, the data consumer at the other end of the pipe
    ; will dictate the multiplexing rate to ODR-DabMux.
    ;
    ; If you use the zmq+tcp:// or the tcp:// output,
    ; you must also enable a simul:// output!
}