Technical Guide: Embedding High-Quality Video Previews in Astro guide illustration
⏱️ 2 min read

Technical Guide: Embedding High-Quality Video Previews in Astro

Table of Contents

Adding short video previews to your guide site makes it more engaging, but hosting them on platforms like YouTube can be bulky and slow. For technical documentation, direct embedding from a fast storage layer like Cloudflare R2 is the superior approach.

1) Compression: FFmpeg Settings

Before uploading, you must optimize your clips to minimize bandwidth. Aim for under 5MB per loop.

Use this FFmpeg command to create a web-optimized H.264 MP4:

ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset faster -an -vf "scale=1280:-1" output_preview.mp4
  • -crf 28: High compression ratio (balanced quality).
  • -an: Removes audio track entirely (saves space).
  • -vf "scale=1280:-1": Scales to 720p width while preserving aspect ratio.

2) The HTML5 Video Tag

To ensure your previews load instantly and don’t require user interaction, use these specific attributes:

<video 
  autoplay 
  loop 
  muted 
  playsinline 
  poster="/path/to/poster.jpg"
>
  <source src="https://cdn.yoursite.com/preview.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>
  • muted and playsinline are required for autoplay to work reliably in mobile browsers.

3) Hosting on Cloudflare R2

Hosting video files in your project repository can slow down your builds and git operations. Instead, use Cloudflare R2:

  1. Create a Bucket: In your Cloudflare dashboard, create an R2 bucket.
  2. Upload Files: Use the dashboard or wrangler r2 object put to upload your MP4s.
  3. Public Access: Connect a custom domain (e.g., cdn.teencamgals.com) to the bucket for fast, global delivery.

4) Reusable Astro Component

Create a simple component to handle the boilerplate:

---
// src/components/VideoPreview.astro
interface Props {
  src: string;
  poster?: string;
}
const { src, poster } = Astro.props;
---
<figure class="video-container">
  <video autoplay loop muted playsinline poster={poster}>
    <source src={src} type="video/mp4" />
  </video>
</figure>

<style>
  .video-container { margin: 1.5rem 0; border-radius: 12px; overflow: hidden; border: 1px solid rgba(var(--gray), 30%); }
  video { width: 100%; display: block; }
</style>

Summary

By combining FFmpeg optimization with R2 delivery, you can provide smooth, high-fidelity previews without the overhead of 3rd-party players.

Related guides

Rate this guide

Loading ratings...

Was this guide helpful?

Comments