Skip to content

Let Instagram Reels and YouTube Shorts take a custom cover image - #505

Merged
paulocastellano merged 21 commits into
mainfrom
feature/instagram-reel-custom-cover
Nov 17, 2026
Merged

paulocastellano merged 21 commits into
mainfrom
feature/instagram-reel-custom-cover

Conversation

@paulocastellano

@paulocastellano paulocastellano commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What

A Reel or a Short can now take an image as its cover, either one the user uploads or a frame of the video, picked like in the Instagram app. Requested in https://github.com/orgs/trypostit/discussions/504.

Composer: the media editor's Thumbnail tab

  • Every video with a Thumbnail tab (Instagram feed and Reels, TikTok, Pinterest video pins, and now YouTube Shorts) picks its frame on a strip of the video's frames under the stage. The selector shows the exact frame, and the stage seeks to it. The old slider on the right is gone.
  • Instagram Reels and YouTube Shorts also get a Video frame | Image switch:
    • Image: upload a JPEG, PNG or WebP. The stage frames it at 9:16 with the same crop stage, crop panel and render as any image (move, resize, rotate, flip, straighten, center, reset). The cover saves already cropped.
    • Video frame: on a Reel, the frame is saved as its time. On a YouTube Short (YouTube takes no frame time), applying takes a screenshot of the frame and saves it as the cover. If the browser cannot read the video's pixels, the editor says so and Apply stays blocked.
  • The picked cover shows on the composer's media tile, always, and on the preview until the video is first played. With no cover picked, both show the video as before. The same VideoStill draws the cover on every post card (list, board, calendar, details).
  • The item row under the stage is hidden when there is a single item to edit.

