--- title: netzSINN VideoThumbnailGrabber Plugin url: "https://www.netzsinn.de/netzsinn-video-thumbnail-grabber" date: 2024-06-06 categories: - name: Joomla Extensions url: "https://www.netzsinn.de/joomla-extensions.md" --- # netzSINN VideoThumbnailGrabber Plugin - Name Content - netzSINN VideoThumbnailGrabber - Current Version 1.2.1 - Compatibility Joomla 5, Joomla 6 - Date 2026-05-14 [More Joomla Extensions](https://www.netzsinn.de/joomla-extensions.md) ![](https://www.netzsinn.de/images/extensions/netzsinn-video-tumbnail-grabber-01.png) ## About The netzSINN VideoThumbnailGrabber Plugin **automatically downloads the official thumbnail images from YouTube and Vimeo videos** from an url in a Joomla Custom Field and saves the link to the thumbnail into another Custom Fields of articles of a specified category – completely without manual effort. - Automatic thumbnail extraction from YouTube and Vimeo - **Smart URL detection** – only works when the video URL changes (performance-optimized!) - **Multiple quality levels** – from Mini (120px) to Maximum (1280px) - Category-based rules – **different settings for different categories** - **Local storage** – thumbnails can be stored locally on your server (recommended) - **Fallback thumbnails** – optional default image if no video thumbnail is found - **Smart performance** – Youtube and Vimeo API is only queried when URL changes, not on every save - **Automatic Storage Cleanup** – Locally stored thumbnails are automatically deleted when video URLs change or are removed, keeping your server clean and preventing orphaned files. - Debug mode – detailed logs for troubleshooting ## Installation Install the Plugin in the Joomla Backend and configure it under **System -> Plugins -> Content -> netzSINN VideoThumbnailGrabber**. Before configuring the plugin, you need at least two custom fields: **Custom Field 1: Video URL** (Text or URL field) - Content → Fields → New - Title: e.g., "Video URL" - Type: Text or URL - Group: Your choice - Assign to category **Custom Field 2: Thumbnail** (Text or URL field) - Content → Fields → New - Title: e.g., "Video Thumbnail" - Type: Text or URL - Group: Your choice (preferably same as Video URL) - Assign to category ### Basic Configuration (Step by Step) The plugin works with **rules**. Each rule defines how the plugin works for specific categories. Click the **green plus icon** to add a new rule. #### 1. Configure Rule **Categories** (Required): Select one or more categories where the plugin should be active. Only articles from these categories will be processed. **Custom Field: Video URL** (Required): Select the custom field that contains the YouTube or Vimeo URL. **Custom Field: Thumbnail** (Required): Select the custom field where the thumbnail URL should be saved. **Thumbnail Quality** - **Low**: YouTube 320x180px | Vimeo ~320x180px - **Medium**: YouTube 480x360px | Vimeo ~640x360px - **High**: YouTube 640x480px | Vimeo ~1350x760px (recommended) - **Maximum**: YouTube 1280x720px | Vimeo ~2280x1280px #### Configure Local Storage (Optional) - **No**: Only external URL is saved (recommended, legally safe) - **Yes**: Thumbnail is downloaded to your server - ⚠️ **Warning**: If "Yes", please note the legal notice above If you enabled "Save Thumbnail Locally": Storage Path: - Default: `images/video-thumbnails/` - Relative path from Joomla root directory - Placeholders available: - `{year}` → 2026 - `{month}` → 03 - `{category_id}` → Category ID - `{article_id}` → Article ID - Example: `images/video-thumbnails/{year}/{month}/` Filename Schema: - **Video ID**: e.g., `youtube_dQw4w9WgXcQ.jpg` (recommended, unique) - **Article ID**: e.g., `article_123_youtube.jpg` - **Timestamp**: e.g., `1678886400_youtube.jpg` **Fallback Thumbnail URL** - URL to a default image if no video thumbnail is found - Used for API errors, invalid URLs, or missing quality levels - **SVG images are supported!** (recommended for placeholders) - Example: `https://your-domain.com/images/video-placeholder.svg` **Debug Mode (Optional)** - **No**: Normal operation, only errors are logged - **Yes**: Detailed logging of all steps - Log file: `administrator/logs/plg_netzsinn_videothumbnailgrabber.log.php` - Useful for troubleshooting #### 2. Create Additional Rules (Optional) Want different settings for different categories? No problem: - Click the **plus icon** again - Create a second rule with different categories - Example: Blog category → High quality, News category → Medium quality Each rule works independently. An article will be processed by the first matching rule. ## Display Thumbnail in Frontend The Plugin is created for use with Yootheme Pro. Use may use the code below to show the thumbnail in a PHP style. ``` jcfields['video-thumbnail']->rawvalue): ?> Video Thumbnail ``` ## FAQ Does the plugin query the API every time I save an article? No! The plugin is **performance-optimized** and only queries the video platform API when: - The video URL has changed - It's a new article (no previous video URL exists) - The video URL was removed (then the thumbnail field is cleared) If the video URL remains unchanged, the plugin skips the API query entirely and keeps the existing thumbnail. This means you can save your articles as many times as you want without unnecessary API calls! What happens when I change the video URL? When you change the video URL to a different video: 1. The old thumbnail is **overwritten** 2. A new thumbnail is fetched from the API (YouTube or Vimeo) 3. The new thumbnail is saved to the thumbnail field 4. If the API fails: The fallback thumbnail is used (if configured) What happens when I remove the video URL? When you delete or clear the video URL field: 1. The thumbnail field is **automatically cleared** 2. This prevents orphaned images without an associated video 3. No API query is made This keeps your data clean and consistent. What if I save the article multiple times without changing the video URL? Perfect scenario for performance: - **No API query** is made - Thumbnail remains **unchanged** - **Maximum performance** – instant saves! The plugin is smart enough to detect that nothing changed and skips all thumbnail processing. No thumbnail appears in my article. What should I do? Follow these debugging steps: 1. **Enable Debug Mode** in the plugin settings 2. **Save the article again** to trigger the plugin 3. **Check the log file**: `administrator/logs/plg_netzsinn_videothumbnailgrabber.log.php` 4. **Verify the following**: - Is the article in one of the configured categories? - Are the custom fields correctly assigned in the rule? - Is the video URL valid and properly formatted? - Is the platform (YouTube/Vimeo) enabled in the rule? - Does the custom field with the video URL actually contain a URL? The log file will show you exactly where the process stops or fails. The fallback thumbnail is being used instead of the video thumbnail. Why? The fallback thumbnail is only used when the actual video thumbnail cannot be retrieved. Possible causes: - **Video not available or deleted** – The video may have been removed from YouTube/Vimeo - **Quality level not available** – For example, "Maximum" quality (maxresdefault.jpg) doesn't exist for older YouTube videos - **API temporarily unreachable** – Network issues or the video platform's API is down - **Invalid video URL** – The URL format is incorrect or the video ID cannot be extracted **Solution**: Check the log file (`administrator/logs/plg_netzsinn_videothumbnailgrabber.log.php`) for detailed error messages that explain exactly why the fallback was used. Local storage isn't working. The thumbnail isn't saved to my server. What's wrong? Check these common issues: 1. **Write permissions** – Verify that the web server has write permissions for the storage path - Default path: `images/video-thumbnails/` - Check folder permissions (should be writable, typically 755 or 775) 2. **Path exists** – The plugin *should* create the directory automatically, but verify it exists - Navigate to: `[your-joomla-root]/images/video-thumbnails/` 3. **Enable Debug Mode** and check the log file for specific error messages - Log file: `administrator/logs/plg_netzsinn_videothumbnailgrabber.log.php` - Look for "Failed to create directory" or "Failed to write file" messages 4. **Test with external URL first** – Disable "Save Thumbnail Locally" to verify the plugin works with external URLs, then troubleshoot local storage separately Can I use different settings for different categories? Yes! This is what **rules** are for. Each rule can have: - Different categories - Different quality settings - Different local storage settings - Different fallback thumbnails Simply create multiple rules in the plugin configuration. Each article will be processed by the first matching rule based on its category. Does the plugin work with private or unlisted videos? **Yes** for unlisted videos, **No** for private videos: - **Unlisted YouTube/Vimeo videos**: Yes, the plugin can fetch thumbnails - **Private videos**: No, thumbnails are not publicly accessible via API - **Embed-disabled videos**: No, these cannot be accessed via the public API If you're working with private videos, you'll need to use the fallback thumbnail feature. What video URL formats are supported? The plugin supports all common YouTube and Vimeo URL formats: **YouTube:** - `https://www.youtube.com/watch?v=VIDEO_ID` - `https://youtu.be/VIDEO_ID` - `https://www.youtube.com/watch?v=VIDEO_ID&t=30s` (with timestamp) - `https://m.youtube.com/watch?v=VIDEO_ID` (mobile) **Vimeo:** - `https://vimeo.com/VIDEO_ID` - `https://player.vimeo.com/video/VIDEO_ID` The plugin automatically extracts the video ID from any of these formats. ## System Requirements Joomla 5, Joomla 6 ## Changelog - v1.2.1 Added the plugin type to the name in the config XML; Refactor: Cleaned up comments in the language file - v1.2.0 Thumbnail grabbing now triggered when URL unchanged but thumbnail field empty (legacy data fix). Improved debug output in the backend and frontend - v1.1.0 Added lightweight DebugHelper for structured debug output with rule tracking and summaries - v1.0.0 First official release ## License GNU general public license ## Download [netzsinn_videothumbnailgrabber_1.2.1.zip (Joomla 4/5)](https://www.netzsinn.de/extensions/plugins/netzsinn_videothumbnailgrabber/netzsinn_videothumbnailgrabber_1.2.1.zip) [Review on JED](https://extensions.joomla.org/extension/access-a-security/netzsinn-videothumbnailgrabber/) Please, support this extension and [review on Joomla Extension Directory JED](https://extensions.joomla.org/extension/social-web/social-share/netzsinn-addmissingogimage/)! [More Joomla Extensions](https://www.netzsinn.de/joomla-extensions.md)