Annotation of multiplexer/iso13818ts.1, revision 1.1
1.1 ! oskar 1: .\" Man page for iso13818ts
! 2: .\"
! 3: .\" Copyright (C) 2001, Convergence Integrated Media GmbH
! 4: .\" Author: Oskar Schirmer
! 5: .\"
! 6: .TH iso13818ts 1 "April 30th, 2001" "0.0.2" "Multiplexer"
! 7: .SH NAME
! 8: iso13818ts \- multiplexer for ISO 13818 transport streams
! 9: .SH SYNOPSIS
! 10: iso13818ts [COMMAND...]
! 11: .SH DESCRIPTION
! 12: Generates an ISO 13818-1 conforming transport stream from multiple
! 13: input streams.
! 14: The result is sent to \fIstdout\fR,
! 15: the input streams are read from explicitely opened files.
! 16: All of the following commands may also be fed to \fIstdin\fR during
! 17: operation by omitting the leading hyphen (e.g. \fBQ\fR) or
! 18: double-hyphen (e.g. \fBquit\fR).
! 19: .TP
! 20: \fB\-\-help\fR
! 21: Display this help.
! 22: .TP
! 23: \fB\-V\fR, \fB\-\-version\fR
! 24: Output version information.
! 25: .TP
! 26: \fB\-Q\fR, \fB\-\-quit\fR
! 27: Quit this program.
! 28: .TP
! 29: \fB\-v\fR, \fB\-\-verbose\fR [\fIlevel\fR]
! 30: Verbose mode, \fIlevel\fR = 0..6, default is 2 (providing warnings
! 31: concerning data errors), initial verbosity is 1 (providing only
! 32: program errors).
! 33: .TP
! 34: \fB\-p\fR, \fB\-\-pes\fR \fIfile\fR \fItarget_program\fR
! 35: Open a PES input \fIfile\fR,
! 36: output the contained stream as \fItarget_program\fR (range 0x0001..0xFFFF).
! 37: .TP
! 38: \fB\-p\fR, \fB\-\-pes\fR \fIfile\fR \fItarget_program\fR \fItarget_stream_id\fR
! 39: Open a PES input \fIfile\fR,
! 40: output the contained stream in \fItarget_program\fR (range 0x0001..0xFFFF)
! 41: with \fItarget_stream_id\fR (recommended range 0xBD..0xFE).
! 42: The \fIfile\fR may be specified as \fB=\fR to denote
! 43: the last previously mentioned file.
! 44: .TP
! 45: \fB\-P\fR, \fB\-\-ps\fR \fIfile\fR \fItarget_program\fR
! 46: Open a PS input \fIfile\fR,
! 47: output the contained program as \fItarget_program\fR (range 0x0001..0xFFFF).
! 48: .TP
! 49: \fB\-P\fR, \fB\-\-ps\fR \fIfile\fR \fItarget_program\fR \fIsource_stream_id\fR [\fItarget_stream_id\fR]
! 50: Open a PS input \fIfile\fR,
! 51: extract the stream with \fIsource_stream_id\fR (range 0x00..0xFF)
! 52: and output that stream in \fItarget_program\fR (range 0x0001..0xFFFF)
! 53: with \fItarget_stream_id\fR (recommended range 0xBD..0xFE).
! 54: If no \fItarget_stream_id\fR is given, \fIsource_stream_id\fR is used instead.
! 55: The \fIfile\fR may be specified as \fB=\fR to denote
! 56: the last previously mentioned file.
! 57: .TP
! 58: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR
! 59: Open a TS input \fIfile\fR,
! 60: extract all programs from it and output them.
! 61: Note, that additional SI data is not propagated,
! 62: see command \fB\-\-si\fR for further information.
! 63: .TP
! 64: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR \fIsource_program\fR [\fItarget_program\fR]
! 65: Open a TS input \fIfile\fR,
! 66: extract the program \fIsource_program\fR (range 0x0001..0xFFFF)
! 67: and output that program as \fItarget_program\fR (range 0x0001..0xFFFF).
! 68: If no \fItarget_program\fR is given,
! 69: don't change the \fIsource_program\fR number.
! 70: The \fIfile\fR may be specified as \fB=\fR to denote
! 71: the last previously mentioned file.
! 72: .TP
! 73: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR \fIsource_program\fR \fItarget_program\fR \fIsource_stream_id\fR [\fItarget_stream_id\fR]
! 74: Open a TS input \fIfile\fR,
! 75: extract the stream with \fIsource_stream_id\fR (range 0x00..0xFF)
! 76: from the program \fIsource_program\fR (range 0x0001..0xFFFF)
! 77: and output that stream as \fItarget_stream_id\fR (recommended range 0xBD..0xFE)
! 78: in program \fItarget_program\fR (range 0x0001..0xFFFF).
! 79: If no \fItarget_stream_id\fR is given, use \fIsource_stream_id\fR instead.
! 80: The \fIfile\fR may be specified as \fB=\fR to denote
! 81: the last previously mentioned file.
! 82: .TP
! 83: \fB\-c\fR, \fB\-\-close\fR \fIfile\fR
! 84: Close input \fIfile\fR, as if eof is reached.
! 85: In combination with \fB\-\-repeat\fR this causes the next repeatition
! 86: to start immediately.
! 87: Note, that the input data file is cut of as is, i.e. no attempt
! 88: is made to close the file on a clean audio or video frame border.
! 89: .TP
! 90: \fB\-a\fR, \fB\-\-append\fR \fIfile1\fR \fIfile2\fR [\fInum\fR]
! 91: Earmark another \fIfile2\fR to be opened as soon as \fIfile1\fR
! 92: comes to its end.
! 93: The appended \fIfile2\fR is foreseen to be repeated \fInum\fR
! 94: times, default is 1 (see \fB\-\-repeat\fR).
! 95: Both files must contain the same type of data,
! 96: as the data of both files is chained without considering clean
! 97: transition of audio or video sequences.
! 98: The \fIfile1\fR may be specified as \fB=\fR to denote
! 99: the last previously mentioned file.
! 100: .TP
! 101: \fB\-f\fR, \fB\-\-file\fR \fIreference_number\fR \fIfile_name\fR
! 102: The positive \fIreference_number\fR is associated with a \fIfile_name\fR.
! 103: For all following commands, the \fIreference_number\fR may be
! 104: used instead of the \fIfile_name\fR. This allows better control
! 105: over file handles, as the same file may be addressed via different
! 106: \fIreference_number\fRs.
! 107: .TP
! 108: \fB\-x\fR, \fB\-\-crop\fR \fItarget_program\fR [\fItarget_stream_id\fR]
! 109: Delete a stream given by \fItarget_stream_id\fR,
! 110: or a complete program given by \fItarget_program\fR
! 111: from the output.
! 112: The corresponding input file will be closed, if not needed otherwise.
! 113: .TP
! 114: \fB\-r\fR, \fB\-\-repeat\fR \fIfile\fR \fInum\fR
! 115: Set the repeatition counter for \fIfile\fR to \fInum\fR
! 116: (or to infinite if \fInum\fR=0).
! 117: The file will be reset as soon as eof is reached
! 118: (or it is closed by the command \fB\-\-close\fR).
! 119: Note, that the file will be reset without considering clean transition
! 120: of audio or video sequences at the restart point.
! 121: The \fIfile\fR may be specified as \fB=\fR to denote
! 122: the last previously mentioned file.
! 123: .TP
! 124: \fB\-R\fR, \fB\-\-reopen\fR
! 125: This command shall precede one of the commands that open a new file
! 126: (i.e. \fB\-\-pes\fR, \fB\-\-ps\fR or \fB\-\-ts\fR must follow
! 127: \fIon the same line\fR).
! 128: The next file will be opened with a new file handle,
! 129: regardless of whether the same file is yet open or not.
! 130: .TP
! 131: \fB\-\-si\fR \fIfile\fR [\fIlower_bound\fR \fIupper_bound\fR]
! 132: In a TS \fIfile\fR, all TS pakets with PID in the range
! 133: from \fIlower_bound\fR to \fIupper_bound\fR
! 134: (possible range 0x0000..0x1FFE, recommended range 0x10..0x1F)
! 135: inclusive are handled as SI pakets (according to ETSI EN 300 468).
! 136: These pakets are bypassed and promoted to the output without further handling.
! 137: If no further data from the \fIfile\fR is in use,
! 138: the SI pakets are promoted \fIgreedy\fR, i.e. without any timing or delay.
! 139: If \fIlower_bound\fR and \fIupper_bound\fR are omitted,
! 140: the special handling of SI pakets is turned off for the given \fIfile\fR.
! 141: The \fIfile\fR may be specified as \fB=\fR to denote
! 142: the last previously mentioned file.
! 143: .TP
! 144: \fB\-I\fR, \fB\-\-ident\fR \fItransport_stream_id\fR
! 145: Set the output \fItransport_stream_id\fR (range 0x0000..0xFFFF).
! 146: .TP
! 147: \fB\-B\fR, \fB\-\-busy\fR [\fInum\fR]
! 148: Set the busy flag to \fInum\fR (range 0..1, default is 1).
! 149: Whenever the program has no more data to handle and
! 150: the busy flag is not set, it stops.
! 151: .TP
! 152: \fB\-\-timed\fR
! 153: Force delay timing, even if solely disk files are in use.
! 154: If not so, if delay is to be awaited while processing regular files,
! 155: the delay is skipped instead and timing information in the resulting
! 156: file is adjusted accordingly.
! 157: .TP
! 158: \fB\-F\fR, \fB\-\-fpsi\fR \fItime\fR
! 159: Set the PSI table frequency to \fItime\fR msec
! 160: (or to infinite if \fItime\fR=0, initial value is infinite).
! 161: The PAT and PMT will be generated at more or less the given
! 162: frequency, even if the tables did not change.
! 163: In any case, the next tables will be generated immediately.
! 164: .TP
! 165: \fB\-\-badtiming\fR
! 166: In conjunction with a program stream originating from a DVB-s
! 167: digital TV receiver card, You might want to automatically
! 168: correct some of the PCR values produced by that card, to
! 169: prevent discontinuities in the output.
! 170: .SH OVERVIEW
! 171: The multiplexer is designed to run uninterrupted and
! 172: be controlled via \fIstdin\fR and \fIstderr\fR.
! 173: It may be invoked interactively with the streams to
! 174: process given as command line options or with
! 175: the commands to be processed typed into \fIstdin\fR
! 176: during operation.
! 177: The latter type of usage is also designed for use
! 178: with an user interface front-end, that may
! 179: translate some GUI input to iso13818ts commands
! 180: and filter its responses to be presented to the user
! 181: as appropriate.
! 182: .P
! 183: Three different types of input are supported:
! 184: Paketized elementary streams (PES),
! 185: Program streams (PS),
! 186: Transport streams (TS).
! 187: .P
! 188: Numeric parameters may be given in decimal (e.g. 31)
! 189: or in hex (e.g. 0x1F).
! 190: .SH DETAILS
! 191: The output file or device does not change throughout the
! 192: time the program runs. The input files, however, may vary.
! 193: Also the contents of an input file may vary, but not its
! 194: type. E.g., a file opened as program stream must contain
! 195: valid program stream data up to its end (and including
! 196: any files that are appended to this file with \fB\-\-append\fR).
! 197: .P
! 198: All basic PSI is evaluated contiguously, and changes in
! 199: the configuration (changing PID, etc.) are taken into
! 200: account and tracked. Thus a stream should not go lost
! 201: simply because its PID is changed in the middle of the
! 202: broadcast.
! 203: .P
! 204: When remultiplexing a transport stream, the user cannot
! 205: rely on the original PIDs to be the same in the output stream.
! 206: Usually output PIDs are different from input PIDs.
! 207: This is because all basic PSI is composed from scratch for the
! 208: output stream, with exception of the descriptors.
! 209: These are not evaluated but only copied and reused
! 210: as appropriate.
! 211: .P
! 212: For each output program one stream within this program
! 213: must contain PCR time stamps. The strategy in selecting
! 214: which stream shall carry the PCR is, first see if there
! 215: is one input stream that contains PCR, if none is found,
! 216: use the stream for which data packets are found first.
! 217: Note, that for a simple mono TV program this is not
! 218: necessarily the video stream.
! 219: .SH EXAMPLES
! 220: To convert a program stream file x.PS to a transport stream file x.TS,
! 221: with program number 42, transport stream id 23
! 222: and PAT and PMT generated about every half second:
! 223: .IP
! 224: $ iso13818ts --fpsi 500 --ident 23 --ps x.PS 42 > x.TS
! 225: .PP
! 226: If the program stream doesn't contain correct PSI,
! 227: the single streams may be extracted one by one. Assuming
! 228: one video stream (0xE0) and mono audio (0xC0):
! 229: .IP
! 230: $ iso13818ts -fpsi 500 --ident 23 --ps x.PS 42 0xE0 --ps = 42 0xC0 > x.TS
! 231: .PP
! 232: To bundle two streams originating from video devices and
! 233: send them out to a streaming device, e.g.:
! 234: .IP
! 235: $ iso13818ts -F 500 -P /dev/video0 0x7300 -P /dev/video1 0x7301 > /dev/xdvb0
! 236: .PP
! 237: To remultiplex a transport stream containing two TV programs
! 238: with program numbers 4711 and 4712, with the audio streams (0xC0)
! 239: of the TV programs exchanged:
! 240: .IP
! 241: $ iso13818ts -F 500 --file 1 /dev/rdvb0 --ts 1 4711 4711 0xE0 --ts 1 4712 4712 0xE0 --ts 1 4711 4712 0xC0 --ts 1 4712 4711 0xC0 > /dev/xdvb0
! 242: .PP
! 243: To invoke the multiplexer for interactive use, it must
! 244: be put in all-time-busy-mode. Subsequently, commands can
! 245: be fed to \fIstdin\fR, e.g. to do the same as with the
! 246: first example:
! 247: .IP
! 248: $ iso13818ts --busy > x.TS
! 249: .br
! 250: fpsi 500 ident 23
! 251: .br
! 252: ps x.PS 42
! 253: .PP
! 254: This instance of the multiplexer will not cease when the
! 255: end of file in x.PS is reached. To stop the multiplexer,
! 256: either \fBquit\fR or \fBbusy 0\fR may be typed to \fIstdin\fR.
! 257: .P
! 258: To output a movie repeatedly (e.g. seven times):
! 259: .IP
! 260: $ iso13818ts -F 500 --ps thepurpleroseofcairo.PS 777 --repeat = 7 > /dev/xdvb0
! 261: .PP
! 262: Note, that if during the movie is processed, the command
! 263: .IP
! 264: close thepurpleroseofcairo.PS
! 265: .PP
! 266: is issued, and supposed it is not yet processed the seventh time,
! 267: it is not closed, but restarted immediately.
! 268: .P
! 269: To concatenate two movies and output them in sequence:
! 270: .IP
! 271: $ iso13818ts -F 500 --ps rambo1.PS 789 --append = rambo2.PS > /dev/xdvb0
! 272: .PP
! 273: Note, that a file can only be appended to a file, that is
! 274: yet in use (i.e. being processed). Thus, it is not possible
! 275: to append a third movie (rambo3.PS) from within the command
! 276: line. Instead, the processing of the second movie must be
! 277: awaited, and then the following command can be fed to \fIstdin\fR:
! 278: .IP
! 279: append rambo2.PS rambo3.PS
! 280: .PP
! 281: To add data from a DSMCC carousel to the output, a DSMCC
! 282: carousel generator must be started seperately. The carousel
! 283: must generate the DSMCC data as a series of transport
! 284: stream packets that contain private sections. The PIDs used by
! 285: the carousel must be known (e.g. 0x10..0x1F):
! 286: .IP
! 287: $ mkfifo dsmcc_pipe
! 288: .br
! 289: $ some_dsmcc_carousel ... > dsmcc_pipe &
! 290: .br
! 291: $ iso13818ts -F 500 --busy --ts dsmcc_pipe --si = 0x10 0x1F > /dev/xdvb0
! 292: .br
! 293: ps x.PS 42
! 294: .br
! 295: ps y.PS 43
! 296: .br
! 297: \&...
! 298: .PP
! 299: .SH "KNOWN PROBLEMS"
! 300: The program might not work in conjunction with device drivers
! 301: that do not deliver or accept data unless a first read or write
! 302: is done on the device. E.g., for a MPEG video data source, that
! 303: does not produce output without being triggered by being read
! 304: from, this program will await the readability of the first
! 305: data infinitely. On the other hand it is obvious that the driver
! 306: should not encode data as long as there is no application that
! 307: will read this data.
! 308: One possibly solution to this dilemma is to patch such a driver
! 309: to interpret the \fIpoll\fR command as an order for data, thus
! 310: triggering the read mechanisms. Analogous considerations hold
! 311: for polling the output device and writing to it.
! 312: .P
! 313: Paketized elementary streams do not necessarily contain
! 314: usable time stamps, so when multiplexing raw PES, streams
! 315: belonging together may be out of sync. This is especially
! 316: noteworthy in case streams shall be demultiplexed and then
! 317: again multiplexed in some way. Results will always be better
! 318: when this remultiplexing takes place entirely within the
! 319: multiplexer, because that way timing information won't go lost.
! 320: .SH BUGS
! 321: Non-ISO_13818-1 descriptors (private descriptors) in
! 322: ISO_13818-1 PSI sections are not promoted.
! 323: .SH "SEE ALSO"
! 324: .BR ISO\ 13818-1 ,
! 325: .BR ETSI\ EN\ 300\ 468 .
! 326: .SH AUTHOR
! 327: Oskar Schirmer (oskar@convergence.de).
LinuxTV legacy CVS <linuxtv.org/cvs>