Video Embed Field
Provides a field type for displaying videos from 3rd party providers such as YouTube and Vimeo.
video_embed_field
Install
composer require 'drupal/video_embed_field:^3.0'
composer require 'drupal/video_embed_field:8.x-2.6'
Overview
Video Embed Field is a comprehensive Drupal module that provides a simple yet powerful field type for embedding videos from external video hosting services. The module stores video URLs and renders them as embedded video players with full support for thumbnails, responsive layouts, and various display options.
The module features a pluggable provider architecture, making it easy to add support for additional video hosting services. Built-in support includes YouTube (including YouTube Shorts and Live videos), YouTube Playlists, and Vimeo. The provider plugin system allows developers to create custom providers for other video services.
Key features include automatic thumbnail downloading from video providers, multiple display formatters (embedded video, thumbnail, lazy loading, and Colorbox modal), responsive video support for mobile-friendly layouts, and time index support for starting videos at specific timestamps. The module also includes permission-based autoplay control, allowing administrators to disable autoplay for specific user roles.
Additional submodules provide integration with Drupal's Media module for media library support, CKEditor5 integration for embedding videos directly in WYSIWYG editors, and migration tools for upgrading from older Drupal versions or transitioning to core oEmbed.
Features
- Provides a dedicated field type for storing video URLs from YouTube and Vimeo
- Pluggable video provider system allowing custom providers to be added via annotations
- Automatic thumbnail download and caching from video providers with image style support
- Multiple display formatters: embedded video player, thumbnail only, lazy load, Colorbox modal, and plain URL
- Responsive video display that scales to container width while maintaining 16:9 aspect ratio
- YouTube support includes regular videos, YouTube Shorts, Live streams, and Playlists with index and start video parameters
- Time index support for starting videos at specific timestamps (e.g., ?t=1m30s)
- Language preference support for YouTube closed captions
- Permission-based autoplay control allowing specific roles to never see autoplaying videos
- Field validation ensuring only URLs from allowed providers are accepted
- Title attribute support with customizable format including video title and provider name from oEmbed data
- Media module integration providing a video_embed_field media source
- CKEditor5 integration for embedding videos directly in WYSIWYG editors with configurable defaults
- Migration support for upgrading from Drupal 6 emfield and Drupal 7 video_embed_field
- Migration path to core oEmbed media via drush command
Use Cases
Adding video content to articles
Add a Video Embed field to your Article content type to allow editors to include embedded YouTube or Vimeo videos. Configure the Video formatter with responsive enabled for mobile-friendly display. Set autoplay to false for better user experience.
Video gallery with thumbnails
Create a content type with a multi-value Video Embed field for video galleries. Use the Thumbnail formatter to display a grid of video thumbnails linked to provider URLs, or use Colorbox formatter to open videos in a modal overlay without leaving the page.
Performance-optimized video pages
Use the Video (lazy load) formatter on pages with multiple videos or videos below the fold. This shows thumbnails initially and only loads the video iframe when users click to play, significantly improving page load performance and reducing bandwidth usage.
Media library integration
Enable video_embed_media submodule to add videos to your Media Library. Create reusable video media entities that can be referenced from multiple content items. Use media browsers and entity embed to include videos in rich text content.
WYSIWYG video embedding
Enable video_embed_wysiwyg submodule to allow content editors to embed videos directly in CKEditor5 text fields. Configure default settings in the text format configuration. Videos are rendered with a thumbnail preview in the editor.
Accessibility-focused video display
Grant the 'never autoplay videos' permission to authenticated users or specific roles to prevent autoplay regardless of formatter settings. Use the title_format setting to provide descriptive iframe titles for screen readers.
Migration from Drupal 7
Use the built-in migration plugins to migrate video_embed_field content from Drupal 7. Field types, formatters, and widgets are automatically mapped. Migration also supports Drupal 6 emfield module content.
Transition to core oEmbed
Use the vem_migrate_oembed submodule with drush vem:migrate_oembed command to transition from video_embed_media to Drupal core's oEmbed implementation when you need features like provider-agnostic embedding or broader format support.
Tips
- Use responsive mode for mobile-friendly video display that maintains 16:9 aspect ratio across all screen sizes
- Grant 'never autoplay videos' permission to anonymous users for a more user-friendly public experience
- YouTube URLs with time parameters (t=1m30s) are supported and will start the video at that timestamp
- For YouTube playlists, include &v= parameter to specify which video should play first
- Use lazy load formatter for pages with multiple videos to improve performance
- Create custom video providers by extending ProviderPluginBase and using @VideoEmbedProvider annotation
- Use hook_preprocess_video_embed_iframe__youtube to customize YouTube-specific parameters like modestbranding
- Video titles are cached from oEmbed API; clear cache to refresh titles after video title changes on provider
Technical Details
Admin Pages 1
/video-embed-wysiwyg/dialog/{filter_format}
AJAX dialog for embedding videos in CKEditor5. Allows entering video URL and configuring display settings before inserting into editor.
Permissions 1
Hooks 3
hook_preprocess_video_embed_iframe
Preprocess video iframes to modify URL, query parameters, attributes, or add classes based on provider.
hook_preprocess_video_embed_iframe__PROVIDER
Provider-specific iframe preprocessing. Allows modifying query parameters for specific providers like enabling YouTube modestbranding.
hook_video_embed_field_provider_info_alter
Alter video_embed_field provider plugin definitions. Useful for removing or replacing providers with custom implementations.
Drush Commands 1
drush vem:migrate_oembed
Migrates video_embed_media content to core oEmbed media. Converts media types from video_embed_field source to oembed:video, updates field storage from video_embed_field to string, and updates view/form displays to use oEmbed formatters/widgets.
Troubleshooting 6
Ensure the URL is from a supported provider (YouTube or Vimeo) and is in a recognized format. Check if field settings restrict allowed providers. YouTube supports watch, embed, youtu.be, shorts, and live URL formats. Vimeo supports vimeo.com and player.vimeo.com URLs.
Thumbnails are downloaded to the files directory (default: public://video_thumbnails/). Check file permissions on this directory. Provider thumbnail URLs may change; clear cache and revisit the content to re-download thumbnails.
Check if the viewing user has the 'never autoplay videos' permission. Browser policies may also block autoplay; most browsers require videos to be muted for autoplay to work. The module automatically mutes videos when autoplay is enabled.
The Video Embed WYSIWYG filter must run BEFORE 'Convert URLs into links' and AFTER 'Limit allowed HTML tags'. Check filter weights in text format configuration. The module validates filter order and displays errors if misconfigured.
The Colorbox formatter only appears when the Colorbox module is installed and enabled. Install via composer require drupal/colorbox and enable the module.
The entered URL doesn't match any provider patterns. Check for typos in the URL. Custom providers can be added via the plugin system. See module documentation for supported URL formats.
Security Notes 5
- Videos are embedded via iframes pointing to provider domains (youtube.com, vimeo.com), not uploaded content
- The iframe title attribute is sanitized using FormattableMarkup to prevent XSS attacks
- Video URLs are validated against provider patterns before being accepted
- The WYSIWYG filter parses JSON tokens and validates structure before rendering to prevent injection attacks
- Thumbnail files are downloaded to local file system and served through Drupal's image style system