Video Support - Imperial Documentation

Video Hosting Made Easy

Imperial supports video uploads with automatic processing, thumbnail generation, and optimized CDN delivery. Upload videos just like images - no special configuration needed.

Videos can be uploaded via the Dashboard or through the Upload API.

Supported Video Formats

MP4

Most Common

Codec: H.264, H.265
Best browser support
Efficient compression

WebM

Web Optimized

Codec: VP8, VP9, AV1
Open source
Great for web

MOV

Apple Format

Codec: ProRes, H.264
High quality
Large file sizes

AVI

Legacy Format

Various codecs
Wide compatibility
Less efficient

Automatic Thumbnail Generation

Every video uploaded to Imperial automatically generates a thumbnail for faster gallery loading and video previews.

How It Works

Video Upload

You upload a video file through the dashboard or API

Frame Extraction

Imperial uses FFmpeg to extract a frame at the 1-second mark

Optimization

The frame is resized and compressed to JPEG format

CDN Upload

Both video and thumbnail are uploaded to R2 and cached globally

Ready to Use

Thumbnail URL is included in the API response

Example Response

{
  "_id": "67d8f9a1b2c3d4e5f6789013",
  "url": "https://origin.imperial.gay/uploads/user-id/video.mp4",
  "thumbnailUrl": "https://origin.imperial.gay/uploads/user-id/thumbs/thumb.jpg",
  "mimeType": "video/mp4",
  "fileSize": 15728640,
  "createdAt": "2026-01-07T12:35:00.123Z"
}

Thumbnails are cached for 90 days on the CDN for instant loading in galleries.

Technical Implementation

FFmpeg Processing

Imperial uses FFmpeg, the industry-standard video processing tool:

// Simplified version of thumbnail generation
async function generateVideoThumbnail(videoBuffer, timeSeconds = 1) {
  return new Promise((resolve, reject) => {
    const command = ffmpeg()
      .input(videoBuffer)
      .seekInput(timeSeconds)           // Jump to 1 second
      .frames(1)                        // Extract 1 frame
      .size('640x?')                    // Scale to 640px width (maintain aspect)
      .format('image2')                 // Output as image
      .outputOptions([
        '-q:v 2',                       // High quality JPEG
        '-update 1'                     // Single frame output
      ])
      .on('end', () => resolve(buffer))
      .on('error', reject);
    
    command.run();
  });
}

Processing Pipeline

Video Upload (video.mp4)
    ↓
FFmpeg Frame Extraction
    ├─ Seek to 1 second
    ├─ Extract frame
    └─ Output as JPEG
    ↓
Sharp Optimization
    ├─ Resize to 640px width
    ├─ Compress to 80% quality
    └─ Strip metadata
    ↓
R2 Upload
    ├─ Video: /uploads/user-id/video.mp4
    └─ Thumbnail: /uploads/user-id/thumbs/thumb.jpg
    ↓
Cloudflare CDN Cache
    ├─ Video: Long-term cache
    └─ Thumbnail: Extended cache (90 days)

Video Streaming

Range Request Support

Imperial’s CDN supports HTTP range requests, enabling:

Seek/Skip

Users can jump to any point in the video

Resume Playback

Continue watching after interruption

Partial Downloads

Download only the needed portion

Bandwidth Savings

Don’t load entire video upfront

How Range Requests Work

# Client requests first 1MB
curl -H "Range: bytes=0-1048575" \
  https://origin.imperial.gay/uploads/user-id/video.mp4

# Response
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1048575/15728640
Content-Length: 1048576

# Client can then request next chunk
curl -H "Range: bytes=1048576-2097151" \
  https://origin.imperial.gay/uploads/user-id/video.mp4

Playback Optimization

Browser Compatibility

Videos are delivered with optimal settings for all major browsers:

Browser	Preferred Format	Fallback
Chrome	MP4 (H.264), WebM (VP9)	MP4
Firefox	MP4 (H.264), WebM (VP9)	MP4
Safari	MP4 (H.264)	MP4
Edge	MP4 (H.264), WebM (VP9)	MP4

MP4 with H.264 has the best compatibility across all devices and browsers.

Mobile Optimization

Special handling for mobile devices:

Mobile Networks
Battery Saving
Data Saving

Adaptive Loading:

Start with thumbnail display
Load video only when played
Support for lower quality on slow connections

Storage Considerations

File Size Guidelines

Videos can be significantly larger than images:

Quality	Resolution	Duration	Approx Size
Low	480p	1 min	5-10 MB
Medium	720p	1 min	15-25 MB
High	1080p	1 min	40-80 MB
Ultra	4K	1 min	150-300 MB

Video files count toward your storage limit. A single 4K video can use as much space as thousands of images.

Compression Recommendations

Unlike images, Imperial doesn’t compress videos automatically. Compress before uploading:

FFmpeg (Command Line)

# Compress to H.264 at 720p
ffmpeg -i input.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 23 \
  -vf scale=1280:720 \
  -c:a aac -b:a 128k \
  output.mp4

-crf 23: Quality (18-28, lower = better)
-preset slow: Slower encoding, better compression
scale=1280:720: Resize to 720p

HandBrake (GUI)

Desktop application for easy video compression:

Load your video
Select “Web” preset
Choose quality (RF 20-24)
Click “Start”

Download: https://handbrake.fr

CloudConvert (Online)

