Documentation

Secure Video Player

When and Why to Use

Use this to present a video stimulus, optionally with a live dial for feedback. It's best for:

  • Ad or creative testing
  • Comprehension and recall studies
  • Real-time sentiment capture via dial testing

A video uploaded as Secure uses DRM playback, watermarked protected viewing and short-lived access. A Non-secure video uses standard playback. The security mode is fixed at upload; see Choosing a media security mode.

Other Names and Formats

With the live dial enabled, this instrument supports dial testing, moment-to-moment rating, a video sentiment question, or continuous response measurement while respondents watch a video stimulus. With the dial enabled, respondents can rate the secure video throughout playback. Without it, the platform plays the video before the follow-up questions.

Chat Experience

  • Video fills most of the screen with start and end messages above and below
  • If dial is enabled, it appears beneath or to the side depending on configuration

Traditional Experience

  • Video plays fullscreen or centered
  • Dial, if used, appears on the right or bottom with live interaction enabled
  • Remote or keyboard users can operate playback and dial
TraditionalMobile optimized
Secure Video PlayerSecure Video Player mobile

Play a video segment

Add your videos to a material. The examples use trailer.mp4 and ad-clip.mp4 in a material named Creatives. Set start_seconds and end_seconds to show a portion of the original video. For example, this plays from 10.5 to 25 seconds:

Code
s.play_video(video=s.get_video("Creatives", file_name="trailer.mp4"), start_seconds=10.5, end_seconds=25)

Omit start_seconds to begin at zero; omit end_seconds to continue to the video's end. Omitting both plays the full video. Bounds must be finite, non-negative seconds within the source duration, with the start before the end. The range must span at least one millisecond after conversion to playback positions.

Segments work with both secure and standard playback and retain the source video's protection settings. start_position still sets the initial dial value; use start_seconds for the playback start.

With a dial enabled, reaction sections cover the viewed segment and retain timestamps measured from the start of the original video. Use those timestamps directly for thumbnail follow-ups. See Dial testing with a video segment.

Dial Testing

Set dial="right" to show the dial on the right of the video or dial="bottom" to show it below; with the default dial="none" no dial is shown. The dial defaults to a 0-100 range with the captions "Dislike", "Neutral", and "Like" — customize it with dial_labels and dial_caption. The video and dial are always displayed in full screen, if available.

Reaction sections and follow-ups

When you enable a dial, play_video returns a result with chronological reaction sections. A section is classified as rising, falling, flat, peak or trough. Independent highest and lowest flags identify the sections containing the video's overall extremes; a local peak is not necessarily the highest reaction.

Each section carries its start and end time, dial value and tags for follow-up questions. Use the original video to request a frame from that section:

Code
video = s.get_video("Creatives", file_name="trailer.mp4") result = s.play_video(video=video, dial="bottom") for section in result.sections: if section.highest: frame = s.get_video_thumbnail(video, section.start_seconds) s.text_question( "What made this part stand out?", image=frame, tags=section.tags, )

To use this example with a Secure video, select that video from its material and keep the same get_video_thumbnail call. The resulting poster or timestamped frame inherits protected, watermarked viewing.

In a test link, play the video and continue to the follow-up. Video playback and frame generation finish independently: a temporary placeholder means the requested frame is still unavailable or processing. Verify the frame before fielding. Secure original-video and review-overlay downloads remain unavailable.

The follow-up retains the section interval, classification, dial value and originating video-question metadata for reporting. See get_video_thumbnail for frame handling.

In reporting, choose the section tag to group or filter by rising, falling, flat, peak or trough. These are tag values; highest and lowest are separate flags. See Report on reaction sections for a screenshot and the reporting tag reference.

Videos without a dial have no reaction sections. For analysis settings and the complete returned fields, see play_video in the API reference. For a fuller survey example, see Dial testing with MX8 Labs.

Configuration Options

OptionTypeRequiredDefaultDescription
videoMediaItemyes-Video attachment to play
end_messagestrno"Thank you for watching the video!"Message shown after the video ends
start_messagestrno"Hit play when you're ready to watch the video."Message shown before the video begins
dialstrno"none"Dial placement: "none", "right", or "bottom"
dial_labelsdict[int, str]no0-100 range labeled "Dislike", "Neutral", "Like"Labels shown on the dial scale
dial_captionstrno"Please adjust the slider to reflect your feelings as you watch the video."Caption shown above the dial
start_positionintnoMidpoint of the dial labelsStarting value for the dial
number_secondsintno0Seconds to wait before allowing the respondent to continue after the video
idstrno-Optional stable identifier for this question
start_secondsfloat | NonenoNonePlayback start in source-video seconds; omitted means zero.
end_secondsfloat | NonenoNonePlayback end in source-video seconds; omitted means the source end.
bucket_secondsintno5Positive reaction-analysis bucket size in seconds.
flat_tolerancefloatno0.05Bucket spread below this fraction of the dial range is flat; must be greater than zero and at most one.

Example Code

python
from survey import Survey s = Survey(**globals()) s.play_video(video=s.get_video("Creatives", file_name="ad-clip.mp4"))

With dial testing:

Code
s.play_video( video=s.get_video("Creatives", file_name="trailer.mp4"), dial="bottom", dial_labels={0: "Very Negative", 50: "Neutral", 100: "Very Positive"}, dial_caption="Move the slider to reflect how you're feeling during the video." )

Notes

  • Secure videos use DRM and protected, watermarked viewing; Non-secure videos use standard playback
  • Downloadable review overlays are available for Non-secure videos
  • Respondents cannot skip; playback is enforced
  • Use dial for moment-to-moment reaction measurement
  • Best followed by comprehension or diagnostic questions