1 /* @begin atscap.txt */
3 /*****************************************************************************
5 * atscap.c (c) Copyright 2004-2006 by inkling@nop.org
6 * ATSC Transport Stream Capture Application Program
8 * Watch your Digital TV shows WHEN, WHERE and HOW you want to watch them.
10 * atscap is free software; you may only redistribute it and/or modify
11 * it under the terms of the GNU General Public License Version 2, as
12 * published by the Free Software Foundation.
14 * atscap source code is distributed to you in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY OR SUPPORT; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please see the
17 * GNU General Public License Version 2 for more details.
19 * You should have received a copy of the GNU General Public License Version 2
20 * along with this program; if not, write me or the Free Software Foundation,
21 * Inc., at 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23 *****************************************************************************/
31 Title, Program Copyright and "No-Warranty" Disclaimer
34 Fair Use Intent Disclaimer
42 Obsolete V4L API is now unsupported
43 Initial setup and multi-card invocation
44 Setting up for user mode operation, instead of root
45 Short list of useful keys, see -h for more.
48 TCP wrapper configuration
49 Mozilla/Firefox configuration
50 Media player bash script
53 Various notes about my setup
55 GNU Screen support options
56 Obsolete kernel/driver alerts
57 Supported device drivers for various cards
58 Unsupported obsolete device drivers for various cards
59 Porting to other operating systems
60 Test system hardware configuration
61 Related Works In Progress
62 Some sources of possible Radio Frequency Interference
63 Known Bugs in DVB API drivers
68 Console user interface definitions of indicators and colors
73 Key Definitions (TODO, see -h for list or [?] key)
76 Availability in your area and definitions of indicators and colors
79 User controls for the console program guide
81 Program Guide part III
82 Notes about filenames, Master Guides and Virtual Channels
85 The format of the lines that the configuration parser recognizes
90 ATSC compliance checklist for fallback operations
92 List of areas and stations where it is known to work
104 /* WHAT THE AUTHOR WANTS ***************************************************
105 * This program is free software, but I do want something in return for it.
106 * I want this program to work with as many stations as possible. Please
107 * consider running the get-samples.sh script, if not during the initial
108 * setup, then at least once some time after you have been using it.
109 * If I have samples of actual streams, any quirks should get worked out.
110 ***************************************************************************/
114 /* DESIGN GOALS ***************************************************************
116 * 1) Small Run one card on 64M RAM, from 32M USB flash volume
117 * 2) Efficient Capture + playback on 1600MHz CPU, cap on 350MHz CPU
118 * 3) Robust Survive console loss from X or ssh and error recovery
120 * These goals are met by the following careful considerations:
121 * 1.a) Keep dependencies to a minimum. No mySQL or Java bloat.
123 * 2.a) Optimized internal functions and fewest external functions.
124 * 2.b) CPU usage is about 3% during capture for one card on AMD-2000XP
126 * 3.a) MPEG-only fallback for when the stations lose ATSC PSIP.
127 * 3.b) GNU Screen with -W option to have a reconnectable session.
128 * 3.c) HD3000 Bullet-Proof driver patch for DVB drivers, see:
129 * http://www.nop.org/inkling/dtv/test/
131 * These design goals allow you to use some old networked machines for
132 * captures and use nfs to serve the files for playback over the network.
133 * You will need a minimum of 20 megabits/second of spare network bandwidth.
134 * You may need newer UDMA hard drives, if older machines can support them.
136 ******************************************************************************/
138 /* COPYRIGHT FAIR USE INTENT DISCLAIMER ***************************************
140 * IN LIGHT OF RECENT COURT DECISIONS THAT FOCUS ON INTENT, THE FOLLOWING *
141 * IS REQUIRED TO STATE UNEQUIVOCALLY WHAT THE INTENT OF THIS PROGRAM IS: *
143 * THIS PROGRAM IS SOLELY FOR YOU TO EXERCISE YOUR FAIR USE RIGHTS. IT IS *
144 * NOT MEANT, NOR SHOULD IT BE USED BY YOU, TO ENGAGE IN ANY INFRINGEMENT *
145 * OF ANY OF THE COPYRIGHTS OF ANY COMPANIES, CORPORATIONS OR INDIVIDUALS. *
147 * YOU MAY NOW PROCEED TO EXERCISE YOUR FAIR USE RIGHTS TO TIME-SHIFT *
148 * AS AFFIRMED IN THE FOLLOWING UNITED STATES SUPREME COURT DECISION: *
150 * SONY CORP. V. UNIVERSAL CITY STUDIOS *
151 * 464 U.S. 417, 104 S. Ct 774, 78L. Ed 2d 574 (1984) *
153 *****************************************************************************/
156 /* VARIOUS THANKS AND CREDITS: ***********************************************
157 Ray, for hosting this open-source party at nop.org.
158 Peter, for examples of working DVB-API code plus Cali atscut -kmgt samples.
159 Gene, for cable test plus Ohio and Mich atscut -kmgt samples.
160 Tupari, for test with DViCo USB DTV device plus NY atscut -kmgt sample.
161 Jedrek, for test with DVB-API supported DViCo Fusion5 DTV device.
162 DVB-API developers, for pass through setting this program requires.
163 Jack, for help with using HD2000/HD3000 cards and the open source drivers.
164 ******************************************************************************/
166 /*****************************************************************************
167 * pchdtvr (old name) was used with permission of Jack Kelliher@pcHDTV.com. *
168 * atscap (new name) reflects generic ability to work with any DVB-API card. *
169 *****************************************************************************/
171 /* FEATURES *******************************************************************
172 (* indicates new for this release)
174 * Can set timers for any arbitrary dates in the future
175 * TCP http server: Remote Control, File Retrieval and Playback
176 * Console and html Event Program Guides w/multi-card support
177 * html controls: timers, searches, spam, info cap, play, zap/del
178 * UDP Multi-Cast for watching live TV from other PCs on network
179 * Generates sequence and frame .tsx files for xtscut cutting
180 * Generic Terrestrial DVB API; it should work with other cards
181 * pcHDTV old V4L and V4L2 drivers are now obsoleted. Use DVB API!
183 . Comprehensive PSIP and MPEG Stream Descriptor Information
184 . Secondary audio is console selectable for SAP/mono/multi-lang
185 . Search events view, add, delete, and search filter for EPG
186 . Journal Filesystems work well with the mutex code. Try XFS!
187 . HyperThreading and Multiple Processors with new mutex code
188 . Automatic Program Guide loading keeps EPG up-to-date
189 . Automatic Event Search schedules by event name/channel/weekday
190 . Multiple Channel Signal Strength Display with Auto Scan
191 . Console Channel Hotkeys for Favorite Stations
192 . Automatic Setup and Manual Channel Configuration
193 . Automatic Timer or Manual Captures
194 . Multiple Cards Supported with console Movable Timers
195 . Virtual Channel or Full Stream Captures
196 . Capture Error and Packet Category Log
197 . High Throughput, Low Latency and Low CPU Use
198 . Extended Logging for Problem Diagnosis
199 . Support for GNU Screen Virtual Console Manager
200 . Interactive, Detached, Daemon and Wait-for-script Modes
201 . Demonstration Mode for Capture Simulation
203 ******************************************************************************/
205 /* QUICK START PART I ********************************************************/
206 /* 1) ************************************************************************
208 * Get the latest v4l-dvb mercurial CVS at LinuxTV.org to have latest fixes.
209 * Compile and install the drivers, then rmmod any old drivers loaded.
211 * Compile and install atscap with:
215 * Use the following to see the list of available compile versions:
219 * Edit the Makefile if you need an optional compile not listed.
222 * Dependencies (besides the usual glibc suspects, you should have already):
224 * libpthread POSIX threads library (tested here: linuxthreads-0.10)
225 * NPTL is also known to work.
227 * librt Accurate timers
230 * The following directories will be created for you automatically:
232 * /dtv Transport capture save directory
233 * /dtv/pg Event Program Guide save directory
234 * /dtv/pg/img Image files for browser interface
236 * Or symlink it, or use atscap -p path option to override /dtv/ default.
238 ****************************************************************************/
240 /* 2a) ***********************************************************************
241 * QUICK START FOR DVB DRIVERS, LINUX KERNEL 2.6.12 AND ABOVE:
243 * ***************** NEWS !!! HD3000 DRIVER LOCKOUT PROBLEM SOLVED ***********
244 * Get the patch for v4l-dvb to prevent driver lock-out for HD-3000:
245 * http://www.nop.org/inkling/dtv/test/dvb-ink.diff.gz
247 * Or a stripped down v4l-dvb only for HD-3000 and ATSC:
248 * http://www.nop.org/inkling/dtv/test/dvb-HD3000-only.tar.gz
250 * Problem was in i2c communication interface desync that
251 * required detecting the error and resetting the Oren chip.
252 * The i2c was also fixed to use faster hardware transfers.
254 *****************************************************************************
256 * Compile kernel with the correct drivers for your card(s), then boot it.
257 * Login as root. This program requires root to use SCHED_FIFO priority.
258 * You can try it as user, but you may experience dropouts in the capture.
260 * To load the HD-2000 driver:
263 * To load the HD-3000 driver:
266 * NOTE: the order you load the drivers determines dvb0-n assignment,
267 * so if you want 1 HD-2000 after 3 HD-3000s, load dvb-bt8xx last.
269 * -iX is device number, so -i0 is dvb0 ... -i3 is dvb3, multi-card support.
271 * atscap -i0 -S to scan for stations on adapter0
273 * atscap -i3 -S to scan for stations on adapter3
275 * Start from xterm (not detachable, closing window terminates):
276 * xterm -fg white -bg black -fn 10x20 -e atscap -i0
278 * Start from xterm (detachable, closing window or stopping X detaches):
279 * xterm -fg white -bg black -fn 10x20 -e atscap -i0 -W
281 * Start from rc.local as detached screen session (default paths /dtv /etc):
282 * /usr/local/bin/atscap -i0 -D
284 * Reconnect to xterm (if started with -W or -D):
285 * xterm -fg white -bg black -fn 10x20 -e atscap -i0 -R
287 ****************************************************************************/
289 /* 2b) **********************************************************************
290 * OBSOLETE: SKIP TO SECTION 3 IF YOU ARE USING DVB
292 * NOT SO DAMN QUICK START FOR V4L2 ATSC 1.6 OR 2.0 pcHDTV DRIVERS
293 * RUNNING ON LINUX KERNELS PRIOR TO 2.6.12 AND 2.4.X KERNELS:
295 * This is mostly for HD3000 users, but driver 1.6 notes apply to HD2000.
297 * Compile it with the above given instructions and put it in the path.
298 * Login as root. This program requires root to use SCHED_FIFO priority.
299 * You may also run it as a user since 2.4.x SCHED_FIFO seems broken.
301 * lsmod to see if cx88-dvb loaded. rmmod cx88-dvb if loaded.
302 * If the unload fails for any reason, you have to rebuild kernel
303 * without DVB support, then modprobe cx88-atsc after reboot and
304 * rebuild of 2.0 cx88-atsc driver, if necessary.
306 * pcHDTV 2.0 driver provides some hacks for modules.conf.
307 * If you modprobe cx8800 then cx88-atsc, you don't need them.
309 * Figure out what driver registered for cx88-atsc device name.
310 * # dmesg | grep -i registered should show [atsc] line
312 * NOTE: cx88-atsc has big delay for microcode load, so generally
313 * speaking, if you notice this delay, it means microcode loaded OK.
314 * The load time is multipled with multiple cards so be patient.
316 * Symlink registered device(s) to /dev/dtv0 (or /dev/dtv[0,1,2,3] for
317 * multicard) then use this to start station/channel scan for /dev/dtv0
320 * For driver 1.4 thru 1.6: video32 . . . 35 is dtv0 . . . 3
322 * # # NTSC is video0-3, ATSC is video32-35
323 * # ln -s /dev/video32 /dev/dtv0
324 * # ln -s /dev/video33 /dev/dtv1
325 * # ln -s /dev/video34 /dev/dtv2
326 * # ln -s /dev/video35 /dev/dtv3
328 * For single card, driver 2.0 will load NTSC and ATSC. NTSC will
329 * be video0 and ATSC will be video1, so you would use:
331 * # ln -s /dev/video1 /dev/dtv0
332 * # # or alternately for udev
333 * # ln -s /dev/v4l/video1 /dev/dtv0
335 * Multiple HD3000 will put devices sequentially after NTSC video#s
336 * # # Two card HD3000, video0 and video1 for NTSC
337 * # ln -s /dev/video2 /dev/dtv0
338 * # ln -s /dev/video3 /dev/dtv1
341 * # for driver 2.0 on kernel 2.6.12
342 * # this method works for me w/o pcHDTV hacks to modules.conf
343 * # modprobe cx8800 # loads tuner and analog section first
344 * # modprobe cx88-atsc # loads ATSC
346 * NOTE: accessing ATSC functions from the NTSC video# will not work.
348 ************************* END OF OBSOLETE V4L NSDQS *************************/
350 /* 3) THE REST OF QUICKSTART *************************************************
351 * THIS APPLIES TO DVB OR V4L API:
353 * Starting atscap without any options is for single card users.
354 * If you have more than one dvb/dtv you need -iX (X=dev#) option.
356 * Start up atscap in channel/station scan mode for first card:
358 * # atscap -S -i0 # -i0 is dvb(dtv)0, -S is station scan
360 * Edit /etc/atscap/atscap.0.conf.new:
361 * Replace the "Nxx" fields with "ABC", "CBS", "NBC",
362 * et cetera, to make html program guide look correct.
364 * # cp /etc/atscap/atscap.0.conf.new /etc/atscap/atscap.0.conf
366 * After the initial scan is done, you might want to do it again with
367 * a different antenna position to see if you get more channels, or
368 * better yet, find out the channels for the stations in your area
369 * and manually add any missing ones to the .conf file to scan them later.
371 * Start atscap with options to force certain things:
372 * # atscap -i0 # force device 0
373 * # atscap -i1 # force device 1
374 * # atscap -12 # force device 2
376 ************ USER MODE (skip to Quick Keys if running as root) **************
378 * If you want to run atscap as a user and not as root, I have
379 * heard, and have seen it myself, that it does indeed work OK as user.
380 * I wouldn't recommend it for simultaneous capture and playback.
382 * There are a bunch of permission hoops you'll have to jump through:
387 * Create atscap user (any name will do):
390 * Add user to dvb group:
391 * usermod -G dvb atscap
393 * Change dvb devices to be owned by group dvb:
394 * # OLD STYLE DEVICE FORMAT
395 * chown root:dvb /dev/dvb/adapter0/demux0
396 * chown root:dvb /dev/dvb/adapter0/dvr0
397 * chown root:dvb /dev/dvb/adapter0/frontend0
398 * chown root:dvb /dev/dvb/adapter0/net0
399 * # if you have more than one card, do adapter1 2 3 the same
401 * # NEW STYLE DEVICE FORMAT
402 * chown root:dvb /dev/dvb*.*
404 * Change dvb device permissions to allow dvb group access:
405 * # OLD STYLE DEVICE FORMAT
406 * chmod 660 /dev/dvb/adapter0/demux0
407 * chmod 660 /dev/dvb/adapter0/dvr0
408 * chmod 660 /dev/dvb/adapter0/frontend0
409 * chmod 660 /dev/dvb/adapter0/net0
410 * # if you have more than one card, do adapter1 2 3 the same
412 * # NEW STYLE DEVICE FORMAT
413 * chmod 660 /dev/dvb*.*
415 * Change /etc/atscap/ permissions to allow dvb group access:
416 * chown root:dvb /etc/atscap
417 * chown root:dvb /etc/atscap/ *
418 * chmod 775 /etc/atscap/
420 * Change /dtv/ permissions to allow dvb group access:
421 * chown root:dvb /dtv
422 * chown root:dvb /dtv/pg
423 * chown root:dvb /dtv/pg/ *
424 * chown root:dvb /dtv/pg/img
427 * chmod 660 /dtv/pg/ *
428 * chmod 775 /dtv/pg/img
430 * COPY of info in GNU screen support section:
432 * Add atscap user to tty control group:
433 * usermod -G tty atscap
435 * Change tty device permissions to allow group access:
436 * chmod 660 /dev/pts/ *
438 ********* See what I mean about a LOT of hoops? I run it as root. *********
444 * 1 to 9 are hotkeys for first 9 channels in list, A-Z for 10-35.
446 * After one minute of no console activity, it will automatically
447 * start looking for the Event Program Guide for each channel -S found.
448 * If no EPG is found after 3 minutes, hit [z] or [BKSP] to stop the EPG
449 * scan and hotkey the station and use [a] key to toggle EPG scan off.
451 * [ENTER] starts manual cap of selected VC on channel [v]+[0-x]+[ENTER]
453 * [ENTER] starts full ATSC capture if VC selection reset. [v]+[r]
455 * [BKSP] stops manaul cap, [z] stops + deletes current user/timer cap
457 * [TAB] switch between timer and channel list. Program guide will not
458 * be loaded during channel list scan, but timers will activate.
460 * [l] to load guide, [p] for program guide, [p]+[t] adds timer from EPG
462 * [v] key for VC selection screen to pick single channel or full capture
464 * [d] key toggles descriptor detail in VC selection screen.
466 * [?] gives a list of the keys that are useful for the current display
468 *****************************************************************************/
470 /* 4) CONFIGURING THE HTTP SERVER (optional) **********************************
472 atscap now has a tiny, fast multi-threaded web server included.
473 With mozilla configured properly, it's truly point and click viewing.
476 This is a possibly incorrect sub-set implementation of RFC2616 and RFC2068.
477 It has no security. Bind to your local subnet only. Do not bind to 0.0.0.0
478 or any internet connected interface. If you don't know what I am talking
479 about, don't use the -w option until you understand how to lock it down.
481 This will keep the hackers and leechers off your television and avoid
482 these two worst case scenarios:
484 1) Something I forgot compromises the capture directory jail.
485 2) All of your bandwidth disappears as your captures get leeched.
488 Sometimes the web page goes blank. Refresh will redraw it.
490 This happens most often with keep-alive enabled. It's caused
491 by running out of web server threads. Click slower or increase
492 WWW_THREADS default, or override it manually with -w option.
493 Keep-alive is set to 1s per connection.
495 Pipelining is not supported. It needs a queue to do it right.
498 CONFIGURING SECURITY VIA TCP WRAPPER EMULATION
500 The -w option will read the /etc/hosts.allow file and look for
501 atscap: entries with ip addresss or names to partial match.
502 Even though atscap isn't really amenable to xinetd, the TCP
503 wrapper interface provides a reasonably standard way to secure it.
505 Deny is the default. You should consider your security needs
506 and at least create /etc/hosts.deny file to protect your
507 other services, See "man 5 hosts_access" for more information:
509 Example /etc/hosts.deny:
513 Example /etc/hosts.allow:
515 # hosts.allow tcp wrapper security
516 # allow connections from .nop.org
518 # allow connections from local subnet
521 The parser is very primitive. It only looks for atscap: lines.
522 You can not use the keyword "ALL" for atscap access control.
523 This is intentional to discourage running it wide open.
525 The address you bind it to is always allowed access.
530 1) You need to make a script to call xine from mozilla:
533 --- xw.sh --- cut here ---
535 # Changes mozilla supplied mpeg:// url to:
536 # a) http:// for xine/mplayer http playback over httpd
538 # b) directory plus basename for playback over mounted filesystem
540 # mplayer can use httpd Range: to seek within file. no slider in xine http://
542 # xine player options can be set to:
543 # -V xvmc overrides to xvmc mode; -p starts playback;
544 # --enqueue adds to mrl list and starts playing if not loaded yet
545 PLAYER=/usr/local/bin/xine
546 #PLAYOPT=-p -V xvmc --enqueue
549 # mplayer options set to xvmc mode playback
550 #PLAYER=/usr/local/bin/mplayer
551 #PLAYOPT=-vo xvmc -vc ffmpeg12mc
553 # replace mpeg with http
557 # change this to local mount used for your remote capture directory
559 # changes URI to basename for playback from mounted filesystem
560 FILE=$DIR/`basename $URI`
562 # uncomment this for playback over http:// address/filename.ts
563 #$PLAYER $PLAYOPT $URL
565 # uncomment this for playback over local mount directory/filename.ts
566 $PLAYER $PLAYOPT $FILE
567 --- xw.sh --- cut here ---
570 2) You need to tell mozilla how to call the xine script.
572 This is what registers the mpeg:// protocol into mozilla.
573 Anything with mpeg:// in front of it will be fed to xw.sh
575 In the mozilla url entry box, enter this:
579 Right mouse to bring up menu then:
581 network.protocol-handler.app.mpeg
582 /usr/local/bin/mpeg.sh
583 (or whatever you named the above script)
585 Right mouse to bring up menu then:
587 network.protocol-handler.external.mpeg
590 Right mouse to bring up menu then:
592 network.protocol-handler.warn-external.mpeg
593 false (or true to warn you before playing)
596 3) Check mozilla Preferences Advanced HTTP Networking, and if you
597 have Keep-Alive or Pipelining enabled, disable them.
598 Using HTTP 1.0 or HTTP 1.1 should work equally well.
602 SETTING UP ATSCAP SOURCE CODE
604 Edit top of atscap.c to set the number of dvb cards in the machine.
605 This will allow you to navigate between the atscap servers.
606 Don't forget to run make again, after you save the changes.
608 Single card users want to change this:
611 The server will start automatically at port 80, unless you change:
615 MULTI-CARD USERS: If you specify multiple DTV devices with
616 "-i devnum" option but no -w port value, the server will start at
617 port 80 + devnum (80 to 83). This may conflict with some other
618 software, and you may wish to change the default port base value.
623 It's configured by default to serve files from the /dtv directory.
624 atscap -p option will change the root directory. The only files that
625 are listed in the index.html files are *.ts and *.html files
626 because these are the only ones interesting to the web user.
628 You may wget other files but you need to know the pathname.
629 It is jailed to the /dtv, or -p directory, but is not fully tested.
631 xine doesn't send "Range:" directive so no random access http://.
632 However you can still get the slider, if you play it from a mount
633 point and use the script above to tell xine where to find it.
635 mplayer is reported to send Range: directives, so forward and
636 backward navigation should be possible.
638 If you want xine embedded in mozilla, see xine-mozilla plug-in.
639 I tried it. Didn't like it. Too buggy and no control.
641 If you don't use xine, it should be obvious what to change.
643 If you don't use mozilla/firefox, good luck with it.
645 The server has only been tested up to about 18 simultaneous
646 wget sessions but it tested OK. Playback up to 5 pre-recorded SD
647 streams during capture worked well. My machine isn't fast enough
648 to play HD and SD at the time, but maybe someday it will be.
654 atscap -w ADDR:MASK:PORT:THREADS
656 ADDRESS is name or dotted notation. It should be less than 224.0.0.0.
657 The address is required. If you want to access it remotely,
658 thought a NAT, you should use a name here, not an IP address, and
659 make /etc/hosts entry on server for name of the local interface,
660 then make /etc/hosts entry on client pointing to the NAT address.
662 MASK can be dotted or number of high bits for netmask, 0 to 32.
663 The mask is optional and defaults to 0.0.0.0.
665 PORT is optional and defaults to 80+dvb device number.
666 Those running from userland should use a port > 1024.
667 Ports lower than 1024 need root. This may be decided
668 automatically in a future version, where user gets port 1080.
673 Bind to 1.2.3.2 with netmask of 0.0.0.0 on port 80.
675 atscap -w 1.2.3.2:31:1080:5
676 Bind to 1.2.3.2 with netmask of 255.255.255.254 on port 1080.
677 Only 1.2.3.2 and 1.2.3.3 will be able to use the server.
678 Use 5 threads instead of the default of 3.
680 atscap -w 1.2.3.2:28:8080:10
681 Bind to 1.2.3.2 with netmask of 255.255.255.254 on port 8080.
682 Only 1.2.3.1 to 1.2.3.14 will be able to use the server.
683 Use 10 threads instead of the default of 3.
685 atscap -i2 -w 0.0.0.0:0
686 Bind card2 to INADDR_ANY, port 82. This is not recommended
687 without a firewall, for obvious security reasons. The
688 main one being the http code isn't well tested yet.
689 A message indicating it's w-w-w-ide open will be logged.
691 It is recommended that you DO NOT bind to a local interface that
692 is visible from the internet, for obvious security reasons.
694 While you can bind it to the loopback, and the http server will
695 work for that machine, it will not be visible to your other machines.
696 If all you have is one machine, binding to loopback should work well.
698 There are some known issues with trying to access via tinyproxy.
699 The images don't load is the main symptom. These bugs will be fixed.
703 HTML PROGRAM GUIDE IMAGES
705 The following imgs are user defined for the html program guide.
706 Note the 16:9 aspect ratio:
708 [SID].png 320x180 image for network from cfg SID
709 FOX.png UPN.png NBC.png, et cetera
711 [event].png 160x90 truncated 2-word EventName.png
712 Same name you see with add search href.
714 [ch].png 50x50 signal strength chart.
716 The atscap-img archive has the stock images for html EPG control.
717 It should have been copied to your /dtv/pg/img during make install.
719 The network logos are stored as /dtv/pg/img/SID.png, where SID is
720 the 3 letter network ID. Belongs in /usr/local/share/atscap/img/,
721 but it looks for the files in /dtv/pg/img for now.
723 Use xine 't' key to cap images and gimp your own icons and images.
724 Cubic calculation method works best for scaling down images.
725 The html code sets the images to be rendered with some hspace.
727 User needs to edit the config so the C line SID fields make sense,
728 e.g. ABC, CBS, NBC etc, or even the NTSC station#'s if you prefer.
731 ******************************************************************************/
733 /******************************************************************************
734 * SEE BELOW FOR MORE USAGE [ usehelp and keyhelp strings ] or start with -h
735 * Updating two places got old real fast, same for updating README | man page.
736 *****************************************************************************/
740 /* NOTES ON WHY THE V4L DRIVERS ARE OBSOLETED ******************************
744 AS A FINAL PUNCH IN THE FACE TO OBSOLESCENCE, I TESTED IT WITH MY OLD
745 MANDRAKE 8.1 AND KERNEL 2.4.26 WITH DRIVER 1.6 SETUP. IT FAILED. LOCK-UP!
746 I DID FIX IT TO RUN, BUT SCHED_FIFO IS BROKEN THERE. RENICING MAY HELP.
747 CHECK THOSE FUNCTION RETURNS OR BE FOOLED IT'S OK FOR A WHILE, LIKE ME.
748 THERE MAY BE A WAY TO MAKE SCHED_FIFO WORK ON 2.4.X BUT I DON'T KNOW IT.
750 UPDATE modutils FOR KERNEL 2.4.X TO LATEST TO AVOID DEPENDENCY PROBLEMS,
751 IF THESE SHOW UP AS SYMBOL ERRORS IN VIDEO_BUF WHEN LOADING CX8800.
755 V4L1 IS SLATED FOR SUPPORT DISCONTINUATION AS OF JULY 2006, FROM THE
756 FRONT PAGE OF LINUXTV.ORG. YOU NEED TO BE ON THE DVB DRIVERS BY THEN,
757 OR KNOW A HELL OF A LOT ABOUT KEEPING THE OLD DRIVERS RUNNING YOURSELF.
759 V4L2 DRIVER SUPPORT IS HODGE-PODGE AND LUCKY-IF-IT-WORKS SCENARIO, BECAUSE
760 IT ONLY EXISTED FOR A SHORT TIME BEFORE MOVING TO DVB DRIVER MODEL.
761 READ THIS AS: STAY AWAY FROM V4L2 ATSC DRIVER 2.0 AND KERNEL 2.6.12!
763 It's difficult for me to test the V4L drivers. The following is why:
765 As I went back to test 1.0-rc-11 on 2.4.26 with 1.6 drivers and
766 2.6.7 with 2.0 drivers, I re-discovered some of the old bad issues that
767 made me want to move to the DVB API in the first place:
770 1) HD2000 always worked fine. HD3000 required loading driver after X
771 because of some /dev/nvidia0 incompatibility that did not get resolved.
772 HD3000 without X looked like it was running atscap/pchdtvr correctly, but
773 it was not tested beyond a capture or two for each card.
775 2) When xine inevitably crashed Xv, going to all blue colorkey only,
776 I had to wait until captures were completed before restarting X. This
777 is some odd driver bug with GEF2 and GEF4 cards. GEF6 6600GT does not
778 seem to have any colorkey or video overlay brightness/contrast at all.
780 3) Unloading the HD3000 drivers then nvidia, then loading nvidia,
781 starting X and reloading the HD3000 drivers invariably crashed it.
782 I'm talking kernel oops and won't shutdown, needing reset button.
783 Every few days with the old drivers, if xine/Xv colorkey blues, I would
784 be rebooting from oops crash. The DVB drivers get along better than that,
785 but up until now they have not been as reliable as the HD-2000 drivers.
787 4) SCHED_FIFO is apparently broken on 2.4.26 in the kernel or glibc.
788 This means the capture process is at the mercy of other processes.
789 Renicing may help, but without SCHED_FIFO you may lose packets.
790 Will run a test on 2.4.32 eventually.
792 DVB DRIVERS TO THE RESCUE FOR CAPTURE DURING PLAYBACK
794 Drawback: Playback is not as smooth under 2.6.16 as under 2.4.32.
795 Solution: Separate capture system for 2.6.16 and player on 2.4.32.
797 The DVB drivers have no problems reloading while X is running.
798 X and nVidia drivers also have no problems reloading with DVB drivers.
800 xine/Xv still goes all blue sometimes but at least now I can restart
801 X with the DVB drivers, without the same problems the V4L drivers had.
802 Oddly enough, putting Load "v4l" in X config file Modules section seems
803 to have helped with reducing the number of times xine or Xv lose colorkey.
805 *****************************************************************************/
808 /* VARIOUS NOTES ABOUT MY SETUP
812 GEF4 Ti4800SE still loses the colorkey, GEF2 MX400 too. No big deal
813 to restart X anymore with the player separate from server now or with
814 screen handling virtual tty reconnects for capture + playback on same box.
815 On same box for capture and playback, X init might glitch the cap a bit.
817 xine colorkey issues only affect GEF2 thru GEF4. GEF5+ seem to
818 have no colorkey anymore, except 6800GT is rumored to have colorkey.
819 GEF7 models may also have color keying removed. If you have a newer
820 nVidia card and never see a blue screen, be glad. The drawback is you
821 no longer have brightness/contrast/saturation controls via Xv,
822 unless you count the sub-optimal nvidia-settings which are useless.
824 Unverified: OpenGL controls are the new location for brt/ctr/sat/hue.
826 I have 6600GT now and have not seen a blue-screen since installing it.
827 I do miss the brightness contrast and color saturation controls that
828 my old 4800SE has. Some broadcasts have poorly adjusted values.
834 MY OLD SAMBA CONFIGURATION (maxed out at 48Mbit 100bt and 120Mbit 1G enet):
836 Player Client Capture Server
837 +---------------+ +---------------+
838 | Kernel 2.4.32 | | Kernel 2.6.16 |
839 | AMD XP2000+ +--- 100bt ---+ (3) HD-3000s |
840 | NV 6600GT | | (1) HD-2000 |
841 +---------------+ +---------------+
844 I'm using 2.4.32 for player because kernel 2.6.16 does not play well.
845 Playback CPU usage is 100% with 2.6.x and 60% with 2.4.x, for same file.
846 Perhaps nVidia is not yet spending any money optimizing for kernel 2.6.x,
847 or my 2.6.x setup has problems that I haven't worked around yet.
849 Samba on 100bt tops at 50Mbit/second, just enough for smooth HDTV playback.
852 MY NEW NFS CONFIGURATION: (maxed out at 568Mbit on 1Gbit enet)
854 Player Client Capture Server
855 +---------------+ +---------------+
856 | Kernel 2.4.32 | 1g enet | Kernel 2.6.16 |
857 | AMD XP2000+ +--- r8169 ---+ (3) HD-3000s |
858 | NV 6600GT | nfs | (1) HD-2000 |
859 +---------------+ +---------------+
861 The Gigabit Ethernet driver for r8169 needed some work, but after
862 a few hours of fiddling with it, I got the performance between both
863 machines at 63 megabytes and 71 megabytes per second, so says netperf.
865 From what I have read, the client reading the server at 71MB/sec is
866 very close to current top end intel cards that give 78MB/sec. The
867 actual throughput from wget testing of my tiny http server gives
868 68MB/sec, when copying files small enough to fit in cache of both and
869 using tmpfs directories for soure and destination. This should
870 be considered remarkable performance from a $12 Linkskey LKG-6100.
872 Samba on 100bt tops at 120Mbit/second, pretty lousy in my opinion.
874 I submitted the r8169 patch for 2.4.32 kernel to netdev, but there
875 is a chance it will not be noticed. The netdev list is very busy.
877 To assist others who would like to immediately see results with
878 their 8169 based cards, these two patches are included in the archive:
886 The fastest way is to bypass TCP/IP altogether with ATA Over Ethernet.
887 But you need clustering filesystems and that will reduce the throughput.
888 But why stop there? Go Raid 5 or Raid 10. Folks, this is only TV.
890 Samba was acceptable for 100 Mbit enet, but the poor performance
891 on gigabit enet doesn't seem to be something very easily addressed.
893 I'm using NFS now. NFS is almost twice as fast as samba and you can
894 set read/write size to the larger gigabit ethernet MTU size, or near it.
899 VIA has new ultra-low power 1GHz mobos. A 200G HD uses more power!
900 However the form factor is so small that it only has a single PCI slot.
902 VIA finally has a few AM2 chipset mobos out. Asus M2V looks good
903 for a server up to 4 PCI cards. This is wish-list a and is not tested.
904 No idea what specification the PCI slots have. Needs 5v for HD2k/3k.
906 *****************************************************************************/
909 /* WARNINGS *******************************************************************
913 This code uses SCHED_FIFO. This requires root. If you don't like
914 running programs as root, for whatever reason, don't use this program.
915 sudo, setuid, whatever works for you is fine with me. It will, most
916 likely, not work correctly if you try to run it as a regular user.
918 This code can optionally set the system time. This also needs root.
923 The code will use mlockall if it is available. This will prevent
924 the code itself from being swapped out, but other applications may
925 still be swapped out. Swapping can cause the capture to glitch,
926 because the amount of time before it returns from the swap may
927 exceed the amount of time driver has to read the card.
929 While I have not seen any problems when running without swap,
930 I have lately been testing a small tmpfs RAM volume as a swapper,.
931 and have noticed absolutely no difference from swapoff -a.
932 Look up working set and understand what it means for your system.
937 This program is useless without the time zone and time being correct
938 for the Program Guide timers to start at the correct times.
940 Make sure /etc/localtime is pointing to proper entry in
941 /usr/share/zoneinfo. After fixing /etc/localtime and restarting
942 ntpd time server daemon, or running ntpdate, use hwclock -w to set it.
943 ATSC Timekeeping does not use hwclock -w, but only sets in-memory time.
946 NEW PROGRAM GUIDE FORMAT ALERT
948 THE STRUCTURE HAS CHANGED AND YOU WILL SEGFAULT WITHOUT THIS STEP.
949 To delete all of the old program guides:
953 ****************************************************************************/
956 /* GNU SCREEN SUPPORT *********************************************************
958 This code can use GNU screen. Version tested: 4.00.02 FAU 5-Dec-03.
959 *******************************************************************
961 This is the only solution I can find for handling X restart. On my
962 setup, I have WindowMaker objects set so LMB starts it and MMB will
963 try to reattach to a detached session. One object for each card.
966 xterm -bg black -fg white -fn 10x20 -e atscap -i0 -W
968 xterm -bg black -fg white -fn 10x20 -e atscap -i0 -R
970 There are problems with displaying beyond 80x25 screen size. except
971 132x25 seems to work fine. Looks like term buffer is too small, since
972 there is no display problem at 132x60 from console with kernel "vga=ask"
973 Xterms show same problem as screen. Can get up to about 160x30.
974 Latest output redux re-writes have maybe helped a little bit.
976 Because of this problem, -W is optional to enable screen support.
978 Example usage of screen ( make sure #define PRODUCTION 1 ):
979 atscap -i0 -W makes a screen session named dtv0
980 atscap -i0 -R attaches screen session dtv0 to current console
981 screen -wipe clears old dead sessions from screen -ls
984 If you want to run atscap as a user, you will have to do some
985 things to make it work with screen. The following should do the trick.
988 usermod -G tty atscap
989 chmod 660 /dev/pts/ *
992 *****************************************************************************/
995 /* OBSOLETED KERNEL ALERTS *****************************************************
998 LINUX KERNEL VERSION CAVEATS, READ THIS IF USING KERNEL < 2.6.13 & V4L
1000 UPDATE modutils IF YOU GET VIDEO_BUF_* SYMBOL ERRORS ON MODPROBE CX8800.
1002 This code is now being developed on vanilla Linux kernel 2.6.14,
1003 using the video4linux v4l-dvb 20060115 mercurial cvs and cx88-dvb module.
1005 IT IS RECOMMENDED THAT YOU MOVE TO A NEW KERNEL WITH DVB ASAP.
1007 All V4L kernel support is discontinued because I can not support
1008 orphaned drivers or kernels that no one else will support, either.
1009 All I can say is it worked the last time I tried it on 2.4.26.
1011 This code was being developed on vanilla Linux kernel 2.6.7,
1012 using the 1.6 drivers available from www.pchdtv.com.
1014 This code was being developed on vanilla Linux kernel 2.4.26:
1015 with patches to the following kernel subsystems:
1017 kernel.org patch: fcntl/mm in the kernel tree:
1018 RML O_STREAMING patch from kernel.org. It's actually
1019 generic enough to apply to 2.4.17 and above, I think.
1021 O_STREAMING is a big help for 2.4 series but 2.6 doesn't need it.
1023 If you have multiple TV cards, you must recompile the drivers
1024 and applications for these so the new videodev structures are properly
1025 allocated and addressed by the kernel and the applications.
1027 Always recompile the entire kernel with any kernel driver patches,
1028 unless it's a tidy snapshot like the v4l-dvb snapshot. Even so, you
1029 may have to recompile other programs to use the snapshot includes.
1032 Kernel 2.6.12 V4L has been tested. HD3000 mostly works, but you will
1033 have to use the pcHDTV-extras download from pcHDTV to get the cx88-atsc
1034 module for compiling and installing. You will also have to manually point
1035 /dev/dtv0 to /dev/video0 and so forth. HD2000 does not work and does not
1036 appear to register the devices to udev, either.
1038 HD3000 most common driver issue is all tuning goes 100% and no capture.
1039 This problem has been fixed with my BulletProof HD3000 DVB driver patch.
1040 ******************************************************************************/
1043 /* OBSOLETED V4L2 COMPILATION GCC ALERT **************************************************
1045 If you get errors compiling user applications with pcHDTV driver 1.6:
1048 According to pcHDTV technical support:
1049 Some distros /usr/include/linux/compiler.h is not current for kernel.
1051 Let driver replace the videodev.h files as normal and do the following:
1052 Check /usr/include/linux/compiler.h against current kernel. If it does
1053 not have __user macro defined, you need to make it match current kernel,
1054 else you get errors compiling because of __user macro causing problems.
1056 If the driver itself compiles ok:
1057 If compiler.h doesn't exist or is comments only, copy kernel version.
1059 In the case of existing but primitive /usr/include/linux/compiler.h,
1060 you may be able to copy /usr/src/new-kernel/include/linux/compiler.h
1061 to /usr/include/linux/compiler.h, but you may have add the primitives.
1063 Quick and dirty fix to /usr/include/linux/compiler.h:
1068 As more distros use newer kernels this problem should go away, as they
1069 will update /usr/include/linux/compiler.h to have the __user macro.
1072 driver 2.0 may fix compiler.h for you, but be warned if you have
1074 HD2000 to stay away from driver 2.0 because HD2000 ATSC seems broken.
1076 HD2000 users will have to use driver 1.6 until things stabilize.
1078 HD3000 users of driver 2.0 will have to adjust /dev/dtvX to be correct.
1079 because driver 2.0 uses different numbering scheme, see above.
1080 *****************************************************************************/
1082 /***************************************
1083 THIS ONLY APPLIES TO OBSOLETED V4L2 API:
1085 THIS APPLIES TO KERNEL 2.6.12, V4L2 ATSC DRIVER 2.0 AND HD3000 ONLY:
1086 PROBLEMS EXIST HAVING DVB DRIVERS COMPILED AS MODULES BUT NOT LOADED.
1087 COMPILE THE KERNEL WITHOUT DVB SUPPORT TO USE THE ATSC DRIVER RELIABLY.
1088 THE V4L2 ATSC DRIVER 2.0 DOES NOT WORK WITH KERNEL > 2.6.12. USE DVB API.
1090 THIS APPLIES TO KERNEL <= 2.6.12 WITH V4L2 ATSC 1.5 OR 1.6 DRIVER WITH HD3000:
1091 DRIVERS WILL OCCASSIONALLY STOP SCANNING AND CAPTURING, GIVING EITHER
1092 22%, 55% OR 100%, FOR ALL STATIONS, DEPENDING ON DRIVER/V4L VERSION.
1093 TRYING TO LIMIT SCANS TO 4 PER SECOND LIKE DVB API. MAYBE THAT WILL HELP.
1094 *******************************************************************************
1096 *******************************************
1097 THIS ONLY APPLIES TO OBSOLETED V4L2 DRIVERS:
1098 USE THIS TO LOAD THE DRIVER AND AVOID EDIT OF /etc/modules.conf
1099 modprobe cx8800 # driver 1.6 and 2.0
1100 modprobe cx88-atsc # driver 2.0 only
1102 USE THIS TO UNLOAD THE DRIVER IF SIGNAL/CAPTURE LOCKOUT OCCURS:
1103 rmmod cx88-atsc # driver 2.0 only (must do before cx8800 or segfaults)
1104 rmmod cx8800 # driver 1.6 and 2.0
1105 *******************************************************************************
1107 *********************** END OF OBSOLETED KERNEL ALERTS ************************/
1110 /* DVB API ALERT **************************************************************
1112 SEE HD-3000 BulletProof driver fix to prevent HD-3000 DVB driver lockout:
1113 http://www.nop.org/inkling/dtv/test/
1115 *******************************************************************************
1116 THIS ONLY APPLIES TO CURRENT DVB API AND DRIVERS:
1118 USE THIS TO LOAD & UNLOAD HD3000 DVB MODULES IF SIGNAL/CAP LOCK-OUT OCCURS:
1119 LOCK-OUT INDICATES DRIVER ACTS NORMAL BUT NOTHING HAPPENS. NOT A LOCK-UP.
1121 rmmod cx88-dvb # only need to reload this one on lock-out
1123 rmmod cx8802 # if it's still locked out on modprobe cx88-dvb
1124 rmmod or51132 # if it's still locked out on modprobe cx88-dvb
1126 modprobe cx88-dvb # loads all the rest
1127 *******************************************************************************/
1132 /******************************************************************************
1135 NEWS: atscap/pchdtvr uses the generic DVB API as of version 1.0-rc-10.
1137 Previous versions used the obsolete and deprecated V4L API and work
1138 with custom pcHDTV ATSC V4L1/2 ATSC drivers for HD2000 and HD3000 ONLY.
1140 Using the DVB API widens the possibility to ANY card DVB API can
1141 support, as long as it provides stream in ATSC Terrestrial format.
1143 There will never be any NTSC support because I can't tolerate NTSC.
1144 There is no cable support, but the DVB API is working now, so that should
1145 make adding cable support a lot easier, if it ever gets done. Cable DTV
1146 uses a wider variety of standards. I don't have any way to test any of it.
1148 Multiple pcHDTV cards may be used concurrently in the same machine.
1149 You may specify which device number with -i# when starting atscap.
1150 The configuration files are in /etc/atscap/atscap.[0-3].conf, 0-3 is dev#.
1154 USE A NEW KERNEL AND THE LATEST DVB API MERCURIAL CVS!
1156 The Linux kernel, versions 2.6.12 and above have built in DVB API
1157 and drivers for the HD2000 and HD3000 cards. This is the driver method
1158 that will be used for pchdtvr 1.0-rc-10 and later, and all atscap releases.
1160 This code was originally developed on the VL4 drivers from Jan 2004.
1161 Versions up to and including 1.0-rc-10 have been fully tested with pcHDTV
1162 ATSC V4L driver 1.6 and driver 2.0 with usually good results, however
1163 due to the remaining problems with X and the lack of future support:
1165 ******************************************************************************
1166 USE OF THE V4L OR V4L2 API IS STRONGLY DISCOURAGED!
1168 Versions after 1.0rc9 are using the generic DVB API. Also, note that
1169 the V4L API code will go away soon, as there is no further need for it.
1171 THE V4L API CODE WILL BE REMOVED FROM THIS PROGRAM VERY SOON!
1172 ******************************************************************************
1175 /* UNSUPPORTED ITEMS **********************************************************
1178 ****** atscap is mostly for Digital Terrestrial (Over The Air) ******
1179 If you want to test cable, you can use the -C option to experiment.
1180 I don't have cable so I can't test it properly, but you can!
1181 A user has reported capturing, once the frequencies were correct,
1182 but with no working guide the weekday timers leave it hard to use.
1183 Maybe, some day, cable companies will follow interoperable standards.
1184 If you know where the guide information is, please tell me!
1188 1.0 final will have conditional compile for users still on old
1189 V4L ATSC drivers. V4L code will be removed from future versions.
1191 ********************************************************************
1192 DO NOT DEPEND ON THE V4L API BEYOND JUNE 2006! IT HAS BEEN SCRAPPED!
1193 ********************************************************************
1196 *****************************************************************************
1197 PORTING TO OTHER OPERATING SYSTEMS OR CPU TYPES:
1199 There are three places where an endian issue will manifest itself.
1200 Program guide binary data, video sequence and frame files will NOT
1201 be compatible between different endian architectures. Since these
1202 are all fairly easily regenerated it is not much of a big deal, but
1203 a routine to swap the values might prove useful in the future.
1205 I tried to stay away from oddball pointer manipulation. The only long
1206 is "long nsec" that may need to be corrected if it gives trouble.
1207 I also intentionally kept the code simple (huh?) to help ease portage.
1209 Undefine USE_DVB, USE_V4L and USE_V4L2 to compile it, then test it
1210 against a full stream capture with the -r replay file option. Once you
1211 see it working on your system, you will then need to flesh out the
1212 get signal lock() function and a few other functions to add the ioctls
1213 that are specific to your ATSC driver.
1215 There are a few needed ioctls but nothing too specific or obtuse. The
1216 TIOCGWINSZ is apparently specific to Linux, so resizing the console may
1217 not work on your system until you find a suitable replacement. The
1218 main logical functions for the ATSC device ioctls are as follows:
1221 1) Frequency Selection
1222 This ioctl sets the channel. Code has V4L, V4L2 and DVB examples.
1225 This ioctl tells when it's OK to read the signal strength.
1226 This is not currently used because the time delta is too large
1227 compared to having signal strength ioctl do same, but the code
1228 is there for it, if you want to enable it.
1231 This ioctl reads the signal strength data from the demodulator.
1232 AOS uses it to reject a capture if the strength is below 45%.
1233 Make sure Receiver Status has valid lock before reading strength.
1234 Receiver Status/Signal Strength are combined in my patched driver.
1236 4) Stream enable/disable.
1237 This ioctl tells the device to start and stop streaming. This is
1238 used in DVB driver to start the ring-buffer fill, but is not used
1239 in the older V4L drivers which try to automate it. Only V4L issue
1240 is requiring sync adjust at start that DVB driver does not need.
1242 5) DVB API has a filter ioctl that is useless for ATSC PSIP. Without
1243 PSIP you have no Event Program Guide and no auto search schedules.
1244 atscap sets the DVB API to pass-through to get around it.
1245 The old V4L drivers had no concept of filtering.
1247 6) read() should get the stream after that, write() is undefined.
1250 The defines to activate 64 bit file size for lib6 may need changing.
1253 Good luck with your porting efforts. Maybe it will be a breeze!
1254 ******************************************************************************/
1256 /********************************* TEST SYSTEM *******************************
1258 Capture doesn't use much CPU, so it can probably run on anything
1259 down to Pentium II 333, but it needs fast disk I/O so ATA33 is needed.
1260 Anything with Ultra DMA 33 or SCSI equivalent should be fast enough
1261 for single captures. Multi-card captures may need faster components.
1263 WARNING: Older machines (3+ years) may have dirty power supplies.
1264 You may need to verify the power supply is giving clean voltages.
1265 If you know what an oscilloscope is, find one and use it.
1270 Both are using 20060115 CVS snapshot + my patches.
1273 2 Channel Master 4228's with RG-6 Quad Shield feedline
1274 1 Walmart RCA "HDTV" amplified rabbit ears and coil
1275 1 Walmart Philips "HDTV" amplified rabbit ears and coil
1277 When propagation is decent, the Channel Masters see more than 8
1278 channels, while the "HDTV" cheapos top out at around 1 or 2, with
1279 a lot of adjustment and ears+coil gyrations just to get those. The
1280 price difference between ears+coil and the Channel Master is $20.00.
1281 However, CM4228 is a meter square, so it is bulky, weighs 11lbs/5kg.
1283 A wire hanging on the wall can get at least one station here.
1285 ******************************************************************************/
1287 /* RELATED WORK IN PROGRESS ***************************************************
1289 Testing a mini-boot 32M root volume with essentials, loaded
1290 from a USB flash drive into a ram drive, via initrd, then mounted.
1291 It lacks almost everything except pam for multi-user, mc, ssh(d)
1292 and atscap to capture to the local hard drive. Minimal but functional.
1293 This could be used for multicasting as a no-moving-parts TV distributor,
1294 or use more memory to load up samba to serve files from the hard drive.
1295 NFS or any other server should work as well as samba for serving files.
1296 ******************************************************************************/
1298 /* MEMORY REQUIREMENTS ********************************************************
1299 The code itself and all tables use about 20M. A small setup for a
1300 low power networked DVR will probably need 128M to handle the caching
1301 to the hard drive, but you *might* be able to get by with 64M, *maybe*.
1302 ******************************************************************************/
1305 /* A FEW WORDS ABOUT RADIO FREQUENCY INTERFERENCE *****************************
1306 * LIGHTNING, GEO-MAGNETIC AND SOLAR STORMS PLUS CAR ALARMS AND CELL PHONES *
1308 They will all wreak havoc with your reception.
1310 My reception and yours are obviously beyond the scope of this code.
1311 Point the antenna, cross the fingers, repeat ad naseum. If you want to
1312 study your environment there are many resources to help. Or you could
1313 hang aluminum foil all around to make a giant dish with antenna at focus.
1315 ******************************************************************************/
1318 /* KNOWN BUGS IN DVB API DRIVERS: *************************************
1322 Some drivers do not have signal strength ioctl, or
1323 it's broken because driver is a work in progress.
1324 SNR fallback can be attempted with the proper defines at top.
1325 Some cards only give a lock indication. There is a define
1326 for this at the top as well.
1328 For the cards that haven't anything but streaming working,
1329 you can comment USE_DVB_AOS to prevent a failed signal stregth
1330 check causing the capture to not start. The capture might be junk,
1331 but the QoS code will attempt to test and log errors in the stream.
1334 HD-3000 DVB API ISSUES
1336 HD-3000 signal scan and capture lock-out after a few hours:
1337 100% signal on all channels and all captures bad.
1339 The old workaround was to reload the driver, cx88-dvb.
1341 For BulletProof HD3000 dvb patch, see:
1342 http://wwww.nop.org/inkling/dtv/test/
1344 Email me for latest stripped down HD-3000 only driver,
1345 if you only have HD-3000(s) and want them to work better.
1347 This has been determined to be a bug with the i2c implementation.
1348 If a signal occurs, it does not finish the i2c transaction and leaves
1349 the kernel i2c-algo-bit confused as to where the next start bit goes.
1350 Bypassing the software i2c-algo-bit with the cx23883 built-in hardware
1351 i2c transfer mode allows better handling by ignoring signals when
1352 waiting for the i2c transfer to finish. Also, i2c-algo-bit handler has
1353 been modified to send the stop bit when a signal aborts the transfer.
1355 From what I can tell, the reason why the HD2000 worked better is
1356 because it uses[?] hardware i2c. This patch is a literal cut and paste
1357 of bttv-i2c hardware function, with some name fixups for the cx2388x.
1358 [?] not sure if it is: bttv HD2000 always had faster scan, but the
1359 microcode load is just as slow as the HD3000 software method.
1361 Aside from fixing the signal scan problem, this patch also makes
1362 the microcode load really fast without the big initial stall. Another
1363 benefit is very low CPU usage during signal scan. The -x option to
1364 see the signal strength during capture works correctly now.
1366 The final benefit from my patch is the fault tolerance and fault
1367 recovery when i2c communication fails. The driver will now reset
1368 the or51132 on the HD-3000 and reload the microcode automatically.
1369 Work is being done to make the HD-2000 driver fault tolerant too.
1370 Check the above test directory for updates to the dvb patch.
1373 FE_TUNE_MODE_ONESHOT:
1375 The DVB driver has a new ioctl to disable the constant software
1376 zigzag tuning that was also causing some problems for the i2c. This
1377 code will use that ioctl if it finds it defined.
1380 ALL OF THIS IS REQUIRED TO MEET DESIGN GOAL #3b.
1383 -------------------------------------------------------------------------------
1385 2) Error counts are not precise and will never be.
1387 This is more of a limitation of the Transport Stream than a bug.
1388 The cards do Reed-Solomon and/or Viterbi error detection and should
1389 set the TEI bit in the packet if the packet is bad. This is usually
1390 enough. ATSC does not send any redundant video or audio packets.
1391 PSIP does send repeat packets, and uses CRC32, so PSIP packet errors
1392 that manage to slip by with TEI not set can be counted then ignored.
1394 MPEG A/V has nothing more than TEI and continuity counter to work
1395 with, so it is very possible you will have MPEG errors, even though
1396 this program did not detect nor log the error in the transport stream.
1398 The MPEG packets that have CRC32, PAT and PMT, are checked, but
1399 since A/V do not have CRC32, it is up to player to determine goodness.
1400 This results in only a rough estimate for the possible error rate.
1402 In this situation it should be considered a limitation, not a bug.
1403 It is likely that some reception interference will be unavoidable,
1404 so don't worry, be happy, the exact error count is not important.
1405 As long as your player can handle the glitches, that is.
1407 -------------------------------------------------------------------------------
1409 3) See CHANGELOG below for version-specific known problems.
1411 ******************************************************************************/
1414 /* DEBUGGING THE CODE ********************************************************
1415 While every attempt is made to locate and remove errors in the
1416 code, you may help make it better by reporting any errors you get.
1417 Add -g to CFLAGS in the Makefile and re-compile, then try it
1418 with gdb atscap, set args and run. If you have a crash that
1419 is reproducible, do what crashes it, then at the gdb prompt:
1421 For a quick summary of where it failed:
1424 For a quick summary of where it failed, with variables:
1427 For a quick summary of the thread status:
1428 gdb> thread apply all bt
1430 You may send the output to me or use it to aid your debugging.
1431 Please send along any patches so that everyone may benefit.
1433 ******************************************************************************/
1435 /* CONSOLE USER INTERFACE NOTES **********************************************
1438 The following is a description of some fields you will see during use.
1443 atscap by inkling@nop.org 21t 965m 130G (32/186G) Tue Apr 20 16:00:42
1446 ^free/total volume space
1448 ^total timer count, minutes and space needed;
1449 this also blinks as TEST MODE NO FILES OPEN
1451 ^title and author; output filename from capture; last program guide status
1456 k Ch Call Net SIG% NONE JUNK SKIP ECHO POOR #FAIR $GOOD !BEST dvb0
1457 2 19 KTXH UPN 75% ###################################
1460 ^ signal strength bar, color is set by percentage
1462 ^ signal strength or other info, [w] key cycles
1464 ^ network abbreviation, use 1-3 letters CBS ABC NBC etc
1466 ^ call sign, use 3-5 letters for the FCC callsign, padded to 5 chars
1468 ^ channel number, 2-69, uses 2 numbers or pad with a space
1470 ^ hotkey, can be 1-9 and A-Z for up to 35 channel hotkeys
1475 T# Status Ch Day Date Time Len Future Date Time SMTWTFS Name
1476 0 TODAY 19 Tue Apr 20 16:30 30 Wed Apr 21 16:30 MTWTF News19
1478 filename to use for this timer ^ TODAY is GREEN
1480 ^ timer runs again @ date/time
1484 ^ timer activates on this date/time, today/near future in color
1486 ^channel, the physical transmission FCC channel assignment
1488 ^ status: TODAY is GREEN, FUTURE is tomorrow or later, STREAM means
1489 this timer is currently capturing, IGNORE means timer is ignored
1490 because it overlaps with manual capture or another timer capture
1492 ^timer number, used for delete, re-queue or move with [d], [r] or [m] keys
1493 [m]ove is only for multi-card users, will make a mess for single card
1497 Time Load (INFO Capture) or
1499 NetCh Time Left SIG% FIFO% QoS% QoSavg% Error# TS PKT# MPEG2#
1500 NBC35 00:00:01 84% 0/ 4 100% 100% 0 12,878 8,000
1502 This line updates once per second, except for NetCh & SIG%.
1504 NetCh is 1-3 char network ID from config file, ch is FCC channel #
1506 Manual capture shows the filename and Time Used in green, top left.
1507 Timer captures show the filename and Time Left in red, top left.
1508 Use [e] key to change time left/elapsed display in timer capture.
1510 SIG% is average signal strength seen at capture start. You
1511 may use -x option to update it during capture, but be aware
1512 that it may cause problems without my patch to dvb driver.
1514 FIFO% is current/maximum FIFO used. It will abort capture at 100%.
1516 QoS% is Quality of Service for past second.
1518 QoSavg% is Quality of Service average since capture start.
1520 Errors are number of errors found since capture start.
1522 TS PKT# is number of transport stream packets seen so far.
1524 MPEG2# is number of MPEG transport packets seen so far.
1527 TRANSPORT STATISTICS FIELDS: [s] key from timer list toggles display
1530 Program: ALL VC: ALL MPEG2 PIDs: ALL
1532 Shows what the current Transport Stream PID capture settings are.
1536 TSER: 0 SYN: 0 TEI: 0 SCR: 0 CC: 0
1537 ATSC: 0 MGT: 0 VCT: 0 EIT: 0 ETT: 0
1539 MPEG: 0 PAT: 1 PMT: 0 VID: 0 AUD: 0
1540 CRC: 0 0 0 VCV: 0 VCA: 0
1544 TSER line has transport stream errors total, with the following breakdown:
1546 SYN are Sync errors: now only seen if kernel or FIFO buffer overflow.
1547 It used to flag trash on very old V4L drivers but sync improved.
1548 You may see it increment during large file copy that starves driver,
1549 and anything else like large file delete may do the same. V4L2 and
1550 DVB drivers provide good sync, so for these it most likely indicates
1551 the driver buffer had an overflow from lack of service.
1553 TEI are Transport Error Indications: this always means bad reception.
1554 This flag is set by the receiving device. This code only checks it,
1555 and ignores the packet if the bit is set, [except full cap?].
1557 SCR are Scrambled: since ATSC is unencrypted, it means bad reception.
1558 This flag should have a valid meaning for cable, if cable works.
1560 For terrestrial broadcast, it can be set in the packets that are
1561 corrupted according to the device, from the TEI flag above. Used
1562 to see SCRs slip past with old driver version and TEI check.
1564 CC are Continunity Counter errors: indicates packets were skipped.
1565 If CC hugely exceeds TEI with SYN at 0, it could be bugs in my code,
1566 or problems with your local station stream multiplexing.
1568 Some CC errors are normal: TEI flag causes packet to be skipped.
1569 Also, CC is only error you might see from video or audio dropout,
1570 since the code can not detect errors in video nor audio beyond CC.
1572 CC is modulo 16, so is limited in reporting how many were skipped.
1575 Some stations give a lot of CC errors but no video problem
1576 is noticed. You can do a full stream capture and look at the
1577 packets with atscut -v17, search for \! and you will probably
1578 find it is the stations PSIP generator that is either broken,
1579 or not multiplexing into the broadcast stream correctly.
1580 You should let your station engineer know about that.
1583 ATSC line has ATSC table count for the tables that did not have errors:
1584 For all of these tables, continually increasing numbers during
1585 capture indicates a problem with your station's PSIP generator.
1586 Norminal observed rate of change is at most once every 3 hours.
1588 ATSC is total number of packets seen for the various tables.
1591 MGT are Master Guide Tables, should increase every three hours.
1592 If this is zero, EIT and ETT will also be zero, no PSIP feed!
1594 VCT are Virtual Channel Tables, should always[?] stay at one.
1595 It will be zero if the station loses PSIP feed, but has working MPEG.
1596 This one should increase only rarely, when the station reconfigures
1597 the available channels, twice daily for some stations like KQED.
1599 EIT are Event Infomation Tables. Only increases if program guide found.
1600 It should increase every 3 hours, but stop increasing after 180s.
1602 ETT are Extended Text Tables. Only increases if program guide found.
1603 KUHT and KRIV are non-compliant, changing ETT version needlessly, so
1604 these two are known to increment ETT beyond nominal observed values.
1605 This makes all EPG loads for those stations take the entire 180 sec.
1606 You may see similar problems with your stations.
1608 RRT are counted for total packet and error counts, but not displayed.
1610 CRC line underneath is how many ATSC payloads computed a bad CRC.
1613 MPEG line has MPEG count for the tables and packets it detected.
1615 MPEG is total number of MPEG packet types seen.
1617 PAT are Program Association Tables, should always stay at one.
1618 If this one is 0, there is no MPEG stream. Doesn't change often.
1620 PMT are Program Map Tables, will vary by number of Virtual Channels.
1621 If this one is 0, there is no MPEG stream. Doesn't change often.
1623 VID are Video packets seen on all Virtual Channels.
1624 Currently no error checking available, so -1 is on the CRC line.
1626 AUD are Audio packets seen on all Virtual Channels.
1627 Currently no error checking available, so -1 is on the CRC line.
1629 VCV are Video packets from the selected Virtual channel.
1631 VCA are Audio packets from the selected Virtual Channel.
1633 CRC line underneath are how many MPEG tables had bad CRC, PAT+PMT only.
1634 Last two items on this line are vid: aud:. These are the counts
1635 of the A/V packets on a single VC, when using single VC capture.
1640 EPG event counts and filter, callsign, indicators, clock and drift:
1642 xxx Events [hamn] KKWW APVMETRUZ Wed May 11 18:36:07 +43
1645 ^ ATSC System Date/Time detected
1646 ^ Multicast is transmitting UDP
1647 ^ RRT Rating categories detected
1648 ^ ETM Extended Text Messages detected
1649 ^ EIT Event Information Table detected
1650 ^ MGT Master Guide Table detected
1651 ^ VCT Virtual Channels Table detected
1652 ^ PMT Program Map Table MPEG2 detected
1653 ^ PAT Program Assoc Table MPEG2 detected
1655 ^ last capture station ID
1657 ^ program guide mask, hide, aged, match, numeric
1659 ^ number of events in program guide, only if program guide found
1661 ***************************************************************************/
1663 /* PROGRAM GUIDE **********************************************************
1665 PROGRAM GUIDE PART I
1669 Cable program guide is not supported, but it may be doable.
1670 There seems to be no standards, at least not ones that are easily found.
1672 Event Program Guides may not be available in your area. This
1673 code follows the spec as closely as I could interpret it. If you don't
1674 see any program guide info, it means that station doesn't have it, or
1675 they are sending mangled useless crap that this code ignores.
1677 In my area, all stations are finally sending some kind of guide.
1678 WB is now the only English station with a decent 5 day guide. All the rest
1679 of my local stations are either primitives, with only 12 hours, or broken.
1680 There are still a few MPEG TS-only stations here, but getting fewer.
1683 GUIDE INDICATORS DURING CAPTURE:
1687 10 Events on FOX [h w] KRIV APVMET Z Tue Dec 12 19:03:09
1694 Stream time is what time the station PSIP generator thinks it is.
1695 It's frequently wrong because most stations don't bother with it. It's
1696 there so you can laugh at how pathetic their timekeeping is. Currently,
1697 it is only used if you specify the Zchannel:offset config option.
1699 Table types are a short indicator of which tables were found.
1700 indicators for what kind of ATSC/MPEG packets have been received, and their
1701 current payload status. The letters have the following meanings:
1703 A is Program Association Table seen, MPEG Transport Stream
1704 P is Program Map Table seen, MPEG Transport Stream
1705 V is Virtual Channel Table seen, ATSC PSIP
1706 M is Master Guide Table seen, ATSC PSIP
1707 E is Event Information Table seen, ATSC PSIP
1708 T is Extended Text Table seen, ATSC PSIP
1709 R is Rating Region Table seen, ATSC PSIP
1710 U is Multicast is currently sending UDP packets (-u and [u] key)
1711 Z is System Time Table seen, ATSC PSIP
1713 Colors for the APVMETRZ payload status display are:
1714 Red Reading payload table packets
1715 White Parsing payload table
1716 Green Payload table is same as previous
1717 Magenta Payload table was ignored like Vogon poetry
1719 If you see A + P there is some MPEG stream selectable, maybe.
1720 If you see V + M you have no guide.
1721 If you see E + T you have a program guide, maybe.
1722 If you see R ratings are available, maybe.
1723 If you see nothing, Vogons are constructing a hyperspace bypass.
1726 Callsign is what was found in the stream, with DT removed.
1727 This doesn't work very well for stations that have multiple callsigns.
1730 h hidden filter active
1731 a aged filter active
1732 m match filter active
1733 w web interface active
1735 Event summary gives event count with applied [ham] filters above.
1738 *******************************************************************************
1739 ******* NO GUIDE FALL-BACK: A COMMON SCENARIO **=******************************
1740 Sometimes a station will fall back to MPEG only, with missing or
1741 partial ATSC PSIP. If all you see is A+P+V+M or A+P, the station is
1742 sending a subset of what is required for program guide. The [v] key
1743 virtual channel should still work, but it may have the identifiers
1744 changed to reflect PAT+PMT as source instead of VCT. This failure mode
1745 also requires the user to fall back to the old capture method of using
1746 weekday timers or entering a volatile timer for later today only.
1748 Also use weekday timers if stations send syndicated shows +2 minutes
1749 late, yet the first-run shows are on-time every time. KHWB does this.
1750 *******************************************************************************
1752 GUIDE COLORS: (these are console, not quite match to html epg colors)
1754 Bright Magenta for aged out, toggle with 'a' key.
1755 Dark Grey for hidden, toggle with 'h' key. (cfg file atscap.spam)
1756 Bright White for timer match, toggle matches-only with 'm' key.
1757 Bright Red for events within 3 hours from now.
1758 Bright Yellow for events 3-6 hours from now.
1759 Bright Cyan for events 6-9 hours from now.
1760 Bright Green for events 9-12 hours from now
1761 Normal White for events beyond 12 hours from now.
1762 Inverse for current event in progress.
1765 AUTOMATIC AND MANUAL GUIDE LOAD:
1767 Top level hold-down on auto-load is :GTO: after callsign in C line.
1768 Change :0: to :1: to scan for a new guide every 3 hours (180 minutes).
1769 If you have multiple cards, you may wish to leave :0: for the stations
1770 that do not come in well enough to update the guide in a timely fashion.
1771 [a] key from channel/timer list toggles/saves between 0 and 180, too.
1773 -S defaults to trying to load the guide from each channel detected.
1774 You must edit :GTO: field of the C line from :1: to to :0: to disable
1775 guide check for stations that you determine do not provide program guide.
1777 You may see the program guide disappear occasionally, for an
1778 indeterminate period of time, until the station gets around to fixing it.
1779 Automatic event scheduling will not work during these station failures,
1780 so you will have to fall back to using T lines in the config file to
1781 handle timers for that station until they fix the program guide. When
1782 the guide comes back, the automatic event scheduling will resume working.
1784 Saved program guide files will try to load whenever channel hotkey
1785 is selected. There is an indicator at bottom left for EPG status.
1787 Some problems have been noticed when hotkeying too fast. Slow down.
1789 ------------------------------------------------------------------------------
1790 PROGRAM GUIDE PART II
1794 If you see "NNN events on XXX" at bottom left, it means
1795 the program guide has some programming events to show you.
1797 You may hit the 'p' key to enter the guide and again to exit.
1799 You may page around the program guide and scroll the descriptions:
1802 [0-9] and [A-Z] will try to take you to 0-35th page.
1803 Nothing happens if that page doesn't exist.
1804 Or worse, it sends you back to page 0.
1806 Scroll diamond is this:
1811 [SPACE] and [b] are forward and back, respectively.
1812 Page Up/Down and arrow keys now work in place of above.
1814 See /dtv/pg/ch.txt for full descriptions over 255 chars.
1816 'a' key toggles display of aged out events
1818 'h' key toggles display of hidden or spam events
1820 'm' key toggles display of events that match timer names
1822 'n' key toggles numeric detail of events and text
1824 't' key to enter a single timer, or optionally a range of timers.
1825 Single event is a single number, number-number for range.
1826 Optional 7 bit weekday flags may be second parameter.
1830 will add events 97 thru 103 inclusive to the timer list
1831 with all the added timers set to recur M-F at that time.
1833 -----------------------------------------------------------------------------
1834 PROGRAM GUIDE PART III
1839 With the addition of program guide and the ability to select a
1840 single Program stream came a need to know at a glance what kind of
1841 file we are dealing with. Simply put, if it has .n in the name, it's
1842 a single Program stream. name.3.ts means it's the first Program
1843 stream, .4 is second program, .5 is third, ad nauseum.
1845 Without a .n in the timer name, it will be a full ATSC capture,
1846 so that, at least, is unchanged from previous versions.
1851 Program Guide will return to timer list when timer status changes,
1852 either by timer start or timer stop. It also returns to timer list when
1853 the guide automatically times out due to a lack of new entries detected.
1854 Changing the config file will stop the guide load and return to timer list.
1859 Program Guide needed a bunch of tables, so you get to see them too.
1860 Use these keys from the main timer list to activate the table display:
1862 The Master Guide table contains a list of Packet IDs (PIDs) to use
1863 for the available PSIP information. These will be the PIDs for
1864 VCT (cable or terrestrial), and EIT/ETT packets for the EPG.
1866 The Virtual Channel table contains a superset of information
1867 from the MPEG Program Association Table and Program Map Tables.
1868 The PIDs listed in the VCT are generally for video and audio.
1871 NOTE: These tables update when ever their version numbers change.
1873 'g' key to see the Master Guide Table.
1874 version number of 0xFF or 0xFE means it's not correct.
1875 [']/[DOWN_ARROW] go down the list
1876 [=]/[UP_ARROW] go up the list
1877 [g] to exit Master Guide Table
1879 'v' key to see the Virtual Channel Table.
1880 This lets you select the parts of the stream you want.
1881 Version number of 0xFF or 0xFE means it's not correct.
1882 Same scroll control as above, if enough entries for scroll.
1883 [1-9] set virtual channel #1 through #9
1884 [a] sets audio channel after selecting one virtual channel
1885 [r] to reset back to full capture
1886 [d] to toggle showing VCT descriptors
1889 'p' key to see Event Information Tables and Extended Text Tables,
1890 as they have been assembled into the local Event Program Guide.
1892 ******************************************************************************/
1894 /* CONFIGURATION **************************************************************
1896 A config file suitable for editing may be created with atscap -S.
1898 REMOTE CONTROL VIA HTTP
1899 The http interface will allow you to do the following:
1900 Add and remove timers, search events, and spam events.
1903 REMOTE CONTROL VIA CONFIGURATION FILE
1904 The configuration file is your remote control to the program,
1905 at least where timers are concerned. If you edit the configuration file
1906 while atscap is running, it will reload the changed file automatically.
1908 You may add/remove timers and channels[*], even currently active.
1909 Timers and channels can remotely be made to appear and disppear at random.
1910 [*] Channel add/remove requires restart for now.
1914 The configuration file is called /etc/atscap/atscap.X.conf.
1915 The X is 0 thru 3 representing the device number, /dev/dvb/adapterX,
1916 or obsolete and deprecated /dev/dtvX for the V4L drivers.
1918 If a line starts with one of these letters: A C V W Z
1919 then it will be parsed for configuration, otherwise it is ignored.
1920 See atscap.0.conf.sample for the format of the configuration lines.
1923 The config file is overwritten during use, so any comments you make
1924 in the file should be kept in a separate copy of the config file.
1928 These are your Physical Transmission Channel numbers according
1929 to the FCC channel number assignments in the UHF or VHF bands. Note
1930 that the frequencies are not linear but spread out across several bands.
1932 This channel will be different from the NTSC channel assignment.
1935 atscap -S scan most likely will not have all of your terrestrial
1936 channels, but if your antenna is tuned well enough, you may get a
1937 decent and usable fraction to start out with. You can add stations
1938 manually later when reception improves, or run -S again, but be
1939 aware that -S may wipe out any existing timers, if you tell it to.
1941 You will need to edit this file to specify 1-5 letter call signs,
1942 if the autodetection of the VCT did not work for some reason, as well
1943 as adding a 1-3 letter station identifier SID, like UPN or WB.
1949 19 is physical transmission channel (index into ptc[] array)
1950 2 is the delta for the station clock. Look at bottom right
1951 during capture to find out what number to use for this. The
1952 ATSC time will be followed by -n or +n, if the time is off.
1955 IT IS RECOMMENDED THAT YOU SET THIS OPTION TO Z0:0 AND USE
1956 ntpd FOR TIMEKEEPING BECAUSE STATION TIMES ARE USUALLY WRONG.
1962 19 is physical transmission channel (index into ptc[] array)
1964 UPN is station/network ID, FOX, UPN, WB, etc
1965 180 is Program Guide Time Out set to reload every 180 minutes
1966 0 is first video virtual channel
1967 0 is first audio on first video virtual channel
1968 (only audio 0 is known to work correctly, for now)
1971 W MANUAL WEEKDAY TIMERS (NO AUTO-GUIDE NEEDED, OLD METHOD):
1973 T19:21:30:030:0101010:Frasier#.3
1974 Captures Frasier-MMDD-HHMMSS.ts from ch19 MWF at 9:30pm for 30m.
1975 Manual timers can be entered from timer list, or you can specify
1976 daybits in Program Guide timer entry.
1977 Can also be set from program guide.
1980 V VOLATILE TIMERS (AUTO EPG, USER EPG or USER MANUAL ENTRY)
1983 Unix time format: Vch:startsecond:capseconds:name
1984 V38:1160096400:03600:Supernatural@.3
1985 Not very easy to read is it? Starting with 1.1-rc6, the user
1986 has a new volatile timer format, that reverts to above:
1988 User time format: Vch:yyyymmdd:hh:mm:minutes:name
1989 V38:20061005:20:00:60:Supernatural@.3
1990 If entered by user, is changed automatically to unix time format.
1993 A AUTOMATIC DYNAMIC EVENT SEARCH PARTIAL NAME MATCH:
1994 Adds a volatile timer based on matching criteria.
1998 Would get all CSINY CSIMiami and CSICrime found on every channel.
1999 You can be more specific with CSINY, or leave the search
2000 overly broad so you can move them all with one fell swoop.
2003 This gets CSI on CBS31 usual broadcast days, but it will not
2004 get any special times or weekend re-runs, so it's possible to
2005 miss a show if you limit the filtering by weekdays.
2007 Program Guide event name is truncated to two significant words,
2008 as is the A entry to keep them consistent. Match is case-insensitive.
2012 will matches the title "The Late Show with David Letterman"
2013 'The' is ignored, and Late Show are next two uncommon words.
2015 ******************************************************************************/
2017 /* SYSTEM TIME AND THE Z CONFIG LINE ****************************************
2019 Use ntpd. I can't stress this enough! If you want consistent
2020 capture times, you have to sync to an external time source.
2022 I use ntpd and so far the times are as accurate as they need to be.
2023 ntpd is very effective for dial up connections, too, because after
2024 a few hours of being connected to the internet, your local clock
2025 time drift has been computed. Subsequent dial-up connections only
2026 have to stay online for 12 minutes at most to get automatic update.
2028 The ATSC stream provides System Time Tables, but if the station
2029 doesn't use ntpd or something similar, what's the point?
2031 You may use Z config option if you like, but you will have to find
2032 a station in your area that provides close-enough time. You will also
2033 have to enable the Guide Time Out for the channel matching Z line channel.
2034 It does not matter if it has no guide, as long as the STT is there.
2036 Be warned that it will change your system time to match the stream
2037 time every time it does one of the auto-guide captures. All kinds of odd
2038 problems can occur if the system time isn't correct, from screensavers
2039 activating early to compiles failing with 'in the future' messages.
2041 The stream vs. system time drift is at bottom right during capture,
2042 so you may see for yourself how well your local stations do timekeeping.
2043 -OSL (Off Scale Low) means the stream time is far behind system time, and
2044 +OSH (Off Scale High) means the stream time is far ahead of system time.
2045 It will drift negative if the STT does not update (bad packets, etc.)
2047 Nominal operation drifts +/- 3 seconds, with correction every 3 hours.
2048 Immediate correction can be done by reloading the config file and
2049 triggering a capture on the station that is configured by the Z line.
2051 ******************************************************************************/
2053 /*************************** DVB DEVICES EXPECTED *****************************
2056 This program expects to find the video devices on /dev/dvb/adapter0
2057 thru /dev/dvb/adapter3. This is the easy generic DVB API method. You
2058 select the device you want with: -i0 for /dev/dvb/adapter0/dvr0.
2059 New udev updates are putting it on dvb0.[ frontend0 dvr0 ], so
2060 there is some code to check for that format first with 1.0rc-11-test.
2062 You can always symlink the old format to the new one, too, if you
2063 have other programs that expect /dev/dvb/ structure.
2065 ****************************** V4L DEPRECATED *********************************
2066 DO NOT USE V4L BECAUSE I CAN NOT SUPPORT IT ANYMORE
2067 *******************************************************************************
2069 This program expects to find the video device on dtv0 thru dtv3.
2070 If you do not have these and they are not created automatically,
2071 you can manually create the major 81 minor 32 video32 device with:
2073 mknod /dev/dtv0 c 81 32
2074 or ln -s /dev/video32 /dev/dtv0 if /dev/video32 is already there.
2076 This gets the right name for the device with the pcHDTV 1.6 drivers.
2078 NOTE: It is different for pcHDTV 2.0 -atsc drivers. It seems to add them
2079 as video#s immediately after the NTSC video numbers, so if you have one
2080 card and you have /dev/video1 and /dev/video2, video2 is probably ATSC.
2081 *******************************************************************************
2085 This doesn't look good with the default xterm so adjust xterm colors.
2087 Example script to start an xterm that should look better:
2090 xterm -geometry 80x25 -bg black -fg white -fn 10x20 $* &
2094 Static PSIP tables and Program Guide require about 8M of storage.
2096 Using FIFO of about 4 * 20Mbits, for 4 seconds of ATSC, about 9M.
2098 Other helper tables bring the total to about 20M.
2100 It's allocated at the start to reduce VM pressure. Memory usage
2101 should not grow/shrink by much. For 2.4.26, O_STREAMING does use cache
2102 but it returns pretty much all of it quickly enough to not be a problem.
2103 Kernels 2.6.7 and above seem to handle returning write cache quickly, too.
2105 malloc instead of calloc could be used to not map the pages until needed.
2109 See ingo-fifo.txt included in the archive.
2111 Based on code contributed by Ingo Oeser that was posted to mailing
2112 list linux-audio-dev@music.columbia.edu, with my fixes and additions.
2114 Thanks Ingo, if you ever get a chance to read this.
2117 XINE (or any other media player for that matter)
2118 xine-hd 0.7 and 0.8 both showed laggy playback during capture, fix is:
2119 right mouse, settings, setup, video tab, change video buffers to 2000.
2121 Sometimes they crash, sometimes they confuse X or Xv.
2122 If you run this in a console, it will keep capturing even if you
2123 have to restart X because Xv died or screwed up something.
2125 Even if Xv (and consoles) crash, you can usually ssh into the box
2126 to kill the rampant 99% X and/or media player and restart X.
2128 X appears to get lost on which video buffer to use, so the 99% usage
2129 top shows is Xv or xine, twiddling screen buffers because they're lost.
2133 Some small stream glitches may occur when X starts. You may see these
2134 as CC or SYN errors in the [s]tatus display. You will likely see buffer
2135 overrun syslog messages, too. Tests indicate it's related to inefficiency
2136 in older kernel agpgart code, not disk i/o.
2138 1.0rc5 and up attempt to reduce the glitching with more precise
2139 parsing of the transport stream. Seems to do better when X restarts.
2140 The glitch is still there, but the packet filtering may remove some
2141 of it, depending on capture mode. Full cap should keep most glitches,
2142 in case you want to analyze them and see how bad they were.
2146 Edit the config file to add channels, callsigns & network IDs.
2147 Make sure channel names are in format given in the config file.
2148 Callsign and station net ID are 1-5 chars and 1-3 chars, respectively.
2149 The config file default name/location is /etc/atscap/atscap.0.conf.
2152 Timers are first-come first-served, so overlaps cause problems.
2153 Whichever timer starts first will be the one that finishes first.
2154 Timers that start in the middle of another timer are ignored, but
2155 will trigger if they overlap beyond the end of the current timer.
2157 Triple timer overlap example and result:
2158 AAAAA captures until end of A
2159 BBBBB captures last two minutes of B
2160 CCCCC captures last two minutes of C
2162 (atscap 1.1-rc 2 needs audit to make sure this is still true.)
2165 If you delete B before A runs out, it captures last four minutes of C.
2166 Multi-card users may have the option of moving the timer to another card.
2168 Testing shows cap start needs about 3 seconds for AOS, depending
2169 on V4L2 or V4L1 used for signal strength. Capture stop may need more
2170 time, maybe more than 10s if files need to be deleted, i.e. zap.
2171 You probably won't see this delay with XFS, if you have that running.
2173 On ext2, file delete needs more than 1 second per gigabyte deleted.
2174 All timers default to ending 5 seconds early for next timer AOS delay.
2175 Timers are automatically adjusted to end more than 5 seconds early if
2176 the size of the file to delete is large enough to require more delay.
2177 Option -f disables the delete time computation for faster filesystems.
2181 You're trying to use with a filesystem or hard drive that is not
2182 capable of writing the data fast enough. Use ext2fs or faster drive.
2185 BIG STALLS (USE XFS IF YOU WANT FAST DELETES)
2186 File truncate/delete time on ext2 can extend upwards of 20 seconds
2187 for 8G file. I need to experiment with other filesystems to find which
2188 balances best with this particular type of workload. I've tried to
2189 make sure there is some indication it's off cycling on file delete.
2191 This *WILL* affect back-to-back timers when overwriting.
2192 The next timer would start late because of the delete time. The
2193 workaround is to end all timers ->secdt seconds early for delete time.
2194 ->secdt is computed based on file size for the speed of my system.
2195 Another workaround is delete after watching so no .$ file delete later.
2196 NOTE: calc secdt may not work. Use # in timer name for -mmdd-hhmm.
2198 There may be a small playback stall, if a timer starts or ends
2199 while you are watching another file. At capture start, this is the
2200 signal scan routine in driver being a CPU pig. Signal scan doesn't
2201 seem to cause buffer overruns but may cause player stalls, so signal
2202 scan is disabled automatically at end of a capture.
2206 Changes to the cfg file mod time will cause channels and timers
2207 to be reloaded; if not capturing, at next show clock, else after capture
2208 NOTE: For now, this will wipe out any manually set timers.
2209 NOTE: If a timer is active at config file load, but you don't want
2210 it to capture, use 'r' to reschedule active timer to its next timeslot.
2211 UPDATE: config file loads during capture to handle timer change.
2215 ext2 was only thing fast enough with O_STREAMING patch. It's now
2216 OK to use Joural Filesystems, according to testing. Using ext3 here.
2217 XFS is supposed to be the fastest. Give it a try and see for yourself.
2221 The error detection is meant to be a general guide, not exact values.
2222 Due to the nature of the ATSC stream, the only packets that can be
2223 easily checked during capture are the ATSC PSIP packets, i.e. STT,
2224 MGT, VCT, EIT, ETT and RRT with their accompanying CRC32 fields, and
2225 the MPEG2 PAT and PMT with their accompanying CRC32 fields. If there
2226 are CRC32s available for audio and video, I have not found them.
2228 It is quite possible you will get errors in audio and video that are
2229 not detected by the stream parsing code and do not show up in the log.
2230 The Transport Stream Continuity Counters wrap at 16. If the packet
2231 loss is 16 or a multiple of 16, it will not know that 16 packets, or
2232 a multiple of 16 packets, have been lost. This program will not attempt
2233 to build and validate each video/audio frame. That's the players job.
2235 *****************************************************************************
2238 Stalls during playback can occur for a number of reasons.
2240 xine-hd 0.8 on 2.4.32 has no problem, same on 2.6.16 has the problem.
2241 Option -N to insert nulls has no effect on what 2.6.16 is doing wrong.
2242 Athlon XP2000 on 2.4.32 uses 60-75% cpu where 2.6.16 is 92-100% and stalls.
2244 xine-hd 0.7 and 0.8 defaults caused laggy playback during capture.
2245 Right mouse, settings, setup, video tab, change video buffers to 2000,
2246 and increase audio buffers to 500 if the audio cuts in and out too.
2248 Hit channel hotkey again to turn off scanning to save CPU. This is
2249 not a source of the problem when using my hardware i2c patch.
2251 Stop any compiles and web page autoloads during playback. This
2252 includes the EPG in atscap, which will refresh every 30m, if you
2253 leave the browser on that page. The [cap] dir doesn't refresh.
2255 If your CPU is under 1.6 GHz, wait until capture done before playback.
2256 720p and 5.1 playback is mostly OK during capture, but some stalls here.
2257 1080i and 5.1 playback during capture does have noticable stalls here.
2258 Lately the stations have reduced the bitrate for the HD shows and the
2259 stalls have gone away, except where there are errors in the stream.
2261 One other thing to notice is some media players do not do a good job
2262 of syncrhonizing at the start of a new stream. The fix is to hit the
2263 left arrow in xine to rewind, or what ever is rewind for your player.
2266 Stream output hold-down until start of video and audio payloads
2267 fixed this problem. No start issues seen since adding the hold-downs.
2269 Playback from live UDP has been observed to stall in ways very
2270 similar to using xine to read directly from the device. This stallling
2271 was one of the original reasons why this program was written. The
2272 problem is caused by xine playing a little bit too fast (dropping frames,
2273 most likely) and having to wait for the device to supply more data.
2274 Playback from file or via TCP shows the problem only near the very end
2275 of a live capture, where the problem manifests as playback ending too soon.
2277 ******************************************************************************/
2280 /* DEBUGGING ******************************************************************
2281 THESE OPTIONS SHOULD ONLY BE USED BY ME
2282 THEY ARE NOT SUPPORTED FOR ANYTHING BUT MY OWN TESTING
2283 *******************************************************************************
2285 It doesn't abort execution if the device can not be opened.
2286 So you can be using it to capture while you debug UI or timer.
2287 /var/log/messages will tell you what is going on, with -l.
2290 -r file.ts will open file.ts in replay mode to show how it parsed
2291 -b bogus mode, AOS always 100%, allows bad streams or antenna adjust
2292 -t start up without timers, but will erase all your current timers
2295 -l enables full debug logging, but it can interfere with captures.
2296 X is the device number, 0-3, specified with -i # option, default is 0.
2297 If device X can be opened, the log label is "atscapX:"
2298 If device X can't be opened, the log label is "atscap-test:"
2300 Most of the logging has been moved to /dtv/atscap?.log, but
2301 there are still a few syslog()'s left in the code. The new dvrlog()
2302 function keeps the same format as syslog() so users can change
2303 the log messages back to syslog if they need to. See USE_SYSLOG.
2305 Default is to log 1 line for each capture, nn is channel:
2306 AOSnn, AOS tries, signal strength and output name.
2308 NOTE: if you use -E option, the full debug logging to RAM drive
2309 should not interfere with captures. It's only a problem if
2310 you're logging to the same volume that you're writing to.
2312 ******************************************************************************/
2315 /* SIGNAL STRENGTH PERCENTAGES ************************************************
2317 Signal percentages give different values depending on Video API:
2319 DVB API reads slow, returns a weighted power value about same as V4L2.
2321 -------------------------------------------------------------------------------
2323 V4L2 is faster and returns a weighted power value over 3 samples.
2324 V4L1 is fastest but returns an inaccurate signal strength value.
2326 The signal stuff *may* be replaced by QOS validation of stream.
2327 Stream error rate may provide better information than get signal strength.
2328 I like the signal meters so they will stay for now.
2330 OBSOLETE NOTE: HD3000 V4L driver 2.0 requires V4L2, so use -2 option,
2331 otherwise you get no signal and think something is broken.
2332 ******************************************************************************/
2336 /* ATSC COMPLIANCE ************************************************************
2338 ***************************************************************
2339 * PARTIAL SUBSET THAT SUPPORTS ONLY WHAT HAS BEEN SEEN SO FAR *
2340 ***************************************************************
2342 This code uses nothing from the ATSC Reference Parser. It is
2343 written by me from the specifications only. Some spec may be missing,
2344 and the rest may be non-functional if your stations use the spec in
2345 ways I did not anticipate or have not fixed from previous User Feedback.
2346 I do NOT see any point in supporting features that are not currently used.
2348 I can't understand dtvstream or ATSC Reference Parser, so I wrote this.
2349 If or when it fails, you have only my code to blame for it not working.
2351 atscap and atscut parse very similarly, but not identical due to
2352 the nature of the processing. Code has cross-pollinated between them,
2353 so generally speaking if the parse works in atscut it should also work
2354 in atscap, and vice versa. "But it ain't necessarily so."
2356 Normal operation will allow non-compliant streams that are missing
2357 reserved bits in certain places. -A option will enforce strict ATSC mode
2358 and log any reserved bit errors that do not agree with published A/65b.
2359 It's optional because lots of stations still get the reserved bits wrong.
2361 ******************************************************************************/
2363 /* FAILURE RECOVERY AND ERROR HANDLING IN ATSC STREAM *************************
2365 As of 1.0 rc8, pchdtvr handles the following kinds of ATSC failures:
2367 ATSC Failure modes handled: Current Status:
2368 Has: MGT VCT EIT ETT
2369 yes yes yes yes OK, EPG, Status Nominal
2370 yes yes yes no OK, EPG, no event description
2371 yes yes no yes OK, no EIT index, ETT ignored
2372 yes yes no no OK, no EPG data received
2375 pchdtvr versions before atscap 1.1 might not ignore EPG when missing data:
2376 This specifically refers to missing VCT source ids required for EPG.
2377 This is considered a bug and the atscap code tries harder to address it.
2379 MPEG Fallback modes (EPG needs VCT for source id to program # xref):
2380 Has: MGT VCT EIT ETT
2381 yes no yes yes OK, no EPG, rest are same:
2382 yes no yes no OK, no EPG, MPEG2TS
2383 yes no no yes OK, no EPG, FALLBACK
2384 yes no no no OK, no EPG, MODE
2386 No MGT means no real ATSC except possibly VCT and STT since they
2387 share the same PID 0x1FFB MGT uses. Not much better than nothing, which
2388 is why the truth table was not drawn for MGT == no. The truth table
2389 will look identical to the above listed VCT-no table, except the
2390 [g] key will not bring up a master guide table listing..
2392 Without VCT to match up the source id via program number, the
2393 EPG will not work. Some test cable streams had an MGT but did
2394 not have any of the MGT-indicated PIDS. One had a TVCT. Some broadcast
2395 stations do not send anything but basic MPEGTS: PAT + PMT + ES PIDS
2396 This is called MPEG2TS fallback mode, indicated in the [v] key display.
2398 NOTE: The built-in table will have to be updated if RRT ever changes.
2400 RRT on PID 0x1FFB: WHO CARES? Using built-in table not received one,
2401 so not parsing it, but does do the payload build and CRC32 test for QoS.
2402 atscut parses it, if you are really hot to see the so-called "V-Chip".
2403 It's the [Rating] text in program guide, if the station provides it.
2404 About the only use I see for it is: detecting MPAA movie ratings, to make
2405 the MOVIE events show up when everything else on station is filtered.
2407 Why anyone bothers to rate movies sanitized by the FCC puzzles me.
2408 Why can't we have ratings for "SD" "HD" "2.0" "5.1" and "REPEAT" ?!?!
2409 Surely that would be more useful to the vast majority of HDTV viewers.
2411 Lastly, if there is no PAT + PMT at all, the parrot has ceased to be.
2413 ******************************************************************************/
2415 /* LIST OF DEVICES KNOWN TO WORK *********************************************
2417 Theoretically it should work with any ATSC card that has a DVB-API driver.
2418 Here is a list devices that it has been reported to work with:
2420 pcHDTV HD-2000 and HD-3000 (signal strength works well in tests here)
2421 DViCo Fusion5 and nano (signal strength is reported to work, 2006-Dec)
2422 AirStar Air2PC HD-5000 (signal strength has reported issues, 2007-Feb)
2424 If your device isn't on this list, let me know and I'll add it.
2426 Once most of the drivers are working at well enough for capture,
2427 the need for this list will go away. Signal strength feature is optional.
2429 Consider using atscap -b option if you get bogus strength values.
2430 Capture QoS% can give a fair estimate of the amount of errors received,
2431 if the signal strength is hopelessly broken, reading 0%, on your driver.
2433 *****************************************************************************/
2436 /* LIST OF AREAS WHERE IT IS KNOWN TO WORK *********************************
2438 San Francisco Bay Area, CA --- including KQED-HD
2447 More samples from other areas are needed. atscap -S will now
2448 ask you if you want to generate some samples to email to me.
2450 If you like this program and use it at all, please consider
2451 either running the getsamples.sh script and send me the output, or
2452 let me know if it works in your area so I can add to this list.
2454 Once enough samples have been collected, the need for this list
2455 will go away because by then most stations should be ATSC compliant.
2457 ***************************************************************************/
2460 /* BUGS ****************************************************************
2461 (not considered critical, see TODO for more specific outstanding issues)
2462 Two lists are not scrollable, help and channel list.
2464 Make xterm/console taller if more than 14 channels.
2465 Don't use [?] key if xterm/console is less than 24 lines.
2467 ******************************************************************************/
2469 /* @end atscap.txt */