Skip to main content

Media Management

The HyperStudy platform provides a comprehensive media management system for organizing, uploading, and using videos and images in your experiments. The system includes folder organization, tagging, and sophisticated permission controls for sharing media across research teams.

Video Management Interface Video management interface showing folder structure and video library with URLs and metadata

Image Management Interface Image management interface with grid view and folder navigation

Media Types​

The platform supports two primary types of media:

Images​

  • Supported formats: JPG, PNG, GIF, SVG
  • Maximum file size: 10MB per image
  • Recommended resolution: 1920x1080px or smaller
  • Common uses: Visual stimuli, diagrams, instructions

Videos​

HyperStudy supports two types of video sources, each with distinct advantages:

Uploaded Videos (Platform-Hosted)​

  • Security: Videos uploaded to the platform use signed URLs that are not publicly accessible
  • Privacy: URLs are only valid for authorized users and expire after 3 hours
  • Performance: Automatically precached for optimal loading and synchronization
  • Accepted formats: MP4, WebM, OGG, MOV, AVI, MKV, M4V
  • Recommended format: MP4 (H.264 video, AAC audio, yuv420p chroma) - see Video Format Recommendations below
  • Maximum file size: 5GB per video
  • Recommended resolution: 1080p (1920x1080) or smaller

External Videos (URL-Based)​

  • Flexibility: Use any publicly accessible video URL
  • No Upload Required: Link directly to videos hosted elsewhere
  • Sources: YouTube, Vimeo, university servers, CDNs, public S3 buckets
  • Note: These videos must be publicly accessible and are not protected by platform security

Video Format Recommendations​

Browser Compatibility Alert

IMPORTANT: Some video formats have known compatibility issues that can cause playback failures, especially in Firefox. These issues particularly affect experiments using timestamp indexing (jumping to specific video times) and the Sparse Rating component (which pauses and resumes video at specific timestamps).

For maximum browser compatibility and reliable playback across all features:

  1. MP4 (H.264 video codec, AAC audio) ⭐ RECOMMENDED

    • Encoding requirements:
      • Video codec: H.264 (x264)
      • Audio codec: AAC
      • Chroma subsampling: yuv420p (critical for Firefox)
      • Container optimization: -movflags +faststart flag
    • Why: Universal browser support, optimal for web playback
    • Best for: All experiments, especially those with sparse rating or timestamp jumping

  2. WebM (VP8/VP9 video, Vorbis/Opus audio) ✅ GOOD ALTERNATIVE

    • Full browser support
    • Open format
    • Good compression

Example FFmpeg command for optimal MP4:

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

Problematic Formats (May Cause Issues)​

Known Issues

The following formats may cause playback errors in Firefox and other browsers, particularly when using features that require precise video seeking (sparse rating, timestamp-based state transitions):

MOV (QuickTime) ⚠️ Compatibility Warning​

Issues:

  • Limited Firefox support: Often fails with "Video can't be played because file is corrupt" error
  • Chroma subsampling incompatibility: Many MOV files use yuv422p or yuv444p chroma subsampling, which Firefox cannot decode (Firefox only supports yuv420p)
  • Partial codec support: Firefox has limited QuickTime container support
Critical Firefox + Signed URL Issue

MOV files may fail to seek in Firefox when served via signed URLs, even if initial playback works. This is due to Firefox's strict handling of range requests combined with QuickTime container limitations. The issue is especially problematic for experiments using:

  • Sparse Rating (pause/resume at specific timestamps)
  • Multi-state video segmentation (different time ranges across states)
  • Any timestamp-based seeking

Solution: Convert MOV files to MP4 with yuv420p chroma subsampling before uploading. MP4 files work reliably with signed URLs in all browsers.

Impact on experiments:

  • ❌ Sparse Rating Component: May fail when pausing/resuming at specific timestamps
  • ❌ Multi-state experiments: May fail when transitioning between states using different time segments of the same video
  • ❌ Seek operations: May crash decoder when jumping to specific timestamps
  • ❌ Signed URL + MOV: Firefox cannot reliably seek to timestamps in MOV files served via authenticated URLs
  • ⚠️ Inconsistent behavior: Works in Chrome/Safari but fails in Firefox

