dvbmux is configured through a command-line interface accessible via the telnet protocol, similarly to telco-grade telecommunications equipment (think Cisco). After the multiplexer is set up, its configuration can be saved as a text file that actually consists of CLI commands to restore the configuration on startup. The file can be edited outside the CLI, which may be a very convenient, though service-disrupting way of making gross changes.
To connect to the CLI, use the standard Linux telnet client. The CLI port defaults to 8001 and is adjustable through the -s startup option (see README). A typical command to execute in a Linux shell to access the multiplexer CLI would be:
telnet localhost 8001
It is also possible to connect to the CLI from a machine running Microsoft Windows (TM).
Click Start / Run and then type telnet [hostname] 8001, where [hostname] is host name or IP address of the server dvbmux is running on. A convenient alternative is to use PuTTY free ssh/telnet client, which is available for download from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
On successful connection, dvbmux will present the user with a prompt consisting of the hash character (#) and a space, denoting that it is ready to accept commands.
[sil@marvin dvbmux]$ telnet localhost 8001 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. #
The CLI commands consist of multiple keywords and identifiers separated by spaces. They are processed only after confirming them with ENTER. Upon successful execution of a command, dvbmux will communicate the command results, if there is anything to communicate, and return to the prompt.
# show version v0.9.3-2 build 479ff66f #
Basic line editing is supported. Left/right arrow keys move the cursor (alternatively, use CTRL+B and CTRL+F). CTRL+E returns to the end of line. Backspace deletes character before cursor, CTRL+W deletes a word before cursor, CTRL+C or CTRL+U clears the whole line. Up/down arrow keys provide simple command history and may be used to recall few last entered commands.
The command line interface features a context help function, owing to which the user needs not to remember exact command syntax. Enter the question mark character (?) during command edition to show a list of available options.
# ? show Show running system information input Configure input streams group Configure PID groups (services) network Configure DVB networks output Configure output streams system Alter system-wide parameters (...) # system ? max-buffer-size Set maximal PID group buffer size buffers Alter all PID group buffers si Control PSI/SI operation
Keywords can be shortened to their prefixes, if the shortening is unambiguous. For example, sh ver may be typed instead of show version. On the other hand, s v will not work, since it is not clear whether s means system or show, which are both acceptable at the beginning of a command.
There is also a tab-completion feature that finishes any keywords or identifiers to save typing. As an example, if there is an output named marvin in the current configuration, pressing TAB key after typing show output mar will cause the CLI to add vin and a space to the command buffer.
To disconnect from the CLI, use the exit command or simply close the connection. The latter is by default done in the Linux telnet client by pressing CTRL+] and then typing "exit".
To start receiving an MPEG-2 Transport Stream over UDP, use the following command:
# input elsat_QAM2 source 229.0.5.2:1234
elsat_QAM2 is a string identifier that will reference the input during further configuration. Obviously, multiple inputs can be defined, providing they have distinct identifiers.
The source parameter tells dvbmux how to receive the input stream. Following input specifications are supported:
# input unicast_in source :55000 (dvbmux will receive the input by listening on UDP port 55000 on all interfaces) # input mcast_in source 229.1.2.4:5512 (dvbmux will join the specified multicast group and receive input on port 5512) # input if_in source :2345@eth1 (dvbmux will bind to UDP port 2345 of interface eth1 in order to receive the input) # input mcast_if_in source 229.1.2.5:8888@10.82.0.5 (dvbmux will receive the input from a multicast group, binding to an interface with IP 10.82.0.5)
To check if an input is actually received by dvbmux, issue the show input summary command and observe the Rx bitrate column.
# show input summary Source Name Rx bitrate CCErrors --------------------------------------------------------------------- | 229.5.5.12:1234 | MPTS | 19982.2 | 3 | 127.0.0.1:12345 | QAM10_Loopback | 4975.4 | 0 | 229.0.5.2:1234 | elsat_QAM2 | 50636.2 | 0 | 229.1.6.29:1234 | iCanal | 37982.7 | 11 | 229.1.1.10:1234 | iTVN | 0.0 | 0
If no data is received (Rx bitrate = 0), use standard Linux network diagnostics tools to troubleshoot. Start with tcpdump to check if the stream actually reaches your machine. The command netstat -nlp can be used to verify that dvbmux actually listens on the proper port and interface.
To stop receiving an input, use the no input [input name] command.
After a few seconds, dvbmux should complete parsing the SDT table of the input stream, if one is present. The show input [input name] services command may be then used to examine services available in the stream.
# show input elsat_QAM2 services === Source 'elsat_QAM2' (229.0.5.2:1234) SID Service name PMT PID Bitrate Other PIDs -------------------------------------------------------------------------- | 12 | Tele_5 | 306 | 0x0132 | 3194.6 kb/s | 96 164 505 | 13 | Polonia_1 | 305 | 0x0131 | 2400.7 kb/s | 100 165 506 | 17 | History | 51 | 0x0033 | 3643.8 kb/s | 113 114 115 | 24 | ITV | 59 | 0x003b | 2120.8 kb/s | 112 168 502 | 60 | National_Geographic | 48 | 0x0030 | 1587.8 kb/s | 116 117 169 510 | 72 | Viasat_History | 58 | 0x003a | 3512.5 kb/s | 1545 1552 | 84 | RTL | 56 | 0x0038 | 5162.0 kb/s | 104 105 106 163 | 85 | RTL_2 | 55 | 0x0037 | 6558.5 kb/s | 68 128 166 | 86 | Sat_1 | 52 | 0x0034 | 2486.1 kb/s | 32 255 256 259 | 87 | ProSieben | 53 | 0x0035 | 4562.6 kb/s | 33 511 512 515 | 88 | Super_RTL | 54 | 0x0036 | 2388.1 kb/s | 82 145 172
This information is retrieved from PMT (Service ID and PIDs of the component streams), as well as from SDT (service names). Even in absence of service information, the show input [input name] es command shows input's active elementary streams.
# sh inp elsat_QAM2 es === Source 'elsat_QAM2' (229.0.5.2:1234) Source PID Bitrate Service ST Flags --------------------------------------------------------------------- | 0 | 0x0000 | 30.0 kb/s| <Unknown> | 00 | | 16 | 0x0010 | 17.4 kb/s| <Unknown> | 00 | ? | 17 | 0x0011 | 66.4 kb/s| <Unknown> | 00 | ? | 18 | 0x0012 | 298.9 kb/s| <Unknown> | 00 | ? | 20 | 0x0014 | 22.1 kb/s| <Unknown> | 00 | ? | 32 | 0x0020 | 264.1 kb/s| <Unknown> | 00 | ? | 33 | 0x0021 | 262.5 kb/s| <Unknown> | 00 | ? | 48 | 0x0030 | 30.0 kb/s| <Unknown> | 00 | ? | 51 | 0x0033 | 28.5 kb/s| <Unknown> | 00 | ? | 52 | 0x0034 | 30.0 kb/s| <Unknown> | 00 | ? | 53 | 0x0035 | 30.0 kb/s| <Unknown> | 00 | ? (...)
If a closer look into PSI/SI of inputs is necessary, the show input [input name] svc [service name or ID] command may be used to display elementary streams making up a particular service.
# show input elsat_QAM2 svc 87 === Source 'elsat_QAM2' (229.0.5.2:1234); service 87 ('ProSieben') PID Bitrate Flags -------------------------------------- | 33 | 0x0021 | 260.9 kb/s | | 53 | 0x0035 | 30.0 kb/s | m | 511 | 0x01ff | 4575.3 kb/s | v | 512 | 0x0200 | 197.7 kb/s | a | 515 | 0x0203 | 395.4 kb/s |
Also, the show input [input name] svc [service name or ID] descriptors detailed command is useful for examining descriptors defined within the PSI/SI tables.
=== Source 'elsat_QAM2' (229.0.5.2:1234); service 87 ('ProSieben') Loc ES PID Descriptor type Contents ------------------------------------------------------ | SDT | | | service | 48 24 01 18 45 6c 73 61 74 20 2d 20 50 61 6b 69 65 74 20 4e 69 65 62 69 65 73 6b 69 09 50 72 6f 53 69 65 62 65 6e Service type: 1 Service provider name: Elsat - Pakiet Niebieski Service name: ProSieben | PMT | 33 | 0x0021 | teletext | 56 05 64 65 75 09 64 ISO639 language code: deu Teletext type: 1 Teletext magazine number: 1 Teletext page number (hex): 100 | PMT | 512 | 0x0200 | iso-639-lang | 0a 04 64 65 75 00 Language code: deu Audio type: 0 | PMT | 515 | 0x0203 | ac3 | 6a 05 ff 42 08 00 00 | PMT | 515 | 0x0203 | iso-639-lang | 0a 04 64 65 75 00 Language code: deu Audio type: 0
To define an output stream, use the output [output name] destination [destination specifier]
# output QAM10 destination 10.82.4.1:1234
Following destination specifier formats are accepted: unicast_IP:port, multicast_group_IP:port, unicast_or_multicast_IP:port@interface_name, unicast_or_multicast_IP:port@interface_address.
All newly defined outputs are frozen by default. To start the actual generation of output packets, type output [output name] run. Also, a PSI/SI rebuild is required for a newly defined output to contain PSI/SI tables (PAT, NIT, SDT etc.). Use output [output name] rebuild-si or system si rebuild to rebuild PSI/SI tables. A PSI/SI rebuild will also be necessary after every reconfiguration that affects PSI tables. It is highly recommended to rebuild PSI/SI globally, after a configuration session has completed.
# output QAM10 run # output QAM10 rebuild-si
It might be reasonable to define a few important output parameters like bitrate, TTL (in case of multicast output), transport stream ID. Use the output [output name] [parameter] [value] series of commands to set them. Alternatively, it is possible to enter an output configuration context to save typing, by issuing simply output [output name]. The context then accepts commands in form of [parameter] [value]. To leave the output configuration context, type exit.
# output QAM10 output(QAM10)# bitrate 50000000 vbr truncate-packets output(QAM10)# ttl 5 output(QAM10)# ts-id 0x2f output(QAM10)# exit #
If the vbr keyword does not follow the configured bitrate, dvbmux will output the stream in CBR (constant bitrate mode) at the specified rate. On the other hand, in the VBR mode, the configured bitrate sets the maximal momentary stream bitrate, ie. dvbmux will avoid trains of packets in excess of the specified value, even at the cost of dropping MPEG packets.
The truncate-packets keyword enables an optional strict VBR mode, in which no ghost packets will be send at all (which may happen in the soft VBR mode when due to a configured repetition interval, a PSI/SI packet has to be sent). Note that in this mode, UDP packets generated by dvbmux will vary in size (ie. will consist of a variable number of MPEG packets).
An output may be temporarily stopped through no output [output name] run, and then re-started using output [output name] run. Use no output [output name] to remove an output.
A group (or service, in MPEG and DVB terminology) is a collection of elementary streams that is mentioned as a single entity in the PSI/SI tables inside a MPEG-2 Transport Stream. Typically, every TV channel available to the end user is a separate service, consisting of a single video stream, an audio stream and possibly additional streams like international (or surround) audio streams, teletext and other.
The group [group name] command is used to define a service within the dvbmux configuration.
To simply copy a service from one of the input MPEG2 Transport Streams, use group [group name] map from [input name] service [service ID or name] command:
# show input elsat_QAM2 services === Source 'elsat_QAM2' (229.0.5.2:1234) SID Service name PMT PID Bitrate Other PIDs -------------------------------------------------------------------------- | 12 | Tele_5 | 306 | 0x0132 | 1877.2 kb/s | 96 164 505 | 13 | Polonia_1 | 305 | 0x0131 | 2397.5 kb/s | 100 165 506 | 17 | History | 51 | 0x0033 | 3091.8 kb/s | 113 114 115 | 24 | ITV | 59 | 0x003b | 2528.8 kb/s | 112 168 502 (...) # group History_Channel map from elsat_QAM2 service History copy-descriptors #
Use the copy-descriptors keyword to copy all stream descriptors from input to output.
To add a particular elementary stream to a service, type group [group name] map from [input] pid [ES PID]. Add to [Dest PID] to remap the elementary stream onto another PID. Note that elementary streams from any number of inputs may be directed to a particular group.
The show group [group name] command can be used to see what elementary streams are routed to a particular group. Please also observe the show group [group name] descriptors detailed command, as well as show running-config group [group name].
# show group History_Channel === Group 'History_Channel', bitrate: 10000000 b/s Input Source PID Destination Errors Comment ------------------------------------------------------------------------ | elsat_QAM2 | 113 | 0x0071 | 113 | 0x0071 | 1 | | elsat_QAM2 | 114 | 0x0072 | 114 | 0x0072 | 1 | | elsat_QAM2 | 115 | 0x0073 | 115 | 0x0073 | 1 | # show group History_Channel descriptors detailed === Group 'History_Channel' Loc ES PID Descriptor type Contents ------------------------------------------------------ | PMT | 113 | 0x0071 | iso-639-lang | 0a 04 65 6e 67 00 Language code: eng Audio type: 0 | PMT | 114 | 0x0072 | iso-639-lang | 0a 04 70 6f 6c 00 Language code: pol Audio type: 0 | SDT | | | service | 48 12 01 08 48 61 72 6d 6f 6e 69 63 07 48 69 73 74 6f 72 79 Service type: 1 Service provider name: Harmonic Service name: History # show running-config group History_Channel group History_Channel bitrate 10000000 service id 890 map from elsat_QAM2 pid 113 - 115 descriptors sdt 481201084861726d6f6e696307486973746f7279 descriptors es 114 0a04706f6c00 descriptors es 113 0a04656e6700 stream-type pid 115 2 pid 114 4 pid 113 4 exit
To stop routing an elementary stream to a group, use group [group name] no map pid [target PID]. A group can be deleted by the way of no group [group name].
Using the output [output name] attach [group name], a group (service) can be attached to a particular output. A PSI/SI rebuild is required for the group to appear in the MPEG and DVB tables presented on that output (use system si rebuild or output [output name] rebuild-si).
It is not a problem for a single group to be attached to multiple outputs, if only destination PIDs of the group's elementary streams do not conflict with other groups attached to all of these outputs.
Use output [output name] no attach [group name] to cease routing a group (service) to an output.
The show output [output name] es command is useful for observing what streams actually are routed to an output:
# output QAM10 attach History_Channel # show output QAM10 es === Output 'QAM10', bitrate: 50000000 b/s Input Group Destination PID Input bitrate --------------------------------------------------------------------------- | elsat_QAM2 | History_Channel | 113 | 0x0071 | 134.6 kb/s | elsat_QAM2 | History_Channel | 114 | 0x0072 | 136.2 kb/s | elsat_QAM2 | History_Channel | 115 | 0x0073 | 2501.4 kb/s #
Note that the PSI/SI streams generated by dvbmux (such as PAT, PMT etc.) are not reported.
By default, dvbmux generates all the PSI/SI tables it supports on every output. These are: PAT (Program Association Table), SDT (Service Description Table), NIT (Network Information Table), TOT (Time Offset Table), TDT (Time and Date Table) and a PMT (Program Map Table) for every service attached to an output.
dvbmux builds these tables out of its current running configuration, as well as descriptors, also entered through the configuration interface. PSI/SI tables contents is only refreshed on user request (output [output name] rebuild-si or system si rebuild).
Please observe the following commands for configuring PSI/SI information that has to be included per every transport stream in the NIT (ts-id, network-id); per every service in SDT (schedule-flag, running-status, pf-flag, free-ca-flag); per every service in the PMT (pmt-pid, pcr-pid, service identifier); as well as per every elementary stream in the PMT (stream-type).
# output QAM10 ts-id 0x5f # output QAM10 network 0x22 # group History_Channel service free-ca-flag # group History_Channel service pf-flag # group History_Channel service schedule-flag # group History_Channel no service free-ca-flag # group History_Channel service running-status pausing # group History_Channel service pcr-pid 114 # group History_Channel service pmt-pid 0x500 # group History_Channel service id 1020 # group History_Channel stream-type pid 113 mp2v
Most of the MPEG and DVB PSI/SI information is contained within descriptors. Through CLI, descriptors can be added and removed to/from transport streams (outputs), services (groups) and elementary streams (group mappings). Generally, to access an object descriptors, start your command with: output [output name] descriptors nit ..., group [group name] descriptors pmt ..., group [group name] descriptors sdt ... or group [group name] descriptors es [ES PID] ....
To add a descriptor, finish with ... add [descriptor type] [descriptor parameters] or ... set [descriptor type] [descriptor parameters]. The latter variant deletes the descriptor first, should a descriptor of this type already exist. Use the context help feature to consult how to define a particular descriptor parameters.
As an example, to define a visible service name, a Service Name descriptor has to be added to the relevant group:
# group History_Channel descriptors sdt set service service-type digital-tv provider Sileman name HistoryChannel
The descriptor contents can be specified as a string of hex digits. This way, even descriptors not supported by the CLI can be added. Use ... add [hex string], for example:
# group History_Channel descriptors es 113 add 6a05ff42080000
Use ... remove [descriptor type] or ... remove [descriptor hex tag] to remove descriptors from an object.
Please note that after adding or removing a descriptor, no tables in the output streams will be altered, unless a PSI/SI rebuild is commanded (system si rebuild).
Note that the copy-descriptors keyword is particularly useful when mapping input streams to groups using group [group name] map from [input name] service [service name] copy-descriptors.
To configure network-wide descriptors, such as NIT or TOT descriptors, a network object has to be defined within dvbmux. Type network [numeric network ID] name [network name] to create a network object. The network descriptors can then be set using network [numeric network ID] nit descriptors ... or network [network ID] tot descriptors .... Please note that outputs have to be attached to a particular network using output [output name] network [network ID or name] before any network descriptors will be included in their NIT and TOT.
# network 34 name Network_Name # network 34 descriptors nit add network-name SILEMAN # network 34 skip-si tot # output QAM10 network 34 # output QAM10 descriptors nit set satellite-delivery frequency 12.220 orbital-position 19.2 east horiz qpsk symbol-rate 68.75 fec-inner conv78 # output QAM10 rebuild-si
Generation of a particular table can be inhibited for an output stream (or a whole network of output streams) by issuing output [output name] skip-si [table name]. A PSI/SI rebuild is required for such a change to complete. A table can be restored into an output stream by output [output name] no skip-si [table name].
All PSI/SI generation can be temporarily suspended by issuing the system si generator disable. This can be then reverted through no system si generator disable. Contrary to any other PSI/SI operations, these two commands effect immediately, without a PSI/SI rebuild required.
To save current configuration into the configuration file, type write memory.
It is very advisable to disable the PSI/SI decoder when it is not needed. The only purpose of the PSI/SI decoder is to provide information to the command line interface user, such as service names or descriptors. There is no point in the PSI/SI decoder running after dvbmux has been configured and is going to be left unattended for a few hours, days, weeks or months. To disable the PSI/SI decoder type system si decoder disable. The decoder can be re-enabled easily, should a reconfiguration be necessary, by executing no system si decoder disable.
The clear si command can be used to restart parsing the PSI/SI data coming on the input streams.
The show logging command shows last entries in dvbmux logging buffer, which may aid troubleshooting.
Use show running-config to see commands building the current configuration. Note that variants of this command, show running-config [object] [object idenfier] can save a lot of typing, especially when issuing de-configuration commands.
# show running-config output QAM10 output QAM10 destination 85.11.67.254:45555 bitrate 50000000 vbr truncate-packets ts-id 95 network 34 attach History_Channel descriptors nit 430b0122200001928168750005 exit output QAM10 run # show running-config group History_Channel group History_Channel bitrate 10000000 service id 1020 pmt-pid 1280 pcr-pid 114 running-status pausing service schedule-flag pf-flag map from elsat_QAM2 pid 113 - 115 descriptors sdt 482d010e53ff69bb6c8d65406d0061006e001c48ff69bb738d74406f0072007900430068fe619b6e7f6e0065fd6c9b descriptors es 114 0a04706f6c00 stream-type pid 114 1 pid 113 2 exit
To assess overall system performance, use the show performance command.
# show performance Total running time: 5023.187 s Total time spent: * Input processing: 424.412 s ( 8.4 %) * Input idling: 3818.406 s ( 76.0 %) * Output processing: 74.927 s ( 1.5 %) * Output idling: 4937.241 s ( 98.3 %) * Command processing: 0.005 s ( 0.0 %) Collective event histogram, counting all outputs: [ 0]: 37568042 99.9980 % (...)
Observe the Input processing and Output processing rows. The percentage of time spent in executing these tasks gives an estimate of the overall multiplexing system load.
Event histograms are another important tool in estimating the system load. Recall that for every output, dvbmux constructs and maintains a schedule that controls the exact timing instant of every output packet. System timers (or a busy loop) are used to generate timer events on these time instants. Normally, only one UDP packet is generated per a timer event.
However, if an event is missed due to some system hiccup (eg. misconfigured cronjobs on the machine dvbmux operates on) or system overload, dvbmux sends the late packet(s) within the next event.
Event histograms (show output [output name] or show performance) give information on how many and how often timer events are lost. The first histogram column [1] shows the count of timer events that were on time, whilst the next columns ([2], [3] and so on) signify the number of timer events that had to emit one, two (and so on) late packets from previous, missed events.
Under increasing load, counters in histograms will gradually move towards further columns. A slight shift is itself not dangerous, unless the devices receiving dvbmux output have strict jitter requirements. An overloaded system will be however noting significant increases in the last column, which means output streams tend to be generated in huge bursts.
# show output QAM10 === Output 'QAM10' Destination : 85.11.67.254:45555 Timer events served : 2226338 UDP packets sent : 985309 (0.4 packets/event) MPEG packets sent : 6897163 Total time serving : 2448894 us Packet construction : 2.5 us NULL packets : 0 (0.0 %) Event histogram : [ 1]: 2226332 [ 2]: 0 [ 3]: 3 [ 4]: 1 [ 5]: 0 [ 6]: 0 [ 7]: 1 [ 8]: 0 [ 9]: 0 [10]: 0 [11]: 0 [12]: 0 [13]: 0 [14]: 0 [15]: 0 [16]: 1
Even if the multiplexing system has spare processing power, it may lose MPEG packets on an output, due to too little bitrate configured. Such a problem will be easily visible in the show output [output name] groups output.
# show output QAM10 groups === Output 'QAM10', bitrate: 2000000 b/s Group In bitrate Buf size Dropped -------------------------------------------------------- | History_Channel | 4274.5 | 4096 pkts | 1331
If the counter in the Dropped increases, it means that the output bitrate has to be raised to acommodate all groups that were directed to that output.
The following common issues are worth checking while troubleshooting an MPEG setup:
It might be also helpful to temporarily send your stream via unicast to a PC running vlc.