Dvbscan

scan is one of the utilities contained in the LinuxTV dvb-apps. It scans specific frequencies for programs that can be received and generates a channel list.

Note: Depending on where/how you got the dvb-apps package, the program may be called either 'scan', 'scandvb' or 'dvbscan'. In the following examples, we'll use the name 'scan' ... dvbscan.

dvbscan does not have a man page. If you run it without parameters, it gives you an overview of the commands, which is usually only sufficient for experts.

dvbscan requires a channel information file to do its job. These files are supplied with the package, but the location where they are installed may vary. In the following examples, the directory is /usr/local/share/dvb/scan/dvb-t/; other installations also use /usr/share/doc/dvb-utils/eamples/scan/dvb-t/. In each case, the name of the file you're looking for is of the form cc-Ttttt, where cc is a two-letter country abbreviation, and Ttttt is the name of the location of the transmitter. So in Adelaide, Australia, you'd look for a file called au-Adelaide; in Oxford, UK (the example at First steps with a DVB device) you would use uk-Oxford.

Scan will need some idea of where to start searching; for this reasons it takes a file for your location as a starting point. Therefore, you need to find channel information for your locality. Again, the location where they are installed may vary. In the following examples, the directory is /usr/share/doc/dvb-utils/examples/scan/dvb-t/; other installations also use /usr/share/doc/dvb-apps-1.1.1 or /usr/local/share/dvb/scan/dvb-t/. DVB-S users should use the folders /usr/share/doc/dvb-utils/examples/scan/dvb-s/, /usr/share/doc/dvb-apps-1.1.1 or /usr/local/share/dvb/scan/dvb-s/. In each case, the name of the file you're looking for is of the form cc-Ttttt, where cc is a two-letter country abbreviation, and Ttttt is the name of the location of the transmitter. So in Adelaide, Australia, you'd look for a file called au-Adelaide; the following example relates to Oxford in the United Kingdom.

Note also that there are other files with similar names:

• /usr/share/doc/dvb-utils/eamples/dvb-t/au-Adelaide is a copy of /usr/share/doc/dvb-utils/eamples/scan/dvb-t/au-Adelaide.
• /usr/local/share/dvb/zap/dvb-t/au-Adelaide is a canned version of the output of dvbscan. It may be out of date, so it's better to generate it from dvbscan, but if you can't get dvbscan to work, you might get further by using this file.

dvbscan outputs a lot of data. Here's some of it:

$ dvbscan /usr/local/share/dvb/scan/dvb-t/au-Adelaide 
scanning /usr/local/share/dvb/scan/dvb-t/au-Adelaide
using '/dev/dvb/adapter0/frontend0' and '/dev/dvb/adapter0/demux0'
initial transponder 226500000 1 3 9 3 1 1 0
(etc)

---

This tries to find the programs it takes from the initial uk-Oxford configuration (or whatever your place is).

For the beginning, do something like this: Adopt this line for your place

 scan /usr/share/doc/dvb-utils/examples/scan/dvb-t/uk-Oxford 

For ATSC:

 $ /usr/bin/scan /usr/share/dvb-apps/atsc/us-ATSC-center-frequencies-8VSB

For North American cable-tv

 $ /usr/bin/scan /usr/share/dvb-apps/atsc/us-Cable-Standard-center-frequencies-QAM256 

---

This information tells you what hardware and channels dvbscan is talking to. There are often many lines of transponder information. The information shown here is wrapped over two lines to make it easier to read.

>>> tune to: 226500000:INVERSION_AUTO:BANDWIDTH_7_MHZ:FEC_3_4:FEC_AUTO:QAM_64:
 TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE
0x0000 0x0250: pmt_pid 0x0102 ABC -- ABC HDTV (running)
0x0000 0x0251: pmt_pid 0x0100 ABC -- ABC TV Adelaide (running)
...
0x0000 0x0257: pmt_pid 0x0106 ABC -- ABC DiG Jazz (running)
Network Name 'ABC Adelaide'