When uploaded, you'll receive a warning recommending conversion to MP4.

AVI ❌ Not Recommended​

Issues:

  • No browser support: Not supported by modern browsers
  • No native HTML5 support: Cannot play in Firefox, Chrome, or Safari
  • Will not work: Guaranteed playback failure

Action required: Convert to MP4 before uploading.

MKV (Matroska) ⚠️ Limited Support​

Issues:

  • Very limited browser support: Only experimental support in Firefox Nightly builds
  • Not production-ready: Should not be used for participant-facing experiments
  • Inconsistent playback: May work in some browsers but fail in others

When uploaded, you'll receive a warning recommending conversion to MP4.

M4V ⚠️ Potential Issues​

Issues:

  • Similar to MOV: Can have same chroma subsampling problems
  • Codec-dependent: Compatibility depends on encoding settings
  • May fail in Firefox: If encoded with yuv422p/yuv444p

When uploaded, you'll receive a warning. Test thoroughly before using in experiments.

Why These Issues Occur​

Technical explanation: Firefox's video decoder only supports YUV 4:2:0 chroma subsampling for H.264 videos. Many professional video cameras and editing software export MOV files with YUV 4:2:2 or YUV 4:4:4 chroma subsampling for higher color fidelity. While these higher-quality formats work fine in standalone media players, they cause Firefox's browser-based decoder to fail with a MEDIA_ERR_DECODE error.

Additional Firefox + Signed URL complexity: Platform-uploaded videos use signed URLs for security. These time-limited, authenticated URLs protect your proprietary content but can interact poorly with Firefox's video decoder when combined with incompatible formats. When Firefox attempts to seek to a specific timestamp in a MOV file served via signed URL, it may fail to properly re-request video segments, causing playback errors even if the initial load succeeded. MP4 files with yuv420p chroma subsampling do NOT have this issue - they work reliably with signed URLs in all browsers including Firefox.

This is particularly problematic for:

  • Timestamp-based features: Seeking to specific video times (used in sparse rating)
  • Video segmentation: Playing different time ranges of the same video across multiple states
  • Multi-participant sync: When Firefox participants cannot decode the video
  • Signed URL + MOV combination: Firefox may fail to seek even if initial playback works

Upload Warnings System​

When you upload a problematic format, the system will warn you:

Warning severity levels:

  • 🔴 Error (AVI): Format will not work, conversion required
  • 🟡 Warning (MOV, MKV, M4V): Format may not work in all browsers

Warning message includes:

  • Specific compatibility issues
  • Browsers affected
  • Recommended formats
  • Note that sparse rating and timestamp features may fail

Your options:

  1. Convert to MP4 (recommended): Use FFmpeg or video editing software
  2. Upload anyway: For testing or if you know all participants use compatible browsers
  3. Cancel: Choose a different file

Converting Videos to Compatible Format​

If you have MOV, AVI, or other problematic files:

Quick conversion (preserves quality):

# Convert MOV to web-optimized MP4
ffmpeg -i input.mov -pix_fmt yuv420p -c:a copy -movflags +faststart output.mp4

Full conversion (with compression):

# Convert any format to optimized MP4
ffmpeg -i input.mov -c:v libx264 -pix_fmt yuv420p -preset medium -crf 23 \
       -c:a aac -b:a 128k -movflags +faststart output.mp4

What these flags do:

  • -pix_fmt yuv420p: Ensures Firefox-compatible chroma subsampling
  • -movflags +faststart: Optimizes for web streaming (moov atom at start)
  • -preset medium: Balances encoding speed vs compression
  • -crf 23: Constant quality (lower = higher quality, 18-28 typical range)

Need help? Many free tools can convert videos:

  • HandBrake (free, cross-platform GUI)
  • FFmpeg (free, command-line)
  • Online converters (for smaller files)

Testing Video Compatibility​