Storage

  • media.*.meta.cover holds the image as a whole media item: a medias row owned by the post (or idea), synced by SyncOwnedMedia like thread reply media. A temporary upload is adopted and another post's row is copied. Removing the cover deletes its row, duplicating the post copies it, and deleting the post deletes it. The cover row shares its video's order.
  • media.*.meta.cover_source (App\Enums\Media\CoverSource: frame or image) says where the cover comes from. Picking an image keeps cover_offset_ms, so a network that only takes a frame still has one.
  • A post on a network that takes no cover image (TikTok, Pinterest, an Instagram feed video, a thread reply's video) drops meta.cover and cover_source on save, as PostMeta::forChannel() drops a poll. Its previews never show an image uploaded for another network either (PlatformPreview).
  • A cover that is not a still image (a video, a GIF) is refused. AuditMedia counts covers as referenced.

API and MCP

  • media[].meta.cover takes {upload_token}, {url} or {id} like a media item, and media[].meta.cover_source takes frame or image (image when a cover is sent without it). This works on create and update.
  • list-content-types-tool adds supports_custom_video_cover. The tool descriptions explain both fields.

Publishing

  • Instagram Reel: an uploaded image goes as cover_url, which Instagram prefers over thumb_offset. It is re-encoded first when it is not a JPEG of up to 8 MB (HostsProcessedImages::hostAsJpeg). A frame goes as thumb_offset, which Instagram shows exactly. An image that cannot be made a JPEG falls back to the frame instead of failing the Reel. Docs
  • YouTube Short: thumbnails.set needs a processed video, so SetYouTubeCover (queued a minute after publishing) checks processingDetails (App\Enums\YouTube\ProcessingStatus) every minute for up to 30 minutes, then uploads the cover. JPEG and PNG go as they are; anything else is re-encoded. It uses the youtube.upload scope we already have and costs 50 quota units. Docs
  • A cover YouTube refuses never fails the post, since the video is already live. The reason (App\Enums\YouTube\ThumbnailWarning: channel not verified, daily limit, invalid image, failed) is kept in posts.error_context.youtube_thumbnail_warning, and the post card shows it with a pointer to YouTube Studio. No new column.
    • A 5xx is tried again.
    • A video removed meanwhile (404, or no longer listed) leaves no warning.
    • A revoked token, a channel no longer connected, or a video YouTube could not process leaves the failed warning at once.
  • FitsImageToCanvas is renamed HostsProcessedImages: it also converts images to JPEG now, through one jpegFrom() that checks the result is a JPEG within the network's size.

Copy

All 17 locales: the Thumbnail hint (the frame strip), the Video frame / Image switch, the upload and replace buttons, the 9:16 hint, the capture error, the two validation errors and the four YouTube warnings.

Storage CORS

The YouTube frame screenshot reads the video with CORS. cdn.trypost.it already answers GET with Access-Control-Allow-Origin: *, so it works on Cloud (checked in the manual run below). A self-hosted bucket needs the same rule, or picking a frame for a YouTube Short fails on Apply; Reels (frame time) and uploaded images work either way.

Automated tests (all passing)

  • tests/Feature/Media/VideoCoverImageTest.php: web, REST API and MCP; adopt, keep, remove and copy; video and GIF refused; duplicate and delete; media audit; frame-only network drops the cover and its source; cover_source validation; thread reply covers dropped; idea keeps its cover; Reel to Feed drops it; cover order
  • tests/Feature/Jobs/SetYouTubeCoverTest.php: processed, still processing, 403 / 429 / 400 warnings, 404 quiet, 5xx retried, out of tries, failed and terminated processing, video gone, revoked token, channel not connected, WebP converted, unreadable image, card shape
  • tests/Feature/Jobs/PublishToSocialPlatformTest.php: the job is queued only for a YouTube video with a cover
  • tests/Feature/Services/Social/InstagramPublisherTest.php: cover_url for an uploaded image, thumb_offset for a frame, re-encoding a PNG and a JPEG over 8 MB, fallback to the frame, a feed video keeps thumb_offset
  • tests/Feature/Resources/PostCardResourceTest.php: the warning, and the failure kept for a context without a category
  • tests/Browser/MediaEditorTest.php: frame strip, upload and 9:16 crop, reframing a stored cover, switching between frame and image, a frame screenshot for YouTube only, a frame picked before YouTube was added, the tile and preview cover, TikTok preview, single-item row
  • LocalizationParityTest, SingleLineCopyTest (17 locales)
  • Full Feature and Unit suites (PostgreSQL); the affected areas on MySQL

Manual test plan

Media editor: Thumbnail tab

  • TikTok video: the Thumbnail tab shows the frame strip under the video, with no Video frame / Image switch; dragging moves the selector, which shows the frame, and the stage seeks to it
  • Instagram feed video and Pinterest video pin: same as TikTok (frame strip, no switch)
  • Instagram Reel: the Video frame / Image switch shows, and Video frame is picked by default
  • YouTube Short: the Thumbnail tab shows (new) with the switch
  • The strip draws its frames quickly on a long (several minutes) and on a 4K video, and the tab stays smooth (a 4K file at a high bitrate fills in over ~30s on a slow connection, bound by download speed; frames not painted yet pulse)
  • A single video: no item row under the stage; several items: the row shows and switches between them
  • Keyboard: Tab reaches the strip and the arrow keys move the frame
  • Instagram carousel with two videos and an image: each video picks its own frame on the strip, the item row switches between them
  • Phone width (390px): the stage, the strip and the panel fit with no sideways scroll
  • Dark mode: the strip, its selector and the switch read clearly
  • Cancel and the X discard every cover change (frame, image, framing)

Image cover

  • Reel → Image → Upload image: the picked image shows on the stage with a 9:16 frame that moves and resizes
  • The crop panel shows rotate, flip, straighten, Center and Reset, with no ratio picker; Reset brings the 9:16 frame back
  • A landscape image: the 9:16 frame starts in the middle and the saved cover matches the frame chosen
  • Replace image swaps it, and Apply then Save keep it
  • Reopen the editor on the saved post: Image is picked, the cover shows framed at 9:16, and Apply stays disabled until something changes
  • Reframe a saved cover, Apply, Save: the new framing is kept
  • The file picker offers JPEG, PNG and WebP, not GIF

Frame cover

  • Reel: pick a frame, Apply, Save; reopen: the selector is on that frame
  • Reel with an image cover → Video frame: the image is dropped and the frame is the cover again
  • Reel with a frame cover → Image: the stage waits for an upload instead of reusing the frame
  • YouTube Short: pick a frame, Apply, Save: a screenshot is saved as the cover
  • A self-hosted bucket without CORS: Apply on a YouTube Short frame shows "Couldn't capture this frame. Upload an image as the cover instead."
  • A YouTube Short whose frame was picked before it had YouTube: opening the editor enables Apply, and applying saves the screenshot

Shared video (one video on several channels)

  • Reel + TikTok sharing a video: upload an image for the Reel; the TikTok preview shows the picked frame, not the image
  • Save, then open the TikTok post: no image cover, the frame strip shows the picked frame, and TikTok publishes that frame
  • Change a Reel draft to Feed and save: the image cover is dropped (expected)

Composer flows

  • Changing the cover (frame or image) marks the post as unsaved: closing the composer asks to discard
  • Duplicate a Reel with an uploaded cover: the copy has the same cover, and editing one does not change the other
  • Schedule a Reel with an uploaded cover (not Publish now): it publishes with that cover at its time
  • A member who needs approval saves a Reel with a cover: the cover stays while pending, and after approval the Reel publishes with it
  • Instagram grid page (channel → Grid): a scheduled Reel with an uploaded cover shows that image; one with a picked frame shows the frame

Regressions in the shared media editor

  • Image editing still works: crop ratios, rotate, flip, straighten, filters and adjustments, Apply saves the edited pixels
  • Alt text and Tag People on an Instagram image: tags place and move with the crosshair cursor
  • Profile photo upload: the square crop opens, resizes and saves (512×512)
  • Workspace logo upload: the square crop opens, resizes and saves
  • An idea with a video: the media editor opens and saves as before

Composer and cards

  • Media tile in the composer: shows the cover (the image, or the video at the picked frame)
  • Preview: shows the cover until Play; after Play the video runs from the start
  • A video with no cover picked: tile and preview show the video as before
  • List, Board, Calendar and post details: a Reel with an uploaded cover shows the image; a TikTok post shows the frame
  • Posts on other networks with video (X, LinkedIn, Facebook, Bluesky): their cards look unchanged

Publishing (real accounts)

  • Instagram Reel with an uploaded image: the Reel's cover and the profile grid show it
  • Instagram Reel with a picked frame: the cover is that frame
  • Instagram Reel with a PNG or WebP cover: publishes with the image (re-encoded as a JPEG)
  • YouTube Short on a verified channel with an uploaded image: the thumbnail changes once the video is processed (a few minutes)
  • YouTube Short with a picked frame: the thumbnail is that frame
  • YouTube Short on a channel that is not verified: the post stays Published and its card shows "YouTube didn't apply your cover image: custom thumbnails need a verified channel…"
  • TikTok with a picked frame: the cover is that frame (unchanged behaviour)
  • Instagram Story and Facebook Story with an image that is not 9:16: still published fitted on a blurred background (the image hosting code was shared and renamed)
  • The YouTube warning on the post card reads naturally in Portuguese

API and MCP

  • REST API PUT /posts/{id} with media[0].meta.cover: {upload_token} on a Reel: saved; on a TikTok post: dropped, cover_offset_ms kept
  • MCP update-post-tool with meta.cover: {id} of another post's image: copied to this post
  • list-content-types-tool shows supports_custom_video_cover: true for instagram_reel and youtube_short only

Languages

  • Spot-check the Thumbnail tab in Portuguese, German and Russian: the switch and the buttons fit on one line, and the hints read naturally

Paulo Castellano added 12 commits November 16, 2026 20:29
A video's cover can now be an image (media.*.meta.cover): one the user
uploads, or a screenshot of the frame picked in the Thumbnail tab. The image
is a medias row owned by the post, synced by SyncOwnedMedia like thread reply
media, and accepted from the web, the REST API and MCP.

Instagram gets it as cover_url on the Reel container (re-encoded as a JPEG
when it is not one or is over 8 MB). YouTube gets it through thumbnails.set
once the video is processed (SetYouTubeCover); a refused cover keeps the post
published and shows a warning on its card, kept in error_context.
…Instagram

The Thumbnail tab shows the video's frames under the stage with a selector
that holds the picked frame; the right panel keeps the Video frame / Image
switch and the upload, and an uploaded cover takes the stage.
…review until it plays

VideoStill draws a video as its cover (the uploaded image, else the picked
frame) on the composer tile and on every post card; the preview keeps the
cover over the video until it is first played.
The cover image goes through the same stage, crop panel and render as any
image: the stage edits the cover's own crop (locked to 9:16, movable and
resizable like a profile photo's square) while the Thumbnail tab shows it,
and a reframed or new cover is rendered at apply.
…, name YouTube's warning

- Store where a cover comes from (meta.cover_source); picking an image keeps
  the frame time, and a post on a frame-only network drops the image on save.
- Rename the warning to App\Enums\YouTube\ThumbnailWarning; add the
  ProcessingStatus enum; warn when YouTube cannot process the video and
  when the token is revoked instead of retrying.
- Drop covers sent on thread reply media; fall back to the frame when a Reel
  cover cannot be made a JPEG.
- Laravel helpers over native calls, one covers() helper, one
  download-process-host flow, named template conditions, strip frames drawn
  at the strip's size, blob URLs revoked.
- Copy: the hint describes the frame strip, Turkish in the file's formal
  voice, one German word for the cover, the unused alt key removed.
- An Instagram Reel whose cover is a frame publishes it as thumb_offset; only
  YouTube, which takes no frame time, gets the frame's screenshot, so Reels
  need no capture (and no CORS) and a new frame time is never beaten by an
  old screenshot.
- A post on a frame-only network drops cover_source with the cover, and its
  Thumbnail tab always shows the frame strip.
- One JPEG conversion (FitsImageToCanvas::jpegFrom) for Instagram and
  YouTube, checking the result is a JPEG within the network's size; a cover
  YouTube cannot get as a JPEG warns at once.
- A cover row shares its video's order instead of taking one of its own.
- The picked file's blob URL survives a failed Apply; detached videos are
  released after use.
- CoverSource and CoverImage live in types/media.ts.
- Clearer Russian, Ukrainian, Greek and French cover buttons.
- Previews of a network that takes no cover image show the frame, never an
  image uploaded for another network.
- A frame picked before YouTube was added gets its screenshot on Apply.
- SetYouTubeCover warns when the channel is no longer connected and stays
  quiet on a 404 (the video was removed); the card's failure is built from
  the context again, ignoring only the YouTube warning.
- YouTube reuses the trait's download (no image buffered in memory); the
  trait is renamed HostsProcessedImages, since it now converts as well.
- Template decisions moved to computeds (stage box class, picked time).
@paulocastellano
paulocastellano merged commit cc87931 into main Nov 17, 2026
17 of 19 checks passed
@paulocastellano
paulocastellano deleted the feature/instagram-reel-custom-cover branch November 17, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant