| TSReader |
Control Server Protocol |
Introduction
The TSReader Standard and Professional include a remote control server. This allows other applications to control many TSReader functions using a standard TCP/IP socket. The protocol is very similar to the FTP control channel, POP3 and SMTP protocols.
TSReader sends one or more lines of information starting with a three digit completion code terminated with a carriage-return/line-feed pair. TSReader accepts commands in either upper or lower case and expects parameters to follow a space after the command. If no parameters are supplied, there should be no space after the command. Input commands are terminated with a carriage-return - line-feed characters are ignored.
If you want to experiment with the control server without writing any software, you can use the Windows telnet application to connect. Assuming the control server is enabled, running on port 1399 and TSReader is running, you would simply click Start/Run and type telnet 127.0.0.1 1399 to get connected.
Port and Registry Settings
TSReader uses a default IP port of 1399 for the control server connection. This port number may be changed by using the Control server settings dialog from TSReader or by editing the registry. By default, the control server is not enabled - it must be enabled by the user or via the registry.
If you want to change the control server settings by changing the registry to meet your needs, edit these values:
HKEY_CLASSES_CURRENT_USER\Software\COOL.STF\TSReader
DWORD:ControlServerEnabled = 0 to disable control server =1 to enable control server
DWORD:ControlServerPort = IP port for the control server connection
Only one connection is supported at a time and this is deliberate to prevent more than process attempting TSReader control. If you use multiple profiles in TSReader simply set each profile's Control Server port to a different value.
Commands
These commands are currently supported by TSReader's control server:
| Command | Parameters | Description |
| ? | Sends a list of commands supported by the server | |
| AUDIO | {stream-number} | Without parameters sends the current audio streams in the mux. Followed by a number (starting from 1), selects an audio stream for recording and streaming. |
| DISEQC | message | Sends a DiSEqC message on supported satellite interfaces. Each DiSEqC message byte should be two-character hex ascii. For example "DISEQC E0 10 38 C0" is used to select port 1 on an uncommited switch. |
| EXPORT | mode filename | Exports SI tables from TSReader. mode can be HTML, XML or XMLTV and filename equals the file to export. HTML (which exports all HTML tables) can be substituted with HTML-nnn - nnn is the ASCII HEX combination of these bit values to select which tables are exported (all in hex): 1-PAT, 2-PMT, 4-CAT, 8-NIT, 10-SDT, 20-EIT,40-SDT only for this mux,80-PID chart,100-thumbnails,200-MPEG-2 stats,400-source info. |
| GRAPH | mode | Display graphs. Mode can be 0-hide any current graph, 1-Active PIDs by rate, 2-Active PIDs by PID, 3-PID usage 2D pie, 4-PID usage 3D pie, 5-Mux usage stacked area, 6-Mux usage line, 7-Video rate area, 8-Video rate line, 9-Program Usage, 10-Video Composition, 11-Signal strength. Also supported are REALTIME and AVERAGE to switch the graphing mode and REFRESH followed by the number of milliseconds between graph samples. |
| HELP | Sends a list of commands supported by the server | |
| INFO | mode | Sends information about TSReader. Modes are: SOURCE for info about the source and MPEG for statistics related to the transport stream. |
| MANUALCHANNEL | program pcr-PID es-type es-PID | Defines a manual channel independant of the stream's PSI. All values except the program number are hex. For example to define program 1 with a PCR PID of 0x1ffe, an MPEG-2 video stream on PID 0x0030, MPEG-1 audio on PID 0x0031 and AC-3 audio on PID 0x0032, one would issue: MANUALCHANNEL 1 1ffe 02 0030 03 0031 81 0032. |
| PIDS | Lists active PIDs in the mux. Response contains PID (hex), continuity errors on PID, TEI errors on PID, percentage of mux, stream bitrate in Mbps and a description of the PID's usage. | |
| PLAY | output | Starts channel playback on the device indicated by output - Roku, Stradis, XNS and VLC1 through VLC16 are supported. |
| PROGRAM | {progam to select} | Either selects the current program or returns a list of programs in the currently tuned mux. |
| QUIT | Terminates the server connection. Closing the socket has the same effect. | |
| RECORD | {mode filename} | mode can be ALL, D-VHS or PROGRAM. Modes ALL and PROGRAM require a filename. With no parameters this returns the record state. |
| RESET | mask | Resets the TSReader counters based on the decimal bitmask. Bit 0=Continuity Counters, bit 1=TEI Counters, bit 2=CRC Counters, bit 3=Section Counters, bit 4=PID chart counters. |
| SETTING | {subparameter true-false} | By itself, the SETTING command returns the status of the settings that can be changed by this command. Subparameter is the name of the parameter to change, true-false is the string "True" or "False" to turn the value on and off. See below for a list of settings that can be changed with this command. |
| SETVLC | {configuration command} | Displays or sets the VLC configuration. configuration is the VLC number (1 through 16) and command is the command-line to pass to VLC. Currently there's no way to update the VLC description. |
| SOURCE | {sourcename} | Changes the source in TSReader or returns a list of the currently available sources. To set the source name, follow SOURCE by the name of the source to set not including the Sources folder name - for example "SOURCE TSReader_Twinhan1020.dll". When SOURCE returns a list of available sources, TSReader sends the current source with an "*" at the end of the line. Once the source has been set, use the TUNE command to tune and restart TSReader. |
| STALL | timeout {parameter} | Stalls TSReader while it parses SI tables. Timeout is specified in 1/10ths of a second - STALL 300 would stall for 30 seconds maximum. The optional parameter is THUMBNAILS which tells TSReader to wait for both table decoding and thumbnail generation to complete. |
| STOP | Stops the current recording or playback | |
| TERMINATE | xyzzy | Closes TSReader. You must specify the "xyzzy" sequence in lower case for the TERMINATE command to work - this is done to prevent accidental shutdowns. |
| THUMBNAIL |
program-number filename command {option} |
Writes the video thumbnail for the selected program to the filename specified or controls thumbnail settings. For saving thumbnail, always use a JPG extension since that's the format TSReader writes in. For controlling thumbnail generation, commands are OFF, LOW, NORMAL and HIGH (which reference the thumbnail priorities) and REFRESH n where n is the refresh rate for thumbnails in seconds. |
| TUNE | varies | Restarts TSReader's source after re-tuning with the parameters specified. Parameters are the same as the command-line interface for the source - the command-line documentation shows these parameters. |
| WINDOW | mode | Manipulates the TSReader main window. Modes are: MAXIMIZE, MINIMIZE, RESTORE and FOREGROUND. |
SETTING command subparameters
| Subparameter Name | Menu Option | Description |
| IGNORE_EITSDT | Ignore DVB SDT and EIT | Controls if TSReader processes data in the SDT and EIT tables. Useful for looking at muxes with a lot of SDT/EIT entries on machines where little memory is available since TSReader stores all the SDT/EIT in memory. |
| SDT_CURRENT_MUX | SDT only for current mux | Tells TSReader to ignore SDT entries for channels on muxes other than the current one. Useful when using the HTML/XML export on networks where all channels in the network are defined. |
| PAST_EIT | Keep past EIT data | TSReader keeps entries in the EIT in memory. If left on a mux with valid EIT data over time, TSReader will run out of memory as new events are transmitted in the EIT. So TSReader checks all EIT entries each time a new EIT entry is added to see if any events are in the past - if they are, they're removed from memory. However, if looking at a recording of a stream, EIT events will inherently be in the past and if you wanted to analyze the EIT's transmitted in the recording, this option must be on. |
| IGNORE_CRC | Ignore table CRC errors | Many tables sent in MPEG-2 transport streams contain a CRC to ensure the data received is correct before it's processeed. By default TSReader will discard any sections sent in tables that have incorrect CRC. This can be overridden but beaware that this mode of operation is not supported and may result in TSReader crashing as it tries to parse what is potentially garbage data. |
| IGNORE_DCIIPMT80 | Ignore DCII PMT ch. 80 | Many Digicipher II muxes have a pseudo entry in the PAT pointing to channel 80, but there's never a PMT for the channel. If this option is enabled, TSReader will ignore the PMT for channel 80 on DCII networks speeding up parsing. |
| IGNORE_PMT_ABOVE_65500 | Ignore PMTs above ch. 65500 | Some PATs (particulally in Digicipher II muxes) have entries for channels higher than 65500 which point to non-existant PMTs. Turning on this option will cause TSReader to ingore any channels with the service number greater than 65500 which may speed up parsing. |
| PLAIN_CA_DESCRIPTORS | Plain CA descriptor decoding | When False, TSReader attempts to decode the operator ID tag that's embedded into the CAT on some networks. When True, TSReader will decode any descriptors in the CAT that are private as hex/ascii data. |
| KEEP_SPECIAL_XML | Keep special XML characters | When exporting to XML the colon character : is removed as it causes syntax errors in the XML. Turning this option on keeps this character. |
Responses
All responses from TSReader's control server are prefixed with a three digit decimal number to allow easy parsing by non-human clients. Responses are grouped into three ranges to allow even easier parsing of results:
|
|
Informational responses |
|
|
Acknowledgement response |
|
|
Error responses |
| Response | Description |
| 200 | The control server sign-in message - conveys TSReader version number when first connecting. |
| 201 | Responses to the HELP or ? command |
| 202 | Responses to the PROGRAM command without parameters. Data sent is the 5-digital decimal program number followed by either the short SDT channel name for DVB muxes or the Service Name from the TCVT for ATSC muxes. This data is repeated for each channel defined in the PAT or created with the manual channel feature. The currently selected program (if any) is indicated by an asterix at the end of the line. |
| 203 | Responses to the SOURCE command without parameters. TSReader sends the names of the sources with the currently selected source indicated by an asterix at the end of the line. |
| 204 | Responses to the SETVLC command without parameters. TSReader sends the VLC configuration number along with the description. |
| 205 | Further responses to the SETVLC command without parameters. TSReader sends the VLC command for the configuration previously sent with a 204 response. |
| 206 | Responses to the AUDIO command without parameters |
| 207 | Responses to the RECORD command without parameters |
| 208 | Responses to the INFO command |
| 209 | Responses to the PIDS command |
| 210 | Responses to the SETTING command without paramters |
| 300 | Program specified in the PROGRAM command was sucessfully selected |
| 301 | TERMINATE starting. This is likely to get returned but depending on the speed of the machine may not be. Monitoring the validity of this socket connection may be a better way to determine when TSReader has indeed terminated. |
| 302 | The PLAY command is starting playback on the output specified. |
| 303 | The STOP command is proceeding. |
| 304 | The RECORD command is starting |
| 305 | The VLC configuration command was updated. |
| 306 | The record/stream audio stream has been set in response to the AUDIO command |
| 307 | The source has been updated by the SOURCE command. Now the TUNE command should be sent to restart the source |
| 308 | Source restarted - sent in response to the TUNE command |
| 309 | XML or HTML has been exported sucessfully with the EXPORT command |
| 310 | The GRAPH command was successfully completed. |
| 311 | The STALL command completed and tables are decoded ready for EXPORT |
| 312 | The STALL command timed-out. Tables are still being updated. |
| 313 | THUMBNAIL command sucessful. |
| 314 | PROGRAM command has completed. |
| 315 | INFO command has completed. |
| 316 | WINDOW command has completed. |
| 317 | PIDS command has completed. |
| 318 | The THUMBNAIL command (other than write) has completed. |
| 319 | Graph mode has been switched to REALTIME. |
| 320 | Graph mode has been switched to AVERAGE. |
| 321 | Graph refresh rate has been updated. |
| 322 | Manual channel added. |
| 323 | SETTING has been updated successfully |
| 324 | DISEQC sequence sent |
|
|
Specified counters reset |
| 500 | Unrecognized command was sent |
| 501 | Invalid program number specified in the PROGRAM command |
| 502 | Program number specified doesn't exist in the current mux |
| 503 | TERMINATE command not complete |
| 504 | TERMINATE command-sequence incorrect - you didn't specify xyzzy on the TERMINATE command |
| 505 | PLAY command incomplete - must include the output device |
| 506 | Already playing - TSReader is currently playing a service - the STOP command should be issued before a new PLAY command. |
| 507 | No program was selected for playback/record - the PROGRAM command should be use to set the channel to playback or record. |
| 508 | The output device in the PLAY command is incorrect. |
| 509 | The STOP command is ignored because recording or playback is not currently active |
| 510 | No filename was specified for the RECORD command |
| 511 | Record mode was not valid. Current record options are ALL, D-VHS and PROGRAM |
| 512 | No parameters for the EXPORT command |
| 513 | No filename given for the EXPORT command |
| 514 | EXPORT mode was not valid. Current export options are HTML, XML and XMLTV |
| 515 | VLC configuration number incorrect in the SETVLC command. |
| 516 | Invalid audio track specified in the AUDIO command |
| 517 | Recording is not currently active (response to the RECORD with no paramters command) |
| 518 | Unable to locate the source name specified in the SOURCE command |
| 519 | The source name specified in the SOURCE command doesn't refer to a valid TSReader source file. |
| 520 | Unable to open the specified file for the EXPORT command |
| 521 | No parameters were specified in the TUNE command. Even if the source doesn't take any parameters (like the Linear Systems ASI card), you still need a space after the TUNE command. |
| 522 | The source rejected the parameters specified in the TUNE command. |
| 523 | No parameters were specified on the GRAPH command. |
| 524 | The GRAPH mode parameter is incorrect. |
| 525 | The STALL command is missing parameters. |
| 526 | The STALL timeout is incorrect. |
| 527 | The parameters on the HELP command-line aren't recognized. |
| 528 | No parameters specified in the THUMBNAIL command |
| 529 | No filename specified in the THUMBNAIL command |
| 530 | Invalid program number range in the THUMBNAIL command (valid range is 1 through 65535) |
| 531 | Invalid program number for the THUMBNAIL command (program is not present in the current mux) |
| 532 | No video thumbnail exists for the program (THUMBNAIL command) |
| 533 | There was a problem writing the thumbnail file specified. |
| 534 | No parameters specified for the INFO command |
| 535 | INFO command mode incorrect. |
| 536 | No parameters specified for the WINDOW command. |
| 537 | WINDOW command parameter incorrect. |
| 538 | No refresh rate provided with the GRAPH REFRESH command. |
| 539 | Channel number or PCR PID incorrect for MANUALCHANNEL. |
| 540 | No parameters specified with MANUALCHANNEL. |
| 541 | Invalid program number for MANUALCHANNEL. |
| 542 | Channel already exists. |
| 543 | Invalid PCR PID for MANUALCHANNEL. |
| 544 | Invalid elementary stream parameters in MANUALCHANNEL. |
| 545 | No elementary streams were specified with the MANUALCHANNEL command. |
| 546 | Too many channels defined. |
| 547 | SETTING subparameter or value missing |
| 548 | SETTING true/false setting incorrect |
| 549 | SETTING subparameter incorrect |
| 550 | Source doesn't support DiSEqC positioner commands |
| 551 | Source doesn't contain a DiSEqC entry-point |
| 552 | No parameters for the DISEQC command |
| 553 | Invalid DiSEqC sequence |
| 554 | No DiSEqC message found |
|
|
No counters reset mask specified |
Sample Code
Here's a sample Perl script that connects to the Control Server and displays a menu of options: Print programs in a mux, Display a graph, switch to a multicast UDP stream, and Play a program via VLC. You'll need to have Perl installed and also download telnet.pm (Google for it) and put it into the same folder as the script. The script assumes TSReader is running on the same PC, i.e. 127.0.0.1