Before using a video in an experiment with sparse rating or timestamp features:

  1. Upload the video to the platform
  2. Check for warnings during upload
  3. Test in Firefox:
    • Create a simple test experiment
    • Add the video to a state with timestamp segmentation (e.g., startTime: 0, endTime: 15, then second state startTime: 15, endTime: 30)
    • Run the experiment in Firefox
    • Verify no "corrupt file" errors when transitioning between states
  4. Test sparse rating: If using sparse rating component, test pause/resume functionality in Firefox

Future Enhancement: Automatic Transcoding​

We are planning an automatic video transcoding system that will:

  • Convert uploaded videos to web-optimized MP4 automatically
  • Eliminate browser compatibility issues
  • Provide optimal performance for all experiments

See docs/technical/video-transcoding-plan.md for details.

Media Library​

Accessing the Media Library​

There are multiple ways to access the media library:

  1. From the Admin Dashboard:

    • Navigate to your dashboard
    • Click the "Media" button in the sidebar
    • Toggle between "Videos" and "Images" tabs

  2. From the Experimenter Dashboard:

    • Access your experimenter view
    • Navigate to the Media section
    • Browse available media based on your permissions

  3. During Experiment Design:

    • When configuring an Image or Video component
    • Click "Browse Library" or "Select Media" in the component properties
    • This opens the media selector interface with filtering options

Library Organization​

The media library provides sophisticated organization features:

  • Folder Structure:

    • Create nested folders for hierarchical organization
    • Folders visible in the left sidebar
    • Quick navigation with breadcrumb trail
    • Add new folders with the "Add Folder" button

  • Media Information:

    • Direct URLs for each media item
    • File metadata (size, format, duration for videos)
    • Upload date and owner information
    • Usage tracking across experiments

  • Search and Filters:

    • Search by filename, URL, or description
    • Filter by media type, date range, or owner
    • Export options for bulk operations
    • Pagination for large libraries

Uploading Media​

Image Upload​

To upload images:

  1. Navigate to the Images section of the Media Library
  2. Click the "Upload" button
  3. Select one or more image files from your device
  4. Alternatively, drag and drop files into the upload area
  5. Add metadata (title, description, tags) during upload
  6. Assign to folders and set permissions
  7. Click "Upload" to complete the process

Video Upload​

The platform supports multiple video methods, each suited to different needs:

Option 1: Upload to Platform (Recommended for Sensitive Content)​

Upload videos directly to HyperStudy's secure storage:

  1. Navigate to the Videos section
  2. Click the "Add Video" button and select "Upload File"
  3. Choose your video file (MP4, MOV, or WebM)
  4. Add metadata during upload (title, description, tags)
  5. Select target folder and set permissions
  6. Monitor upload progress

Security Benefits:

  • Private by Default: Videos are not publicly accessible
  • Signed URLs: Access controlled through time-limited, authenticated URLs
  • Permission Controls: Share only with authorized users or groups
  • Automatic Expiration: URLs expire after 3 hours, preventing unauthorized access
  • No Public Exposure: Videos cannot be accessed outside the platform

When to Use:

  • Proprietary or sensitive research materials
  • Videos requiring access control
  • Content that shouldn't be shared publicly
  • Materials with copyright or licensing restrictions

Use publicly accessible videos hosted elsewhere:

  1. Navigate to the Videos section
  2. Click "Add Video" and select "From URL"
  3. Enter the public video URL
  4. Supported sources:
    • YouTube/Vimeo: Direct video URLs
    • University Servers: Publicly accessible institutional hosting
    • Cloud Storage: Public S3, CloudFront, or Google Cloud URLs
    • CDNs: Any publicly accessible video URL
  5. Add metadata and save

When to Use:

  • Videos already hosted on public platforms
  • Content you want to remain publicly accessible
  • Sharing videos across multiple platforms
  • Large video libraries already hosted elsewhere

Important: External videos must be publicly accessible. The platform cannot add authentication to external URLs.

Processing​

All uploaded videos are automatically processed:

  • Thumbnails generated automatically
  • Duration and resolution detected
  • Format conversion if needed for compatibility
  • Optimization for web playback

Bulk Upload​

For multiple files:

  1. Select multiple files during the upload process
  2. Apply batch metadata to all files
  3. Set common permissions and folder location
  4. Individual files can be edited after the upload completes

