Annotation of multiplexer/iso13818ps.1, revision 1.2
1.1 oskar 1: .\" Man page for iso13818ps
2: .\"
3: .\" Copyright (C) 2001, Convergence Integrated Media GmbH
4: .\" Author: Oskar Schirmer
5: .\"
1.2 ! oskar 6: .TH iso13818ps 1 "August 30th, 2001" "0.0.2" "Multiplexer"
1.1 oskar 7: .SH NAME
8: iso13818ps \- multiplexer for ISO 13818 program streams
1.2 ! oskar 9: .SH SYNOPSIS
! 10: iso13818ps [COMMAND...]
! 11: .SH DESCRIPTION
! 12: Generates an ISO 13818-1 conforming program 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
! 35: Open a PES input \fIfile\fR,
! 36: output the contained stream.
! 37: .TP
! 38: \fB\-p\fR, \fB\-\-pes\fR \fIfile\fR \fItarget_stream_id\fR
! 39: Open a PES input \fIfile\fR,
! 40: output the contained stream
! 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
! 46: Open a PS input \fIfile\fR,
! 47: output the contained program.
! 48: .TP
! 49: \fB\-P\fR, \fB\-\-ps\fR \fIfile\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
! 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: .TP
! 62: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR \fIsource_program\fR
! 63: Open a TS input \fIfile\fR,
! 64: extract the program \fIsource_program\fR (range 0x0001..0xFFFF)
! 65: and output that program.
! 66: The \fIfile\fR may be specified as \fB=\fR to denote
! 67: the last previously mentioned file.
! 68: .TP
! 69: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR \fIsource_program\fR \fIsource_stream_id\fR [\fItarget_stream_id\fR]
! 70: Open a TS input \fIfile\fR,
! 71: extract the stream with \fIsource_stream_id\fR (range 0x00..0xFF)
! 72: from the program \fIsource_program\fR (range 0x0001..0xFFFF)
! 73: and output that stream as \fItarget_stream_id\fR (recommended range 0xBD..0xFE)
! 74: .
! 75: If no \fItarget_stream_id\fR is given, use \fIsource_stream_id\fR instead.
! 76: The \fIfile\fR may be specified as \fB=\fR to denote
! 77: the last previously mentioned file.
! 78: .TP
! 79: \fB\-T\fR, \fB\-\-ts\fR \fIfile\fR 0 \fIsource_stream_id\fR [\fItarget_stream_id\fR]
! 80: As before, but extract a stream with \fIsource_stream_id\fR (range 0x00..0xFF)
! 81: from a transport stream with broken or missing PAT/PMT information.
! 82: The stream is opened only, if there is \fBnot\fR any entry in the
! 83: tables for that stream.
! 84: Note, that if there is more than one stream with the given
! 85: \fIsource_stream_id\fR,
! 86: only one matching stream will be opened, and
! 87: the choice is not deterministic.
! 88: .TP
! 89: \fB\-c\fR, \fB\-\-close\fR \fIfile\fR
! 90: Close input \fIfile\fR, as if eof is reached.
! 91: In combination with \fB\-\-repeat\fR this causes the next repeatition
! 92: to start immediately.
! 93: Note, that the input data file is cut of as is, i.e. no attempt
! 94: is made to close the file on a clean audio or video frame border.
! 95: .TP
! 96: \fB\-a\fR, \fB\-\-append\fR \fIfile1\fR \fIfile2\fR [\fInum\fR]
! 97: Earmark another \fIfile2\fR to be opened as soon as \fIfile1\fR
! 98: comes to its end.
! 99: The appended \fIfile2\fR is foreseen to be repeated \fInum\fR
! 100: times, default is 1 (see \fB\-\-repeat\fR).
! 101: Both files must contain the same type of data,
! 102: as the data of both files is chained without considering clean
! 103: transition of audio or video sequences.
! 104: The \fIfile1\fR may be specified as \fB=\fR to denote
! 105: the last previously mentioned file.
! 106: .TP
! 107: \fB\-f\fR, \fB\-\-file\fR \fIreference_number\fR \fIfile_name\fR
! 108: The positive \fIreference_number\fR is associated with a \fIfile_name\fR.
! 109: For all following commands, the \fIreference_number\fR may be
! 110: used instead of the \fIfile_name\fR. This allows better control
! 111: over file handles, as the same file may be addressed via different
! 112: \fIreference_number\fRs.
! 113: .TP
! 114: \fB\-x\fR, \fB\-\-crop\fR [\fItarget_stream_id\fR]
! 115: Delete a stream given by \fItarget_stream_id\fR,
! 116: or the complete program
! 117: from the output.
! 118: The corresponding input file(s) will be closed, if not needed otherwise.
! 119: .TP
! 120: \fB\-r\fR, \fB\-\-repeat\fR \fIfile\fR \fInum\fR
! 121: Set the repeatition counter for \fIfile\fR to \fInum\fR
! 122: (or to infinite if \fInum\fR=0).
! 123: The file will be reset as soon as eof is reached
! 124: (or it is closed by the command \fB\-\-close\fR).
! 125: Note, that the file will be reset without considering clean transition
! 126: of audio or video sequences at the restart point.
! 127: The \fIfile\fR may be specified as \fB=\fR to denote
! 128: the last previously mentioned file.
! 129: .TP
! 130: \fB\-R\fR, \fB\-\-reopen\fR
! 131: This command shall precede one of the commands that open a new file
! 132: (i.e. \fB\-\-pes\fR, \fB\-\-ps\fR or \fB\-\-ts\fR must follow
! 133: \fIon the same line\fR).
! 134: The next file will be opened with a new file handle,
! 135: regardless of whether the same file is yet open or not.
! 136: .TP
! 137: \fB\-\-descr\fR [\fIdescr_tag\fR [\fIdescr_length\fR \fIdata\fR...]]
! 138: Add, inhibit or delete in the PMT section a descriptor,
! 139: that does \fBnot\fR belong to a specific stream.
! 140: To add a descriptor, all parameters must be given,
! 141: \fIdescr_tag\fR (range 0x00..0xFF),
! 142: \fIdescr_length\fR (range 1..255),
! 143: and the appropriate amount of bytes given as \fIdata\fR (range 0x00..0xFF).
! 144: To inhibit any descriptor with a given \fIdescr_tag\fR,
! 145: \fIdescr_length\fR is set to \fB0\fR and no \fIdata\fR is given.
! 146: This causes matching descriptors from input streams to
! 147: be discarded instead of being copied to the target stream.
! 148: To delete the manual setting of a descriptor,
! 149: \fIdescr_length\fR is omitted. This causes descriptors
! 150: with matching \fIdescr_tag\fR to be passed from input to
! 151: the target stream.
! 152: To delete all manual settings,
! 153: that do \fBnot\fR belong to a specific stream,
! 154: the \fIdescr_tag\fR is omitted, too.
! 155: Note, that \fB\-\-descr\fR never modifies descriptors,
! 156: that belong to a specific stream.
! 157: To modify these, use the command \fB\-\-sdescr\fR.
! 158: .TP
! 159: \fB\-\-sdescr\fR [\fIstream_id\fR [\fIdescr_tag\fR [\fIdescr_length\fR \fIdata\fR...]]]
! 160: Add, inhibit or delete in the PMT section a descriptor,
! 161: that does belong to a specific stream.
! 162: To add a descriptor, all parameters must be given,
! 163: \fIstream_id\fR (recommended range 0xBD..0xFE),
! 164: \fIdescr_tag\fR (range 0x00..0xFF),
! 165: \fIdescr_length\fR (range 1..255),
! 166: and the appropriate amount of bytes given as \fIdata\fR (range 0x00..0xFF).
! 167: To inhibit any descriptor with a given \fIdescr_tag\fR,
! 168: \fIdescr_length\fR is set to \fB0\fR and no \fIdata\fR is given.
! 169: This causes matching descriptors from the corresponding input streams to
! 170: be discarded instead of being copied to the target stream.
! 171: To delete the manual setting of a descriptor,
! 172: \fIdescr_length\fR is omitted. This causes descriptors
! 173: with matching \fIdescr_tag\fR to be passed from input to
! 174: the target stream.
! 175: To delete all manual settings for a \fIstream_id\fR,
! 176: the \fIdescr_tag\fR is omitted, too.
! 177: To delete all manual settings for all streams \fBand\fR those
! 178: that do not belong to a specific stream,
! 179: the \fIstream_id\fR is omitted, too.
! 180: .TP
! 181: \fB\-B\fR, \fB\-\-busy\fR [\fInum\fR]
! 182: Set the busy flag to \fInum\fR (range 0..1, default is 1).
! 183: Whenever the program has no more data to handle and
! 184: the busy flag is not set, it stops.
! 185: .TP
! 186: \fB\-\-timed\fR
! 187: Force delay timing, even if solely disk files are in use.
! 188: If not so, if delay is to be awaited while processing regular files,
! 189: the delay is skipped instead and timing information in the resulting
! 190: file is adjusted accordingly.
! 191: .TP
! 192: \fB\-F\fR, \fB\-\-fpsi\fR \fItime\fR
! 193: Set the PSI table frequency to \fItime\fR msec
! 194: (or to infinite if \fItime\fR=0, initial value is infinite).
! 195: The PAT and PMT will be generated at more or less the given
! 196: frequency, even if the tables did not change.
! 197: In any case, the next tables will be generated immediately.
! 198: .TP
! 199: \fB\-\-trigin\fR \fItime\fR
! 200: Set the input buffer trigger timing to \fItime\fR.
! 201: For any input stream, that is newly opened
! 202: (or has to be retriggered, e.g. due to intermediate emptiness),
! 203: the buffer is triggered for promotion to the splice unit
! 204: with a delay of \fItime\fR msec compared to the time
! 205: of data entrance into the buffer.
! 206: For any stream yet triggered the timing is not changed
! 207: unless retriggering takes place.
! 208: Not affected by this value are the other trigger conditions,
! 209: mainly a certain buffer fullness
! 210: and cotriggering with a corresponding stream that is triggered.
! 211: .TP
! 212: \fB\-\-trigout\fR \fItime\fR
! 213: Set the output buffer trigger timing to \fItime\fR.
! 214: As the output buffer is triggered for promotion to \fIstdout\fR,
! 215: this is done with a delay of \fItime\fR msec compared to the time
! 216: of data entrance into the buffer.
! 217: The new timing is only valid if set before the first triggering
! 218: of the output buffer,
! 219: or if retriggering takes place, e.g. due to intermediate emptiness.
! 220: Not affected by this value is the trigger condition
! 221: of a certain buffer fullness.
! 222: .TP
! 223: \fB\-C\fR, \fB\-\-config\fR \fInum\fR
! 224: Order output configuration of target stream with \fInum\fR=1,
! 225: switch off with \fInum\fR=0.
! 226: Set \fInum\fR=2, to get information about descriptors, too.
! 227: When switched on, the configuration is printed each time it changes.
! 228: First, the number of programs is printed,
! 229: then for each program one line of description and
! 230: for each stream within that program another line is printed.
! 231: When \fInum\fR=2, then for each descriptor there is printed one more line.
! 232: The following values are compiled:
! 233: .RS
! 234: .TP
! 235: \fIprogs\fR
! 236: Number of programs in target stream.
! 237: .TP
! 238: \fIprog\fR
! 239: Program number within target stream.
! 240: .TP
! 241: \fIpmt\fR
! 242: PMT PID for the program.
! 243: .TP
! 244: \fIpcr\fR
! 245: PCR PID for the program.
! 246: .TP
! 247: \fIstreams\fR
! 248: Number of streams in the program.
! 249: .TP
! 250: \fIstream\fR
! 251: Stream PID.
! 252: .TP
! 253: \fItype\fR
! 254: Stream type (according to ISO 13818-1 table 2-29).
! 255: .TP
! 256: \fIsid\fR
! 257: PES stream ID.
! 258: .TP
! 259: \fIfile\fR
! 260: Source file contents type (PES=0, PS=1, TS=2).
! 261: .TP
! 262: \fIsource\fR
! 263: Stream index in source file (SID for PS, PID for TS).
! 264: .TP
! 265: \fInum\fR
! 266: Source file reference number (-1 if none).
! 267: .TP
! 268: \fIname\fR
! 269: Source file name.
! 270: .TP
! 271: \fIdescr\fR
! 272: Descriptor tag.
! 273: .TP
! 274: \fIlen\fR
! 275: Descriptor length, number of data bytes in the descriptor.
! 276: .TP
! 277: \fIdata\fR
! 278: Descriptor data, bytewise.
! 279: .RE
! 280: .TP
! 281: \fB\-S\fR, \fB\-\-statistics\fR \fItime\fR
! 282: Order output load statistics to be generated about every
! 283: \fItime\fR msec.
! 284: Switch off with \fItime\fR=0.
! 285: The statistics are written to \fIstderr\fR linewise,
! 286: the following values are calculated:
! 287: .RS
! 288: .TP
! 289: \fInow\fR
! 290: Internal clock in msec.
! 291: .TP
! 292: \fIout\fR
! 293: Number of bytes written to stdout since last statistics,
! 294: and number of write operations needed.
! 295: .TP
! 296: \fIbuf\fR
! 297: Number of bytes in the output buffers (lower and upper bound).
! 298: .TP
! 299: \fItime\fR
! 300: Time in msec, for how long the contents of the
! 301: output buffers should suffice (lower and upper bound).
! 302: .TP
! 303: \fIburst\fR
! 304: Size of write burst, i.e. number of bytes prepared to
! 305: be written in a single write operation (lower and upper bound).
! 306: .RE
! 307: .TP
! 308: \fB\-\-badtiming\fR
! 309: In conjunction with a program stream originating from a DVB-s
! 310: digital TV receiver card, You might want to automatically
! 311: correct some of the PCR values produced by that card, to
! 312: prevent discontinuities in the output.
! 313: .SH OVERVIEW
! 314: The multiplexer is designed to run uninterrupted and
! 315: be controlled via \fIstdin\fR and \fIstderr\fR.
! 316: It is designed to process data in real time,
! 317: i.e. if the processing is not performed fast
! 318: enough (e.g. because of low processor performance),
! 319: errors in the resulting data may occur, namely
! 320: concerning the timing.
! 321: The multiplexer may be invoked interactively with
! 322: the streams to process given as command line options
! 323: or with the commands to be processed typed into
! 324: \fIstdin\fR during operation.
! 325: The latter type of usage is also designed for use
! 326: with an user interface front-end, that may
! 327: translate some GUI input to iso13818ps commands
! 328: and filter its responses to be presented to the user
! 329: as appropriate.
! 330: .P
! 331: Three different types of input are supported:
! 332: Paketized elementary streams (PES),
! 333: Program streams (PS),
! 334: Transport streams (TS).
! 335: .P
! 336: Numeric parameters may be given in decimal (e.g. 31)
! 337: or in hex (e.g. 0x1F).
! 338: .SH DETAILS
! 339: The output file or device does not change throughout the
! 340: time the program runs. The input files, however, may vary.
! 341: Also the contents of an input file may vary, but not its
! 342: type. E.g., a file opened as program stream must contain
! 343: valid program stream data up to its end (and including
! 344: any files that are appended to this file with \fB\-\-append\fR).
! 345: .P
! 346: All basic PSI is evaluated contiguously, and changes in
! 347: the configuration (changing PID, etc.) are taken into
! 348: account and tracked. Thus a stream should not get lost
! 349: simply because its PID is changed in the middle of the
! 350: broadcast.
! 351: .SH EXAMPLES
! 352: To convert a program stream file x.PS to a program stream file y.PS,
! 353: and System Header and Stream Map generated about every half second:
! 354: .IP
! 355: $ iso13818ps --fpsi 500 --ps x.PS > y.PS
! 356: .PP
! 357: If the program stream doesn't contain correct PSI,
! 358: the single streams may be extracted one by one. Assuming
! 359: one video stream (0xE0) and mono audio (0xC0):
! 360: .IP
! 361: $ iso13818ps --fpsi 500 --ps x.PS 0xE0 --ps = 0xC0 > y.PS
! 362: .PP
! 363: To bundle two streams originating from video devices and
! 364: send them out to a video output device, e.g.:
! 365: .IP
! 366: $ iso13818ps -F 500 -P /dev/video0 -P /dev/video1 > /dev/video2
! 367: .PP
! 368: .PP
! 369: To invoke the multiplexer for interactive use, it must
! 370: be put in all-time-busy-mode. Subsequently, commands can
! 371: be fed to \fIstdin\fR, e.g. to do the same as with the
! 372: first example:
! 373: .IP
! 374: $ iso13818ps --busy > y.PS
! 375: .br
! 376: fpsi 500
1.1 oskar 377: .br
1.2 ! oskar 378: ps x.PS
! 379: .PP
! 380: This instance of the multiplexer will not cease when the
! 381: end of file in x.PS is reached. To stop the multiplexer,
! 382: either \fBquit\fR or \fBbusy 0\fR may be typed to \fIstdin\fR.
! 383: .P
! 384: To output a movie repeatedly (e.g. seven times):
! 385: .IP
! 386: $ iso13818ps -F 500 --ps thepurpleroseofcairo.PS --repeat = 7 > /dev/video2
! 387: .PP
! 388: Note, that if during the movie is processed, the command
! 389: .IP
! 390: close thepurpleroseofcairo.PS
! 391: .PP
! 392: is issued, and supposed it is not yet processed the seventh time,
! 393: it is not closed, but restarted immediately.
! 394: .P
! 395: To concatenate two movies and output them in sequence:
! 396: .IP
! 397: $ iso13818ps -F 500 --ps rambo1.PS --append = rambo2.PS > /dev/video2
! 398: .PP
! 399: Note, that a file can only be appended to a file, that is
! 400: yet in use (i.e. being processed). Thus, it is not possible
! 401: to append a third movie (rambo3.PS) from within the command
! 402: line. Instead, the processing of the second movie must be
! 403: awaited, and then the following command can be fed to \fIstdin\fR:
! 404: .IP
! 405: append rambo2.PS rambo3.PS
! 406: .PP
! 407: If the source is a transport stream with broken or
! 408: missing PSI (i.e. PAT/PMT), and if further it can
! 409: be assumed, that there is only one program to be found
! 410: in the stream, then the \fIsource program number\fR
! 411: can be specified as \fB0\fR. With the following
! 412: example, one video and one audio stream are extracted
! 413: (the first one found, if more than one exist):
! 414: .IP
! 415: $ iso13818ps -F 500 -T deficient.TS 0 0xE0 -T = 0 0xC0 > complete.PS
! 416: .PP
! 417: .SH "KNOWN PROBLEMS"
! 418: The program might not work in conjunction with device drivers
! 419: that do not deliver or accept data unless a first read or write
! 420: is done on the device. E.g., for a MPEG video data source, that
! 421: does not produce output without being triggered by being read
! 422: from, this program will await the readability of the first
! 423: data infinitely. On the other hand it is obvious that the driver
! 424: should not encode data as long as there is no application that
! 425: will read this data.
! 426: One possibly solution to this dilemma is to patch such a driver
! 427: to interpret the \fIpoll\fR command as an order for data, thus
! 428: triggering the read mechanisms. Analogous considerations hold
! 429: for polling the output device and writing to it.
! 430: .P
! 431: Paketized elementary streams do not necessarily contain
! 432: usable time stamps, so when multiplexing raw PES, streams
! 433: belonging together may be out of sync. This is especially
! 434: noteworthy in case streams shall be demultiplexed and then
! 435: again multiplexed in some way. Results will always be better
! 436: when this remultiplexing takes place entirely within the
! 437: multiplexer, because that way timing information won't get lost.
! 438: .SH BUGS
! 439: End of action sometimes is not detected correctly, which
! 440: causes the multiplexer to hang.
! 441: Nevertheless, it then can be stopped by the \fBquit\fR command.
! 442: .P
! 443: Changing configuration is not printed if the change
! 444: is solely a descriptor coming from a source file.
! 445: .SH "SEE ALSO"
! 446: .BR iso13818ts (1),
! 447: .BR ISO\ 13818-1 ,
! 448: .BR ETSI\ EN\ 300\ 468 .
1.1 oskar 449: .SH AUTHOR
450: Oskar Schirmer (oskar@convergence.de).
LinuxTV legacy CVS <linuxtv.org/cvs>
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to iso13818ps.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [DVB] / multiplexer