This is the tuning information for the first transponder. Each transponder can transmit multiple programs. The last one is a radio program, which you can see from the output later on.

During scanning, you may see error messages like:

>>> tune to: 571500000:INVERSION_AUTO:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:
 TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE
WARNING: >>> tuning failed!!!

This is not fatal. It's possible that the scan files contain information about stations that are not yet, or no longer, in service. Check the output at the end to see whether you have all the advertised programmes.

This should produce output saying "WARNING: >>> tuning failed!!!" if a signal was not found on that particular frequency. Eventually, a list of services found should be displayed.

It will take a while for scan to search through all the frequencies listed in those initial files, but it will output its progress in the shell. Note that the screen output you get into your shell doesn't really say if you can receive something. On the other hand, if a signal was not found on a particular frequency, you will notice that the output produces "WARNING: >>> tuning failed!!!". Do not be alarmed by such tuning failed messages. Eventually, upon scan completion, a list of services found should be displayed. Here is a sample list for an ATSC scan:

 dumping lists (7 services)
 KPAX-DT:177028615:8VSB:49:52:1
 KPAX-CW:177028615:8VSB:65:68:2
 KUFM-HD:551028615:8VSB:49:52:3
 KUFM-DT:551028615:8VSB:65:68:4
 KTMF-DT:605028615:8VSB:49:52:3
 [0001]:605028615:8VSB:49:52:1
 KECI-1:629028615:8VSB:49:52:3

For a DVB-T scan, the output might look like this:

 BBC ONE:578000000:INVERSION_AUTO:BANDWIDTH_8_MHZ:FEC_3_4:FEC_3_4:QAM_16:TRANSMISSION_MODE_2K:GUARD_INTERVAL_1_32:HIERARCHY_NONE:600:601:4171

which says that the channel BBC ONE is found on frequency 578000000 Hz, and has has the two PIDs 600 and 601 for the video and audio stream.

At the end, dvbscan outputs a list of channels corresponding to what it has found, for example:

ABC HDTV:226500000:INVERSION_AUTO:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:
  TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:2314:0:592
ABC DiG Jazz:226500000:INVERSION_AUTO:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:
  TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:0:2318:599
...
TEN Digital:219500000:INVERSION_AUTO:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:
  TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1617

This is a "colon-separated" file. It consists of a number of fields delimited by colons. Here's the meaning of the three lines shown above:

channels.conf format

Field	First programme	Second programme	Third programme
Programme name	ABC HDTV	ABC DiG Jazz	TEN Digital
Frequency (Hz)	226500000	226500000	219500000
Inversion mode	INVERSION_AUTO	INVERSION_AUTO	INVERSION_AUTO
Symbol rate	BANDWIDTH_7_MHZ	BANDWIDTH_7_MHZ	BANDWIDTH_7_MHZ
FEC name, HP	FEC_3_4	FEC_3_4	FEC_3_4
FEC name, LP	FEC_3_4	FEC_3_4	FEC_1_2
Constellation	QAM_64	QAM_64	QAM_64
Transmission mode	TRANSMISSION_MODE_8K	TRANSMISSION_MODE_8K	TRANSMISSION_MODE_8K
Guard interval	GUARD_INTERVAL_1_16	GUARD_INTERVAL_1_16	GUARD_INTERVAL_1_16
Hierarchy information	HIERARCHY_NONE	HIERARCHY_NONE	HIERARCHY_NONE
Video pid	2314	0	512
Audio pid	0	2318	650
Service ID	592	599	1617

These fields vary depending on the type of modulation; the ones shown are for QFDM (and, paradoxically, not for QAM). For other forms of modulation, the meanings of the fields differ. See the source code (and document it, please!) at util/scan/dump-zap.c.

Looking at the values, it's clear that ABC DiG Jazz is a radio programme, since it doesn't have a video pid. Less clear is why ABC HDTV does not have an audio pid. This is a real issue: this means that when tuning to these streams, no audio is output. We'll look at how to solve this problem below.

