SageTV Server Streaming Protocol 7/31/2004
Copyright 2001-2008 Frey Technologies, LLC. All rights reserved.

Here's the first set of information on network encoding that applied to V1.4:

The protocol accepts only a single command at a time. The server should ack it (everything should return "OK\r\n" or the appropriate value plus "\r\n") and then it may close the connection after it flushes the socket stream. The server will return a descriptive error message if there's a problem instead of the OK response.

Here's the commands:
client send: STOP\r\n
server responds: OK\r\n
This should stop any encoding on that encoding server

client send: START sourceName|channel|durationMilliseconds|filename|encodingQuality\r\n
server responds: OK\r\n
This starts a recording according to the specified parameters. ALL parameters must be there, do not use an empty string for any parameters
sourcename - This is the capture device name appended with the source name. For "Hauppuge WinTV PVR PCI II Capture #2" on the "TV Tuner" this would be "Hauppauge WinTV PVR PCI II Capture #2 TV Tuner"; without any quotes.
channel - channel to tune to, if using S-Video or Composite this will be ignored if no IR transmitter is configured.
durationMilliseconds - how long the capture should go for. This can be stopped early with the STOP commmand.
filename - the filename to capture to
encodingQuality - the recording quality to use; this should match one of the names in SageTV Recorder (i.e. Great, DVD Long Play, etc.)

client send: SWITCH channel|filename\r\n
server responds: OK\r\n
This starts continues recording, but just changes the channel and the file that it is writing to. It uses the capture device from the last START command. ALL parameters must be there, do not use an empty string for any parameters
channel - channel to tune to, if using S-Video or Composite this will be ignored if no IR transmitter is configured.
filename - the filename to capture to

client send: GET_SIZE\r\n
server responds: size in bytes\r\n
This returns the amount of data that has been written to the last started capture file in bytes, \r\n terminated. 

client send: NOOP\r\n
server responds: OK\r\n
This is a 'ping' used by SageTV to detect if an encoder is alive or not, SageTV will actively add/remove them as they go online/offline

SageRecorder 1.3.2 implements this EncodingServer interface. If you set the encoding_server property to be a number, then it'll open up a port on that address as an encoding server.


Updates:

1. There's 2 new commands BUFFER and BUFFER_SWITCH. These are just like START and SWITCH, but instead of the end time it sends the buffer size. The data should be written to a circular file with a file size matching the buffer size. This is only needed for direct stream viewing which occurs in Channel Setup and in Color Calibration, otherwise this call is never used. File size calls in these modes should return the accumulated bytes written, not the file size or file position.

2. Added "GET_FILE_SIZE filename" command.  It works just like GET_SIZE, but it takes a filename as the argument. This resolves asynchornicity issues to ensure that the file size queried for is actually the one returned (in case the recording got changed asynchronously).

3. Added 2 new commands TUNE and AUTOTUNE. These are only used in direct stream control situations like #2. They each take one parameter which is the channel number to tune (or autotune) for the currently recording device.

INFO ON RUNNING MULTIPLE ENCODING SERVERS:

You can run more than one instance by making copies of the SageRecorder folder after you've installed it.

To run multiple encoding servers on a single PC; just use a difference encoding_server property in the SageRecorder.properties file for each instance. It should be a valid TCP/IP port number.

4. For the VERSION command You should just return a string with the version number followed by \r\n. If your version is <2 then you only accept one command per connection. If your version is >=2 then the connection can be kept alive.

For version 3 or higher; it'll give you an extra parameter for the stop, autotune, switch, buffer_switch, tune, autoscan, autoinfoscan commands of the capture device name as the first parameter (so multiple capture devices can be handled by one encoding server). And for the buffer, start, buffer_switch, switch commands it will also optionally insert an extra token in the second slot which is the 'upload ID' and can be used as a key to stream the file back to the server instead of writing it to disk directly (its an authentication token to prevent unauthorized uploads).


SUPPORT:

Please direct all questions to jeff@freytechnologies.com