Developers Downloads Licenses Products Help datatype
Home Page SummaryBugsListsNewsDoxygenCVSFiles
 
datatype
Navigation

[History]  

From Helix Community

Jump to: navigation, search
DTR-USR-001-1.0

Developer Guide to dtdriver framework

Revision History
-----------------+-------------+------------------------------------+---------
Name | Date | Reason For Changes | Version
-----------------+-------------+------------------------------------+---------
Milko Boic | Nov-05-2004 | Initial Version | 1.0
| | |
-----------------+-------------+------------------------------------+---------


Table of contents:
==================

1. Introduction

2. dtdriver architecture

3. dtdriver/engine - the framework kernel
3.1. dtdriver/engine interfaces
3.2. Integrating applications with dtdriver/engine

4. dtdriver/dtdrplin - framework SDK
4.1. dtdriver/dtdrplin interfaces
4.2. Integrating applications with dtdriver/dtdrplin

5. Source Handlers
5.1. Structure of Source
5.2. Source Handler Interface

6. dtdrive - media processing tool

7. dtdrtest - dtdriver/dtdrplin unit test tool

8. Appendix:

A. dtdriver options
A.1. Engine built-in data processing tools
A.1.1. A/V sync and frame rate adjustment
A.1.1. Decrypting
A.1.2. Decoding
A.1.3. Encoding
A.1.4. File writer configuration
A.1.5. Human readable output
A.1.6. File reading mode selection
A.2. Data source controls
A.2.1. Bitrate selection
A.2.2. Dynamic bitrate switching
A.2.3. Start Offset
A.3. Performance analysis tools
A.3.1. Execution timing
A.3.2. Heap allocation profiling
A.3.3. Heap allocation leak detection

B. Common Helix DNA interfaces
C. dtdriver Helix DNA code location references
D. dtdriver build targets and profiles
E. Standardized file and stream header properties

F. File and stream headers of common formats
F.1. Uncompressed Audio
F.2. Uncompressed Audio and Video


1. Introduction

Datatype driver framework allows for building applications that have need 
for leveraging Helix DNA Datatypes and filesystem:
- file formats
- renderers/decoders
- encoders
- file writers
- local or network file systems
Typically, such applications will deal with file parsing, trnsformatting,
decoding or transcoding of datatypes supported by Helix DNA.

The framework can also support DRM and thus be used for transcrypting.

The framework is native to Helix DNA architecture and as such written in
C++, fully integrated with Helix DNA common libraries and Helix DNA build 
system.


2. dtdriver architecture

+------------------------------+ +----------------------------------+
| dtdrtest (sample application:| | dtdrive (sample application: |
| dtdrplin unit test)| | media processing tool) |
+------------------------------+ | |
 : | |
+------------------------------+ | |
| dtdriver/dtdrplin (framework | | | 
| SDK) | | | 
+--------+---------------------+---+----------------------------------+
 : | dtdriver/engine (framework kernel) |
 : | |
 : | |
 : +------------------------------------------------------------+
 :  :
 :  :
+----+ +- ... -+ +----+ +----+ +----+ +-- ... --+ +----+ +----+ 
| | | | | | | | | | | | | | | |
|Source Handler Plugins| | Datatype and Filesystem Plugins |
| | | | | | | | | | | | | | | |
+----+ +- ... -+ +----+ +----+ +----+ +-- ... --+ +----+ +----+

Figure 1 - dtdriver architecture


3. dtdriver/engine - the framework kernel

This is the kernel of dtdrive framework. It builds the chain of
of datatype processing components according to instructions and drives
data through them.

The chain is always started with the following:
1. File system plugin
2. File format plugin

It continues with the following optional components (source handlers):
3. A/V sync and rate adjuster ............ (built into engine)
4. Decrypter ............................. (built into engine)
5. Decoder ............................... (built into engine)
6. Encoder ............................... (built into engine)
7. any number of generic source handlers . (not in engine)
(It is possible for generic source handlers to be positioned
in between components 3 - 6 in any distribution pattern).

The chain ends with the following optional forked components:
* Media file writer
* Media data sink
* Human readable output

+--------+ +--------+ +---+ +---+ ... +---+ +--------+
| file | --> | file | --> | | -> | | | | ---+---> | media |
| system | | format | | source handler chain | | | file |
+--------+ +--------+ | | | | | | | | writer |
+---+ +---+ ... +---+ | +--------+
| +--------+
+---> | media |
| | data |
| | sink |
| +--------+
| +----------+
+---> | human |
| readable |
| output |
+----------+

Figure 2 - dtdrive component chain


The engine conceptually uses a single thread and executes actions 
synchronously.

Helix DNA applications can be built by linking to engine and its support 
libraries. Example of such application is dtdrive - a command line linear 
digital media processing tool.

For non-Helix DNA applications, this is not the recommended point of 
integration. Non Helix DNA application should make use dtdriver/dtdrplin
(framework SDK) as integration point (see 4. for more information).