The frequencies shown here are in Hz. They correspond to 226.5 MHz for ABC and 219.5 MHz for TEN. Note that the first two programmes are the same frequency, so they come in the same MPEG stream. They're distinguished by the pids.

Creating channels.conf

Next create a "channels.conf", a file in a hidden (dotted) directory off your "home" directory.

For DVB-T:

 mkdir /root/.tzap
 scan /usr/share/doc/dvb-utils/examples/scan/dvb-t/uk-Oxford > /root/.tzap/channels.conf

For ATSC:

 $ mkdir ~/.azap
 $ scandvb /usr/share/dvb-apps/atsc/us-ATSC-center-frequencies-8VSB > ~/.azap/channels.conf
 

Next display the contents of the channels.conf file to make sure the file creation proceeded correctly

 $ cat ~/.azap/channels.conf

Next display the contents of the channels.conf file to make sure the file creation proceeded correctly

 $ cat ~/.czap/channels.conf

Note: if your signal is too weak and you receive only some channels, the way to find out which is to look in the channel.conf file that you just created. If for a program the two PIDs (third and second last number in line) are 0, you can't receive it. If the first PID is 0 and the second is not 0, then it's probably a radio channel.

This file with the data for your TV-programs, if stored into the place as above, can be used by a "zapper" such as tzap

The data shown above is what tzap and friends want in their channels.conf file. tzap expects to find it in a file ~/.tzap/channels.conf. Create it like this:

$ cd ~
$ mkdir .tzap
$ dvbscan /usr/local/share/dvb/scan/dvb-t/au-Adelaide > .tzap/channels.conf

Presumably czap and szap require directories called ~/.czap and ~/.szap, but you should confirm this.

No sound with HDTV

scan does not alwyas recognize the audio streams, at least for DVB-T. In Australia, most channels broadcast HDTV with AC3 audio, which scan does not recognize when invoked as above. The result is the output shown above for ABC HDTV: no audio.

This is almost certainly a bug in scan. Until it is fixed, you can proceed in the following way:

• Create the channels.conf file as shown above.
• Run tzap to tune to the stream:

$ tzap -S "ABC HDTV" &

The -S ("silent") option tells tzap not to output its usual signal quality information; the & tells the shell to issue a new prompt when it has started tzap.

Next, run dvbscan with the -c (scan on currently tuned transponder only) option:

$ dvbscan -c
using '/dev/dvb/adapter0/frontend0' and '/dev/dvb/adapter0/demux0'
0x0000 0x0250: pmt_pid 0x0102 ABC -- ABC HDTV (running)
0x0000 0x0251: pmt_pid 0x0100 ABC -- ABC TV Adelaide (running)
dumping lists (6 services)
ABC HDTV         (0x0250) 01: PCR 0x0905 V 0x090a TT 0x090c AC3 0x090b
ABC TV Adelaide  (0x0251) 01: PCR 0x0080 V 0x0200 A 0x028a (eng) TT 0x0240 AC3 0x0294

This output was limited to the interesting information. The last two lines show the output for ABC HDTV and ABC TV Adelaide. ABC TV Adelaide has a video pid 0x200, an audio pid 0x28a, and an AC3 pid 0x294. The meanings of the other values still need to be documented.

By contrast, ABC HDTV has a video pid 0x90a, and AC3 pid 0x90b--and no audio pid. This is the problem. In the output from scan based on the transmitter data, the corresponding values are (leaving out the middle of the lines, which aren't of interest here):

ABC HDTV: ... :2314:0:592
ABC TV Adelaide: ... :512:650:593

As described above, the third-last value is the video pid, and the second-last value is the audio pid. In this output they're in decimal, while in the output of dvbscan -c they're in hexadecimal; but they correspond.

To work around the lack of audio pid in ABC HDTV, convert the value of the AC3 pid (0x90b) to decimal (2315) and edit the channels.conf file:

ABC HDTV: ... :2314:2315:592