INTRODUCTION

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

DVBMUX COMMAND LINE INTERFACE BASICS

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".

INPUT STREAMS

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.

DIGGING INTO PSI/SI OF INPUTS

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

OUTPUT STREAMS

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.

GROUPS (SERVICES)

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

CONNECTING GROUPS TO OUTPUTS

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.

CONTROLLING THE PSI/SI GENERATOR

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.

OTHER USEFUL COMMANDS

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

MONITORING DVBMUX PERFORMANCE

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.

CHECKLIST

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.