3.1. dtdriver/engine interfaces

Interfacs methods from dtdriver/engine/pub/ffdriver.h: class FFDriver::

HX_RESULT Init(char* pOutputFileName, 
char* pWriteFileName,
char* pTempDirName,
IHXValues *pOptions,
IHXSourceInput* pSourceSink = NULL,
IHXFileWriter* pFileWriter = NULL,
IHXSourceHandler** pSourceHandlerList = NULL,
IHXFileWriterMonitor* pFileWriterMonitor = NULL);

Called to initialize the engine.

Parameters:
pOutputFileName = NULL or file name for human readable output

pWriteFileName = NULL or file name of output media file
The file writer module will be selected
based on file name extension.
Thus for file.rm, RealMedia file writer
would be selected.

pTempDirName = NULL of directory name to use for temporary
files used during media file writing process.
The directory will be created if not already
present.

pOptions = NULL or a set of properties (name-value
pairs) providing configuration/instruction 
for the engine and all source handlers.
It is through this property set that 
framework built in source handlers need to 
be configured into the component chain. 

Options are globally made available to all 
source handlers.

The list of engine reserved properties
and their description is located in appendix
A.

pSourceSink = NULL or an interface to be used as data sink

pFileWriter = NULL or file writer interface as a media
file writer. Overrides search for file writer
by pWriteFileName extension.

pSourceHandlerList = NULL or NULL terminated array of source
handler interfaces to incorporate into
component chain.

pFileWriterMonitor = NULL or file writer monitor interface to
be handed to the media file writer. This
interface provides file writing status.

void Close(void);

Shuts down the engine and return engine to uninitialized state.

void Stop(void);

Causes engine to cease driving data through the component chain.
This is the only method that is thread safe to allow interruption
of ongoing Drive() operation. Stop() can be called at any time.

The stopping does not occur immediately and upon return from Stop
method caller cannot make assumption that stop has completed.
The invocation of Stop only starts the stopping process which is
carried out by cutting of the data flow at the source (file format).
All the data currently queued in the component chain will be
processed and only then will stop occur.

The caller should look for OnTermination call in registered 
pSourceSink interface to synchronize with the stop completion.

HX_RESULT InitContext(BOOL bPersistentContext = FALSE, 
char* pCompanyName = 0, 
char* pProductName = 0, 
int nMajVer = 0, 
int nMinVer = 0);

Initializes the context of the engine. 

Context is set of basic operation primitives which the engine 
uses during execution.

This method need not be called if default context properties are 
desired. If context is already initialized, this method will not
cause re-initialization. Thus, it should be called prior to 
issuing the Drive() command which will initialize context if not 
already initialized.

Parameters:
bPersistentContext = if TRUE, context will not destroyed and
created with each drive operation.
Instead, the same context will be kept
throughout the engine life-time.
Not even the Close() methods will result
in destruction of the context.

Reason for persistent context is to allow
the calling code to share the same context
without concern for destruction of the
context.

Reason for non-persistent context is for
application that needs to perform heap
allocation checking and thus needs to have
all heap resources de-allocated upon 
completion of Drive() method.

The default setting is FALSE.

pCompanyName = Name of company producing the application 
utilizing dtdrive framework.
The default setting is "Helix".

pProductName = Name of product (application) uilizing
utilizing dtdrive framework.
The default setting is "DTDrive".

nMajVer = Major version of the product (application)
utilizing dtdrive framework.
The default setting is 10.

nMinVer = Minor version of the product (application)
utilizing dtdrive framework.
The default setting is 0.

pCompanyName, pProductName, nMajVer, nMinVer are used to store
framework state information data into unique location.
On windows, they are used to form the registry key name as 
follows:

HKEY_CLASSES_ROOT\Software\<pCompanyName>\<pProductName>\<nMajV
er>.<nMinVer>

Thus, default setting is as follows:

HKEY_CLASSES_ROOT\Software\Helix\DTDriver\10.0

The state information data is cached information on plugins the
framework uses. If deleted, it is rebuilt automatically.

HX_RESULT SetClientContext(IUnknown* pClientContext);

Extends the framework context with custom client context.

After client context is set, any interface queried and not found
within standard framework context will be queried for the set client
context. This allows for application specific source handlers to 
establish custom, out of band communication with the application as 
each source handler has access to context.

This method must be called after context has been initialized (see 
InitContext).

HX_RESULT GetContext(IUnknown** pContext);

Retrieves the framework context.

HX_RESULT Drive(char *pInputFileName, char* pWriteFileName = NULL);

Initiates the data flow through the component chain.

The engine must be initialized prior to Drive() invocation
(see Init()).

This methods does not return until the processing of the entire
data stream has been completed.

Parameters:
pInputFileName = URL-like designation of the media file to
use for source (input).

Format: [[<FSName>,]<Protocol>://]<File>

FSName = Helix DNA file system name.
It is used to differentiate file 
systems claiming the same protocol 
support.

Default = unspecified

Protocol = File transfer protocol to use for
reading the file.
E.g.: file, http

Default = file

File = File name path.


pWriteFileName = Same as pWriteFileName in Init() method.
If not NULL, overrides pWriteFileName provided
in Init() method.

Interface methods are not thread safe with exception of Stop() which can
be called from a different thread to abort initiated processing.

IHXSourceInput, IHXSourceHandler:

These interfaces are discussed in section 5.

IHXFileWriter, IHXFileWriterMonitor:

These interfaces are discussed in "Real Media File Writer User Manual"
and are not discussed in this document.

IHXValues:

This interface and other common interfaces are described in appendix B.

3.2. Integrating applications with dtdriver/engine

Integration with dtdriver/engine has dependencies on many header files and
support libraries native to Helix DNA architecture. Thus, integration at
this level is sensible only for Helix DNA application that leverages Helix
DNA build system (ribosome) and Helix DNA source tree.

The most complicated aspect of this integration is inclusion of needed
libraries and include search paths. However, any Helix DNA application can
easily leverage the ribosome build system for successful build integration.

Sample application that integrates directly with dtdriver/engine is 
"dtdrive" which resides in datatype/tools/dtdriver/apps/dtdrive directory 
of Helix DNA source tree.

Calling application will typically perform the following steps when
interfacing dtdriver/engine:

- enable Helix DNA DLL access paths at global scope:

#include "dllpath.h"

ENABLE_DLLACCESS_PATHS(g_DTDriveAccessPath);

- set dll access paths prior to initializing (explicitly or implicitly) the
dtdriver/engine context:

GetDLLAccessPath()->SetPath(DLLTYPE_PLUGIN, pPluginPathToSet);

GetDLLAccessPath()->SetPath(DLLTYPE_CODEC, pCodecPathToSet);

GetDLLAccessPath()->SetPath(DLLTYPE_ENCSDK, pEncoderSDKPathToSet);

DLLTYPE_PLUGIN are as follows:
* file systems
* file formats
* renderers
* file writers
* source handlers
* payload formatters

DLLTYPE_CODEC are as follows:
* audio decoders
* video decoders (front-end and back-end components)
* color converters

DLLTYPE_ENCSDK
* Helix DNA Producer framework

- Include datatype/tools/dtdriver/engine/pub/ffdriver.h file
that declares the main dtdriver/engine object:

#include "ffdriver.h" 

- Create FFDriver object, followed by sequence of interface calls:

pFFDriver = new FFDriver;

pFFDriver->Init(pOutputFileName, 
pWriteFileName,
pTempDirName,
pOptions);

pFFDriver->Drive(pInputFileName);

pFFDriver->Close();


4. dtdriver/dtdrplin - framework SDK

This is a layer on top of the dtdriver/engine which is intended as 
integration point with either Helix DNA or non Helix DNA applications.

The underlying architecture concepts and functionality of this module are 
in great part those of dtdriver/engine (see 3).

dtdriver/dtdrplin differs from dtdriver/engine in the following:

* It adds new functionality to the dtdriver/engine:

- Helix DNA COM style, asynchronous, non-blocking interface
- Explicit throttling control
- Progress reporting
- Source handler loading by GUIDS
- Certificate support as means for authentication of actions 
(source handler chains) on protected content

* It runs the dtdriver/engine in a separate thread and marshals
all communication back to the caller to the same thread
the caller opened dtdriver/dtdrplin framework on.

* dtdriver/dtdrplin is a dynamically linked library (DLL) which
eliminates the need for integration at build time.

4.1. dtdriver/dtdrplin interfaces

IHXDataTypeDriver2:

STDMETHOD(Open) (THIS_ 
const char* pCertificate,
int nSourceHandlerGUIDs,
GUID* pSourceHandlerGUIDs,
int nSourceHandlerList,
IHXSourceHandler** pSourceHandlerList,
IHXValues* pOptions,
IHXDataTypeDriverResponse* pResponse,
IHXSourceInput* pSourceInput
) PURE;

Opens and initializes the framework for operation.

Parameters:

pCertificate = NULL or certificate string associating
source handler GUIDS and rights to content
needed for the specified source handler
chain to be applied to the content.

nSourceHandlerGUIDs = number of source handler GUIDS pointed to
by pSourceHandlerGUIDs

pSourceHandlerGUIDs = NULL or array of source handler GUIDS to be
incorporated into the component chain

If any source handler GUIDS are specified,
dtdriver/dtdrplin will attempt to load them
in order specified. If any of them fail to
load, the operation will be fail.

nSourceHandlerList = number of source handlers pointed to by
pSourceHandlerList

pSourceHandlerList = NULL or array of source handlers to be
incorporated into the component chain

pOptions = NULL or a set of properties (name-value
pairs) providing configuration/instruction 
for the engine and all source handlers.
It is through this property set that 
framework built in source handlers need to 
be configured into the component chain. 

Options are globally made available to all 
source handlers.

The list of engine reserved properties
and their meaning is listed in appendix A.

pResponse = response interface through which progress
of started operation is reported

pSourceInput = data sink interface through which fully
processed data stream (after applying the 
entire specified component chain) is pushed 
through

Source handler list is constructed in the following order:
1. source handlers as identified by a valid certificate in 
pCertificate
2. source handlers identified by a GUID list in
pSourceHandlerGUIDs
3. source handlers identified by explicit list in
pSourceHandlerList

STDMETHOD(Drive) (THIS_ const char* pInFileName,
const char* pOutFileName
) PURE;

Initiates the data flow through the component chain.

The engine must be initialized prior to Drive() invocation (see 
Open()).

This methods returns as soon as data flow through the component chain
has been initiated. It can be called multiple times after opening the
framework to process multiple file through the same component chain 
and settings. If called while another data flow is still being 
processed, it will halt the other data flow before initiating the new
one.

Parameters:
pInputFileName = URL-like designation of the media file to
use for source (input).

Format: [[<FSName>,]<Protocol>://]<File>

FSName = Helix DNA file system name.
It is used to differentiate file 
systems claiming the same protocol 
support.

Default = unspecified

Protocol = File transfer protocol to use for
reading the file.
E.g.: file, http

Default = file

File = File name path.

pWriteFileName = NULL or file name of output media file
The file writer module will be selected
based on file name extension.
Thus for file.rm, RealMedia file writer
would be selected.

STDMETHOD(Stop) (THIS_ ) PURE;

Causes engine to cease driving data through the component chain.
This is the only method that is thread safe and can thus be called
from any thread. Stop() can be called at any time.

The stopping does not occur immediately and upon return from Stop
method caller cannot make assumption that stop has completed.
The invocation of Stop only starts the stopping process which is
carried out by cutting of the data flow at the source (file format).
All the data currently queued in the component chain will be
processed and only then will stop occur.

The caller should look for OnTerminate call in registered pResponse
interface to synchronize with the stop completion.

STDMETHOD(Close) (THIS) PURE;

Closes down and cleans-up resources used by the framework.

If called while still processing a file, the processing will be 
terminated. The framework will need to be reinitialized by calling 
Open() before it can be given a Drive() command again.

STDMETHOD(Pause) (THIS) PURE;

Pauses the data flow through the component chain.

While paused, no registered IHXDataTypeDriverResponse or 
IHXSourceInput interface methods will be invoked.

STDMETHOD(Resume) (THIS) PURE;

Resumes the data flow through the component chain.

IHXSetClientContext:

STDMETHOD(SetClientContext) (THIS_
IUnknown* pUnknown) PURE;

Extends the framework context with custom client context.

After client context is set, any interface queried and not found
within standard framework context will be queried for the set client
context. 

This allows for application to implement IHXUpgradeCollection in the
client context to get plugin component upgrade requests.

This also allows for application specific source handlers to 
establish custom, out of band communication with the application as 
each source handler has access to context.

IHXDataTypeDriverResponse:

STDMETHOD(OnProgress)(THIS_ UINT32 progress) PURE;

Reports the progress of data stream processing in terms of percentage.
The reported value is in range of 0..100 .

The frequency of reports is never greater than once per percentage 
point.

STDMETHOD(OnTerminate)(THIS_ HX_RESULT result) PURE;

Reports the termination of data stream processing with appropriate
result code.

Expected result codes:
HXR_OK - termination upon complete successful data stream 
processing
HXR_CLOSED - termination upon incomplete data stream processing
<other> - abrupt termination due to severe error reported by
one of chained components or dtdrive framework.

IHXSourceInput, IHXSourceHandler:

These interfaces are discussed in section 5.

IHXValues:

This interface and other common Helix DNA interfaces are discussed in 
appendix B.

4.2. Integrating applications with dtdriver/dtdrplin

Sample application that integrates with dtdriver/dtdrplin is "dtdrtest" 
which resides in datatype/tools/dtdriver/apps/dtdrtest directory of 
Helix DNA source tree.

Calling application will typically perform the following steps when
interfacing dtdriver/dtdrplin:

- include few Helix DNA C++ header files defining the needed interfaces and 
add Helix DNA include directory to the include directory search path of 
the build system used

- load dtdriver/dtdrplin DLL (dtdr3260.dll):

Windows OS code:

HINSTANCE hDTDR = LoadLibrary("dtdr3260.dll");

- Obtain entry point functions to dtdriver/dtdrplin DLL:

Windows OS code:

fpCreateInstance = 
(FPCREATEINSTANCE) GetProcAddress(hDTDR, "RMACreateInstance");

fpSetDLLAccessPath = 
(FPSETDLLACCESSPATH) GetProcAddress(hDTDR, "SetDLLAccessPath");

- Set DLL access paths for dtdriver framework to be able to load its
components as needed:

char szDLLAccessPath[SUFFICIENTLY_LARGE_SIZE];
memset(szDLLAccessPath, 0, SUFFICIENTLY_LARGE_SIZE);

int offset = 0;
offset += 1 + sprintf(szDLLAccessPath+offset, 
"DT_Plugins=%s", 
pPluginPathToSet);
offset += 1 + sprintf(szDLLAccessPath+offset, 
"DT_Codecs=%s", 
pCodecPathToSet);
offset += 1 + sprintf(szDLLAccessPath+offset, 
"DT_EncSDK=%s", 
pEncoderSDKPathToSet);

fpSetDLLAccessPath(szDLLAccessPath);

For explanation of different types of DLL access paths, see section 3.2.
regarding DLLTYPE_PLUGIN, DLLTYPE_CODEC and DLLTYPE_ENCSDK.

- Create instance of dtriver/dtdrplin framework:

HX_RESULT status;
IUnknown* pUnk = NULL;

status = fpCreateInstance(&pUnk);

- Obtain common class factory interface from the framework that will allow
creation of property set object passed into the framework (IHXvalues):

IHXCommonClassFactory* pCCF;

status = pUnk->QueryInterface(IID_IHXCommonClassFactory, 
(void**) &pCCF);

- Create property set object to add framework options to and pass into
framework upon opening.

IHXvalues* pOptions = NULL;
status = pCCF->CreateInstance(CLSID_IHXValues, 
(void**) &pOptions);

Use of IHXValues interface is described in appendix B.

- Obtain the main interface to the dtdriver/dtdrplin framework
(IHXDataTypeDriver2):

IHXDataTypeDriver2 pDTDriver2 = NULL;

status = pUnk->QueryInterface(IID_IHXDataTypeDriver2, 
(void**) &pDTDriver2);

- If needed, obtain IHXSetClientContext interface:

IHXSetClientContext* pSetClientContext = NULL;

status = pUnk->QueryInterface(IID_IHXSetClientContext,
(void**) &pSetClientContext);

- Provide implementation for IHXDataTypeDriverResponse, IHXSourceInput 
interfaces.

- If needed, provide implementation for any number of source handlers behind
IHXSourceHandler to pass to the framework upon opening.

- Use IHXDataTypeDriver2 and IHXDataTypeDriverResponse as described in 4.2.:
- Configure and initiate processing:
* issue .............. IHXSetClientContext::SetClientContext()
* issue .............. IHXDataTypeDriver2::Open()
* issue .............. IHXDataTypeDriver2::Drive()

- Receive processed stream and monitor and control processing rate:
* receive ............ IHXSourceInput methods 
(described in section 5.) 

* issue .............. IHXDataTypeDriver2::Pause() and Resume()
* issue on exception . IHXDataTypeDriver2::Stop()

* receive ............ IHXDataTypeDriverResponse::OnProgress()
* receive ............ IHXDataTypeDriverResponse::OnTerminate()

- Close the framework:
* issue .............. IHXDataTypeDriver2::Close()


5. Source Handlers

Source handler components are generic data source processing components in
Helix DNA architecture. Their purpose is to transform a set of streams 
(called source in Helix DNA architecture). The transformation can be simply
in representation (e.g. change of codec) or can be structural in which case
streams may be added or removed from the source.

All source handler receive and output data through the same type of 
interface: IHXSourceInput. Conceptually, output of each source handler can
be viewed as directly connected to input of another source handler:

+---------+ +---------+
| Source | | Source |
| handler | | handler |
IHXSourceInput +---------+ IHXSourceInput +---------+ ...
Source ---------------> | | ---------------> | | --->
| | | |
| | | |
+---------+ +---------+

Figure 3 - source handler chaining

Besides the support for IHXSourceInput, source handler needs to support only
two additional methods to be complete (InitSourceHandler() and Close()).
IHXSourceHandler interface actually derives from IHXSourceInput and simply
adds the two additional methods.

The data moves through the source handlers in a push model. Data is pushed 
into a source handler through inbound IHXSourceInput interface and each 
source handler pushes the data out through outbound IHXSourceInput
interface.

There is no limit to number of source handlers that can be chained. The 
number of chained source handlers does not in itself increase the call stack
depth. The call stack depth of two chained source handlers is the same
as call stack depth of hundred chained equivalent source handlers.

Source handlers methods in dtdriver framework are always called in mutually
exclusive manner although not necessarily in the same thread.

5.1. Structure of Source

Source in Helix DNA a architecture is a collection of streams that are 
associated by common meta-data header, are synchronized to each other and
reside in the same time-base.

The source is represented by following elements in the order given:

1. File header

File header is a property set (IHXValues) that contains any number of
properties (name-value pairs) that describe the source and contain
meta-data information common to all streams.

Many of the property names are reserved (standardized) for components
to be able to interoperate (see appendix E).

Only one property is required to be present in this header:

Property Type Definition
-------- ---- ----------
StreamCount UINT32 Number of streams in the source

The following is also typically present in the stream header:

Property Type Definition
-------- ---- ----------
Title Buffer Title of the presentation
Author Buffer Author of the presentation
Copyright Buffer Copyright
Abstract Buffer Abstract

Refer to appendix F for examples of some common datatype file headers.

2. Stream header for each stream in the source

Stream header is a property set (IHXValues) same in structure as file
header. The stream header identifies the stream via the stream mime-type,
carries any needed decoder configuration information and any stream
specific meta-data.

Same as with file header, many properties are reserved (standardized)
for components to be able to interoperate (see appendix E).

The following properties are always required to be present in the stream
header:

Property Type Definition
-------- ---- ----------
StreamNumber UINT32 Stream sequence number in the source
Must be in [0..<StreamCount>-1]
MimeType CString Stream-Mime type uniquely identfying 
the payload type of the stream.

The following is also typically present in the stream header:

Common Property Type Definition
--------------- ---- ----------
StreamName CString Human readable identification of the
stream.
AvgBitRate UINT32 Average stream bitrate in bits per
second.
Duration UINT32 Stream duration in milliseconds
SamplesPerSecond UINT32 Samples per second of media time base
ASMRuleBook CString Definition of the rules for the 
stream.
Rules enable stream structure to be
abstracted and manipulated by 
applications in data agnostic manner.
Some examples of ASMRuleBook use:
- multi-rate content
- key frame identification
- marker bit identification 
(for RTP payloads)

Visual Property Type Definition
--------------- ---- ----------
Width UINT32 Picture width in pixels
Height UINT32 Picture height in pixels

Audio Property Type Definition
--------------- ---- ----------
Channels UINT32 Number of audio channels

Refer to appendix F for examples of some common datatype stream headers.

3. Sequence of payload packets

Payload packet is protocol agnostic packet. It carries meta-information
such as time-stamps in abstracted form allowing packet to be packaged
into RTP, RDT or other protocol and be carried over UDP, TCP or other
transport mechanisms.

Each packet carries the following information:
- StreamNumber = Stream sequence number within source
Must be in [0..<StreamCount>-1]

- Time Stamp = Decode/dispatch time stamp in milliseconds.
If composition time-stamp is not available, it is
assumed to be the same as Decode/dispatch time
stamp.

- ASM Rule Number = Index into the ASM Rule Book describing structure
of the media stream

- ASM Flags = SWITCH_ON / SWITCH_OFF flags provide generic 
recommendation on starting or stopping point
for the stream on a particular packet.

- Lost Flag = Indicates if the packet is lost.
If set to TRUE, Time Stamp, ASM Rule Number and
ASM Flags carry unspecified values and Buffer
will be NULL.

- Buffer = Protocol and Transport agnostic payload buffer.


A packet can be extended with a composition time-stamp:

- RTPTime = Composition time-stamp in units of 
SamplesPerSecond.
The default value of SamplesPerSecond is 1000 but
can be overriden by SamplesPerSecond property in
the stream header.

If a single packet in stream is extended with composition time-stamp,
then all packets in the stream are extended with the composition 
time-stamp.

5.2. Source Handler Interface

IHXSourceInput:

STDMETHOD(OnFileHeader) (THIS_
HX_RESULT status,
IHXValues* pValues) PURE;

Delivers file header information.

STDMETHOD(OnStreamHeader) (THIS_
HX_RESULT status,
IHXValues* pValues) PURE;

Delivers stream header information.
It is called once for each stream header.

STDMETHOD(OnStreamDone) (THIS_
HX_RESULT status,
UINT16 unStreamNumber) PURE;

Signals the end of particular stream from the source.

STDMETHOD(OnPacket) (THIS_
HX_RESULT status,
IHXPacket* pPacket) PURE;

Delivers packets from the source,

STDMETHOD(OnTermination) (THIS_s
HX_RESULT status) PURE;

Indicates the source is terminated and receiver is to release all its
resources required for processing source input.
Any input performed after this call is to be ignored.

IHXSourceHandler (extends IHXSourceInput):

STDMETHOD(InitSourceHandler) (THIS_
IHXSourceInput* pSourceSink,
IHXValues* pOptions) PURE;

Provides configuration options and outbound source sink.

STDMETHOD(Close) (THIS) PURE;

Release all resources used by the source handler.


6. dtdrive - media processing tool


7. dtdrtest - dtdriver/dtdrplin unit test tool


8. Appendix
===============================================================================

A. dtdriver options

dtdriver/engine options control the following aspects of dtriver 
functionality:

* engine built-in data processing tools:
- A/V sync and frame rate adjustment
- decrypting
- decoding
- encoding
- file writer configuration
- human readable output

* data source controls:
- file reading mode selection
- bitrate selection for multi-rate files
- dynamic bitrate switching for multi-rate files
- start offset

* performance analysis tools:
- execution timing
- heap allocation profiling
- heap allocation leak detection

A.1. Engine built-in data processing tools

A.1.1. A/V sync and frame rate adjustment

A.1.1. Decrypting

A.1.2. Decoding

Property Type
-------- ----
DecodeSource UINT32
DecodeAudio UINT32
DecodeVideo UINT32
DecodeNonAV UINT32
DecodeStream UINT32
DecodeStreamMode UINT32
BlockFilter UINT32
MaxSpeed UINT32

DecodeSource:

Indicates index position that built in decoder is to take in the
component chain.

Index is 1 based.

Value of 0 (default) indicates exclusion of decoder from the component 
chain.

Non zero value, implies all streams in the source are decoded unless
overridden by additional options.

Any gaps in the index are filled in with external source handlers if 
passed in or are otherwise collapsed. Any collisions in index values are
reconciled by the following assumed order of the built in source 
handlers:
1. A/V sync and rate adjuster
2. Decrypter
3. Decoder
4. Encoder

DecodeAudio:

Indicates special treatment of audio streams during decode.
If set to any value, non-audio stream types will not be decoded unless
explicitly requested by setting stream corresponding option.

0 = Do not decode, apply BlockFilter to this stream
1 = Normal Decode
2 = Do not decode - pass through regardless of BlockFilter setting

DecodeVideo

Indicates special treatment of video streams during decode.
If set to any value, non-video stream types will not be decoded unless
explicitly requested by setting stream corresponding option.

0 = Do not decode, apply BlockFilter to this stream
1 = Normal Decode
2 = Do not decode - pass through regardless of BlockFilter setting

DecodeNonAV

Indicates special treatment of non-A/V streams during decode.
If set to any value, A/V stream types will not be decoded unless
explicitly requested by setting stream corresponding option.

0 = Do not decode, apply BlockFilter to this stream
1 = Normal Decode
2 = Do not decode - pass through regardless of BlockFilter setting

DecodeStream

Indicates special treatment of a streams identified by its sequence
number in the source during decode. If set, other streams will not be
decoded unless explicitly requested by setting stream corresponding 
option.

Valid values: [0..<StreamCount>-1]

DecodeStreamMode

Indicates decode mode to apply to the stream singled out by 
DecodeStream option:

0 = Do not decode, apply BlockFilter to this stream
1 = Normal Decode
2 = Do not decode - pass through regardless of BlockFilter setting

BlockFilter

Governs the handling of streams not selected for decode during source 
decode process:

0 = Pass through (retain in the source in coded form)
1 = Block (remove from the source)

MaxSpeed

When set to 1, instructs decoder to keep output in machine native 
endianess.

If not set or set to 0, decoder will chnage data endianess to conform
to standard representation of decoded data (big-emdian).
This option currently only affects audio.

Example Big Endian PCM Audio Stream Header:
AvgBitRate = 1411200
Channels = 2
Duration = 196101
SamplesPerSecond = 44100
StreamNumber = 0
MimeType = audio/L16

Example Little Endian PCM Audio Stream Header:
AvgBitRate = 1411200
Channels = 2
Duration = 196101
SamplesPerSecond = 44100
StreamNumber = 0
MimeType = audio/X-RN-LE16

A.1.3. Encoding

A.1.4. File writer configuration

A.1.5. Human readable output

Property Type
-------- ----
Header UINT32
Packet UINT32
Verbose UINT32

Header:

When set to non-zero value, will result in every header exiting the
component chain to be written out to standard output.

Default: 1

Sample output:

*************************************************************************
****** Begin File=news-H264_150k_AAC_40k.3gp Protocol=Unspec. ShortName=U
*************************************************************************
====== Begin File Header ================================================
Duration = 30060
Height = 288
IsRealDataType = 0
StreamCount = 2
Width = 352
====== End File Header ==================================================
------ Begin Stream Header = 0 ------------------------------------------
AvgBitRate = 150879
Duration = 29999
HasOutOfOrderTS = 1
Height = 288
RTPPayloadType = 96
SamplesPerSecond = 90000
StreamNumber = 0
TrackID = 201
Width = 352
ASMRuleBook = Marker=0;Marker=1;
MimeType = video/X-HX-AVC1
StreamName = Video Track
OpaqueData = <Buffer>
------ End Stream Header = 0 --------------------------------------------
------ Begin Stream Header = 1 ------------------------------------------
AvgBitRate = 40000
Duration = 30060
HasOutOfOrderTS = 1
MaxBitRate = 40000
RTPPayloadType = 96
SamplesPerSecond = 22050
StreamNumber = 1
TrackID = 101
ASMRuleBook = Marker=0;Marker=1;
MimeType = audio/X-RN-MP4-RAWAU
StreamName = Audio Track
OpaqueData = <Buffer>
------ End Stream Header = 1 --------------------------------------------
...... Start Packets ....................................................
...... End Packets ......................................................
****** End File=news-H264_150k_AAC_40k.3gp Protocol=Unspec. ShortName=Uns
*************************************************************************

Packet:

When set to non-zero value, will result in every packet exiting the
component chain to be written out to standard output.

Default: 0

Sample output:

Strm# ___Time____ Rule# Lst Flgs BufferSize __RTPTime__
S= 0 T= 0 R= 1 L=F F=03 B= 2859 t= 0
S= 1 T= 0 R= 1 L=F F=03 B= 6 t= 0
S= 0 T= 40 R= 1 L=F F=02 B= 657 t= 3597
S= 1 T= 46 R= 1 L=F F=03 B= 230 t= 1024
S= 0 T= 80 R= 1 L=F F=02 B= 698 t= 7197
...

Verbose:

When set to non-zero value, will result in every buffer in header 
property or packet to be written to standard output. The output is
comprised of hex-decimal byte values and the corresponding ASCII
interpretation.

Default: 0

Sample output:

00 00 00 26 61 76 63 43 01 4d 40 0d ff e1 00 0f 67 4d 40 | ...&avcC.M@.....gM@
0d 96 54 0b 04 a7 fe 00 02 00 02 01 01 00 04 68 ee 38 80 | ..T............h.8.
00 00 00 14 62 74 72 74 00 00 49 3e 00 02 49 f0 00 02 49 | ....btrt..I>..I...I
f0 | .

A.1.6. File reading mode selection


A.2. Data source controls

A.2.1. Bitrate selection

A.2.2. Dynamic bitrate switching

A.2.3. Start Offset

Property Type
-------- ----
StartTime UINT32

StartTime:

It specifies the data source start time in milliseconds. The data source
(file format) will be seeked to appropriate offset.

The proximity of data stream to specified StartTime is data-type 
specific.

Default: 0

A.3. Performance analysis tools

A.3.1. Execution timing

A.3.2. Heap allocation profiling

A.3.3. Heap allocation leak detection


B. Common Helix DNA interfaces


C. dtdriver Helix DNA code location references

datatype/tools/dtdriver


D. dtdriver build targets and profiles

Build targets:

datatype_tools_dtdriver:
Entire franework (engine, SDK, sample applications).
Plugins are not included.

datatype_tools_dtdriver_dtdrplin:
dtdriver/dtdrplin (dtdriver SDK)

dtdrive:
dtdrive application and all plugins

datatype_tools_dtdriver_apps_dtdrive:
dtdrive application without plugins

datatype_tools_dtdriver_extplugins:
plugin for dtdriver framework

Profiles:

helix-dtdr-local-audio-transcode.pf
Local file, audio only support.

helix-dtdr-local-video-transcode.pf
Local file, audio and video support.

helix-dtdr-all-defines.pf
Local file and network support (for network file systems) along with
audio and video support.


E. Standardized file and stream header properties


F. File and stream headers of common formats

F.1. Uncompressed Audio

====== Begin File Header ======================================================
IsRealDataType = 0
StreamCount = 1
Author = <Buffer>
56 61 72 69 6f 75 73 20 41 72 74 69 73 74 73 00 | Various Artists.
Title = <Buffer>
4f 68 20 48 65 6c 6c 20 59 65 61 68 00 | Oh Yeah.
====== End File Header ========================================================
------ Begin Stream Header = 0 ------------------------------------------------
AvgBitRate = 1411200
Channels = 2
Duration = 196101
RTPPayloadType = 10
SamplesPerSecond = 44100
StreamNumber = 0
ASMRuleBook = Marker=0;Marker=1;
MimeType = audio/L16
------ End Stream Header = 0 --------------------------------------------------

F.2. Uncompressed Audio and Video:

====== Begin File Header ======================================================
IsRealDataType = 0
StreamCount = 2
Copyright = <Buffer>
32 30 30 30 00 | 2000.
Title = <Buffer>
58 6d 65 6e 00 | Xmen.
====== End File Header ========================================================
------ Begin Stream Header = 0 ------------------------------------------------
AvgBitRate = 1411200
Channels = 2
Duration = 147121
RTPPayloadType = 10
SamplesPerSecond = 44100
StreamNumber = 0
ASMRuleBook = Marker=0;Marker=1;
MimeType = audio/L16
------ End Stream Header = 0 --------------------------------------------------
------ Begin Stream Header = 1 ------------------------------------------------
BitsPerPixel = 12
Duration = 146849
Height = 360
StreamNumber = 1
Width = 320
ASMRuleBook = Marker=0;Marker=1;
MimeType = video/X-HX-I420
------ End Stream Header = 1 --------------------------------------------------

This page was last modified 22:08, 4 March 2008.This page has been accessed 48,588 times.
 

Site Map   |   Terms of Use   |   Privacy Policy   |   About Us   |   Contact Us

We have performed maintenance on Helix Community that turned off deprecated accounts. To re-apply for access, please contact licensing@helixcommunity.org

Copyright © 1995-2014 RealNetworks, Inc. All rights reserved. RealNetworks and Helix are trademarks of RealNetworks.
All other trademarks or registered trademarks are the property of their respective holders.