TSReader

Control Server Protocol


Updated January 23, 2008

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:

2xx
Informational responses

3xx
Acknowledgement response

5xx
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

325
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

555
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