Control Server Protocol

Updated July 26, 2017


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 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:


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.


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. A value of 0 selects all audio streams and -1 selects all audio streams and as well as all other streams associated with the program.
CAPTION option {flags filename} In TSReader Pro, toggles the caption decoder on and off with CAPTION ON or CAPTION OFF. CAPTION LOG turns on loggin for the current caption session. The flags field is the sum of the options to enable:: 1 - Log raw user data 2 - log EIA-608 data 4 - log EIA-708 data 8- log PTS/DTS 16 - dump user data 32 - dump EIA-608 odd 64 - dump EIA-608 even 128 - dump EIA-708. This field is followed by the filename. Issuing a CAPTION LOG command without a filename while logging is turned on turns it off.
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. Leaving the filename blank causes the exported data to be sent over the control server socket.
module ON/OFF
Enables and disables the forwarder function in TSReader Professional. The module is the name of the output device shown on the Forward menu. The PIDFILTER sub-command lists the PIDs to not forward - they are seperated by spaces and can be prefixed 0x for hexadecimal.
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, REFRESH followed by the number of milliseconds between graph samples. The SAVE option (followed with a filename) saves the currently active graph as a PNG file and the SEND option sends the same PNG image of the chart over the control server connection. The PNG is sent as hex ASCII, two hex characters per byte with a final single line with a period character terminating the transmission.
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.
mode on/off/name
Turns on logging mode for TSReader Pro. Mode can be either SCTE35 followed by the log filename or the word OFF or TSBITCOUNTER followed by ON or OFF
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.
If the optional password function is used, this command must be sent before any other commands can be sent (other than QUIT).
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. Version 2.8.46d adds the scrambled status of the PID (0 for clear, 1 for encrypted) to the end of the line.
PLAY  output Starts channel playback on the device indicated by output - Stradis, 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 or PROGRAM. Modes ALL and PROGRAM require a filename. With no parameters this returns the record state. TSReader Pro also supports the RECORD ALL PROGRAMS commands which starts the archiving mode - in this case, the filename option is not used.
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.
Syncs the PC's time to the stream time.
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.
PROGRAM prog dest
MUX dest
Enables and disables UDP forwarding in TSReader Professional. The PROGRAM command sets the destination and enables the program over UDP, i.e. UDPFORWARD PROGRAM 1 enables program 1 and UDPFORWARD PROGRAM 1 with no destination disables the PROGRAM. The MUX version of this command has no program number and enables/disables forwarding of the entire mux. UDPFORWARD PROGRAM can be used even if the forwarder is already running - UDPFORWARD MUX requires the forwarder turned off first. STATUS returns the current status of the UDP forwarder.
WINDOW mode Manipulates the TSReader main window. Modes are: MAXIMIZE, MINIMIZE, RESTORE and FOREGROUND.
XMLTV XMLTV data Used to set the EPG data in TSReader when the mux doesn't contain any EPG data. This is used along with the archiver function present in TSReader Pro. Please see the section below for more details of this command.

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.

XMLTV command details

This command is used to set the EPG data for a channel when the mux being processed by TSReader doesn't contain any EPG data. The data sent with the XMLTV command is then used to set the recording times, event description and channel names which are then subsequently used by the archiver mode in TSReader Professional. As a result, this command is only supported in the Professional edition.

Two different sets of XMLTV records need to be sent - first one to set the channel name and the other to set the EPG events.

XMLTV commands should be sent as a single line of text with a carriage-return at the end-of-the-line. The two commands are:

XMLTV <channel>
channel id MPEG program number and the decription of the channel seperated with a - character
transport-stream-ID The transport stream of the mux carrying the channel

Example: XMLTV <channel id="1-MPT HD"><display-name lang="en">MPT HD</display-name><transport-stream-ID>1397</transport-stream-ID><signal-info /></channel>

Once the XMLTV command has been sent for a particular MPEG program, subsequent commands are ignored.

