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. 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. |
FORWARD | PIDFILTER 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. |
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. |
PASSWORD |
password |
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 - 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. 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. |
TIMESYNC | 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. |
UDPFORWARD |
ON OFF PROGRAM prog dest MUX dest STATUS |
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
224.0.0.1:1234 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**.
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 |
6xx |
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 |
335 |
FORWARD module activated |
336 |
FORWARD module decactivated |
337 |
UDPFORWARD activated |
338 |
UDPFORWARD deactivated |
339 |
UDPFORWARD PROGRAM completed |
340 |
UDPFORWARD MUX completed |
341 | Response to the TIMESYNC command |
342 |
Password accepted |
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 |
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) |
578 |
XMLTV REMAP filename wasn't
provided |
579 |
XMLTV post export command not
specified |
580 |
An error occurred when sending a
graph's PNG file over the socket |
581 |
An error occurred writing a
graph's PNG file |
582 |
The STALL sub-command parameter
wasn't understood |
583 |
The FORWARD command didn't have
any parameters |
584 |
Not enough parameters for the
FORWARD command |
585 |
The forwarder module specified
was not found |
586 |
The forwarder can't be activated
since it's already active |
587 |
The forwarder module cannot be
activated |
588 |
The forwarder module can't be
decativated since it's not already active |
589 |
The forwarder module didn't
deactivate |
590 |
Unknown FORWARD sub-command |
591 |
The UDPFORWARD command had no
parameters |
592 |
UDPFORWARD can't be started
since it's already running |
593 |
The UDP forwarder can't be
stopped since it's not already running |
594 |
no longer used |
595 |
Invalid UDPFORWARD PROGRAM
program number |
596 |
UDPFORWARD PROGRAM command
couldn't open the Windows registry |
597 |
The UDPFORWARD MUX command
cannot be used when the UDP forwarder is running |
598 |
UDPFORWARD MUX command couldn't
open the Windows registry |
599 |
Unrecognized UDPFORWARD
sub-command |
600 | Problem enabling the program to
forward with UDPFORWARD PROGRAM |
601 |
Problem disabling the program to
forward with UDPFORWARD PROGRAM |
602 |
The PASSWORD command is
incomplete (no password specified) |
603 |
The password is incorrect |
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