Five video formats

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.

Player that loads on click

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.

Sync that resumes where it stopped

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.

Updates that preserve editor content

The plugin writes only inside marked regions in the post. Content added by the editor outside those regions stays in place after each resync.

Unpublishes posts whose video was removed

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.

Elementor widgets

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.

flow
YouTube channel
      ↓
Work queue (50 videos per page)
      ↓
Only videos not on the site yet
      ↓
Post with player, description, thumbnail and tags

Rules 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.

FormatHow it is detectedDefault
VideoRegular uploadImported as published
ShortDuration, a request to youtube.com/shorts or a hashtag, depending on the mode described belowImported as draft
LiveStream in progressOff
ScheduledLive stream or premiere with a scheduled dateOff
Recorded streamEnded stream, which can also be treated as a regular videoImported 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).

Strict (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.

Duration

Looks only at the video length, within the configured limit.

Hashtag

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_Angeles time 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:

FieldHow it is filled
TitleAs on YouTube, in UPPERCASE or with Each Word Capitalized, depending on the setting
DateThe video's publication date on YouTube
ExcerptThe first 40 words of the description
AuthorThe author set in the settings; without one, the first administrator
Status and categoryThe ones from the video format's rule
TagsChannel name, fixed tags, up to 15 of the video's own tags and shorts or live when applicable
Featured imageThe 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:

  1. 1
    Pick the resolution

    Tries maxres, then sd, then hq.

  2. 2
    Check the address

    Accepts only HTTPS on the ytimg.com, ggpht.com and googleusercontent.com domains. The heroyt_thumbnail_hosts filter extends the list.

  3. 3
    Download with limits

    Does not follow redirects and limits the file to 5 MB.

  4. 4
    Check the file

    The actual file format must be JPEG, PNG or WebP, up to 8192 px per side and 20 megapixels.

  5. 5
    Save 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.

regions
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.com domain 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-loaded event or window.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-cli
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.

HookTypeWhat it is for
heroyt_video_typefilterOverride the detected video type
heroyt_post_datafilterChange the post data before saving
heroyt_post_contentfilterRewrite the generated content
heroyt_post_tagsfilterChange the applied tags
heroyt_player_htmlfilterChange the player HTML
heroyt_query_argsfilterAdjust the widgets' query
heroyt_time_budgetfilterAdjust the time per batch
heroyt_capabilityfilterChange the capability required in the admin
heroyt_thumbnail_hostsfilterExtend the domains accepted for thumbnails
heroyt_allow_remote_thumbnailfilterAllow the remote thumbnail when there is no local image
heroyt_rest_public_metafilterChoose which metadata the REST API exposes
heroyt_after_importactionReact to the creation of a post
heroyt_after_updateactionReact 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 keyContent
videoIDThe video ID, kept from version 1; identifies the video among already imported posts
_heroyt_channel_id, _heroyt_type, _heroyt_durationSource channel, detected type and duration in seconds
_heroyt_live_state, _heroyt_scheduled_startStream state and scheduled start
_heroyt_published_at, _heroyt_synced_atYouTube publication and last sync
_heroyt_availability, _heroyt_unavailable_since, _heroyt_auto_status, _heroyt_checked_atAvailability 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.

language:: PHP 7.4+
platform:: WordPress 6.0+
api:: YouTube Data API v3
queue:: WordPress options · lock · time limit
scheduling:: WP-Cron · WP-CLI
player:: facade · youtube-nocookie · WP Consent API
admin:: Settings API · AJAX