XMLTV <programme>
programme start Year, month, day, hour, minute and second of the event start time. This is in UTC.
program stop Year, month, day, hour, minute and second of the event stop time. This is in UTC.
program channel The same data as sent for the channel id in the XMLTV <channel> command, i.e. program number and decription seperated by a - character.
title The title of the event
desc The description of the event

Example: XMLTV <programme start="20090204133000" stop="20090204153000" channel="1-MPT HD"><title>Suze Orman Women & Money</title><desc>In Suze Orman Women & Money, Suze shares her surprising insights into the complicated, often dysfunctional relationship women have with their money. In the special, Suze also equips women with the financial knowledge and emotional awareness to overcome</desc></programme>

If an event is sent more than once (based on the event start time), duplicates for the same time are ignored. To delete an existing event (for example as a result of a schedule change), send the XMLTV <programme> command again for that event with the title set to **DELETE**.


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

Graph sent via control server socket

Graph saved to file
328 XMLTV channel command completed
329 XMLTV programme command completed
330 Caption decoder has been started
331 Caption decoder has been stopped
332 Caption logging started
333 Caption logging disabled
334 FORWARD PIDFILTER command completed
FORWARD module activated
FORWARD module decactivated
UDPFORWARD activated
UDPFORWARD deactivated
341 Response to the TIMESYNC command
Password accepted
TSBITCOUNTER logging is disabled
TSBITCOUNTER logging is enable
SCTE-35 logging is disabled
SCTE-35 logging is enabled
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 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.
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
556 No RESET value specified
557 No graphs currently active
558 Graph PNG filename wasn't spciefied
559 No XMLTV parameters
560 XMLTV channel id is misformed - needs the program-name format
561 XMLTV programme stop time missing
562 XMLTV programme channel missing
563 XMLTV programme title missing
564 XMLTV programme description missing
565 XMLTV programme channel is misformed - needs the program-name format
566 XMLTV command not recognized
567 XMLTV program has no duration
568  No parameters specified in the CAPTION command
570 Program not selected in the CAPTION command
571 Caption decoder can't be stopped as its not active
572 Caption decoder log can't be enabled because the caption decoder isn't active (use CAPTION ON first)
573 Parameters for the CAPTION LOG command are missing
574 CAPTION LOG filename missing
575 CAPTION LOG flags are zero - this would mean logging nothing
576 CAPTION LOG is already active - stop with CAPTION LOG (no other parameters) and then repeat the command
577 CAPTION command not understood (not ON, OFF or LOG)
XMLTV REMAP filename wasn't provided
XMLTV post export command not specified
An error occurred when sending a graph's PNG file over the socket
An error occurred writing a graph's PNG file
The STALL sub-command parameter wasn't understood
The FORWARD command didn't have any parameters
Not enough parameters for the FORWARD command
The forwarder module specified was not found
The forwarder can't be activated since it's already active
The forwarder module cannot be activated
The forwarder module can't be decativated since it's not already active
The forwarder module didn't deactivate
Unknown FORWARD sub-command
The UDPFORWARD command had no parameters
UDPFORWARD can't be started since it's already running
The UDP forwarder can't be stopped since it's not already running
no longer used
Invalid UDPFORWARD PROGRAM program number
UDPFORWARD PROGRAM command couldn't open the Windows registry
The UDPFORWARD MUX command cannot be used when the UDP forwarder is running
UDPFORWARD MUX command couldn't open the Windows registry
Unrecognized UDPFORWARD sub-command
600 Problem enabling the program to forward with UDPFORWARD PROGRAM
Problem disabling the program to forward with UDPFORWARD PROGRAM
The PASSWORD command is incomplete (no password specified)
The password is incorrect
The LOG command is incorrectly formatted
Response when attempting  to turn off TSBITCOUNTER logging when its not enabled
Response when attempting to turn on TSBITCOUNTER when its already turned on
LOG TSBITCOUNTER is not followed by ON or OFF
Attempted to turn off SCTE-35 logging that's not enabled
Attemping to turn on SCTE-35 logging that's already enabled
SCTE-35 log file could not be opened
Unknown LOG mode command

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.