metadata toolkit spe ifi ations - dartfishbeta.dartfish.com/metadata toolkit specifications8.pdf ·...

©Dartfish – 2003/2015 page 1

METADATA TOOLKIT SPECIFICATIONS

DARTFISH 8

Project : Dartfish 8

Date : 11 September 2015

Version : 1.14 Author : Pascal Binggeli


History

Date Version Description Author Support

12.11.2015 1.14 Fixed event notifications description PBI DF8

20 August 2015 1.13 Fixed details Change version to Dartfish 8

PBI DF8

24 September 2014 1.12 Fixed Javascript sample DF7, DF6

10 Feb 2012 1.11 Fixed documentation of the tagging command PBI DF6

9 Feb 2012 1.10 Completed documentation for tagging command PBI MDTK v5.5

8-Sep-2009 1.9.1 New chapter “Error Codes...”

Complete reordering of the chapters

FD MDTK v.5.5

27-Jul-2009 1.9 New Command to add key positions within the ITA FD MDTK v.5.5

22-Dec-2008 1.7.0 Add Commands in Video Import and Tagging

Add SetFileName in ITA, VI and Tagging

FD MDTK v.5.0

17-Aug-2006 1.6.5 Add "ITA Preroll Value" notification MM MDTK v1.2.9

31-May-2006 1.6.4 Add "SetVideoPosition" command and "Notify New Play Position" notification

MM MDTK v1.2.8 MDTK sim v1.4.1 DSOPack v1.13.1

04-Jan-2006 1.6.3 Fix some minor typos (second param index is "2" and not "1" in command description).

MM MDTK v1.2.3 MDTK sim v1.2 DSOPack v1.8

16-Nov-2005 1.6.2 Remove typo in specification erroneously indicating that continuous stream flowtype are not implemented. They were implemented since 1.4b version of the specifica-tion document.


19-May-2005 1.6 New commands for defining categories for the video clip being captured


18-May-2005 1.5 Add Custom External Event in section 3 and description of external supported commands in section Error: Ref-erence source not found

MM MDTK v1.2.2

04-Mar-2008 1.8 New Commands for Tagging:

Create/Delete Events etc.

Chapter 15: command and notification example

Frédéric Despont

MDTK v.5.1 28-Oct.2004 1.4b Modify meaning of “onlyStructure” parameter in SendData method in IDFMetadataSender interface.

Provide more information concerning multi-thread safety in the toolkit.

Add IDFMetadataSender2 interface

MM MDTK v1.2.1 DSOPack v

18-Aug-2004 1.3 Add ProgId for the COM implementations, remove ref-erence to Dartfish metadata XML document.

MM


1 CONTENTS

2 Goal of the present document ................................................................................................................................... 6

3 Dartfish Metadata Model .......................................................................................................................................... 6

4 Sender Class ............................................................................................................................................................... 7

4.1 IDFMetadataSender .......................................................................................................................................... 7

4.1.1 Initialize ......................................................................................................................................................... 7

4.1.2 SendData ....................................................................................................................................................... 7

4.1.3 RegisterListenerForMDEvents ...................................................................................................................... 7

4.2 IDFMetadataSender2 ........................................................................................................................................ 9

4.2.1 SendCommand .............................................................................................................................................. 9

5 Command ................................................................................................................................................................. 10

5.1 IDFMetadataCmd ............................................................................................................................................ 10

5.1.1 Name ........................................................................................................................................................... 10

5.1.2 ParameterCount ......................................................................................................................................... 10

5.1.3 ParameterName .......................................................................................................................................... 10

5.1.4 AssignParamValue ...................................................................................................................................... 10

6 Command Factory .................................................................................................................................................... 11

6.1 IDFMetadataCmdFactory ................................................................................................................................ 11

6.1.1 CreateCmd .................................................................................................................................................. 11

6.1.2 IsSupported ................................................................................................................................................. 11

7 Supported Commands ............................................................................................................................................. 12

7.1 Start Capture Command.................................................................................................................................. 12

7.2 Stop Capture Command .................................................................................................................................. 12

7.3 Keep Captured File Command ......................................................................................................................... 12

7.4 Set File Name Command ................................................................................................................................. 12

7.5 Set Capture Category Value Command ........................................................................................................... 12

7.6 Delete Capture Category Value Command ..................................................................................................... 13

7.7 Clear Capture Category Value Command ........................................................................................................ 13

7.8 Set Video Position Command .......................................................................................................................... 13

7.9 ITA Request Preroll Value Command .............................................................................................................. 13

7.10 Add Key Position Command ............................................................................................................................ 14

7.11 Create Tagging Event Command ..................................................................................................................... 14


7.12 Delete Tagging Event Command ..................................................................................................................... 14

7.13 Clear All Tagging Events Command ................................................................................................................. 15

7.14 Set Tagging Event Category Value ................................................................................................................... 15

7.15 Request Video Position Command .................................................................................................................. 15

8 Multi-threadING Issues ............................................................................................................................................ 17

9 Metadata.................................................................................................................................................................. 17

9.1 IDFMetadata ................................................................................................................................................... 17

9.1.1 Initialize ....................................................................................................................................................... 17

9.1.2 AddStream .................................................................................................................................................. 17

9.1.3 ClearData .................................................................................................................................................... 17

9.1.4 Clear ............................................................................................................................................................ 18

9.1.5 GetStream ................................................................................................................................................... 18

9.2 IDFMetadataStream ........................................................................................................................................ 18

9.2.1 Initialize ....................................................................................................................................................... 18

9.2.2 SetStreamAttribute ..................................................................................................................................... 18

9.2.3 Clear ............................................................................................................................................................ 19

9.2.4 AddData ...................................................................................................................................................... 19

9.2.5 Name ........................................................................................................................................................... 19

9.3 IDFVector ......................................................................................................................................................... 20

9.3.1 SetSize ......................................................................................................................................................... 20

9.3.2 CopyTo ........................................................................................................................................................ 20

9.3.3 CloneTo ....................................................................................................................................................... 20

9.3.4 Clear ............................................................................................................................................................ 20

9.3.5 Size .............................................................................................................................................................. 21

9.3.6 Element ....................................................................................................................................................... 21

9.4 IDFTimestamp ................................................................................................................................................. 21

9.4.1 CopyTo ........................................................................................................................................................ 21

9.4.2 Create .......................................................................................................................................................... 21

9.4.3 Add .............................................................................................................................................................. 21

9.4.4 LowPart ....................................................................................................................................................... 22


9.4.5 HighPart ...................................................................................................................................................... 22

9.5 IDFClock ........................................................................................................................................................... 22

9.5.1 Initialize ....................................................................................................................................................... 22

9.5.2 GenerateTimestamp ................................................................................................................................... 22

9.5.3 SetGlobalTimeShift ..................................................................................................................................... 22

10 Error Codes (HRESULT) ............................................................................................................................................. 23

11 Appendix 1 : Metadata Stream Attributes ............................................................................................................... 24

11.1 Stream Attributes Description ........................................................................................................................ 24

11.1.1 FlowType (feature attribute) .................................................................................................................. 24

11.1.2 LimitCount (recording attribute) ............................................................................................................ 25

11.1.3 FreezeDelay (recording attribute) .......................................................................................................... 25

11.1.4 InterpolationType (feature attribute)..................................................................................................... 25

11.1.5 DefaultValue (recording attribute) ......................................................................................................... 25

11.1.6 HighRange and LowRange (feature attribute) ........................................................................................ 25

11.1.7 valueUnit(feature attribute) ................................................................................................................... 25

12 Appendix 2: Example in Javascript ........................................................................................................................... 26

13 Appendix 3: Example in pseudo C# for Tagging commands .................................................................................... 28


2 GOAL OF THE PRESENT DOCUMENT

This document specifies the tool provided by Dartfish for helping customers to send metadata to Dartfish Software.

The tool is composed of 2 parts:

a DLL containing COM implementations1 of classes allowing formatting and sending metadata to Dartfish

Software.

a set of scriptable COM interfaces for using the aforementioned COM classes.

The DLL must be registered in the target system by the usual command line command: regsvr32. Usually, it is auto-

matically registered during the installation phase of Dartfish Software. So, the metadata toolkit is directly available

after Dartfish software installation.

The availability of the Metadata toolkit SDK depends on the installed Edition of Dartfish Software. Please contact Dart-

fish for more information.

The different interfaces described in this document are implemented by different COM implementations registered

during the installation phase of Dartfish Software. All of these COM implementations are “inproc” COM servers.

3 DARTFISH METADATA MODEL

All metadata, which are collected from external entities, are represented as real-time streams of time stamped values.

External clients send metadata to Dartfish Software as real-time streams. When the ITA module is in “Live” mode, the

received streams are recorded in temporary buffers and their current value can be displayed on the video. When the

ITA records a video clip, the different streams of metadata are recorded and associated with the video clip. In order to

synchronize the metadata streams with video streams, each stream value has a timestamp created with a common

reference clock. The metadata toolkit provides this reference clock to external entities.

Each time new metadata are available, external clients create metadata streams (more precisely portions of streams)

and send the new values to Dartfish software.

1 COM (Component Object Model) is a technology developed by Microsoft. A good introduction of this tech-

nology can be found in the book entitled “Essential COM”, Don Box, Addison Wesley, 1998. More infor-

mation can be found in MSDN.


4 SENDER CLASS

4.1 IDFMETADATASENDER

The IDFMetadataSender interface is used for sending metadata to Dartfish Software process.

This interface is implemented by the Sender class.

The ProgID for this class is "DartfishMDTK.DFMetadataSender".

interface IDFMetadataSender : IDispatch

{

HRESULT Initialize();

HRESULT SendData(

[in] IDFMetadata* dataToSend,

[in, defaultvalue(0)] long clearStreams

);

HRESULT RegisterListenerForMDEvents(

[in] DWORD windowHandleHWND,

[in] UINT messageID

);

HRESULT UnregisterListenerForMDEvents(

[in] DWORD windowHandleHWND

);

}

4.1.1 INITIALIZE

The Initialize()method must be called prior to calling any method.

4.1.2 SENDDATA

The SendData() method sends the metadata instance to Dartfish Software. The parameter clearStreams is

used for automatically invoking ClearData() method internally after the content of each stream has been saved.

This parameter is especially useful in a multithread environment where several threads update the metadata streams

and a different thread invoke the SendData() method. When the parameter clearStreams is set to 1, it is en-

sured that saving the content of a stream and invoking ClearData() method are done as an atomic operation.

4.1.3 REGISTERLISTENERFORMDEVENTS

The RegisterListenerForMDEvents() method registers a window (referenced by a handle) as a target for

receiving metadata notification messages as windows notification messages (win32 messages) with id = messageID.

When a metadata event occurs, a win32 message with the id = messageID is posted to the specified window. The

lparam parameter of the received messages indicates the type of event. The following types of events are currently

notified:


struct MDEvents

{

// sent when Dartfish Software starts recording a video clip

StartOfVideoCapture = 1,

// sent when Dartfish Software stops recording a video clip

EndOfVideoCapture = 2,

NewPlayPosition = 3,

ITAPrerollValue = 4,

TaggingEventId = 5,

KeyPositionId = 6,

NewRecordingPosition = 7,

// sent by Dartfish Software when mapped to remote control keys

CustomExternalEvent1 = 101,





};

IMPORTANT: Be sure to call ChangeWindowMessageFilterEx to allow Windows to send message to the

window you have registered.

The event NewPlayPosition generated when the player, analyzer, video import or tagging (all modes) module is ena-

bled and a video is being played. The wParam value corresponds to the current video cursor position expressed in

msec. Each time the user modifies the video cursor position or when the clip is being played, the new video cursor

position in the timeline is notified with "Notify New Play Position" notification. When a video clip is being played, all

positions are not necessarily notified for limiting the number of notifications. This notification is not emitted when the

ITA module is enabled.

The event ITAPrerollValue notifies the pre-roll value for the ITA module. The wParam value corresponds to the pre-

roll value expressed in seconds.

The event TaggingEventId notifies the id of a tagging event just created. The wParam value corresponds to the concat-

enation of the id and the token previously sent to create the tagging event. The id is the 16 highest bits of the 32 bits

integer that is the wParam and the token is the 16 lowest bits of it. Id = wParam >> 16. Token = wParam & 0x0ffff.

The event KeyPositionId notifies the id of the key position just added. The wParam value corresponds to the concate-

nation of the id and the token previously sent to create the key position. The id is the 16 highest bits of the 32 bits in-

teger that is the wParam and the token is the 16 lowest bits of it. Id = wParam >> 16. Token = wParam & 0x0ffff.

The NewRecordindPosition notifies when the recording position is updated. The wParam value correspond to the

video position in milliseconds. This is notified every 200 ms

4.1.3.1 UNREGISTERLISTENERFORMDEVENTS

This method unregisters a previously registered window.


4.2 IDFMETADATASENDER2

The IDFMetadataSender2 is an extension of the IDFMetadataSender interface.

This interface is implemented by the Sender class. This interface is the default interface returned when creating an

implementation of a sender (cf. section 12).

interface IDFMetadataSender2 : IDFMetadataSender

{

HRESULT SendCommand([in] IDFMetadataCmd* cmdToSend);

}

4.2.1 SENDCOMMAND

The SendCommand() method sends a command created with the command factory to Dartfish Software.


5 COMMAND

5.1 IDFMETADATACMD

The IDFMetadataCmd interface defines a root interface shared by all commands.

This interface is implemented by the Command class.

Each command is characterized by a name (property) and a list of parameters. Each command parameter is character-

ized by an index (starting at “1”, the first command parameter has index “1”) and a name.

interface IDFMetadataCmd : Idispatch

{

// methods

HRESULT AssignParamValue( [in] BSTR paramName, [in] VARIANT* value);

// properties

HRESULT Name([out, retval] BSTR* name);

HRESULT ParameterCount([out, retval] int* paramCount);

HRESULT ParameterName( [in] int index, [out, retval] BSTR* name);

}

5.1.1 NAME

The Name property (read-only) returns the command name.

5.1.2 PARAMETERCOUNT

The ParameterCount property (read-only) returns the number of parameters allowed for the command.

5.1.3 PARAMETERNAME

The ParameterName property (read-only) returns the name of a command parameter given its index number in the

command. The index of the first parameter in a command is "1".

5.1.4 ASSIGNPARAMVALUE

The AssignParamValue() method assigns a value to a command parameter given its name. If the parameter

does not exist for the current command, then returns an error. Also returns an error if the parameter is of the wrong

type.

Commands can only be created using the Command Factory.

The command names and parameters are not case sensitive.


6 COMMAND FACTORY

6.1 IDFMETADATACMDFACTORY

The IDFMetadataCmdFactory interface defines the methods for creating a command. This interface is imple-

mented by the MetadataCommandFactory class.

The ProgID for this class is DartfishMDTK.DFMetadataCmdFactory.

interface IDFMetadataCmdFactory : IDispatch

{

// methods

HRESULT CreateCmd(

[in] BSTR cmdName,

[out, retval] IDFMetadataCmd** newCmd);

HRESULT IsSupported(

[in] BSTR cmdName,

[out, retval] VARIANT_BOOL* success);

}

6.1.1 CREATECMD

The CreateCmd() method creates a command given its name. It returns null if the command name does not exist.

The returned object is a polymorphic object that can be queried for specialized command interfaces. For scripting lan-

guages, the methods of the derived interface can be directly invoked thru the IDispatch invoke mechanism.

6.1.2 ISSUPPORTED

The IsSupported() method returns S_OK or success == VARIANT_TRUE if the requested command name is supported

by the current version of the metadata toolkit. Returns S_FALSE and success == VARIANT_FALSE otherwize. For script-

ing languages, the returned values correspond to logical “true” or “false” values in the corresponding languages.


7 SUPPORTED COMMANDS

7.1 START CAPTURE COMMAND

Start a capture in the ITA, Video Import (VI) or Tagging given an optional timestamp. When the optional parameter is

not set, the intended meaning is “capture as soon as possible”.

Command name: “startcapture”

Parameters count: 1 (optional)

Parameter 1 name and type: “StartTimestamp” of type IDFTimestamp.

7.2 STOP CAPTURE COMMAND

Stop a capture in the ITA, VI or Tagging given an optional timestamp. When the optional parameter is not set, the in-

tended meaning is “stop capturing as soon as possible (= now)”.

Command name: “stopcapture”


Parameter 1 name and type: “StopTimestamp” of type IDFTimestamp.

7.3 KEEP CAPTURED FILE COMMAND

Save the last captured file in the ITA if the capture option has not been set to “Autokeep” in the ITA settings.

Command name: “KeepCapturedFile”

Parameters count: none.

7.4 SET FILE NAME COMMAND

Set the file name template in the ITA, VI or Tagging for the next capture. This command must be called before the cap-

ture has started.

Command name: “SetFileName”

Parameters count: 1

Parameter 1 name and type: “FileName” of type string.

7.5 SET CAPTURE CATEGORY VALUE COMMAND

Set a category value for all the next video clip being captured. This command adds a category value to the set of cate-

gory-values that will be added to all next upcoming recorded video clips including the one been recorded (i.e. a cate-

gory can be set after a capture has started, but not after it has stopped).


Command name: “SetCaptureCategoryValue”

Parameters count: 2.

Parameter 1 name and type: “CategoryName” of type string.

Parameter 2 name and type: “CategoryValue” of type string.

7.6 DELETE CAPTURE CATEGORY VALUE COMMAND

Delete a previously set category value. Remove a category value from the set of category-values that will be added to

all next upcoming recorded video clips including the one been recorded.

Command name: “DeleteCaptureCategoryValue”

Parameters count: 1.

Parameter 1 name and type: “CategoryName” of type string.

7.7 CLEAR CAPTURE CATEGORY VALUE COMMAND

Clear all category-values that have been set. This command resets all the category-values that has been set for being

stored with next upcoming captured video clips including the one been recorded.

Command name: “ClearCaptureCategoryValue”

Parameters count: none.

7.8 SET VIDEO POSITION COMMAND

Set the current position of the video currently being played in the Player, Analyzer, Video Import (VI) or Tagging (all

modes) module to the requested position expressed in msec. This command only works when a video is being played.

It has no effect when the current module is "ITA". The requested video position is expressed in msec. So, when "Posi-

tion" parameter value is 1500, the play head will move to position 1.5 sec. The effect of "SetVideoPosition" command

is to set the cursor position in the timeline to the value "position" expressed in msec.

Command name: "SetVideoPosition"

Parameters count: 1

Parameter 1 name and type: "Position" of type integer.

7.9 ITA REQUEST PREROLL VALUE COMMAND

Request for a notification concerning the current pre-roll value for the ITA. This command only succeeds if the ITA is

the current active module.

Command name: "ITARequestPrerollValue"

Parameters count: none


7.10 ADD KEY POSITION COMMAND

Add a key position to the current clip playing in InTheAction module. This command only succeeds if the InTheAction

module is the current active module. When the optional parameter is not set, the intended meaning is “capture as

soon as possible”. The parameters “name” and “description” are the textual content of the key position. The parame-

ter “token” must be unique to the client and is returned by the notification providing the id of the key position. (The id

may be used in the future to apply new operations on the key position.)

Command name: “AddKeyPosition”

Parameters count: 4

Parameter 1 name and type: “Position” of type IDFTimestamp

Parameter 2 name and type: “Name” of type string

Parameter 3 name and type: “Description” of type string

Parameter 4 name and type: “Token”of type short integer (16bits)

7.11 CREATE TAGGING EVENT COMMAND

Create an event in the Tagging module in both play and record modes. This command only succeeds if the Tagging is

the current active module. The EventIn parameter is the cue in offset relative to the play head. The EventIn is in milli-

seconds can be positive or negative as long as it is in the range of the current video. The EventDuration Parameter is in

milliseconds and must be positive. The EventIdToken parameter is a short integer of 16 bits generated by the client.

The EventIdToken must be unique to the client and is returned by the notification providing the id of the event. If no

notification is received, it means that the events hasn't been created, possibly because of a wrong parameter (See

Dartfish log file to detect the error). See the event TaggingEventId notification for more info.

Command name: "CreateTaggingEvent"

Parameters count: 4

Parameter 1 name and type: “EventIn” of type IDFTimestamp

Parameter 2 name and type: “EventDuration” of type integer

Parameter 3 name and type: “EventName” of type string

Parameter 4 name and type: “EventIdToken” of type short integer (16bits)

Pseudo code to create an event and add a keyword to it:

short int token = GenerateEventToken();

CreateTaggingEvent(position, duration, “Name”, token);

int eventId = WaitForTaggingEvent(token);

SetTaggingEventCategoryValue(eventId, “Category”, “Keyword”);

7.12 DELETE TAGGING EVENT COMMAND

Delete an event in the Tagging module in both play and record modes. This command only succeeds if the Tagging is

the current active module. The id parameter is a short integer of 16 bits retrieved from the notification received after

the event creation command of the MDTK. This means that only event created in the current session through the

MDTK can be deleted through this command.


Command name: “DeleteTaggingEvent”

Parameters count: 1

Parameter 1 name and type: “EventId” of type short integer (16bits)

7.13 CLEAR ALL TAGGING EVENTS COMMAND

Clear all events in the Tagging module that have been created through the MDTK command during the current ses-

sion. This command only succeeds if the Tagging is the current active module. There is no parameter.

Command name: “ClearAllTaggingEvents”

Parameters count: none

7.14 SET TAGGING EVENT CATEGORY VALUE

Add/Modify a category value of an event. This command only succeeds if the Tagging is the current active module.

The EventId parameter is the id of the event (See CreateTaggingEvent command for more info). The EventCatego-

ryName and the EventCategoryValue cannot be empty. The EventCategoryName corresponds to the colon name in

the tagging table and the EventCategoryValue is the cell value in that colon for the corresponding event.

Command name: “SetTaggingEventCategoryValue”

Parameters count: 3

Parameter 1 name and type: “EventId” of type short integer (16bits)

Parameter 2 name and type: “EventCategoryName” of type string

Parameter 3 name and type: “EventCategoryValue” of type string

7.15 REQUEST VIDEO POSITION COMMAND

Request the video position in playback or recording mode in Tagging, ITA or Analyzer. In the Analyzer no position is

returned for the recording mode. Specifying the playback vs. recording mode is done through the optional parameter

positionKind. If the parameter is not specified the playback position is returned. The position is returned through a

notification (described in chapter [


Sender]). The parameter PositionKind can have the following values: “Playback”, “Recording”.

Command name: "RequestVideoPosition"


Parameter 1 name and type: “PositionKind” of type string.


8 MULTI-THREADING ISSUES

The implementation for the classes DFMetadata, DFMetadataStream and DFMetadataSender is multi-thread safe. In

other terms, different threads can access their methods concurrently. These implementations have built-in synchroni-

zation mechanism.

9 METADATA

9.1 IDFMETADATA

The IDFMetadata interface builds metadata that will be sent to Dartfish Software. A metadata instance is com-

posed of several Metadata streams.

The ProgID for this class is DartfishMDTK.DFMetadata.

interface IDFMetadata : Idispatch

{

HRESULT Initialize(

[in] BSTR name,

[in] int id);

HRESULT AddStream(

[in] IDFMetadataStream*);

HRESULT GetStream(

[in] BSTR streamName,

[out] IDFMetadataStream** ppStream,

[out, retval] VARIANT_BOOL* outResult);

HRESULT Clear();

HRESULT ClearData();

}

9.1.1 INITIALIZE

The Initialize method must be called prior to calling any method. The name parameter is the name of the

metadata instance (DataSource). The id parameter is a unique number defined by the user. This method can only be

called once.

9.1.2 ADDSTREAM

The AddStream method adds a new stream to the Metadata.

9.1.3 CLEARDATA

The ClearData method clears the content of all the Metadata streams, that is, it iterates on all the streams and

calls their Clear method. This method allows reusing the current stream structure by clearing only the data and not

the structure (each stream description inside the current metadata instance is preserved and only the data are re-

moved).


9.1.4 CLEAR

The Clear method removes all streams from the DFMetadata instance.

9.1.5 GETSTREAM

The GetStream method allows finding a stream based on its name. It returns a reference to the internal found

stream.

The implementation of IDFMetadata is multi-thread safe. Several thread can concurrently access the different meth-

ods published in IDFMetadata interface.

9.2 IDFMETADATASTREAM

The IDFMetadataStream interface represents a stream (or a portion) of stream of metadata. A metadata stream

is characterized by a Name, an identifier and the type of data in the stream.

The ProgID for this class is DartfishMDTK.DFMetaDataStream.

interface IDFMetadataStream : Idispatch

{

// methods

HRESULT Initialize(

[in] BSTR streamName,

[in] int streamId,

[in] BSTR typeName);

HRESULT SetStreamAttribute(

[in] BSTR name,

[in] VARIANT value);

HRESULT AddData(

[in] VARIANT data,

[in, defaultvalue(0)] IDFTimestamp*);

HRESULT Clear();

// properties

HRESULT Name([out, retval] BSTR*);

}

9.2.1 INITIALIZE

The Initialize() method must be called prior to calling any method. The typeName parameter defines the type

of the values in the Stream. The following types are currently recognized: “integer”, “string”, “float”, “vector6”, “vec-

tor3”. This method can only be called once.

9.2.2 SETSTREAMATTRIBUTE

The SetStreamAttribute() method is used to set the optional attributes of the Stream.

The names for the optional attributes are described in the section [24] on page 24.


9.2.3 CLEAR

The Clear() method clears all the data that have been added to the stream. This method does not clear the op-

tional attributes.

9.2.4 ADDDATA

The AddData() method add a new data to the Metadata stream instance with an optional timestamp. Returns an

error if the provided timestamp is before any of the timestamps already recorded. Values of type “vector6” and “vec-

tor3” must be create with IDFVector instances.

9.2.5 NAME

The Name property (read-only) returns the name of the current stream.

The implementation of Metadata stream is multi-thread safe. Several threads can concurrently access the different

methods published in IDFMetadataStream interface.


9.3 IDFVECTOR

The IDFVector interface defines Dartfish vectors. Instances of IDFVector must be used for defining values of type

“vector3” and “vector6” instead of native vector types defined in the calling programming language (e.g. vector in Vis-

ual Basic). The use of DFVector type allows for greater portability between different programming languages instead

of favoring a particular one.

DFVector are basically homogeneous vectors of typed values. Contrary to polymorphic vectors, an instance cannot

contain values of different types. In other terms, given an instance, all the values have the same type. The type of the

vector values are set when the first value is entered in the vector by invoking the put_Element(...) method or modify-

ing one of the Element properties.

The ProgID for this class is DartfishMDTK.DFVector.

interface IDFVector : IDispatch

{

// methods

HRESULT SetSize([in] long);

HRESULT CopyTo([in, out] IDFVector** ppVector);

HRESULT CloneTo([out, retval] IDFVector** ppVector);

HRESULT Clear();

// properties

[propget, id(5)]

HRESULT Element([in] long index, [out, retval] VARIANT*);

[propput, id(5)]

HRESULT Element( [in] long index, [in] VARIANT*);

[propget, id(6)]

HRESULT Size( [out, retval] long*);

};

9.3.1 SETSIZE

The SetSize() method sets the size of the instance and clears the instance content.

9.3.2 COPYTO

The CopyTo() method performs a deep copy of the current instance content to another instance.

9.3.3 CLONETO

The CloneTo() method clones the current instance and create a new one that is a deep copy of the current in-

stance.

9.3.4 CLEAR

The Clear() method clears the vector instance and sets its type to none.


The Element()property (read/write) sets or reads an element of the instance given its index (0 based). Trying to set

an element with the “wrong” type produces an error. The first element sets in the current instance determines the

type of the vector values. Subsequent calls to modify elements must use the same value type because all elements in

a DFVector must have the same type (data abstraction invariant condition). A call to Clear() method resets the

type of the instance to “none” (= undetermined).

9.3.5 SIZE

The Size() property (read only) return the current number of elements.

9.3.6 ELEMENT

Access an element of the vector (read/write).

9.4 IDFTIMESTAMP

The IDFTimestamp interface represents a value given by the reference clock. A timestamp consists of 2 parts: a low

part and a high part. Timestamp instances are created with the GenerateTimestamp method defined in ID-

FClock interface.

The ProgID for the object is DartfishMDTK.DFTimeStamp.

interface IDFTimestamp : Idispatch

{

HRESULT CopyTo([in, out] IDFTimestamp**);

HRESULT Create(

[in] int lowPart,

[in] int highPart);

HRESULT Add([in] int timeIntervalInUsec);

// properties

HRESULT LowPart([out, retval] int*);

HRESULT HighPart([out, retval] int*);

};

9.4.1 COPYTO

Copy the current timestamp to another instance of timestamp (deep copy).

9.4.2 CREATE

Create a timestamp from a low part and high part values.

9.4.3 ADD

The Add method is used for adding (or subtracting) a signed time interval value expressed in microseconds to the cur-

rent timestamp. This method can be used for performing fine time corrections on the generated timestamps. This

method can also be used repeatedly to send successive data points at a regular sampling interval."


9.4.4 LOWPART

Return the low part of a timestamp value.

9.4.5 HIGHPART

Return the high part of a timestamp value.

9.5 IDFCLOCK

The IDFClock interface allows accessing a common reference clock between Dartfish Software and the client appli-

cation. The main purpose of this interface is to generate Timestamps.

The ProgID for the object is "DartfishMDTK.DFClock".

interface IDFClock : Idispatch

{

HRESULT Initialize();

HRESULT GenerateTimestamp([in, out] IDFTimestamp**);

HRESULT SetGlobalTimeShift([in] int delayInUsec);

}

9.5.1 INITIALIZE

The Initialize method must be called prior to any call to the other methods.

9.5.2 GENERATETIMESTAMP

The GenerateTimestamp method is called for generating a new timestamp. This timestamp instance is used with

the MetadataStream “AddData()” method.

9.5.3 SETGLOBALTIMESHIFT

The SetGlobalTimeShift method is used for setting a global time correction value. All upcoming timestamps are

generated by taking the clock value and adding the time shift value. Since the time shift value is signed, it is possible to

program time delay correction directly in the DFClock. For example, assuming that it is known that the data received

from the physical sensor suffer a time delay “Delay_1”, by invoking SetGlobalTimeShift method and providing

“–Delay_1” as the value, it is possible to let the DFClock automatically generate “corrected” timestamps.


10 ERROR CODES (HRESULT)

Some methods of the API may return the following specific error codes if there aren't used properly.

MDTK_ERR_VECT_MIXTYPE = 0x80040400

All the values in a DFVector must have the same type.

MDTK_ERR_VECT_OUTOFRANGE = 0x80040401

The requested index is out of the range.

MDTK_ERR_VECT_BADSIZE = 0x80040402

Size parameter is not correct (probably <= 0).

MDTK_ERR_INIT2TIMES = 0x80040403

Initialize method cannot be called 2 times.

MDTK_ERR_UNKN_STRE_TYPE = 0x80040404

The requested stream type is not supported.

MDTK_ERR_INTERNAL_ERR = 0x80040405

Internal unknown error.

MDTK_ERR_STRE_SAME_NAME = 0x80040406

Trying to add a stream whose name already corresponds to an existing stream in DFMetadata.

MDTK_ERR_NOT_INIT = 0x80040407

Object has not been initialized.

MDTK_ERR_BAD_VAR_TYPE = 0x80040408

The provided type (variant type) is not supported as a value for a stream.

MDTK_ERR_STRE_MIXTYPE = 0x80040409

Trying to add a value to a stream with the wrong type. A metadata stream consists of a list of values with the same type. It is not

allowed to mix data types in a metadata stream.

MDTK_ERR_STRE_ATTBADTYPE = 0x8004040A

Bad type is provided for the requested metadata stream attribute.

MDTK_ERR_STRE_UNKN_ATTR = 0x8004040B

The requested stream attribute does not exist.

MDTK_ERR_CANT_CONNECTDT = 0x8004040C

Cannot connect to the Dartfish Software metadata server.

MDTK_ERR_OVERFLOW = 0x8004040D

Overflow condition has been detected.

MDTK_ERR_UNDERFLOW = 0x8004040E

Underflow condition has been detected.

MDTK_ERR_UNK_CMD_NAME =0x8004040F

The requested command name is not supported.

MDTK_ERR_NO_SUCH_PARAM = 0x80040410

This parameter name is not defined for the given command.

MDTK_ERR_INVALID_FLOW_TYPE_ARG =0x80040411

The argument for flow type is invalid. Flow type can only be "continuous" or "constant".

MDTK_ERR_BAD_PARAM_TYPE =0x80040412

Invalid type for the command parameter.

MDTK_ERR_INIT_SERIAL_MEM = 0x80040413

Cannot initialize DFSender: trying allocating memory for serializer failed.

MDTK_ERR_CANNOT_SERIAL =0x80040414

Cannot send metadata or command: internal serialization error.

MDTK_ERR_DATA_OUT_RANGE 0x80040415

Provided value is not valid because it is out of range.

MDTK_ERR_ATT_BAD_VALUE = 0x80040416

The provided value is not correct for the given attribute. Maybe the provided value does not correspond to a valid value for an enu-

merated type.


11 APPENDIX 1 : METADATA STREAM ATTRIBUTES

11.1 STREAM ATTRIBUTES DESCRIPTION

A stream has 3 required attributes:

name

identifier

xsi_type

5 optional feature attributes:

flowType

lowRange

highRange

interpolationType

valueUnit

3 optional recording attributes:

limitCount

freezeDelay

defaultValue

The required attributes are set when invoking the “Initialize()” method on IDFMetadataStream interface. The 8 op-

tional attributes are set by invoking the “SetStreamAttribute” method on IDFMetadataStream.

There are 2 types of optional metadata stream attributes:

recording attributes: used for specifying how to record the metadata streams during the video recording.

feature attributes: used for characterizing some features of the metadata streams.

11.1.1 FLOWTYPE (FEATURE ATTRIBUTE)

The attribute “flowType” indicates how the stream handles flow of data after it has been recorded.

There are currently 2 defined values:

“constant”: indicate that the values in the stream do not depend on the time parameter after the stream has

been recorded. The stream has only a single value (therefore the word “constant”). When such a stream is

recorded with a video clip, it contains a single value that is valid all through the video clip. As an example, let

us take a stream that represents the name of an athlete. A new value is sent each time a new athlete is de-

tected. This corresponds to the real-time stream. But when a video clip is recorded, only a single value is con-

sidered for the stream. Such a stream is a metadata stream with flowType = “constant”.

“continuous”: indicate that the values in the stream depends on the time parameter. When such a stream is

recorded with a video clip, the current value synchronized with the video depends on the time parameter. A

“Continuous” metadata stream represents a metadata that can vary during a video clip.

By default (= when not defined), the “flowType” of a stream is “continuous”.


11.1.2 LIMITCOUNT (RECORDING ATTRIBUTE)

The optional attribute “limitCount” is a positive integer allowing limiting the depth of the internal buffer where the

data are temporarily stored for holding the stream values of the “live” stream. This internal buffer is similar to the pre-

roll buffer for the video but it is used for metadata.

Each metadata stream has an associated internal preroll buffer. The “limitCount” parameter can be precisely tuned

for each metadata stream. Strictly speaking, this is only useful for metadata streams with high sampling rate when

using high values of video preroll.

11.1.3 FREEZEDELAY (RECORDING ATTRIBUTE)

The optional attribute “freezeDelay” is an integer representing a time value in msec that represents the maximum

delay used for allowing updating metadata after the end of a video capture. Once a video capture is stopped, the rec-

orded metadata stream is still updated until “freezeDelay” time elapses.

11.1.4 INTERPOLATIONTYPE (FEATURE ATTRIBUTE)

The optional attribute “interpolationType” defines how the metadata stream interpolates the data. There are 2 al-

lowed values for this attribute: “latest” and “linear”. By default, a metadata stream interpolates with “latest” method.

11.1.5 DEFAULTVALUE (RECORDING ATTRIBUTE)

The optional attribute “defaultValue” specifies the default value for the metadata stream when no data has been re-

ceived.

When this attribute is not defined, the default value of a stream is equal to 0 for numerical types and the empty char-

acter string for the alpha value types.

11.1.6 HIGHRANGE AND LOWRANGE (FEATURE ATTRIBUTE)

The optional attributes highRange and lowRange respectively define the highest and lowest possible values for the

stream data. For example, defining lowRange as “10” in an integer metadata stream means that all values will be

