Embedding video in Contentful can be done either by uploading video files directly or by referencing external platforms like YouTube, Vimeo, or other video hosting services. Each method influences how the content is stored, rendered, and delivered on the frontend. Both workflows involve different technical considerations for asset handling, playback, and integration.

Video Embedding Options in Contentful

Contentful supports two primary approaches for handling video content:

  1. Uploading video files directly as assets.
  2. Embedding external video sources using structured fields.

Both methods support flexible rendering through frontend frameworks but vary in terms of processing, delivery, and playback capabilities.

Method 1: Uploading Video Assets to Contentful

Uploading video files directly into Contentful allows you to manage video content in the same way as images or documents. This method treats videos as static assets, meaning no processing or transformation is applied to optimize playback. It"s suitable for lightweight, internal, or demo videos that don"t require advanced streaming features.

Step 1 : Upload the Video Asset

Use the Contentful Web App or the Content Management API (CMA) to create a new asset entry.

API Example:

code
POST /spaces/{space_id}/assets

Request Body:

code
{"fields": {"title": { "en-US": "Demo Video" },"file": {"en-US": {"contentType": "video/mp4","fileName": "demo.mp4","upload": "https://yourdomain.com/demo.mp4"}}}}

Explanation:

  • upload: A publicly accessible URL from which Contentful will fetch the video.
  • contentType: Should match the MIME type (e.g., video/mp4).
Banner for Video Embedding

Step 2 : Process the Uploaded Asset

Once the asset is created, trigger file processing:

code
PUT /spaces/{space_id}/assets/{asset_id}/files/en-US/process

This prepares the file for use in the Content Delivery API (CDA).

Step 3 : Publish the Asset

Use the CMA to publish the processed asset, making it accessible through queries and media fields.

Key Technical Notes

  • Playback must be implemented on the frontend using <video> or JavaScript players.
  • No adaptive bitrate streaming or video transcoding is supported.
  • Large videos may affect loading time and performance.

Method 2: Embedding Videos from External Platforms

For enhanced playback control, streaming, and analytics, Contentful recommends embedding videos from external platforms such as YouTube, Vimeo, or enterprise video providers.

Options:

  • Short Text Field: Store the embed URL (e.g., https://www.youtube.com/embed/...) in a string field.
  • Rich Text Field with Embedded Entry: Embed a video component as a linked entry using the EmbeddedEntryBlock.

Example: Rich Text Embed Structure

code
{"nodeType": "embedded-entry-block","content": [],"data": {"target": {"sys": {"type": "Link","linkType": "Entry","id": "entry_id"}}}}

Explanation:

  • This structure represents an embedded entry block in a Rich Text field, linking to another Contentful entry by its ID.
  • The nodeType defines it as a block, and the data.target.sys.id holds the reference to the actual entry to be rendered in the frontend.

Frontend Handling:

Render embeds using conditional logic based on the contentType or use custom components for different providers. Contentful does not automatically render embeds"developers must handle this in the frontend.

Comparison table summarizing the two methods

Criteria Direct Upload External Embed
Processing None (static file) Host platform handles
Streaming Progressive download only Adaptive (HLS/DASH)
Best For Small files, internal use Public-facing, high-traffic

Video Asset Delivery via Contentful CDN

When videos are uploaded to Contentful, they are served as static files through Contentful"s global CDN. Each file receives a permanent, public URL that can be embedded in applications or websites.

Example URL format:

code
https://images.ctfassets.net/{space_id}/{asset_id}/{filename}.mp4

This approach ensures global caching and fast delivery, but it comes with specific limitations:

  1. No media optimization: Videos are not transcoded or resized. The original file is served as-is, with no support for adaptive streaming or multiple resolutions.
  2. No fallback support: There"s no automatic format switching (e.g., from MP4 to WebM) for browser compatibility.
  3. Limited security: URLs are public and do not support signing or token-based expiration. Any user with the link can access the file.
  4. Access control must be manual: To restrict access, developers must implement logic at the application layer or proxy requests through a secured backend.

This method is suitable for lightweight or non-sensitive video content where performance and access control are not critical requirements. For more advanced needs, consider using a dedicated video delivery service.

Best Practices

  • Use external video platforms if adaptive streaming, subtitles, analytics, or custom playback control is required.
  • Use Contentful-hosted videos only for small, non-critical media files without high performance or streaming requirements.
  • Store video metadata (duration, dimensions, platform ID) in dedicated fields for structured frontend rendering.