YouTube-2-Post
Imports YouTube channel videos, Shorts and live streams as WordPress posts, with a title, description, thumbnail, category and player.

Videos, Shorts, live streams, scheduled streams and recorded streams each use their own status, category and rule. Stream status takes precedence over duration, so a short live stream does not become a Short.
The post displays a thumbnail and a play button. The YouTube iframe is only created on click or when consent has already been granted through the WP Consent API or an event from the consent manager.
Fetching runs through a queue in short batches, with a lock against duplicate runs, a daily quota limit and scheduling from 15 minutes. When the quota or server time runs out, processing resumes in the next cycle.
The plugin writes only inside marked regions in the post. Content added by the editor outside those regions stays in place after each resync.
Deleted, private or rejected videos become drafts (or private posts, trashed posts or flagged posts). The post is published again if the video returns, while respecting manual decisions made by the editor.
The widgets display videos in a grid or list, with filters for type, channel, category and tag, or display a single video. Clicking opens the post, opens YouTube or plays the video inside the widget.
YouTube videos as posts
I built YouTube-2-Post for people who publish videos on YouTube and want the same collection in WordPress without copying each title, description and thumbnail manually. With a YouTube Data API key and channels (ID, @handle or URL), each video becomes a post with a title, description, excerpt, thumbnail as the featured image, category, tags and player.
The post uses the video's YouTube publication date and stores the video ID in a dedicated field. The plugin uses this field to track videos already imported.
YouTube channel
↓
Work queue (50 videos per page)
↓
Only videos not on the site yet
↓
Post with player, description, thumbnail and tagsRules for each video format
The plugin classifies each video before importing it. For each format you turn importing on or off and choose the post status (published, draft, pending or private) and the category.
| Format | How it is detected | Default |
|---|---|---|
| Video | Regular upload | Imported as published |
| Short | Duration, a request to youtube.com/shorts or a hashtag, depending on the mode described below | Imported as draft |
| Live | Stream in progress | Off |
| Scheduled | Live stream or premiere with a scheduled date | Off |
| Recorded stream | Ended stream, which can also be treated as a regular video | Imported as published |
Stream status takes precedence over duration: a two-minute live stream is still a live stream. Active live streams and premieres are checked again every 15 minutes. When they end, the same post follows the recorded stream rule.
How the plugin recognizes a Short
The YouTube Data API does not flag Shorts. The plugin has three detection modes, chosen in the settings, and a duration limit between 15 and 600 seconds (180 by default).
The video must fit the duration limit and be checked through a request to youtube.com/shorts/{id}, without following redirects: a 200 response identifies the video as a Short; a redirect does not. The result is cached for 30 days.
Looks only at the video length, within the configured limit.
Looks only for #short or #shorts in the title or description, ignoring duration.
Outside hashtag mode, a video above the limit is never a Short. In strict mode, if the request to YouTube is inconclusive, the plugin decides by hashtag or by a duration of up to 60 seconds.
Queued sync
Fetching reads each channel's uploads playlist in pages of 50 videos. A single query compares the page's IDs with videos already stored on the site. Metadata for new videos is fetched in batches of 50. Processing runs in short batches, with a time limit per run (20 seconds by default), and stops before reaching the PHP memory limit.
- Incremental (default): stops at the first page with no new videos and uses 1 quota unit per channel when there are no new videos.
- Full scan: scans the entire history and rechecks the videos that were skipped before.
- Scheduled: every 15 minutes, 30 minutes, hour, twice a day or once a day, through WP-Cron.
- Manual: from the admin screen or through WP-CLI, which has no request time limit and suits the first import of large channels.
If a run is interrupted, progress is preserved. Deduplication uses the video ID stored in each post, so the next cycle resumes where processing stopped. A quota or key error pauses the queue, and the plugin retries in 15 minutes. An individual failure is retried up to 3 times before the job is discarded and logged.
API quota
Google provides 10,000 units per day per key. The admin displays daily usage, and sync pauses automatically at the configured limit.
- The daily counter uses the date in the
America/Los_Angelestime zone, which Google uses for the daily quota reset. - Before each call, the plugin checks the local ceiling (10,000 by default) and, if it was reached, stops before making the call.
- Calls that fail with a network error, a 5xx response or a 429 response are retried up to 3 times, with increasing waits, and each call has a 15-second limit.
- API errors (quota exceeded, invalid key, API disabled, blocked IP or referer) appear in the admin in Portuguese.
Channels
Each channel can be entered as an ID (UC…), an @handle or a URL in the /channel/, /@, /c/ and /user/ formats. The plugin resolves the channel, keeps the result for 24 hours and accepts up to 25 channels at once in the admin.
Queue and lock
- The queue has four job types: discover videos, import, refresh live streams and validate availability.
- An atomic lock prevents two runs at the same time. It lasts 300 seconds, and an abandoned lock is released automatically.
- The configurable time per cycle ranges from 5 to 120 seconds and never exceeds 60% of the server's
max_execution_time. In the admin the maximum is 15 seconds and, on the command line, the minimum is 120. - Execution stops when memory reaches 85% of the PHP limit.
- Videos that were removed or rejected by a rule go into an ignored list (up to 1,000) so they are not evaluated again every cycle. The list is cleared when the type, Short or live rules change.
What each post receives
Private videos and videos with a failed, rejected or deleted upload are not imported. The rest become posts of the type you choose, with these fields:
| Field | How it is filled |
|---|---|
| Title | As on YouTube, in UPPERCASE or with Each Word Capitalized, depending on the setting |
| Date | The video's publication date on YouTube |
| Excerpt | The first 40 words of the description |
| Author | The author set in the settings; without one, the first administrator |
| Status and category | The ones from the video format's rule |
| Tags | Channel name, fixed tags, up to 15 of the video's own tags and shorts or live when applicable |
| Featured image | The video thumbnail, downloaded to the media library (next section) |
Thumbnail downloaded with checks
The featured image is a copy of the thumbnail in the site's media library, and it is what the player shows before the click. The plugin retrieves and saves the image in five steps:
- 1Pick the resolution
Tries
maxres, thensd, thenhq. - 2Check the address
Accepts only HTTPS on the
ytimg.com,ggpht.comandgoogleusercontent.comdomains. Theheroyt_thumbnail_hostsfilter extends the list. - 3Download with limits
Does not follow redirects and limits the file to 5 MB.
- 4Check the file
The actual file format must be JPEG, PNG or WebP, up to 8192 px per side and 20 megapixels.
- 5Save to the media library
The image's alternative text is the video title.
Without the local image, the player shows a plain placeholder. The remote thumbnail is only used if the site allows it through the heroyt_allow_remote_thumbnail filter.
Resync that preserves editor content
Generated content stays inside regions marked by HTML comments. Resync replaces only the content inside them. Anything the editor wrote before, after or between the regions remains. Reapplying the import produces exactly the same content.
Editor text, before <!-- heroyt:player:ID --> … <!-- /heroyt:player --> <!-- heroyt:description --> … <!-- /heroyt:description --> Editor text, after
Posts from version 1.x with a plain iframe are converted to the consent-based player once, replacing the old embed. No videos are reimported. In the posts list, the Ressincronizar do YouTube (Resync from YouTube) action updates a specific video.
Consent-based player (LGPD)
A standard YouTube iframe contacts Google's servers when the page opens. The default mode, called a facade, displays the thumbnail stored on the site and a play button. The iframe is created on click or loaded without playback when consent has already been granted.
- Uses the
youtube-nocookie.comdomain by default. - Automatic integration with the WP Consent API, using the configured consent category (marketing by default).
- Any other consent platform can enable the player with an event:
document.dispatchEvent(new Event('heroyt-consent-granted')). - Editable privacy notice with a link to the site's privacy policy.
- Link to watch on YouTube when JavaScript is disabled.
- Optional direct mode with a standard iframe.
- 9:16 aspect ratio for Shorts and 16:9 for other videos.
- The play button has a label for screen readers and, when activated by keyboard, focus moves to the video.
- For content inserted after the page loads, the
heroyt-content-loadedevent orwindow.heroytPlayers.init()activates the new players.
The site publisher is responsible for the privacy policy and the legal basis for processing personal data.
Unavailable videos
A separate check, daily by default, confirms that each imported video is still available. Deleted, private or rejected videos get the action configured for the post, which by default turns it into a draft so the site does not promote a video nobody can watch. Checking the whole collection costs 1 quota unit per 50 videos.
- Convert to draft (default)
- Make private
- Move to trash
- Flag only, without changing the post
The action is idempotent. The original status is stored, and the plugin acts only once in each case. When a video returns, it only republishes posts it unpublished itself. If the editor changes the status manually, that decision is respected. When the author blocks embedding, the plugin only flags the video, since the video still exists and the post remains published.
The posts list includes a YouTube column and filters for type and availability.
The check does not run while there is an active queue or lock.
Elementor widgets
When Elementor is active, two widgets are available in the HeroYT: YouTube category. Importing and publishing work independently of Elementor.
“Vídeos do YouTube (lista/grade)”: list and grid
- Grid with columns per device, or list with the image on the left or right.
- Filter by type (only Shorts, only live streams or any combination), channel, category and tag, or select videos manually.
- Sort by date, title, duration, last update, manual order or random order, with pagination.
- Enable elements individually: image, play button, badge, duration, title, excerpt, date, channel and button.
- Clicking opens the post, opens YouTube or plays the video in place with the consent-based player.
- Style controls for cards, media, badges, text and buttons.
“Vídeo do YouTube (único)”: single video
Displays the current post's video in single-post templates, a selected video or the latest video matching a set of filters. The aspect ratio is automatic, with 9:16 for Shorts. Title, badge, duration, date and link are optional. The player, play button and privacy notice have separate style controls.
The list and the latest video matching the filters hide videos that the availability check marked as deleted or private.
Admin and command line
The YouTube to Post menu contains five screens: Sincronização (Sync), with active channels, imported videos, quota used today, the next sync and buttons to sync, run a full scan, check availability, test the connection and cancel; Configurações (Settings), Licença (License), Registro (Log) and Documentação (Documentation).
The Configurações (Settings) screen covers the YouTube connection, channels, publishing, privacy, rules for each video type, ended streams, Shorts detection and sync.
On the Sync screen, the browser requests one queue step every 0.4 seconds and shows the progress bar, counters and a live log. If another run holds the lock, it waits 3 seconds. The browser stops requesting steps when the queue pauses because of quota or key, and gives up after 5 consecutive steps without progress. When the screen is reopened, it resumes a half-finished run on its own.
In the background, four WP-Cron events handle the rest: sync, at the chosen interval; the live stream refresh, every 15 minutes; the availability check; and resuming work left pending when a run does not finish. If WP-Cron is disabled on the server, the admin shows a warning.
wp heroyt sync # incremental sync wp heroyt sync --full # full scan wp heroyt validate # check availability wp heroyt status # queue, quota and schedules wp heroyt reset # clear queue, lock and log
Extension points
The plugin has 13 hooks (11 filters and 2 actions) and 2 JavaScript events.
| Hook | Type | What it is for |
|---|---|---|
heroyt_video_type | filter | Override the detected video type |
heroyt_post_data | filter | Change the post data before saving |
heroyt_post_content | filter | Rewrite the generated content |
heroyt_post_tags | filter | Change the applied tags |
heroyt_player_html | filter | Change the player HTML |
heroyt_query_args | filter | Adjust the widgets' query |
heroyt_time_budget | filter | Adjust the time per batch |
heroyt_capability | filter | Change the capability required in the admin |
heroyt_thumbnail_hosts | filter | Extend the domains accepted for thumbnails |
heroyt_allow_remote_thumbnail | filter | Allow the remote thumbnail when there is no local image |
heroyt_rest_public_meta | filter | Choose which metadata the REST API exposes |
heroyt_after_import | action | React to the creation of a post |
heroyt_after_update | action | React to the update of a post |
The JavaScript events are heroyt-consent-granted, which enables the player after consent, and heroyt-content-loaded, which signals that there is new content on the page.
Each imported post stores this metadata:
| Meta key | Content |
|---|---|
videoID | The video ID, kept from version 1; identifies the video among already imported posts |
_heroyt_channel_id, _heroyt_type, _heroyt_duration | Source channel, detected type and duration in seconds |
_heroyt_live_state, _heroyt_scheduled_start | Stream state and scheduled start |
_heroyt_published_at, _heroyt_synced_at | YouTube publication and last sync |
_heroyt_availability, _heroyt_unavailable_since, _heroyt_auto_status, _heroyt_checked_at | Availability check data |
Requirements
- WordPress 6.0 or later and PHP 7.4 or later.
- A YouTube Data API v3 key created in Google Cloud.
- Working WP-Cron or a server cron job calling wp-cron.php for automatic sync.
- A server with outbound HTTPS access to Google and YouTube and a writable uploads directory for thumbnails.
- Elementor and WP Consent API are optional.
- The admin screens are mostly in Portuguese, with part of the texts translated into English.
Uninstalling removes the plugin's options and scheduled jobs and keeps imported posts.
How it was built
Class-based PHP plugin with no third-party dependencies. The API client, queue, classifier, player, validator and widgets are all custom code. Elementor and WP Consent API are optional integrations detected at runtime.