statement_data_model.md

Current Version: xAPI Video Profile v1.0

#2. xAPI Statement Data Model

##2.1 Statement ID

The LRP MUST assign a statement id property in UUID format (as defined in the xAPI specification) for all statements it issues.

##2.2 Actor

The Actor property must be defined as per the xAPI Specification.

When the video is launched in an LMS, Actor must be provided by the LMS.

##2.3 Verbs

The following xAPI verbs are defined in this specification.

LRP MUST use the below verbs that are indicated as mandatory in other sections of this specification.

###2.3.1 Initialized

Verb	Initialized
ID	http://adlnet.gov/expapi/verbs/initialized
Description	An "Initialized" statement is used by the LRP to indicate that the video has been fully initialized or launched.
LRP Obligations	The LRP MUST use "Initialized" in the first statement in the video session. The LRP MUST NOT issue multiple statements with "Initialized" for the same video session.
Usage	An "Initialized" statement is used by the LRP to indicate that the video has been fully initialized or launched.

###2.3.2 Played

Verb	Played
ID	https://w3id.org/xapi/video/verbs/played
Description	Indicates that the actor started experiencing the recorded media object.
LRP Obligations	The LRP MUST use "Played" when the actor starts experiencing the media.
Usage	Used when the actor generally played a video or clicked the play button.

###2.3.3 Paused

Verb	Paused
ID	https://w3id.org/xapi/video/verbs/paused
Description	Indicates that the actor temporary or permanently stopped experiencing the recorded media object.
LRP Obligations	The LRP MUST use "Paused" when the media is stopped. A paused statement MUST be sent before a terminated statement if not already sent.
Usage	Indicates that the actor temporary or permanently stopped experiencing the recorded media object.

###2.3.4 Seeked

Verb	Seeked
ID	https://w3id.org/xapi/video/verbs/seeked
Description	Indicates the actor changed the progress towards a specific point.
LRP Obligations	The LRP MUST use "Seeked" when the Actor moves the progress bar forward or backward to a specific time in video.
Usage	Used in combination with time-from and time-to extensions when the Actor moves the progress bar forward or backward to a specific time in the video.

###2.3.5 Interacted

Verb	Interacted
ID	http://adlnet.gov/expapi/verbs/interacted
Description	Used to express that the actor interacted with the player (except play, pause, seek). e.g. mute, unmute, change resolution, change player size, etc.
LRP Obligations	Optional
Usage	Used to express that the actor interacted with the player (except play, pause, seek). e.g. mute, unmute, change resolution, change player size, etc.

###2.3.6 Completed

Verb	Completed
ID	http://adlnet.gov/expapi/verbs/completed
Description	Used to express that the actor completed a video by watching all parts of the video at least once.
LRP Obligations	The LRP MUST use "Completed" when the Actor has completed a video by watching all parts of the video at least once. The "completion" property of the result MUST be set to true for this statement. The "duration" property of the result MUST be included in this statement and MUST represent total time spent during consuming the video under current registration. e.g. PT218S
Usage	Used to express that the actor completed a video by watching all parts of the video at least once. The progress and heatmap result extension can be used to calculate the duration and completion of video.

###2.3.7 Terminated

Verb	Terminated
ID	http://adlnet.gov/expapi/verbs/terminated
Description	Used to express that the actor ended a video.
LRP Obligations	Optional. The LRP MAY use "Terminated" when the Actor has terminated the video. A "Paused" statement MUST be sent before "Terminated" statement if not already sent. Any statements after this in the current video session MUST NOT be sent, and will be ignored if sent.
Usage	Used to express that the actor ended a video.

##2.4 Object

An Object with objectType "Activity" MUST be present, as specified in the xAPI Spec.

The Object represents the video or media being consumed by the Actor.

###2.4.1 Definition

Object definition MAY contain name, description and other details of the media, as per the xAPI Spec.

Object definition MUST be present and MUST contain activity "type" as: https://w3id.org/xapi/video/activity-type/video

##2.5 Result

Result is an optional property that represents a measured outcome related to the Statement in which it is included.

It may be present in a statement depending on the verb used.

###2.5.1 Score

A score is not required to be reported. If a score is reported, it must be as per the xAPI Spec.

###2.5.2 Completion

The "completion" property of the result MUST be set to true for the 'completed' statement.

Other Video Profile statements MUST NOT include the "completion" property.

###2.5.3 Duration

The "duration" property is an ISO 8601 formatted time value.

Duration MUST be included in "completed" statement and MUST represent total time spent consuming the video under current registration. e.g. PT218S

###2.5.4 Result Extensions

There are several additional results related values defined in Video Profile that can be added to the statement under result extensions.

###2.5.4.1 Time

Extension	time
ID	https://w3id.org/xapi/video/extensions/time
Description	Used to express the time into the video.
LRP Obligations	The LRP MUST assign time value to statements with "played", "paused", "terminated", "interacted" and "completed" verbs. Float Value with maximum 3 decimals.
Usage	Example: "23.560" represents video position at 23 seconds and 560 milliseconds.

###2.5.4.2 Time From

Extension	time-from
ID	https://w3id.org/xapi/video/extensions/time-from
Description	Used to identify the point in time the actor changed from in a media object during a seek operation.
LRP Obligations	The LRP MUST assign time-from value to statements with "seeked" verbs only. Float Value with maximum 3 decimals.
Usage	Example: "23.560" represents video position at 23 seconds and 560 milliseconds.

###2.5.4.3 Time To

Extension	time-to
ID	https://w3id.org/xapi/video/extensions/time-to
Description	Used to identify the point in time the actor changed to in a media object during a seek operation.
LRP Obligations	The LRP MUST assign time-to value to statements with "seeked" verbs only. Float Value with maximum 3 decimals.
Usage	Example: "23.560" represents video position at 23 seconds and 560 milliseconds.

###2.5.4.4 Progress

Extension	progress
ID	https://w3id.org/xapi/video/extensions/progress
Description	Used to expresses the percentage of media consumed by the actor.
LRP Obligations	The LRP MUST assign progress value to statements with "paused", "terminated" and "completed" verbs. The LRP MAY assign progress value to other statements. Float value between 0 and 1, with a maximum of 3 decimals.
Usage	The progress value includes all attempts made during the current registration. The heatmap extension can be used to calculate the progress.

###2.5.4.5 Played Segments

Extension	played-segments
ID	https://w3id.org/xapi/video/extensions/played-segments
Description	Played segments data shows parts of the video the actor watched during current registration in chronological order.
LRP Obligations	The LRP MUST assign played-segments value to statements with "paused", "terminated" and "completed" verbs. The LRP MAY assign played-segments value to other statements. Value is a string. Each part of the video watched is separated with [,]. The 'Time From' and 'Time To' values are separated with [.]. The time values must match the values recorded as time, time-to and time-from in played, paused, seeked statements.
Usage	The played-segments value includes all attempts made during the current registration. It is used for computing the progress and completion. It can also be used to generate heat map of the users consumption of the video. Example: 0.000[.]12.000[,]14.000[.]21.000[,]18.000[.]30.000

##2.6 Context

All Video Profile statements MUST contain a context that includes all objects/values as defined in this section.

###2.6.1 Registration

The value for the registration property used in the context object MAY be the value provided by the LMS via the launch URL. If registration is not provided via the launch mechanism, the LRP MAY set a fixed registration value.

The registration value is important because the "progress", the "played-segments" value and "completion" is based on aggregate of all attempts with same registration value attempted by the Actor for the specific media.

###2.6.2 Language

Code representing the language in which the experience being recorded in this Statement (mainly) occurred in, if applicable and known.

Language is used to provide the spoken language for the audio.

The value must be RFC 5646, e.g en, en-US, etc

###2.6.2 Context Extensions

####2.6.2.1 Session ID

Extension	session-id
ID	https://w3id.org/xapi/video/extensions/session-id
Description	Used to tell which session the statement is part of. A session starts with the initiated statement and ends with terminated statement.
LRP Obligations	The LRP SHOULD assign a session id to all the statements sent during a session. Value of session id MUST be the UUID statement id of the initiated statement, i.e. the initialized statement.
Usage

###2.6.2.2 CC/Subtitle Enabled

Extension	cc-subtitle-enabled
ID	https://w3id.org/xapi/video/extensions/cc-subtitle-enabled
Description	Used to expresses whether subtitle or closed captioning is enabled.
LRP Obligations	Value MUST be boolean i.e. true or false.
Usage

###2.6.2.3 CC/Subtitle Language

Extension	cc-subtitle-lang
ID	https://w3id.org/xapi/video/extensions/cc-subtitle-lang
Description	Used to express the language of subtitle or closed captioning.
LRP Obligations	Used only when cc-subtitle-enabled is true.
Usage	The lexical and value spaces of xsd:language are the set of language codes defined by RFC 5646. Examples: "en" for English or "en-US" for American English

###2.6.2.4 Frame Rate

Extension	frame-rate
ID	https://w3id.org/xapi/video/extensions/frame-rate
Description	Used to express the frame rate or frames per second of a video (or average rate of frames per second in the case of variable frame-rate).
LRP Obligations
Usage	Represented as a decimal, such as 29.970.

###2.6.2.5 Full Screen

Extension	full-screen
ID	https://w3id.org/xapi/video/extensions/full-screen
Description	Used to expresses that the video is played in full screen mode.
LRP Obligations	Value MUST be boolean i.e. true or false.
Usage

###2.6.2.6 Quality

