| blob | 4e2ec793009736d92f9bcdc8bd00b1a416575fa9 |
1 .TH atscap 1 "2007-Dec-07" "atscap-1.1" "(C) 2004-2007 inkling@users.sourceforge.net"
2 .SH NAME
3 .B atscap
4 \- ATSC Transport Stream Capture Application Program
5 .SH SYNOPSIS
6 .B atscap [\-123ACEDNRSTWadehklmnqtvx]
7 .IP
8 .B [\-F frequencies]
9 .br
10 .B [\-c cfgpath]
11 .br
12 .B [\-p outpath]
13 .br
14 .B [\-o capfile]
15 .br
16 .B [\-z QoS]
17 .br
18 .B [\-i devnum]
19 .br
20 .B [\-r file.ts]
21 .br
22 .B [\-s seconds]
23 .br
24 .B [\-u addr:port]
25 .br
26 .B [\-w addr:mask:port:threads]
28 .SH DESCRIPTION
29 This manual page describes the options for
30 .B atscap,
31 a capture application for digital TV using the North American ATSC
32 specification with the Linux DVB-API for supported ATSC capture devices.
34 .SH OPTIONS WITHOUT PARAMETERS
35 .TP
36 These options enable features to do various things.
38 .TP
39 .B \-d
40 Forks to a process detached from stdio.
41 .IP
42 Control is returned immediately to caller.
43 Use with -s if you don't want script to wait.
44 Use without -s and it enters timer daemon mode.
46 .TP
47 .B \-e
48 Extra error detail toggle off.
49 .IP
50 Disables filling .html capture log with errors/second detail.
52 .TP
53 .B \-h
54 Help, possibly shows more options than this generic page.
56 .TP
57 .B \-k
58 No keyboard.
59 .IP
60 Disables stdin. Useful for unattended operation.
61 .br
62 See also:
63 .B -q
65 .TP
66 .B \-l
67 Log debug, shows a whole lot more than anyone wants to know.
68 .IP
69 Default is to log startup and brief capture info. This option may
70 drop packets unless using tmpfs for logging.
72 .TP
73 .B \-m
74 Captures sequence and frame data to .tsx files.
75 .IP
76 MPEG sequence dump makes xtscut usable immediately after capture, without
77 having to generate .tsx file with atscut -s. Data is generated only for
78 single program captures.
80 .TP
81 .B \-n
82 Pad single program cap with NULL packets.
83 .IP
84 NULL packets replace removed packets to keep bitrate constant for hardware
85 players that need it for TCP or UDP playback. It uses 8.7G per hour. Use
86 .B atscut -e pgmnum
87 to extract NULLs.
89 .TP
90 .B \-q
91 Quiet disables stdout, but doesn't detach.
92 .IP
93 Control is not returned to caller until completion. Use with -s if you
94 want cron script to wait.
96 .TP
97 .B \-v
98 Show version, boilerplate and memory buffer use.
100 .TP
101 .B \-A
102 Strict enforcement ATSC A/65b & MPEG TS tables reserved bits:
103 .IP
104 If VCT or MGT or EPG stop working with this it means the station is a bit
105 out of spec. Default checks are CRC32, Table ID and protocol version,
106 for tables that have them. MPEG Video and A52 audio are not checked.
108 .TP
109 .B \-S
110 Setup the configuration by scanning all the channels.
111 .IP
112 This takes a while to run. You should only have to run it when upgrading.
113 It will overwrite the .conf files with any detected channels, but also wipes
114 out any event timers you might have placed in those files. It sometimes
115 gets the callsign wrong, but you can edit the atscap[0-3].tsid.[vsb/qam]
116 file to retain the callsigns you want to keep the next time you use -S.
119 .SH GNU SCREEN OPTIONS
120 .TP
121 These options require GNU screen. Version 4.00.02 is known to work.
123 .TP
124 .B \-W
125 Use GNU screen to manage the session. Default: no.
126 .TP
127 .B \-D
128 Use GNU screen to start detached. Default: no.
129 .TP
130 .B \-R
131 Use GNU screen to re-attach session. Default: no.
133 .SH EXPERIMENTAL OPTIONS
134 .TP
135 These options may or may not work correctly.
137 .TP
138 .B \-N
139 No boilerplate/mem usage splash delay.
140 .IP
141 Makes it start immediately. This is
142 .B NOT
143 recommended because the devices usually need a few seconds, to reset
144 and load the microcode, before attempting to issue any commands.
146 .TP
147 .B WARNING: SPIN-DOWN MAY NOT WORK OR MAY CAUSE FILESYSTEM PROBLEMS!
148 .IP
149 .B There is a risk of file-system corruption because of spin-down,
150 .B mostly due to the risk of the drive not spinning up ever again.
151 .B Consider using a dedicated physical volume for captures.
152 .PP
153 There may be a significant power savings if you can spin-down your drives.
154 Not all hard drives support spin-down. Most new ones do, however spin-down
155 does not work with smartd because smartd wakes the drive up to query it.
156 Non-dedicated systems may prefer to have smartd over spin-down.
157 Also,
158 .B hdparm -S
159 may be IDE and SATA specific. You may not be able to spin-down
160 SCSI or USB or 1394 (FireWire) attached drives with this method. For IDE, you
161 can use
162 .B hdparm -C
163 to inspect it and try
164 .B hdparm -S60
165 to spin-down after 5m idle.
166 .TP
167 .B \-E
168 Energy Saver operation.
169 .IP
170 Use tmpfs for config and program guide files to allow hard drive spin-down timer
171 to kick in and save power.
172 .B AMD Cool-n-Quiet
173 or
174 .B Intel SpeedStep
175 may also be used to reduce the CPU cycles during capture.
176 .B atscap
177 uses very little CPU, even when capturing, so it should keep both methods at
178 the lowest speed settings.
179 .IP
180 .B NOTE:
181 Mount tmpfs at /dtv/ram, or -p path + "ram/" prior to using this option.
182 The following files and directories are copied to tmpfs when atscap starts,
183 and copied back on exit:
184 .IP
185 /etc/hosts.allow (not copied back to /etc)
186 /etc/atscap/*
187 /dtv/pg/* or -p dir/pg/*
188 /dtv/pg/img/* or -p dir/pg/img/*
189 .IP
190 If you want to change the running config while using the
191 .B -E
192 option, you will need to edit the tmpfs copy of atscap[devnum].conf.
193 The atscapN.log files are also stored in tmpfs directory and
194 will be copied and deleted on normal exit.
195 .IP
196 .B atscap
197 does not spin down the drives nor put the CPUs to sleep. You will have to
198 configure your power management software to handle that part. It will wake up
199 every 3 hours to save the updated program guides if there are no timers. If
200 there is a timer, it will attempt to wake up the ATSC device and the HDDs 30s
201 before capture. See hdparm -S option for IDE HDD spindown settings. SCSI HDD,
202 USB HDD, FireWire HDD and CPU power reduction may require additional software
203 outside the scope of this document.
204 .TP
206 .TP
207 .B WARNING: SOME CAPTURES MAY FAIL TO START WITH THIS OPTION!
208 .TP
209 .B \-a
210 Acquisition of Signal check.
211 .IP
212 Enabling AOS prevents captures from stations with weak signal strength.
213 It is
214 .B NOT
215 recommended that you use this mode of operation unless you know the driver
216 for your ATSC device has working signal strength function.
218 .TP
219 .B WARNING: SOME CAPTURES MAY BE CORRUPTED WITH THIS OPTION!
220 .TP
221 .B \-x
222 Signal check during capture.
223 .IP
224 Enables display of signal strength during capture. This is known to
225 work well with drivers that have hardware i2c [bt878] for data transfer.
226 Drivers using software i2c [cx88] have been known to fail when using
227 this mode of operation. Try it to see if it crashes the driver,
228 or causes more capture dropouts.
230 .SH OPTIONS WITH PARAMETERS
231 .TP
232 These change defaults to user supplied parameters.
234 .TP
235 .B \-i devnum
236 Selects DVB device number
237 .B devnum.
238 .IP
239 Default is 0 for /dev/dvb/adapter0. 3 is the maximum.
241 .TP
242 .B \-c cfgpath
243 Config file is in
244 .B cfgpath
245 directory, or is the file given as
246 .B cfgpath.
247 .IP
248 Default config file is /etc/atscap/atscap[devnum].conf to match -i devnum
249 .br
250 See also:
251 .B -i
253 .TP
254 .B \-p outpath
255 Captures will go to the
256 .B outpath
257 directory.
258 .IP
259 Default is /dtv.
260 .br
261 See also:
262 .B -s -o
264 .TP
265 .B \-o capfile
266 Output capture to
267 .B capfile
268 overriding default of MMDD-hhmm-CH.ts.
269 .IP
270 Mostly used for single capture from cron script.
271 .br
272 See also:
273 .B -s -p
275 .TP
276 .B \-s num
277 Capture arg channel for
278 .B num
279 seconds duration; example:
280 .IP
281 -s1800 19 gets chan 19 for 30 minutes, ignoring stdin. 19 is not part
282 of the option, but a single non-option arg. (FIXME)
283 .br
284 See also:
285 .B -o -p -i -q -d
287 .TP
288 .B \-z num
289 Zap cap if QoS drops below
290 .B num
291 for one minute. (FIXME)
292 .IP
293 The default is 0 for now.
295 .TP
296 .B \-F num
297 Select frequency table
298 .B num
299 from one of the following:
300 .PP
301 8-VSB: (The default if -F not specified)
302 .IP
303 .B 0
304 USA ATSC center frequencies (-28615 Hz)
305 .PP
306 QAM-256: (for testing only, not supported)
307 .IP
308 .B 1
309 USA Cable EAI-542 HRC center frequencies
310 .br
311 .B 2
312 USA Cable EAI-542 IRC center frequencies
313 .br
314 .B 3
315 USA Cable HRC center frequencies
316 .br
317 .B 4
318 USA Cable IRC center frequencies
319 .br
320 .B 5
321 USA Cable Standard center frequencies
323 .TP
324 .B \-w addr[:mask:port:threads]
325 Enable multi-threaded HTTP server subset:
326 .IP
327 .B addr
328 is required, may be dotted IP address or hostname.
329 .IP
330 .B mask
331 defaults to Class C subnet, may be dotted or number of bits notation.
332 .IP
333 .B port
334 is TCP port base range (
335 .B port + devnum
336 ) to use for the httpd server. It defaults to TCP port 80 +
337 .B devnum.
338 .IP
339 .B threads
340 defaults to 5 threads
342 .TP
343 .B \-u addr:port
344 Echo live stream during captures to Multicast UDP IP at
345 .B addr
346 and
347 .B port.
348 .IP
349 [u] key will toggle the UDP streaming off or on. Default is on.
350 .IP
351 This will probably only work OK with hardware decoders that can render
352 the required frame rate without delays. Use -n option for hardware deocders.
353 They need nulls. You also have to set the Virtual Program Number because most
354 hardware players can't understand multiplexed streams. Captures are saved
355 for later playback in case there was a problem with the UDP streaming.
356 .br
357 See also: -n
359 .TP
360 .B \-r file
361 Read-only replay of captured
362 .B file
363 at >10x speed.
364 .IP
365 Mostly used for PSIP debug of atscut -kmgt .ts samples.
366 Specifying a path overrides default of /dtv/ or -p path.
368 .SH CONSOLE CONTROLS
369 These are the console keys you may be able to use while it is running.
370 .TP
371 .B Manual Control
372 .PP
373 PGUP/DN scroll keys for navigation
374 Arrows edit-pad scroll keys for navigation
375 = [ ] ' non edit-pad scroll keys for navigation
377 * = disabled during capture
378 $ = disabled during timer
380 ctrl-L clear and refresh display
381 * ctrl-C abort atscap: exits if no capture in progress
382 * 1-9 1-9 keys to select channel and stop/start scan
383 * A-Z A-Z keys to select channel and stop/start scan
384 * SP toggle channel lock | scan (spacebar key)
385 * w toggle strength% | SNR | freq | wavelen
386 * a toggle automatic EPG for this station (magenta)
387 * q quit, disabled during capture prevents accidents
388 * TAB toggle timer/channel list display
389 $ NL [ENTER] start VC capture of MPEG2 on selected VC
390 $ BS [BackSpace Delete] (not ^H) stop capture
391 l load Program Guide for current channel
392 o override in-progress timer to manual, unlocks BS
393 p Event Program Guide (EPG) listings
394 v Virtual Channel display with video + audio select
395 g Master Guide Table (MGT) display, scrollable list
396 f capture log with overall errors per second
397 s statistics display toggle
398 z zap stops capture/deletes files or stops info cap
400 .B Timer Control (main screen):
401 .PP
402 t set a timer for channel
403 m move timer to another config file
404 r reschedule/remove a timer or range of timers
405 d delete a timer or range of timers
406 e toggle elaspsed or remaining time for timer
407 _ manually reload configuration file
408 + manually save configuration file
409 ! delete all timers on list, BE CAREFUL
411 .B Program Guide Control (screen after [p] key):
412 .PP
413 0-9/A-Z jumps to page of program guide, 0 is first page
414 t add EPG event, or range of events, to timer list
415 a toggle display of aged-out Program Guide events
416 h toggle display of hidden/unavailable/junk events
417 m toggle display of events that match timer names
418 n toggle numeric debug display
419 x clear program guide and stored EIT/ETT payloads
420 z zaps current capture, if any, and exits guide
421 p exits guide
423 .B Virtual Channel Control (screen after [v] key):
424 .PP
425 c set the virtual channel number
426 a set the audio stream number
427 r reset to full capture mode
428 d toggle VCT and PMT descriptor details
429 m toggle MPEG/ATSC Virtual Channel info
431 .SH ENVIRONMENT VARIABLES [NOT IMPLEMENTED YET]
432 .TP
433 [TODO: need to write parse_envars()...]
434 .PP
435 .B "ATSCAP_FIFO = n "
436 allocate n bytes for the FIFO
437 .br
438 .B "ATSCAP_UDP = a:p "
439 same as parameters for UDP *cast
440 .br
441 .B "ATSCAP_TCP = a:m:p:t "
442 same as parameters for httpd bind
444 .SH WEB SERVER CONFIGURATION
445 If you're not using -w option, you can skip this section. However, a lot
446 of work has gone into making the web server easy to use, so you really
447 should consider using the -w mode unless you actually like the console.
448 The user is expected to employ safe internet practices by using firewalls.
450 .IP
451 .B atscap -i0 -w 1.2.3.1:24:1080:5
452 .PP
453 Starts the http server for a 253 IP subnet at 1.2.3.1, on port 1080
454 with a maximum of 5 threads to be used for http, on dvb0.dvr0.
455 This is assuming you have a TCP/IP interface at 1.2.3.1.
456 .IP
457 .B atscap -i1 -w dtv:0:380:5
458 .PP
459 Starts the http server at port 380, without a netmask with 5 threads.
460 .IP
461 .B atscap -i1 -w dtv:0
462 .PP
463 Starts the http server at default port 1381 (default 1380 + devnum),
464 without a netmask and with the default of 5 threads.
466 .IP
467 The atscap TCP wrapper emulation default denies all traffic external to the
468 interface. Use /etc/hosts and/or /etc/hosts.allow (or tmpfs copy if using -E)
469 to grant access to the atscap web interface:
470 .TP
471 /etc/hosts:
472 .IP
473 1.2.3.1 dtv
474 .br
475 1.2.3.2 player
476 .TP
477 /etc/hosts.allow:
478 .IP
479 atscap: player
480 .PP
481 NOTE: NAT access isn't well tested. Because of this and the fact that the
482 web server code might have security flaws, it is NOT recommended allowing
483 public access to the HTTP user interface. Use netfilter + iptables if you
484 need to punch a hole to serve broadcast EPGs to a buddy on cable.
485 .PP
486 If you use a hostname to access it behind NAT, you will need to update
487 /etc/hosts with the hostname you will use, with different IP addresses
488 on the server and the client machines.
489 .PP
491 .SH WEB BROWSER CONFIGURATION
492 If you're not using -w option, you can skip these sub-sections.
494 .PP
495 .B PLAYER SCRIPT CONFIGURATION
496 .IP
497 You need to register the mpeg:// protocol into mozilla.
498 Any URI with mpeg:// calls mpeg.sh.
499 .PP
500 In the mozilla url entry box, enter this:
501 .IP
502 about:config
503 .PP
504 Right mouse to bring up menu then:
505 .IP
506 New -> String:
507 .br
508 network.protocol-handler.app.mpeg
509 .br
510 /usr/local/bin/mpeg.sh
511 (or where you put mpeg.sh)
512 .PP
513 Right mouse to bring up menu then:
514 .IP
515 New -> Boolean:
516 .br
517 network.protocol-handler.external.mpeg
518 .br
519 true
520 .PP
521 Right mouse to bring up menu then:
522 .IP
523 New -> Boolean:
524 .br
525 network.protocol-handler.warn-external.mpeg
526 .br
527 false (true warns you before playing)
529 .PP
530 .B EDITOR SCRIPT CONFIGURATION
531 .IP
532 You also need registers the xtc:// protocol into mozilla.
533 Any URI with xtc:// calls xtc.sh.
534 .PP
535 In the mozilla url entry box, enter this:
536 .IP
537 about:config
538 .PP
539 Right mouse to bring up menu then:
540 .IP
541 New -> String:
542 .br
543 network.protocol-handler.app.xtc
544 .br
545 /usr/local/bin/xtc.sh
546 (or where you put xtc.sh)
547 .PP
548 Right mouse to bring up menu then:
549 .IP
550 New -> Boolean:
551 .br
552 network.protocol-handler.external.xtc
553 .br
554 true
555 .PP
556 Right mouse to bring up menu then:
557 .IP
558 New -> Boolean:
559 .br
560 network.protocol-handler.warn-external.xtc
561 .br
562 false (true warns you before editing)
564 .SH UDP SERVER CONFIGURATION [WARNING: NOT WELL TESTED]
565 Use this for relaying live capture to other local clients, even WiFi.
566 Assume for these examples the server local IP address is 1.2.3.1,
567 with a hostname of dtv.
568 .PP
569 .B MULTICAST
570 .PP
571 This can be received by multiple devices:
572 .IP
573 .B -u 224.1.2.3:1234
574 .PP
575 Multicast will be chosen if you use a Multicast address.
576 Compile a kernel with UDP Multicast enabled, tunnelling and routing are not
577 needed for local relay, for every machine that will receive the stream.
578 .PP
579 Software decoders can play it back like this:
580 .IP
581 .B xine -p udp://224.1.2.3:1234
582 .PP
583 .B UNICAST (FIXME/TODO)
584 .IP
585 .B PLEASE BE CAREFUL WHERE YOU POINT THAT UDP CANNON!
586 .PP
587 This can be received by only one client at 1.2.3.3:
588 .IP
589 .B -u 1.2.3.3:1234
590 .PP
591 Unicast will be chosen if you don't use a Multicast address.
592 Software decoders can play it back like this:
593 .IP
594 .B xine -p udp://1.2.3.1:1234
595 .PP
596 .B HARDWARE DECODER ISSUES
597 .PP
598 The UDP Multi/Unicast option is primarily for hardware decoder support.
599 Hardware decoders will also need -n option to pad the stream with nulls
600 to keep the bitrate at what the decoder expects.
601 .PP
602 The hardware decoders that support UDP may also support Multicast.
603 If so, use it. If not, you will be limited to Unicast mode.
604 .PP
605 .B SOFTWARE DECODER ISSUES
606 .PP
607 UDP testing doesn't play very smoothly here. It's not any better than
608 telling xine to read the card live. Using TCP for software playback of
609 capture files works much better, via mounted filesystem or
610 .B -w
611 HTTP server:
613 .B RTP/RTSP IS NOT IMPLEMENTED
614 .PP
615 Because atscap is primarily designed for a single user, multi-stream
616 VOD using RTP/RTSP/RSVP or STCP is not currently implemented. If
617 you want this feature, write it and post the patch.
619 .B XINE PLAYBACK EXAMPLE FOR HTTP
620 .IP
621 .B xine -p http://dtv:80/CaptureFile-1220-2300.3.ts
622 .PP
623 It has been reported that mplayer navigates via http:// better than
624 xine because mplayer supports the HTTP Range: directive.
625 Both work fine when playback is from a mounted filesystem.
626 Using a VLC server is outside the scope of this document.
628 .SH QUICK START EXAMPLE
629 Check DVB device for ATSC stations and create configuration file:
630 .IP
631 .B atscap -i0 -S
632 (single card users or first card)
633 .PP
634 Multi-card users may save time by copying the first config file, or
635 if your antennas have widely varying signal qualities, do the rest:
636 .IP
637 .B atscap -i1 -S
638 (two card users)
639 .br
640 .B atscap -i2 -S
641 (three card users)
642 .br
643 .B atscap -i3 -S
644 (four card users)
645 .PP
647 .SH SIGNAL OPTIONS
648 .B atscap
649 accepts the following signals via kill or killall:
650 -2 SIGINT is same as control-c, but does not work during capture
651 -15 SIGTERM save the state and if needed stops any current capture
652 -9 SIGKILL kills it if other signals fail to do same
654 .SH HISTORY
655 .B atscap
656 was written because no fast forward, no rewind and no pause
657 is not Advanced Television!
659 .SH BUGS
660 All kinds! Good luck finding them! Please send bug reports and patches.
662 .SH SEE ALSO
663 .PP
664 atscap_conf(5), atscut(1), xtscut(1), screen(1), hosts_access(5), mount(8)
665 .PP
666 The ATSC specifications may be found at the following location:
667 .IP
668 .B http://www.atsc.org/
670 .SH AUTHOR
671 .PP
672 The author of this manual page is
673 .B <inkling@users.sourceforge.net>
675 .SH COPYRIGHT
676 .PP
677 This manual page is part of the atscap-1.1 distribution software.
678 .PP
679 atscap is Copyright (C) 2004-2007 by
680 .B <inkling@users.sourceforge.net>
682 .SH LICENSE
683 .PP
684 Permission is granted to copy, distribute and/or modify this document
685 under the terms of the GNU General Public License, Version 2.
686 .PP
687 A copy of the GPLv2 with the file name COPYING or LICENSE should have been
688 included in this distribution. If it was not included, please contact me,
689 .B <inkling@users.sourceforge.net>,
690 or write to:
691 .IP
692 The Free Software Foundation, Inc.
693 51 Franklin Street, Fifth Floor
694 Boston, MA 02110-1301, USA