Synchronized Video Component

The Synchronized Video component allows you to present video content precisely synchronized across all participants. It's one of the core features of the HyperStudy platform, enabling experiments where participants view the same media with millisecond-level synchronization.

Usage Scenarios

Showing stimulus videos to multiple participants simultaneously
Social viewing experiments where participant reactions are recorded
Media co-consumption studies
Measuring physiological responses to synchronized video content

Configuration Options

Parameter	Description	Default
`videoSource`	URL or file ID of the video to display	(required)
`autoPlay`	Automatically start video when component loads (host only)*	`false`
`showControls`	Display video playback controls	`true`
`showTimecode`	Display current time position	`false`
`syncAccuracy`	Target synchronization accuracy in milliseconds	`50`
`hostControlOnly`	Only allow the host role to control playback	`true`
`allowSkipping`	Allow seeking through the video	`true`
`startTime`	Initial playback position in seconds	`0`
`endTime`	If set, video will automatically proceed to next state at this time	(optional)
`width`	Width of the video player (px or %)	`100%`
`height`	Height of the video player (px or %)	`auto`
`skipOnComplete`	Automatically advance to next state when video completes	`false`

Autoplay Browser Policies

Important: Modern browsers have strict autoplay policies. Videos with sound may not autoplay automatically, especially:

On the first visit to your experiment
Without prior user interaction
In certain browsers (Firefox, Safari)

If autoplay is blocked, the host participant will need to manually click the play button to start the video. This is a browser security feature and cannot be bypassed without compromising experiment integrity.

Host Controls

When hostControlOnly is enabled (default), only the participant assigned to the "host" role can control video playback. All other participants will be synchronized to the host's playback position. Host controls include:

Play/pause
Seeking to specific positions
Adjusting playback rate
Emergency resynchronization

Synchronization Technology

The component uses a sophisticated synchronization system:

Kalman Filter: Predicts host position accounting for network latency
PID Controller: Adjusts playback rates to maintain synchronization
Server-mediated Time: Shares a common time reference across all clients
Adaptive Buffering: Handles client buffering events intelligently

Adding a Synchronized Video

In the Experiment Designer, select the state where you want to add the video
Set the focus component to "Synchronized Video"
Configure the video options:
- Select a video from the media library or provide a URL
- Set playback options
- Configure synchronization parameters
Save your changes

Video Sources

The Synchronized Video component supports two types of video sources:

Platform-Hosted Videos (Recommended)

Videos uploaded to HyperStudy's media library:

Security: Protected by signed URLs (not publicly accessible)
Performance: Automatically precached for instant playback
Synchronization: Optimized for precise multi-participant sync
Privacy: URLs expire after 3 hours, preventing unauthorized access
Best For: Proprietary content, sensitive materials, research videos

External Videos

Videos hosted on external platforms:

Flexibility: Use videos from YouTube, Vimeo, university servers, CDNs
No Upload: Link directly to publicly accessible URLs
Requirement: Must be publicly accessible
Best For: Public educational content, videos already hosted elsewhere
Note: No access control or signed URL protection

Video File Requirements

Critical: Format Compatibility

Some video formats will cause playback failures in Firefox, particularly when using timestamp-based features like Sparse Rating or multi-state experiments with time segmentation. Always use MP4 (H.264, yuv420p chroma) for maximum compatibility.

See the Video Format Recommendations section in the Media Management guide for detailed compatibility information.

Recommended Format (Best Compatibility)

MP4 with specific encoding:

Video codec: H.264 (x264)
Audio codec: AAC
Chroma subsampling: yuv420p (Firefox requires this)
Container optimization: faststart flag enabled
Resolution: 720p or 1080p recommended (higher resolutions increase bandwidth)
Duration: Videos under 20 minutes perform best
File size: Keep under 200MB when possible for faster precaching
Hosting: Use the built-in media library for best performance and security

Alternative format:

WebM (VP8/VP9 video, Vorbis/Opus audio) - Full browser support

Problematic Formats ⚠️

The following formats may cause Firefox playback failures, especially when:

Using Sparse Rating component (pause/resume at timestamps)
Jumping to specific timestamps (startTime/endTime state parameters)
Segmenting videos across multiple states

Formats to avoid:

❌ MOV (QuickTime) - Firefox often fails with "corrupt file" error due to chroma subsampling incompatibility
❌ AVI - No browser support
⚠️ MKV - Very limited browser support
⚠️ M4V - May have same issues as MOV

What happens with incompatible formats:

Video may play initially but crash when seeking/pausing
State transitions may fail with decode errors
Sparse rating pause/resume may cause video to freeze
Works fine in Chrome/Safari but fails in Firefox

Solution: Convert problematic formats to MP4 using FFmpeg:

ffmpeg -i input.mov -c:v libx264 -pix_fmt yuv420p -preset medium -crf 23 \
       -c:a aac -b:a 128k -movflags +faststart output.mp4

For detailed information about format compatibility issues and conversion, see the Media Management guide.

Advanced Features

Automatic Media Precaching

The platform automatically precaches videos before the experiment starts to ensure optimal performance:

How It Works:

Videos are identified during experiment initialization
All participants preload videos before entering video states
Playback starts instantly without buffering delays
Browser caching optimized for efficient re-use

Benefits:

Instant Playback: No loading delays when video state begins
Perfect Synchronization: All participants start from fully loaded state
Consistent Timing: Eliminates network-dependent loading variability
Improved UX: Smooth, professional experiment experience

What Gets Precached:

All videos used in Video components throughout the experiment
Both platform-hosted and external videos (when possible)
Images used in Image components

Best Practice: Upload videos to the platform's media library for optimal precaching support. External videos may have variable precaching success depending on CORS policies and hosting configuration.

Synchronization Quality Indicator

Enable the showSyncIndicator option to display a small indicator showing current synchronization quality. Colors represent:

Green: Excellent synchronization (within 50ms)
Yellow: Acceptable synchronization (50-200ms)
Red: Poor synchronization (>200ms)

Variable Capture

Set the capturePositionToVariable option to store the current playback position to a specified variable at regular intervals or when playback stops.

Time-based Events

Use the timeEvents array to trigger events or set variables at specific timestamps during playback:

"timeEvents": [
  {
    "time": 45.5,
    "action": "setVariable",
    "variable": "exposureComplete",
    "value": true
  },
  {
    "time": 120,
    "action": "showOverlay",
    "content": "Pay attention to the next section"
  }
]

Best Practices

Use Platform-Hosted Videos: Upload videos to the media library for best security, performance, and precaching support
Test Across Devices: Video performance can vary - test on comparable devices to what participants will use
Keep Videos Short: Long videos increase the chance of synchronization issues
Secure Sensitive Content: For proprietary or sensitive materials, always upload to the platform rather than using external URLs
External Videos: When using external videos, ensure they are:
- Publicly accessible (no authentication required)
- Hosted on reliable, fast servers
- Direct MP4 links rather than service URLs when possible
Monitor Precaching: During testing, check console logs to confirm videos precache successfully before experiment starts
Consider File Size: Larger videos take longer to precache - balance quality with loading time

Common Issues and Solutions

Issue	Possible Cause	Solution
"Video can't be played because file is corrupt" (Firefox)	MOV/AVI/MKV format with incompatible encoding	Convert to MP4 with yuv420p chroma (see format guide above)
Sparse rating fails/freezes	Incompatible video format (MOV)	Use MP4 (H.264, yuv420p) instead
State transitions fail with decode error	MOV file with yuv422p/yuv444p chroma	Convert to MP4 with `-pix_fmt yuv420p`
Video won't load	External URL not publicly accessible	Upload to platform or use a public URL
Video won't synchronize	Network latency variation	Increase buffer time, reduce video quality
Black screen on some devices	Codec compatibility	Convert video to H.264 MP4 with yuv420p
Frequent buffering	Bandwidth limitations	Reduce video resolution or bitrate
Long loading delay	Video not precached	Upload to platform for automatic precaching
"Access Denied" error	External URL requires authentication	Use publicly accessible URL or upload to platform
Audio/video out of sync	Processing limitations	Use lower resolution video, close other applications
Seek controls don't work	`allowSkipping` disabled	Enable this setting if seeking is required
Inconsistent performance	Using external URL	Upload to platform for consistent performance
Works in Chrome but not Firefox	Video encoding incompatibility	Ensure yuv420p chroma subsampling (not yuv422p/yuv444p)

Media Management Guide - Learn about video security, precaching, and the differences between uploaded and external videos
Image Component - Display images in your experiments (also supports precaching)
Video Chat Component - Real-time video communication between participants

Usage Scenarios​

Configuration Options​

Autoplay Browser Policies​

Host Controls​

Synchronization Technology​

Adding a Synchronized Video​

Video Sources​

Platform-Hosted Videos (Recommended)​

External Videos​

Video File Requirements​

Recommended Format (Best Compatibility)​

Problematic Formats ⚠️​

Advanced Features​

Automatic Media Precaching​

Synchronization Quality Indicator​

Variable Capture​

Time-based Events​

Best Practices​

Common Issues and Solutions​

Related Documentation​