README

   1 $Id$
   2
   3 Welcome to DVBlast!
   4 ===================
   5
   6 DVBlast is a simple and powerful MPEG-2/TS demux and streaming
   7 application with several input methods:
   8  - linux-dvb-supported cards (DVB-S, DVB-S2, DVB-C, DVB-T...)
   9  - DVB-ASI cards
  10  - UDP or RTP stream carrying a transport stream
  11
  12 It outputs one or several RTP streams carrying transport streams with:
  13  - hardware or software PID filtering
  14  - PID-based or service-based demultiplexing
  15  - optional descrambling via CAM device
  16  - optional DVB tables
  17
  18 DVBlast is written to be the core of a custom IRD, CID,or ASI gateway,
  19 based on a PC with a Linux-supported card. It is very lightweight and
  20 stable, designed for 24/7 operation.
  21
  22
  23 Current features
  24 ================
  25
  26  - Lightweight program designed for extreme memory and CPU conditions
  27  - No runtime dependancy; one build dependancy (biTStream)
  28  - CAM menus (MMI) support via an external application
  29  - The configuration file describing outputs can be reloaded without losing
  30    a single packet
  31  - Support for the new S2API of linux-dvb
  32  - IPv6 network support
  33  - UDP rather than RTP output for IPTV STBs which don't support RTP
  34
  35
  36 Tuning DVBlast
  37 ==============
  38
  39 You usually want to supply DVBlast with the parameters of a transponder,
  40 for instance for DVB-S :
  41
  42 dvblast -f 11570000 -s 27500000 -v 18
  43
  44 This tunes to frequency 11570 MHz, symbol rate 27500, horizontal (-v 18). For
  45 DVB-S2, you must indicate a modulation with -m qpsk or -m psk_8. For DVB-T,
  46 a bandwidth (usually -b 8 for 8 MHz multiplexes).
  47
  48 Please note that frequencies are in kHz for DVB-S/S2/C, but Hz for DVB-T.
  49 Symbol rates are in symbols/s, and bandwidths in MHz. If you have several
  50 linux-dvb cards in the machine, specify which one to use with -a.
  51
  52 You generally want to run DVBlast in DVB compliance mode with option -C.
  53 This option will pass through or generate mandatory DVB tables (NIT, SDT,
  54 EITp/f, TOT, TDT). If you also want to pass-through the EIT schedule tables,
  55 use the -e switch. It is considered a good practice to configure the name
  56 of the network (for the NIT) with the -M option.
  57
  58 If you don't want to set these options on a general basis, you can set them
  59 per output - see below.
  60
  61 Other rarely used options are available - run dvblast -h for more
  62 information.
  63
  64
  65 Alternative inputs
  66 ==================
  67
  68 DVBlast may handle several DVB adapters in the same machine with the -a switch:
  69 -a 3 will use /dev/dvb/adapter3.  Additionally, selecting between frontends on
  70 a single card is supported with the -n switch.  This is useful for hybrid
  71 DVB/S + DVB/T cards.
  72
  73 If you own a Computer Modules DVB-ASI input card, you can have DVBlast
  74 filter and demultiplex the inputs. You just need to specify the slot number
  75 with -A.
  76
  77 DVBlast can also read from a UDP or RTP IPv4 source carrying for
  78 instance a multi-program transport stream. The address is specified with
  79 -D. See the 'advanced features' section for information on how to create
  80 such a stream for instance to cross network boundaries between the
  81 receivers and the target network.
  82
  83 The syntax of the -D option is:
  84 [<src host>[:<src port>]@]<src mcast>[:<port>][/<opts>]*
  85 where <src mcast> is the multicast address carrying the stream, and <src
  86 host> is optionally the address of the source, for source-specific multicast.
  87 Options include:
  88  /udp (for streams without an RTP header)
  89  /mtu=XXXX (sets the maximum UDP packet size)
  90  /ifindex=X (binds to a specific network interface, by link number)
  91  /ifaddr=XXX.XXX.XXX.XXX (binds to a specific network interface, by address)
  92
  93 For example:
  94 -D 239.255.0.2:1234/udp/ifindex=1
  95
  96
  97 Configuring outputs
  98 ===================
  99
 100 DVBlast reads a configuration file containing one or several lines in the
 101 format :
 102 <IP>[:<port>][@<IP>[:<port>]][/<option>]*       <always on>     <SID>   [<PID>,]*
 103
 104 For instance :
 105 239.255.0.1:1234                1       10750   1234,1235,1236
 106
 107 The configuration file can be reloaded by sending "HUP" to the program, or
 108 via the dvblastctl program.
 109
 110 IPv6 is supported, the destination address must be specified in the format
 111 described by RFC2732.  When using link-local scope addresses, it is
 112 mandatory to include the interface name in the address, as shown in the
 113 example below.  If you do not include the interface name, you will see an
 114 "invalid argument" error.  The interface name is optional for site-local and
 115 global scope addresses.
 116
 117 For example :
 118 [ff12::1%eth0]:1234             1       10750
 119 [ff15::abcd]:1234               1       10750
 120
 121 An optional bind address can be specified after an '@' sign. The typical
 122 usage of this is to allow binding to a specific interface in a system which
 123 has several. For instance:
 124 239.255.0.1:1234@192.168.42.1   1       10750
 125
 126 For IPv6 the bind address is not relevant; binding to an interface is achieved
 127 via the option "/ifindex=X" where X is the number of the link, as given by
 128 the command `ip link`.
 129
 130 The "always on" flag tells DVBlast whether the channel is expected to
 131 be on at all times or if it may break. If set to "1", then DVBlast will
 132 regularly reset the CAM module if it fails to descramble the service,
 133 assuming the module is dead. Every time it is reset a few TS packets
 134 will be lost, that is why this feature is optional.
 135
 136 Other options can be set by appending / to the multicast address definition.
 137 Available options include :
 138  /udp (turns on -U for a specific output)
 139  /dvb (turns on -C for a specific output)
 140  /epg (turns on -C -e for a specific output)
 141  /tsid=XXX (sets the transport stream ID)
 142  /ssrc=XXX.XXX.XXX.XXX (sets the RTP synchronization source IPv4)
 143  /retention=XXX (see -E)
 144  /latency=XXX (see -L)
 145  /ttl=XX (see -t)
 146  /tos=XX (sets the IPv4 Type Of Service option)
 147  /mtu=XXXX (sets the maximum UDP packet size)
 148
 149 Several options can be appended, for instance:
 150
 151 239.255.0.1:1234/udp/epg/tsid=42/ssrc=192.168.0.1
 152
 153 The optional "/udp" parameter can be used to force DVBlast to output
 154 raw UDP stream. This functionality is provided for backwards compatibility
 155 with IPTV set top boxes that don't support RTP and should only be used
 156 if absolutely necessary. If you need both RTP and UDP streams of the same
 157 program, specify them on separate lines like this:
 158
 159 239.255.0.1:1234        1       10750
 160 239.255.0.2:1234/udp    1       10750
 161
 162
 163 There are three ways of configuring the PIDs to stream :
 164
 165 1. SID-based
 166
 167 239.255.0.1:1234        1       10750
 168
 169 DVBlast will stream all known PIDs from service 10750 (video, audio, and
 170 subtitles). The resulting stream is fully MPEG-compliant, with PAT and PMT.
 171
 172 2. SID and PIDs
 173
 174 239.255.0.1:1234        1       10750   1234,1235
 175
 176 DVBlast will stream SID 10750, but only PID 1234 and 1235 will be output.
 177 Other known PIDs will be discarded and removed from the PMT. The list of
 178 PIDs in the config file does not include the PAT and PMT, but it must
 179 include the PCR PID if it is different from the video or audio PID, otherwise
 180 the stream won't be compliant.
 181
 182 3. PIDs only
 183
 184 239.255.0.1:1234        1       0       0,128,1234,1235
 185
 186 DVBlast will only stream the PIDs passed. No PAT and PMT will be generated,
 187 so if they are not included the stream won't be compliant. Also the
 188 included PAT and PMT may contain ghost programs or ESes.
 189
 190 Note that the CAM will not be programmed in that case (unless it has
 191 been programmed by another line of the config file). The file is read
 192 from the command-line :
 193
 194 dvblast -c /tmp/dvblast.conf
 195
 196
 197 Buffering
 198 =========
 199
 200 DVB cards usually output packets in big chunks. This can be problematic
 201 with low bitrate multiplexes. By default, DVBlast bufferizes 200 ms
 202 and tries to smooth the output. It may be desired to change this value
 203 with the -L option. The appropriate value for the output latency should be :
 204   chunk_size / multiplex_bitrate
 205
 206 The chunk size for saa7146-based cards is 512000 bits ; for
 207 cx23885-based cards is 192512 bits. The chunk size can be modified with
 208 an appropriate kernel patch (see extra/). The multiplex_bitrate depends
 209 on the symbol rate and many other factors such as the modulation.
 210
 211 The current default value allows for multiplex_rates as low as 2.56 Mbi/s.
 212 Smaller multiplexes are rare but exist, so in that case you may want to
 213 increase the buffer size. A typical DVB multiplex is 30 or 40 Mbi/s, so
 214 the default introduces a superfluous latency ; the buffer can be lowered
 215 to 50 ms if latency is an issue.
 216
 217 DVBlast also has another parameter called "max retention time" (-E).
 218 This controls how TS packets are grouped together in IP datagrams : the
 219 difference between the theorical output times of the first and the last
 220 TS packets cannot exceed the maximal retention time.
 221
 222 IP datagrams are normally output at the output time of the earliest TS
 223 packet ; it implies that the next TS packets are sent too soon and must
 224 be buffered at the receiver level. ISO/IEC 13818-1 makes no provision for
 225 this, since IP wasn't in mind when designing TS, so in theory we risk a
 226 buffer overflow.
 227
 228 However normal IP receivers feature a jitter buffer which can absorb the
 229 overflow ; DVB recommends a 50 ms buffer. DVBlast's default maximal
 230 retention time is just below, at 40 ms, which should be fine in most
 231 situations.
 232
 233 If some anal set-top-box complains about buffer overflows or clock issues,
 234 you may try to lower the value ; the drawback is that on low bitrate
 235 streams it will introduce padding. People with low bitrate streams and
 236 nice receivers with big buffers can raise this value to avoid superfluous
 237 padding and lower the total bitrate.
 238
 239 Please bear in mind though that setting a value for max retention time
 240 greater than the output latency has no effect.
 241
 242
 243 Monitoring
 244 ==========
 245
 246 If dvblast is run with the -r option, the dvblastctl program can be used
 247 to retrieve information from DVBlast about the front-end or CAM module.
 248
 249 dvblastctl -r /tmp/dvblast.sock fe_status
 250 dvblastctl -r /tmp/dvblast.sock mmi_status
 251 dvblastctl -r /tmp/dvblast.sock shutdown
 252
 253
 254 CAM menu
 255 ========
 256
 257 For easier access to the CAM menus, the dvblast_mmi.sh shell script is
 258 provided :
 259
 260 dvblast_mmi.sh -r /tmp/dvblast.sock
 261
 262
 263 Advanced features
 264 =================
 265
 266 For better latency, run DVBlast in real-time priority: -i 1 (requires root
 267 privileges).
 268
 269 DVBlast can also stream the entire transponder to an IPv4 or IPv6 address :
 270 dvblast -u -d 172.16.42.42:1235 -f 11570000 -s 27500000 -v 18
 271 dvblast -u -d [fe80::0ca:feff:fec0:ffee]:1235 -f 11570000 -s 27500000 -v 18
 272
 273 Note that IPv6 addresses specified on command line may need to have the square
 274 brackets escaped (\[ and \]), depending on your shell.
 275
 276 The -u switch disables the PID filters, so that all PIDs, even the
 277 unused ones, can be output.
 278
 279 Other options are self-understandable, and are listed in dvblast -h.
 280