TSReader

Source Modules


Updated August 5, 2008

Note: This document is currently being updated.

Introduction

TSReader internally receives the MPEG-2 transport stream (TS from now on) from Windows DLLs that we dub Source Modules. The job of the Source Module is to take the MPEG-2 TS data from the hardware interface and put it into a circular buffer. There are many different source modules included in TSReader: ones for actual hardware interfaces like satellite and terrestrial tuner cards, for network delivered streams like UDP and RTP multicast and also from files containing recordings of MPEG-2 TS muxes.

This document is written for developers that want to interface their own hardware to TSReader. A knowledge of C and/or C++ is assumed.

Requirements

Each Source Module DLL is placed into the TSReader/Sources folder. The DLL must have a prefix of "TSReader_" - this allows you to include your own support files and have them not collide with our DLLs (prefix with your Source Module name).

Each Source Module DLL needs to export a number of named functions, some of which are optional. The following table shows the export definitions:

Name Optional Function
     
TSReader_Init N Called just after TSReader loads the Source Module DLL. In this call, the hardware interface should be initialized.
TSReader_DeInit N Called after TSReader shuts down or if the user uses the Restart Source function
TSReader_Start N Will be called when TSReader is ready to accept the stream. This is where you should enable your DMA and start a data pump thread.
TSReader_Stop N Called by TSReader when the stream needs to stop. Here you disable your DMA and shutdown your data pump thread.
TSReader_Tune N Tunes the hardware - this does not display any dialog - just an error if the tuning didn't work
TSReader_GetDescription N Returns a description and capability flags of the source module. May be called at any time (before Init() is called).
TSReader_ParseCommandLine N Before the TuneDialog() function is called, TSReader calls this with any text remaining on the TSReader command-line. There are standard parsing functions exported by the source helper DLL - if they return valid data, you can use the values returned and skip the TuneDialog() function.
TSReader_TuneDialog N Just before the Tune() call, this function is used to give the source a chance to display a tuner dialog. The source helper DLL has many standard tuner dialogs for many different RF and network types - or you can implement your own. If the ParseCommandLine() function returned valid data, no dialog should be shown and the Tune() function should be supplied with the data returned.
TSReader_PIDManagement N If your hadware has a demux, TSReader will call this function to select which PIDs it needs to process. Since most hardware returns the entire TS, typically this function will be defined but not actually implemented.
TSReader_IsPIDActive N Returns TRUE if the specified PID is active. TSReader uses this to set the PID chart colors for PIDs that in the stream but not currently selected in the demox. Since most hardware these days doesn't use a demultiplexor, this function will normally just return TRUE.
TSReader_SetChannel Y  
TSReader_GetSignalString Y Called at a 1Hz rate by TSReader to obtain a signal string to be displayed in the main TSReader window
TSReader_GetTunerString Y Also called at a 1Hz rate to get the tuner parameters for the main TSReader window
TSReader_SendDiSEqC Y Called when TSReader wants a DiSEqC string sent
TSReader_GetSyncLossCount Y TSReader uses this call to obtain the number of sync losses in the stream
TSReader_GetRetuneCount Y And this call for the number of times tuner lock has been lost.

The SOURCESTRUCT

Take a look in the TSReader_SampleSource folder at the sources.h file. It contains the definition of the SOURCESTRUCT that TSReader uses to communicate with source modules.

Inside this struct is another struct called TSBUFFERS that contains pointers to the ring buffer used to feed data in. The source module writes up to 128K (slightly less since this is multiples of 188 byte TS packets) into the first buffer, sets the size of the data available and then bumps a counter of the number of outstanding packets along with a byte counter that's used to drive the "Last Sec" value in the main TSReader window. All of these counts are protected by standard Windows CRITICAL_SECTION structures so that the code can be run across multiple threads.

The Source Helper DLL

TSReader exports many functions that will be of use to developers writing their own source modules. The definition prototypes are included in the sources.h file and the TSReader_SampleSource folder includes the lib file needed.