TSReader Control Server Protocol

TSReader
Control Server Protocol

Updated November 29, 2004

Introduction

The full version of TSReader (not TSReader Lite) includes 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.

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.

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.

EXPORT mode filename Exports SI tables from TSReader. mode can be HTML, XML or XMLTV and filename equals the file to export. For HTML export, all tables are exported.

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.

HELP Sends a list of commands supported by the server

PLAY output Starts channel playback on the device indicated by output - Roku, Stradis, XNS and VLC1 through VLC16 are supported.

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.

PROGRAM {progam to select} Either selects the current program or returns a list of programs in the currently tuned mux.

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 Stalls TSReader while it parses SI tables. Timeout is specified in 1/10ths of a second - STALL 300 would stall for 30 seconds maximum.

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.

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 readme file documents these parameters.

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

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

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.

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.

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.
EXPORT	mode filename	Exports SI tables from TSReader. mode can be HTML, XML or XMLTV and filename equals the file to export. For HTML export, all tables are exported.
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.
HELP		Sends a list of commands supported by the server
PLAY	output	Starts channel playback on the device indicated by output - Roku, Stradis, XNS and VLC1 through VLC16 are supported.
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.
PROGRAM	{progam to select}	Either selects the current program or returns a list of programs in the currently tuned mux.
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	Stalls TSReader while it parses SI tables. Timeout is specified in 1/10ths of a second - STALL 300 would stall for 30 seconds maximum.
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.
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 readme file documents these parameters.

2xx	Informational responses
3xx	Acknowledgement response
5xx	Error responses

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

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.

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.