Difference between revisions of "ExternalRecorder"

Revision as of 23:06, 31 July 2014

External Recorder

As of v0.28-pre-1073-g44d6bb7 mythbackend has the ability to communicate with an external "Black Box" application for recording. This external application module does whatever it needs to do to generate a transport stream which mythbackend then reads and records.

MythTV will be told about such a module when adding an 'External Recorder' to its list of "capture cards". MythTV will be told the name of the external application (module) as well as any parameters to pass to the external application. For example, I have written an 'External Recorder' module called "mythfilerecorder". This module reads a MPTS file directly off of disk, and feeds the stream into MythTV. Configuring mythbackend to use the "mythfilerecorder" recording device is as simple as creating a "capture card" of type EXTERNAL, and telling it that the application path is "/usr/local/bin/mythfilerecorder --infile /storage/test.ts".

When mythbackend wants to start a recording using the 'External Recorder', it executes the application, and then communicates with it via STDIN, STDOUT and STDERR. Commands will show up on the applications STDIN. The application will respond to the commands via its STDERR. When told to stream a MPTS (or SPTS) the application will send the data out STDOUT.

For example, mythbackend will exec "/usr/bin/mythfilerecorder --infile /storage/test.ts", and then send the command "HasTuner?", which mythfilerecorder will read on its STDIN. mythfilerecorder will respond "OK:No" on its STDERR. mythbackend reads the "OK:No" response and concludes that mythfilerecorder does not support tuning. mythbackend will ask the external applications some other questions to figure out its capabilities, and finally will tell the application that it is ready to start recording by sending the "StartStreaming" command. mythfilerecorder will send "OK:Started" to STDERR, and start preparing to send MPTS data to STDOUT.

These are the commands that the external recorder application (module) needs to understand:

• "Version?" (Valid respons is "OK:" followed by an version information the application wishes to provide.
• "IsOpen?" (Valid response is "OK:Yes" or "OK:No") Is the recorder application in a good state?
• "CloseRecorder" (Valid response is "OK:Terminating", and the application will shut down)
• "HasTuner?" (Valid response is "OK:Yes" or "OK:No") Does the recorder have a tuner?
• "HasPictureAttributes?" (Valid response is "OK:Yes" or "OK:No") Does the recorder support picture adjustments (hue, brightness, etc.) ?
• "LockTimeout?" (Valid response is "OK:<value>", where value indicates a value in ms indicating when to give up on acquiring a signal lock)
• "SignalStrenghtPercent?" (Valid response is "OK:<value>", where value indicates the strength of the signal in a range of 0-100). App should return "OK:100" if the concept of a signal strength does not apply.
• "HasLock?" (Valid response is "OK:Yes" or "OK:No") Used for DBS type recorders. If not applicable, app should return "OK:Yes"
• "StartStreaming" (Valid response is "OK:Started", and the Transport Stream should be sent to STDOUT)
• "StopStreaming" (Valid response is "OK:Stopped", and data should no longer be sent to STDOUT)
• "FlowControl?" (Valid response is "OK:XON/XOFF" or "OK:Polling")
• "SendBytes:<value>” (When using Poll flow control) -- deprecated as xon/xoff works better
• "XON" (When using XON/XOFF flow control)
• "XOFF" (When using XON/XOFF flow control)

If the application returns "OK:Yes" to "HasTuner?", then it needs to handle:

• "TuneChannel:<value>"

<value> will be a channel number, possibly looking like 1234-23 to indicate major-minor elements.

If the application returns "OK:Yes" to "HasPictureAttributes?", then it also needs to deal with these commands:

• "SetBrightness:<value>"
• "SetContrast:<value>"
• "SetColour":<value>"
• "SetHue":<value>”

The value included in the "SendBytes:<value>" query indicates how much data mythbackend can handle without blocking. The application can send less or more than that value.

When the external module receives the "SendBytes:<value>" or "XON" command, it will respond in one of four ways via its STDERR:

• "OK" -- which indicates that Transport Stream data is forthcoming via its STDOUT
• "OK: some descriptive text" -- same as just "OK", but allows the external module to tell mythbackend to log the external module's 'state'.
• "WARN: some descriptive text" -- which indicates that the external module is not able to send any bytes right now, but to try again.
• "ERR: some descriptive text" -- which indicates that the external module is in an error state, and the recording needs to abort and possibly restart.

This enables a "flow control" between the external module and mythbackend and allows the external module to report problems.

The external module has the burden of buffering the transport stream. If mythbackend does not read the transport stream fast enough from the external module, the external module will have to decide if it needs to increase its buffer, or if it should drop packets. If the external module needs to drop packets, that might be a case where it would respond with something like "OK: # packets have been dropped".