File Size Considerations​

When uploading media, consider:

  • Network Bandwidth: Larger files take longer to upload
  • Storage Limits: Your account may have storage quotas
  • Participant Experience: Larger files may cause loading delays
  • Quality Needs: Balance file size with required quality

Media Organization​

Creating Folders​

To organize media into folders:

  1. In the Media Library, click "New Folder"
  2. Enter a name for the folder
  3. Select a parent folder (optional)
  4. Set permission level for the folder
  5. Click "Create"

Folders can be nested to create a hierarchical structure.

Using Tags​

Tags offer flexible categorization:

  1. Select one or more media items
  2. Click "Edit" or use the tag field in the info panel
  3. Enter new tags or select from existing ones
  4. Tags are searchable and can be used as filters

Example useful tags: "stimuli", "instructions", "faces", "landscape", "high-arousal".

Searching and Filtering​

To find specific media:

  1. Use the search bar to find by filename, description, or tags
  2. Apply filters to narrow results:
    • Type: Image or video
    • Date: Recently added, modified date range
    • Size: Small, medium, large
    • Creator: Who uploaded the media
    • Tags: Filter by specific tags

Batch Operations​

For managing multiple items:

  1. Select multiple items by clicking with Shift or Ctrl/Cmd
  2. Available batch operations:
    • Move to folder
    • Add/remove tags
    • Change permissions
    • Delete multiple items

Media Permissions​

The platform uses a comprehensive permission system to control media access.

Permission Levels​

Media items can have three visibility levels:

  1. Private: Only visible to you
  2. Group: Visible to members of specified groups
  3. Public: Visible to all experimenters on the platform

Setting Permissions​

To set permissions for media:

  1. Select the media item(s)
  2. Click "Permissions" or find the permissions section in the info panel
  3. Choose the visibility level
  4. For Group visibility, select which groups can access
  5. Click "Save" to apply the permissions

Folder Permissions​

Folders have their own permission settings:

  1. Folder permissions can be set during creation or edited later
  2. All items in a folder inherit its permissions by default
  3. Individual items can override folder permissions
  4. Moving items between folders updates their permissions

Experimenter Groups​

Permission groups allow controlled sharing:

  1. Administrators create experimenter groups
  2. Groups typically represent labs, departments, or research teams
  3. When you share with a group, all members get access
  4. You can be a member of multiple groups

To see your groups:

  1. Go to your profile settings
  2. Check the "Groups" section
  3. Group membership is managed by administrators

Using Media in Experiments​

In Image Components​

To use images in your experiment:

  1. Add an Image component to a state
  2. In the component properties, click "Select Image"
  3. Browse the media library for your image
  4. Only images you have permission to access will appear
  5. Select the image and configure display settings

In Video Components​

To use videos in your experiment:

  1. Add a Video component to a state
  2. In the component properties, click "Select Video"
  3. Browse the media library for your video
  4. Only videos you have permission to access will appear
  5. Select the video and configure playback settings

Using External Media​

Besides the media library, you can also use:

  1. External URLs: Link directly to online media
  2. Embedded Content: Use embeddable media from platforms like YouTube
  3. Dynamic URLs: Generate URLs programmatically using variables

Note that external media may have less reliable loading and synchronization.

Media Optimization​

Image Optimization​

For optimal performance:

  1. Resize before uploading: Match image dimensions to display size
  2. Compress appropriately: Use JPG for photos, PNG for graphics with transparency
  3. Check file size: Keep under 1MB when possible for faster loading
  4. Use vector formats: SVG is ideal for diagrams and illustrations

Video Optimization​

For optimal video performance:

  1. Use appropriate resolution: 720p or 1080p is sufficient for most experiments
  2. Compress efficiently: Use H.264 encoding with balanced quality settings
  3. Consider segmentation: Break long videos into shorter segments
  4. Progressive loading: Enable for longer videos

Media Precaching for Performance​

HyperStudy automatically precaches media to ensure smooth playback and precise timing:

How Precaching Works​

  1. Automatic Detection: The platform identifies all media used in your experiment
  2. Pre-experiment Loading: Media is loaded before the experiment starts
  3. Browser Caching: Optimized cache headers ensure fast subsequent access
  4. Synchronized Loading: All participants preload media before entering states

Benefits​

  • Eliminates Loading Delays: No waiting for videos to buffer during critical moments
  • Improved Synchronization: Preloaded videos start playing immediately across all participants
  • Consistent Timing: Removes variability caused by network-dependent loading
  • Better Performance: Reduces bandwidth usage during active experiment phases

What Gets Precached​

  • Videos: All videos used in Video components
  • Images: All images used in Image components
  • Platform-Hosted Media: Uploaded media benefits most from precaching
  • External Media: External videos are also precached when possible

Best Practices​

  1. Upload to Platform: Platform-hosted media has optimal precaching support
  2. Keep Media Reasonable: Very large files (>500MB) may take time to precache
  3. Test Precaching: Check the console logs during testing to verify precaching completion
  4. Stable URLs: External videos should have stable, consistent URLs

Monitoring Precaching​

During experiment initialization, you can monitor precaching progress:

  • Check browser console for "Media preload complete" messages
  • Loading screens display precaching status
  • The experiment won't start until essential media is preloaded

Note: Precaching is automatic and requires no configuration. The system intelligently determines which media to precache based on your experiment design.

Collaboration Through Media Sharing​

Sharing with Colleagues​

To collaborate using shared media:

  1. Organize related media in dedicated folders
  2. Set appropriate group permissions
  3. Tag media with project-specific tags
  4. Notify colleagues when new media is available

Best Practices for Shared Media​

When working with shared media:

  1. Consistent Naming: Use clear, descriptive filenames
  2. Complete Metadata: Add thorough descriptions and tags
  3. Version Control: Include version information in filenames
  4. Attribution: Note the source or creator in the description
  5. Usage Notes: Add information about intended purpose

Media Analytics​

The platform provides insights into media usage:

  1. Usage Tracking: See which experiments use each media item
  2. View Counts: Track how often media is accessed
  3. Performance Metrics: Monitor loading times and playback issues
  4. Storage Utilization: Track how much of your quota is used

Access analytics in the Media Library by selecting an item and viewing its info panel.

Advanced Features​

URL-Based Media​

HyperStudy supports various URL formats for maximum flexibility:

  1. YouTube Integration:

    • Direct YouTube video URLs
    • Automatic thumbnail extraction
    • Synchronized playback controls

  2. Cloud Storage:

    • Amazon S3 URLs (public or signed)
    • CloudFront CDN URLs
    • Google Cloud Storage URLs

  3. Streaming Protocols:

    • HLS (.m3u8) for adaptive bitrate streaming
    • DASH for dynamic streaming
    • Progressive download for simple MP4s

Media Synchronization​

For experiments requiring precise timing:

  1. Frame-Accurate Sync: Videos synchronized across all participants
  2. Preloading: Media cached before experiment start
  3. Bandwidth Adaptation: Quality adjusts based on connection
  4. Fallback Options: Alternative URLs if primary fails

Monitoring Usage​

To check your current storage usage:

  1. Go to your Profile Settings
  2. Select the "Storage" tab
  3. View current usage, quota, and item breakdown
  4. Get notifications when approaching quota limits

Managing Storage​

If approaching storage limits:

  1. Archive Unused Items: Move to long-term storage
  2. Optimize File Sizes: Reduce unnecessarily large files
  3. Remove Duplicates: Delete redundant media
  4. Request Quota Increase: Contact administrators if needed

Troubleshooting​

Common Upload Issues​

IssuePotential Solutions
Upload failsCheck file size and format; ensure stable internet connection
Processing stuckFor videos, check format compatibility; try re-uploading
Permissions errorVerify you have upload rights; check quota availability
File too largeCompress or resize the file; split large videos

Playback Problems​

IssuePotential Solutions
Video won't playCheck format compatibility; verify processing completed
Poor playback qualityCheck internet connection; lower video resolution
Image display issuesVerify format support; check image dimensions
Synchronization problemsUse platform-hosted media instead of external links

Next Steps​

Now that you understand media management, explore these related topics: