Annotation of multiplexer/iso13818ps.1, revision 1.13

1.1       oskar       1: .\" Man page for iso13818ps
                      2: .\"
1.4       oskar       3: .\" Copyright (C) GPL 2001, Convergence Integrated Media GmbH
1.11      oskar       4: .\" Copyright (C) GPL 2004..2005, Oskar Schirmer
1.1       oskar       5: .\"
1.13    ! oskar       6: .TH iso13818ps 1 "March 4th, 2005" "1.0.8" "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
1.3       oskar      94: is made to close the file on a clean audio or video frame boundary.
1.2       oskar      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
1.5       oskar     311: correct broken PCR values produced by that card, to
                    312: avoid discontinuities in the output.
1.2       oskar     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
1.6       oskar     318: enough (e.g. because of low system performance),
1.2       oskar     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
1.6       oskar     450: Oskar Schirmer (schirmer@scara.com).

LinuxTV legacy CVS <linuxtv.org/cvs>