publish-social
Publish video to social media platforms with metadata, thumbnails, and platform-specific optimization.
SKILL.mdAutoAnimation/.claude/skills/publish-social/SKILL.md
GitHubPublish to Social Media
Publish an exported video to social media platforms (TikTok, YouTube, Instagram, Facebook, X/Twitter) with AI-generated metadata, platform-specific optimization, and scheduling.
Purpose
After exporting a video, publish it to connected social media accounts with optimized titles, descriptions, hashtags, and posting times. Handles OAuth flows, platform compliance, auto-reframe for different aspect ratios, and scheduled publishing.
Steps
Connect social accounts via OAuth popup flow:
- Call
connectPlatform('tiktok')to initiate OAuth in a popup window. - The backend (
/api/social/auth/:platform) provides the authorization URL. - Tokens are stored server-side -- the frontend only sends its Supabase JWT.
- Available platforms:
facebook,instagram,tiktok,x,youtube.
- Call
Generate platform-optimized metadata:
generatePublishMetadata(contentSummary, platform, tone)calls Gemini to produce:title-- short catchy title (max 100 chars).description-- engaging description (max 300 chars for TikTok/IG, 500 for YouTube).hashtags-- 5 relevant hashtags.suggestedPostingTime-- best time to post in 24h format.
- Falls back to simple heuristic metadata if Gemini API key is not configured.
Check platform compliance before publishing:
- Each platform has specific requirements defined in
PLATFORM_PROFILES:- TikTok: 9:16, 15-60s, max 287MB, hook in first 3s, bottom 20% safe zone.
- YouTube Shorts: 9:16, 30-60s, max 256MB, hook in first 5s.
- Instagram Reels: 9:16, 15-90s, max 250MB, hook in first 3s, bottom 20% safe zone.
- YouTube: 16:9, 60-600s, max 12GB.
- Instagram Feed: 1:1 or 4:5, 3-60s, max 100MB.
analyzePlatformFit()returns aPlatformFitResultwith compliance score and adjustments.
- Each platform has specific requirements defined in
Auto-reframe for target platform (if aspect ratio differs):
autoReframe.tscomputes layout transforms: center-crop for backgrounds, repositions characters/text within platform safe zones.- Supports batch export to multiple aspect ratios simultaneously.
Publish the video:
- Upload the exported video blob to the platform via
/api/social/publish/:platform. - Pass platform-specific options (privacy, disable comments, etc.).
- Returns a
PublishResultwith post URL and status.
- Upload the exported video blob to the platform via
Schedule posts (optional):
- Use
autoPublishService.tsfor scheduling posts at optimal times. postingTimeHeuristics.tsprovides optimal posting time recommendations per platform.
- Use
Key Files
| Purpose | Path |
|---|---|
| Social publishing service | src/services/socialPublish.ts |
| Metadata generator (Gemini) | src/services/publishMetadataGenerator.ts |
| Platform optimizer | src/services/platformOptimizer.ts |
| Auto-reframe service | src/services/autoReframe.ts |
| Posting time heuristics | src/services/postingTimeHeuristics.ts |
| Auto-publish scheduler | src/services/autoPublishService.ts |
| Social types | src/types/social.ts |
| Platform optimization types | src/types/platformOptimization.ts |
| Share panel UI | src/components/panels/SharePanel.tsx |
| Auto-publish panel | src/components/panels/AutoPublishPanel.tsx |
| Server social routes | server/routes/social.ts |
| Server auto-publish routes | server/routes/autoPublish.ts |
Common Issues
- OAuth popup blocked: Browser blocks the popup. User must allow popups for the site. The service returns
{ success: false, error: 'Popup was blocked' }. - 401 from social endpoints: Supabase JWT expired. The user needs to re-authenticate.
getAuthHeaders()throws ifsession.access_tokenis missing. - Platform compliance failures: Video does not meet platform requirements (wrong aspect ratio, too long, file too large). Run
analyzePlatformFit()before publishing to catch issues. - Metadata generation fails: Gemini API key not set or API error. Falls back to
fallbackMetadata()which extracts first 10 words as title. - Auto-reframe distortion: Characters or text placed outside safe zones get cropped. Use
compositionEngine.tssafe zone functions to verify placement.
Examples
Connect TikTok account:
import { connectPlatform } from '@/services/socialPublish'
const result = await connectPlatform('tiktok')
if (result.success) console.log('Connected!')
Generate metadata:
import { generatePublishMetadata } from '@/services/publishMetadataGenerator'
const meta = await generatePublishMetadata(
'AI tools that save time for developers',
'tiktok',
'energetic'
)
// { title: '5 AI Tools Devs Need NOW', hashtags: ['#AI', '#DevTools', ...], ... }
Check platform fit:
import { analyzePlatformFit } from '@/services/platformOptimizer'
const fit = analyzePlatformFit('tiktok', {
aspectRatio: '9:16', durationSeconds: 30, width: 1080, height: 1920
})
// fit.score, fit.adjustments, fit.passed