Web-based video converter:

Upload video
Convert to MP4
Set quality/resolution
Download result

Visit: https://cloudconvert.com

API Integration

Upload Video

curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "file=@video.mp4"

Response with Thumbnail

{
  "_id": "67d8f9a1b2c3d4e5f6789013",
  "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
  "thumbnailUrl": "https://origin.imperial.gay/uploads/user-id/thumbs/67d8f9a1b2c3d4e5f6789013-thumb.jpg",
  "filename": "67d8f9a1b2c3d4e5f6789013-video.mp4",
  "originalFilename": "video.mp4",
  "fileSize": 15728640,
  "mimeType": "video/mp4",
  "compressed": false,
  "createdAt": "2026-01-07T12:35:00.123Z"
}

Embed in HTML

<!-- Simple video player -->
<video controls poster="https://origin.imperial.gay/.../thumb.jpg">
  <source src="https://origin.imperial.gay/.../video.mp4" type="video/mp4">
  Your browser doesn't support video playback.
</video>

<!-- With thumbnail fallback -->
<div class="video-container">
  <img src="https://origin.imperial.gay/.../thumb.jpg" 
       alt="Video thumbnail"
       class="thumbnail">
  <video controls>
    <source src="https://origin.imperial.gay/.../video.mp4" type="video/mp4">
  </video>
</div>

Performance Metrics

Thumbnail Generation Time

Video Size	Resolution	Generation Time
10 MB	1080p	1-2 seconds
50 MB	1080p	2-4 seconds
100 MB	4K	4-6 seconds
500 MB	4K	10-15 seconds

Thumbnail generation happens asynchronously. The video is immediately available even if thumbnail generation is still processing.

CDN Delivery Performance

First load (uncached):

Request → Cloudflare Edge
    ↓ (cache miss)
    Fetch from R2: 200-500ms
    ↓
    Cache at edge
    ↓
    Stream to user: 1-5s (depends on size/bandwidth)

Subsequent loads (cached):

Request → Cloudflare Edge
    ↓ (cache hit)
    Stream from edge cache: 0.1-1s

Limitations

Current Limitations:

No transcoding (upload optimized videos)
No adaptive bitrate streaming
No live streaming support
Maximum file size limited by storage tier

Future Features (Coming Soon)

✨ Multiple quality options (auto-generated 720p/480p)
✨ Adaptive bitrate streaming (HLS/DASH)
✨ Custom thumbnail selection (choose frame)
✨ Video analytics (views, watch time)

Best Practices

Optimize Before Upload

Compress videos with FFmpeg or HandBrake
Use H.264 codec for best compatibility
Target 720p or 1080p for web use
Use reasonable bitrates (2-8 Mbps for 1080p)

Choose Right Format

MP4 (H.264): Best for general use
WebM (VP9): Good for web-only
Avoid uncompressed formats (AVI, MOV)

Consider File Size

Keep videos under 100 MB when possible
Split longer videos into segments
Use thumbnails effectively in galleries

Test Playback

Verify on mobile and desktop
Check loading times
Ensure thumbnails load quickly

Troubleshooting

Thumbnail Not Generating

Possible causes:

Video codec not supported by FFmpeg
Video file corrupted
Video too short (< 1 second)
Processing timeout (very large files)

Solution: Re-upload or try a different format (MP4 with H.264).

Video Won’t Play

Possible causes:

Browser doesn’t support codec
File size too large for device
Network issues

Solution: Use MP4 with H.264 for best compatibility.

Slow Loading

Possible causes:

Video not optimized (high bitrate)
User on slow connection
Cold start (not cached yet)

Solution: Compress video before upload, or wait for CDN cache to warm up.

Get Started

Ready to upload videos?

Upload Your First Video

Try video hosting with automatic thumbnails

​Video Hosting Made Easy

​Supported Video Formats

MP4

WebM

MOV

AVI

​Automatic Thumbnail Generation

​How It Works

​Example Response

​Technical Implementation

​FFmpeg Processing

​Processing Pipeline

​Video Streaming

​Range Request Support

Seek/Skip

Resume Playback

Partial Downloads

Bandwidth Savings

​How Range Requests Work

​Playback Optimization

​Browser Compatibility

​Mobile Optimization

​Storage Considerations

​File Size Guidelines

​Compression Recommendations

​API Integration

​Upload Video

​Response with Thumbnail

​Embed in HTML

​Performance Metrics

​Thumbnail Generation Time

​CDN Delivery Performance

​Limitations

​Future Features (Coming Soon)

​Best Practices

​Troubleshooting

​Thumbnail Not Generating

​Video Won’t Play

​Slow Loading

​Get Started

Upload Your First Video

Video Hosting Made Easy

Supported Video Formats

Automatic Thumbnail Generation

How It Works

Example Response

Technical Implementation

FFmpeg Processing

Processing Pipeline

Video Streaming

Range Request Support

How Range Requests Work

Playback Optimization

Browser Compatibility

Mobile Optimization

Storage Considerations

File Size Guidelines

Compression Recommendations

API Integration

Upload Video

Response with Thumbnail

Embed in HTML

Performance Metrics

Thumbnail Generation Time

CDN Delivery Performance

Limitations

Future Features (Coming Soon)

Best Practices

Troubleshooting

Thumbnail Not Generating

Video Won’t Play

Slow Loading

Get Started