Guide to the Tutor Message format (v4) > Media Logging > <tool_message> (media logging)

3.3. <tool_message> (media logging)

3.3.1. <semantic_event> (media logging)
3.3.2. <event_descriptor> (media logging)
3.3.3. XML Examples of tool messages for logging media events

While the context message places the actions of the student in context of the curriculum, the tool message captures the actions of the student. Generate a <tool_message> whenever the student interacts with the media or the tutor itself performs some action on the media. This will capture whenever media is stopped, started, muted, etc.

A tool message in media logging is structurally the same as a tool message for tutor logging. See Section 2.5, “<tool_message>” for a description of the tool message content model. In addition, the following constraints exist.

3.3.1. <semantic_event> (media logging)

Each tool message must include a <semantic_event> element. This element contains the transaction_id, which must be unique within the context message for each tool message. If this is a tutored event, a subsequent <tutor_message> will be paired with the tool message by this transaction_id.

[Note]Note

We decided that the media event is semantically important and as such we use the <semantic_event> element instead of the <ui_event> element. The <ui_event> element is for capturing events that may not be important such as mouse movements and key strokes.

The name attribute of the <semantic_event> is dependent on whether or not the event is tutored. A tutored event uses the standard ATTEMPT value; an untutored event should use a value from the following table:

Table 6. Recommended values for the <semantic_event> name attribute for a media object

name attribute value Description 
VIDEO_ACTIONUsed for an action on a video object.
AUDIO_ACTIONUsed for an action on an audio object.
MEDIA_ACTIONUsed for an action on another type of media object.

The <semantic_event> element has two attributes which are worth noting here: the trigger and the subtype. The trigger should be set to either of the following:

Table 7. Recommended values forthea <semantic_event> trigger attribute for a media object

trigger attribute valueDescription 
USERIf the user initiates the event.
DATAIf the tool or tutor initiates the event.

The subtype attribute is more of a free-form field that further qualifies the type of event. It can be set to something like tutor-performed. The value is stored in the DataShop database and exported, but no reasoning is dependent on this value.

3.3.2. <event_descriptor> (media logging)

Included in each tool message is the <event_descriptor> element which provides the details of the semantic event: it describes the specifics of the student's interaction with the tool. This should be a measurable change of state in the tool. It can be either a student action or an action taken for the student by the tool (see Section 3.3.1, “<semantic_event> (media logging)” for how to signify events initiated by the tutor).

For media logging, the event descriptor will include the action performed, the time(s) it occurred within the clip, and which interface elements were part of the interaction. Place these in the <selection>, <action>, <input> elements, each with a type attribute to further clarify the information those elements contain. The recommended list of media actions along with their expected selections and inputs are as follows:

Table 8. Format of an <event_descriptor> selections, action, and input values for a media object

 SelectionsAction Input(s)Notes
  • selection

  • media_file

  • clip_length

playtimestart/resume playback of clip; time is location in clip where playback was started
  • selection

  • media_file

  • clip_length

pausetimetime is location in clip where playback was paused
  • selection

  • media_file

  • clip_length

stoptimetime is location in clip where playback was stopped
  • selection

  • media_file

  • clip_length

closetimetime is location in current clip when media was closed
  • selection

  • media_file

  • clip_length

endtimethe end of the clip has been reached and playback has stopped; time should be the same as clip length
  • selection

  • media_file

  • clip_length

cue
  • start_cue

  • end_cue

start_cue is the time in the clip when the starting cue point was added; end_cue is the time in the clip when the ending cue point was added
  • selection

  • media_file

  • clip_length

mutetimetime is location in clip when this action occurred
  • selection

  • media_file

  • clip_length

unmutetimetime is location in clip when this action occurred
  • selection

  • media_file

  • clip_length

volume_change
  • time

  • start_level

  • final_level

time is location in clip when this action occurred. start_level is the volume level before the change, and final_level is the resulting volume level.
  • selection

  • media_file

  • clip_length

next_cliptimemove to the next media clip; time is location in current clip when this action occurred
  • selection

  • media_file

  • clip_length

prev_cliptimemove to the previous media clip; time is location in current clip when this action occurred

Every action is expected to have three selections. The first selection is the widget, button, or component that the student actually clicked on. The second is the name of the media file, and the third is the length of that file.

Example 3. Three selections for every media action

<selection>_level0.VideoPlayerInstance1.sliderButtonName</selection>
<selection type="media_file">mymovie.flv</selection>
<selection type="clip_length">00:08:34.823</selection>

The <input> elements will be used to indicate the media timing. Similar to <selection> elements the type attribute will be used to differentiate the different inputs. The inputs will vary by the action as noted in the table above. All time values should be in the form HH:MM:SS.SSS

Example 4. Example input

<input type="time">00:02:34.243</input>

3.3.3. XML Examples of tool messages for logging media events

The following are examples of typical media event log messages.

Example 5. Tool message for "play"

<tool_message 
   context_message_id ="02CE3AE5-F6D5-9177-913F-C34730F1096C">
   <semantic_event 
      transaction_id="1F3A9B23-9164-DD83-EBB2-1589FD38D4B3" 
      name="VIDEO_ACTION" />
   <event_descriptor>
         <selection>_level0.VideoPlayerInstance1.sliderButtonName</selection>
         <selection type="media_file">mymovie.flv</selection>
         <selection type="clip_length">00:08:00.0</input>
         <action>play</action>
         <input type="time">00:02:34.2</input>
   </event_descriptor>
</tool_message>

Example 6. Tool message for "stop"

<tool_message 
   context_message_id ="02CE3AE5-F6D5-9177-913F-C34730F1096C">
   <semantic_event 
      transaction_id="A43B003-9164-DD83-EBB2-1589FD38D435" 
      name="VIDEO_ACTION" />
   <event_descriptor>
      <selection>_level0.VideoPlayerInstance1.sliderButtonName</selection>
      <selection type="media_file">mymovie.flv</selection>
      <selection type="clip_length">00:08:00.0</input>
      <action>stop</action>
      <input type="time">00:05:32.2</input>
   </event_descriptor>
</tool_message>

Example 7. Tool message for "cue"

<tool_message 
   context_message_id ="02CE3AE5-F6D5-9177-913F-C34730F1096C">
   <semantic_event 
      transaction_id="B503948-9164-DD83-EBB2-1589FD38D435" 
      name="VIDEO_ACTION" />
   <event_descriptor>
      <selection>_level0.VideoPlayerInstance1.sliderButtonName</selection>
      <selection type="media_file">mymovie.flv</selection>
      <selection type="clip_length">00:08:00.0</input>
      <action>cue</action>
      <input type="start_cue">00:04:34.8</input>
      <input type="stop_cue">00:05:42.2</input>
   </event_descriptor>
</tool_message>