Extension	quality
ID	https://w3id.org/xapi/video/extensions/quality
Description	Used to express the video resolution or quality.
LRP Obligations	Value is a string. e.g. 360, 480, 720, 1080, 2160, sd, hd, 4k, 8k etc.
Usage

###2.6.2.7 Screen Size

Extension	screen-size
ID	https://w3id.org/xapi/video/extensions/screen-size
Description	Used to express the device playback screen size or the maximum available screen size for Video playback.
LRP Obligations	Value MUST be in WxH format in pixels. e.g. 1080x960, 640x480, 800x600
Usage

###2.6.2.8 Video Playback Size

Extension	video-playback-size
ID	https://w3id.org/xapi/video/extensions/video-playback-size
Description	Used to identify the size in Width x Height of the video as viewed by the user.
LRP Obligations	Value MUST be in WxH format in pixels. e.g. 1080x960, 640x480, 800x600
Usage

###2.6.2.9 Speed

Extension	speed
ID	https://w3id.org/xapi/video/extensions/speed
Description	Used to express the play-back speed.
LRP Obligations	Value MUST be represented with decimal or integer values along with an 'x' meaning multiplying factor to the normal speed. e.g. -2x, -1x, -0.5x, 0.5x, 1x, 2x.
Usage	Negative value means rewind. e.g. -1x, -2x Positive value with value greater than 1x means fast forward. e.g. 1.5x, 2x, 4x Positive value with value less than 1x means slow motion play back. e.g. 0.5x, 0.25x, 0.125x

###2.6.2.10 Track

Extension	track
ID	https://w3id.org/xapi/video/extensions/track
Description	Used to identify the name of the audio track in a media object.
LRP Obligations	Value MUST be a string.
Usage

###2.6.2.11 User Agent

Extension	user-agent
ID	https://w3id.org/xapi/video/extensions/user-agent
Description	Used to identify the User Agent string of the browser, if the video is launched in browser.
LRP Obligations	Value MUST be a string.
Usage

###2.6.2.12 Volume

Extension	volume
ID	https://w3id.org/xapi/video/extensions/volume
Description	Used to identify the loudness of sound specified for a media object.
LRP Obligations	Value MUST be a float value between 0 and 1.
Usage	Minimum 0 = Mute. Maximum 1 = 100% Volume

###2.6.2.13 Length

Extension	length
ID	https://w3id.org/xapi/video/extensions/length
Description	The actual length of the media in seconds.
LRP Obligations	Value MUST be a float value with maximum 3 decimals. It MUST be included in Video Profile statements with these verbs: initialized, completed, terminated and paused.
Usage

###2.6.2.14 Completion Threshold

Extension	completion-threshold
ID	https://w3id.org/xapi/video/extensions/completion-threshold
Description	Completion Threshold specifies the percentage of media that should be consumed to trigger a completion.
LRP Obligations	Value MUST be between 0 and 1. Value MUST be a float value with maximum 3 decimals. If Completion Threshold is not included, it is assumed to be 1, i.e. 100%. If Completion Threshold is not 1, it MUST be included in Video Profile statements with these verbs: initialized, completed, terminated and paused.
Usage

###2.6.2 Context Activities

####2.6.2.1 Category

ID	https://w3id.org/xapi/video
Description	xAPI Video Profile statement
LRP Obligations	Must.
Usage	Identifies a statement as conforming to the xAPI Video Profile

###2.7 Summary of Extensions Usage

Verbs	Required	Optional
Initialized	Context Extensions Length Completion Threshold (if value < 1)	Context Extensions Session ID CC/Subtitle Enabled CC/Subtitle Language Frame Rate Full Screen Quality Screen Size Video Playback Size Speed Track User Agent Volume Completion Threshold (if value = 1)
Played	Result Extensions Time	Context Extensions Session ID
Paused	Context Extensions Length Completion Threshold (if value < 1) Result Extensions Time Progress Played Segments	Context Extensions Session ID Completion Threshold (if value = 1)
Seeked	Result Extensions Time From Time To	Context Extensions Length Session ID Result Extensions Progress Played Segments
Interacted	Context Extensions Context Extensions for which the value has changed during interaction MUST be included Result Extensions Time	Context Extensions Session ID CC/Subtitle Enabled CC/Subtitle Language Frame Rate Full Screen Quality Video Playback Size Speed Track Volume
Completed	Context Extensions Length Completion Threshold (if value < 1) Result Extensions Time Progress Played Segments Others result.completion = true result.duration = (total time spent consuming the video under current registration)	Context Extensions Session ID Completion Threshold (if value = 1)
Terminated	Context Extensions Length Completion Threshold (if value < 1) Result Extensions Time Progress Played Segments	Context Extensions Session ID Completion Threshold (if value = 1)

*Session ID is optional. However, it SHOULD be added in all statements, unless there is a reason not to.