higher or equal to 10.

These 2 attributes are required for graphically displaying a recorded metadata stream.

11.1.7 VALUEUNIT(FEATURE ATTRIBUTE)

The optional attributes valueUnit defines the unit name that could be displayed with the stream values. For example,

defining valueUnit as “DaN” means that the values represent deca Newton (force unit).


12 APPENDIX 2: EXAMPLE IN JAVASCRIPT

In this first example, we continuously send metadata taken from a heartbeat sensor to Dartfish Software. We use a

single stream of metadata called “Heart Rate”.

This code requires Internet Explorer and allow the script from running ActiveXObject.

<!DOCTYPE html>

<html>

<body>

<h1>provide Metadata to ITA via JavaScript code</h1>

<button type="button" onclick="main()">Send data</button>

<p id="demo"></p>

<script>

function sleep(millis, callback) {

setTimeout(function ()

{ callback(); }

, millis);

}

var refClock;

var timestamp;

var sender;

var mdStream;

var metadataToSend;

function getData()

{

// TODO: get data from somewhere

return Math.random(); // generate value between [0.0;1.0)

}

function sendData() {

// generate data every three seconds

var data = getData ();

refClock.GenerateTimestamp(timestamp);

mdStream.Clear();

mdStream.AddData(data, timestamp);

sender.SendData(metadataToSend);

// output something to the html page

document.getElementById("demo").innerHTML += "<br/>" + Date();


// wait 3 secs

sleep(3000, sendData);

}

function main() {

try

{

// initialize MDTK context

refClock = new ActiveXObject("DartfishMDTK.DFClock");

refClock.Initialize();

timestamp = new ActiveXObject("DartfishMDTK.DFTimeStamp");

sender = new ActiveXObject("DartfishMDTK.DFMetadataSender");

sender.Initialize();

// create the stream of metadata used to collect the data to be sent.

mdStream = new ActiveXObject("DartfishMDTK.DFMetaDataStream");

// configure the stream for floating point value

mdStream.Initialize("Heart Rate", 1000, "integer");

// create the metadata and add the previous stream

metadataToSend = new ActiveXObject("DartfishMDTK.DFMetadata");

metadataToSend.Initialize("DataSource", 1002);

metadataToSend.AddStream(mdStream);

// start sending data to the MDTK

sendData();

}

catch (error) {

window.alert(error);

}

}

</script>

</body>

</html>

For being executed, this Javascript example must be saved in a file and the “GetDataFromSomewhere(...)” statement

modifed. The script must be executed after Dartfish Software is launched and ITA module enabled.


13 APPENDIX 3: EXAMPLE IN PSEUDO C# FOR TAGGING COMMANDS

First the operation regrouped in the Initialize() method must be called. Like in the WndProc method (e.g. available in

any control of Winform), the window message must be handled in order to catch the notification thrown by Dartfish

Software through the MDTK. When the sender is initialized, it can be used to send commands like in the Cre-

ateAnEvent method. The command sent must be created thanks to the command factory and before it is sent the pa-

rameters must be assigned.

// Define the signature for the RegisterWindowMessage from Win32

[DllImport("User32.dll", CharSet = CharSet.Auto)]

private static extern int RegisterWindowMessage(string msg);

public Initialize()

{

// Get a common message identifier for communicating between

// Dartfish Software and the plug-in.

m_msgId = RegisterWindowMessage("MdtkTaggingListener");

m_sender = new DFMETADATATOOLKITLib.DFMetadataSenderClass();

m_sender.Initialize();

m_sender.RegisterListenerForMDEvents(

(uint)m_control.Handle.ToInt32(),

(uint)msgId);

}

protected override void WndProc(ref Message m)

{

base.WndProc(ref m);

if (m.Msg == m_msgId)

{

// Catch message 5 which is the "Tagging New Event" notification.

if (m.LParam.ToInt32() == 5)

{

// Transform WParam into id and token and forward both parameters

SetIdToCreatedEvent(

m.WParam.ToInt32() >> 16,

m.WParam.ToInt32() & 0x0ffff);

}

else

{

Trace.WriteLine("Mdtk noification id is: " + m.LParam);

}

}

}


public void CreateAnEvent()

{

DFMETADATATOOLKITLib.DFMetadataCmdFactory cmdFactory =

new DFMETADATATOOLKITLib.DFMetadataCmdFactoryClass();

DFMETADATATOOLKITLib.IDFMetadataCmd cmd =

cmdFactory.CreateCmd("CreateTaggingEvent");

DFMETADATATOOLKITLib.IDFTimestamp timestamp =

new DFMETADATATOOLKITLib.DFTimestamp();

// Set the event position at 10.200 seconds.

timestamp.Create(10, 200);

object eventIdToken = “2345”;

object eventName = “MyEvent”;

object eventIn = timestamp;

object eventDuration = “2000”;

// assign parameters to the command

cmd.AssignParamValue(”EventIdToken”, ref eventIdToken);

cmd.AssignParamValue(”EventName”, ref eventName);

cmd.AssignParamValue(”EventIn”, ref eventIn);

cmd.AssignParamValue(”EventDuration”, ref eventDuration);

// send command

m_sender.SendCommand(cmd);

}

metadata toolkit spe ifi ations - dartfishbeta.dartfish.com/metadata toolkit specifications8.pdf ·...

Documents