xhs-card-video

Faceless Explainer Video Xiaohongshu

This is an independent short video production route specifically for Xiaohongshu drafts using a "real content screenshot card + dynamic landscape background + local BGM" format. It does not modify or replace the existing $explainer skill; the latter remains responsible for 16:9, voiceover, and full explainer videos.

The core audience consists of individuals aspiring to start their own business, currently learning about AI, and possessing a basic understanding of business and AI. Screenshots serve only as evidence entry points; the real content value lies in translating the insights within the screenshot into actions that this audience can judge and execute.

First, Define the Boundaries

• Each piece of content delivers only two things to the user: an openable .mp4 file and an .md publication draft with the same title. Paired files from multiple pieces of content within the same week can be placed directly into the same weekly directory; internal tracking manifests are not part of the delivery and must not be placed in the weekly directory.
• Default placement: ExplainerXiaohongshuXX/WeekN/. Finished videos and publication drafts from the same week are placed directly in the weekly directory; no subdirectories for individual content items are created.
• The publication draft must always have publish_status: draft; before final delivery, title_status must be locked. By default, do not automatically log in, upload, publish, comment, like, or follow. Only when the editor explicitly requests it may the specified finished video and publication draft be uploaded to a logged-in Xiaohongshu Creator Center and saved as a draft. Never click "publish." If the user explicitly confirms a list of candidate accounts, they can be manually followed one by one in a logged-in X App; batch scripting or using this for engagement growth is prohibited.
• X content must come from user-provided screenshots or posts visible in the user's logged-in X App. Do not bypass CAPTCHAs, paywalls, or permissions; do not rearrange screenshot text or fabricate accounts, numbers, or dates.
• Do not include an X source line by default, unless the user specifically requests it; source and license information are stored only in the asset library metadata.
• One screenshot is the sole information card. Do not superimpose word-by-word subtitles, title bars, stickers, logos, intros, outros, CTAs, a second card, or characters.
• When the user has not provided factual evidence, titles and copy can only be clearly marked summaries; do not present speculation as fact.
• Each finished video must have an internal run_manifest.json file stored outside the weekly directory, recording the screenshot, background, BGM, target audience, topic score, title candidates, body structure, audit package, hashes, and human confirmation. This is not a delivery file and must not be placed in the weekly directory.

When to Use

Use this skill when the user says "make an explainer Xiaohongshu," "turn the X screenshot into a video," "use a dynamic landscape as background," "pair it with a BGM," or "give me the video and publication draft." When operations on a logged-in desktop/X App are needed, first read the available computer-use/browser control skill. For media probing and rendering, use local ffprobe, ffmpeg, or authorized editing tools. If a screenshot, background, compliant BGM, or title basis that would change the factual meaning is missing, stop at WAIT_DATA/WAIT_USER; do not fabricate.

Input and Output Contract

Generation and review rules for titles, 50-character body text, and tags are detailed in content-generation-contract.md. This reference file is the standard for content production in this skill, not optional inspiration.

Minimum Input

1. An X screenshot, or a post locatable within a logged-in X App.
2. A user-uploaded layout reference image, used to lock source_crop_rect_px; if the user explicitly confirms that the X screenshot itself serves as the layout reference, the same file may be reused.
3. A dynamic background video. If the user does not provide one, it can be obtained from the explicit download page of Pexels/Unsplash, with license/source records saved; do not use assets based solely on search result pages.
4. A local BGM, or permission to select from the local ExplainerXiaohongshuBGMLibrary. Audio without clear authorization must not be included in the finished video.

Optional: Theme, target emotion, week number, user-specified title, whether to retain the visible image area of the original post; video duration is not an input and is permanently fixed at 8 seconds.

Video Fixed Specifications

• Canvas permanently fixed to 1080×1440 px (3:4), default 30 fps, H.264 video, AAC audio.
• Video duration permanently fixed to 8 seconds; must not be adjusted to any other duration.
• Dynamic background fills the entire frame; slight dimming/vignetting/blurring is allowed to support the card; the background must not be frozen into a static frame.
• Screenshot card width permanently fixed to 880 px, canvas left and right margins permanently fixed to 100 px (100 + 880 + 100 = 1080).
• The screenshot card is first cropped from the source screenshot according to the user's reference image to lock the crop area, then filled and cropped (cover) to fill the 880 px width; padding, letterboxing, or any blank space filling is strictly prohibited. Key text must not be rewritten, rearranged, or obscured.
• The screenshot card height is naturally determined by the screenshot proportions after locking the reference: if logical_card_height <= 1440, then final_card_height = logical_card_height and y = floor((1440 - final_card_height) / 2); if it exceeds 1440 px, first apply source_vertical_crop_px = floor((logical_card_height - 1440) / 2) for centered vertical cropping, final_card_height = 1440, y = 0. In neither case are fixed top/bottom margins specified; the width must not be reduced and blank space must not be filled.
• The final visible layer of the screenshot uniformly uses a 24 px rounded corner mask (based on the output 1080×1440 pixels), a 2 px light gray stroke #C9D1D8 drawn inward from the outermost edge of the card, and a soft drop shadow: black, 16% opacity, blur radius 12 px, offset (0, 8 px), spread 36 px. The stroke and shadow belong to the screenshot card itself and do not change the card's outer dimensions of 880 px or add a second information layer. If no reference image is provided, stop at WAIT_USER; do not lock the crop rectangle.
• The screenshot card appears by default from 0 seconds as the first and only information card in the video and remains until the end; if the user explicitly requests an entrance animation, it can only be a subtle, readable change applied to this card itself.
• The visual composition consists only of a "background + one screenshot card." Extra subtitles, stickers, source bars, intros, outros, and a second information layer are prohibited.
• By default, only one BGM audio track is used; no voiceover is added. The music covers the entire video with short fade-in/fade-out to avoid clipping and abrupt cuts.

Publication Draft Fixed Specifications

The Markdown base filename must be identical to the video: <title>.mp4 and <title>.md. The body text is strictly 50 Chinese characters by default. The count only considers Chinese characters in the body text, excluding the title, punctuation, numbers, English, tags, and status fields. Only when the user explicitly selects a loose mode may 45–65 characters be used. The draft retains only:

publish_status: draft
title_status: locked
copy_length: exact_50
platform: xiaohongshu
content_review_status: claude_approved
content_review_agent: claude
content_generation_agent: claude
editorial_review_status: codex_approved
editorial_review_agent: codex

# Title

Body text (exactly 50 Chinese characters, containing an engaging hook and a clear conclusion)

#Tag1 #Tag2 #Tag3

Do not include BGM licenses, download links, or production processes in the reader-facing copy. For traceability, write them into the asset library index.json or the internal run results; do not add files to the weekly delivery.

Workflow

1. Receive and Validate: Confirm the screenshot, separate layout reference image (or user explicitly confirms screenshot doubles as reference), background, theme, week number, and asset library status; list gaps. If the title contains numbers, causes and effects, or benefit promises, first verify the screenshot actually supports them.
2. Capture Content: When the user authorizes operations on the X App, capture only the currently visible content; copy the original screenshot read-only to a temporary workspace. After the video is accepted, clean up temporary copies; do not delete the user's original screenshot, video, or music.
3. Screen, Select Topic, and Claude First Draft: Subsequent automation reads only public posts from the confirmed X account pool, first passing the screenshot quality threshold of content-generation-contract.md; after passing, create a topic_packet, score it, then have Claude generate 5 title candidates, 1 recommended title, 2 backup titles, four body text options, and 5 tags. If the editor has already specified a title, lock that title directly; Claude only generates body text and tags. Claude's output is always a material draft and cannot be directly delivered.
4. Codex Deep Editorial Review and Final Draft Audit: Codex must rethink Claude's draft, focusing on reviewing the hook, catchiness, genuine pain points, conflict, identity claiming, memorable phrases, action value, and evidence boundaries; rewrite entirely if necessary, not just compress word count. After completing a mechanical check of exactly 50 Chinese characters and 5 tags, send the final draft to Claude for compliance review; only switch to Hermes if Claude is unavailable, and record the fallback_reason. Only when editorial_review_status: codex_approved and the compliance status is claude_approved or a legitimate hermes_approved can it proceed to delivery.
5. Select Background: Prioritize using the user's provided video. External assets are only downloaded from authorized official pages with source records. Crop/scale to 3:4 without affecting the readable area of the screenshot card.
6. Select BGM: First run audit_bgm.py, then filter from local records with approved, sync_allowed=true, commercial_allowed=true by mood, energy, duration, and vocal status. Select one using a fixed seed from the top 3–5 scoring tracks. pending can only be offered as a candidate suggestion; production/delivery must use --confirmed-only with human_listen_status=confirmed. AI does not make the final choice for humans. CC BY tracks must also have a placeable attribution text, otherwise they are eliminated.
7. Compose: Rebuild the complete timeline from the source screenshot, background, and BGM using ffmpeg/editing tools to output a 1080×1440 MP4. If an error is found, go back and rebuild from the source materials; do not apply patches on top of an already rendered MP4.
8. Acceptance: Use ffprobe to mandatorily check aspect ratio, frame rate, H.264/yuv420p, AAC, single audio track, audio starting at 0 seconds and covering the full duration, duration of 8 seconds (allow muxing tolerance ±0.05 seconds); extract frames to confirm the card is clear and no extra text layers are present; check audio for no clipping, no silent start, and no obvious vocal conflict; text must first pass Codex deep editorial review, then Claude compliance review, or Hermes backup review if Claude connection fails and the reason is recorded.
9. Archive: Write exactly one MP4 and one Markdown file directly into ExplainerXiaohongshuXX/WeekN/; place the internal manifest outside the weekly directory. Clean up only temporary copies, temporary frames, logs, and backup versions generated during this run; do not clean up user's original assets; retain source, license, and hash records in the manifest; keep as local drafts, no external publishing.
10. Xiaohongshu Draft Box (Only When User Explicitly Requests): Prioritize taking over the user's logged-in desktop Google Chrome Xiaohongshu Creator Center; do not treat the login state of Codex's built-in browser as a desktop browser session. After confirming the Creator Center is logged in, upload the specified .mp4, fill in the same title and the final body text/5 tags from the Markdown, wait for processing to complete, then click "Save Draft" or an equivalent button. After saving, must perform authoritative verification using the page prompt, draft list, or title readback, and write draft_upload_status, timestamp, and draft identifier into the manifest outside the weekly directory. When encountering login pages, CAPTCHAs, risk control, copyright notices, or any other page requiring user judgment, stop at WAIT_USER; must not click "publish," schedule publish, cross-post, or perform any interaction operations.

Hermes / Faceless Explainer Acceptance Hard Constraints

Every delivery must record factual evidence; do not approve based solely on a "looks about right" judgment:

• Canvas: ffprobe must confirm 1080×1440.
• Horizontal Geometry: Extracted frames or filter logs must prove that the screenshot card is at x=100, w=880, right_margin=100.
• Fill Crop: The screenshot card must not have pad, letterbox, white margins, or transparent padding; any overflow must result from cover cropping.
• Vertical Geometry: If not exceeding 1440, y=floor((1440-final_card_height)/2); if exceeding, first record centered source_vertical_crop_px, final card height is 1440, y=0.
• Rounded Corners, Stroke, Shadow, and Layers: The mask radius of the final screenshot visible layer is 24px; the inward stroke from the outermost edge of the card is fixed at 2px #C9D1D8; the shadow is fixed at black 16%, blur 12px, offset (0,8px), spread 36px; the composition can only consist of the dynamic background and this single screenshot card.
• Reproducibility: The manifest must include the above geometric values, the user's reference image path/hash, source_crop_rect_px, acceptance timestamp, paths and hashes for the first, middle, and last frames, filter log path, and next_state; stop at WAIT_USER if the reference image or evidence is missing.

Rounded corners, stroke, and shadow must be applied to the screenshot card before it enters the composition: first draw a 2px #C9D1D8 stroke inward from the outermost edge of the card, then use scripts/make_rounded_mask.py --width 880 --height FINAL_CARD_H --radius 24 --output rounded-mask.pgm to generate a PGM mask of the final card dimensions and apply alphamerge; generate the expanded, blurred, and offset shadow from the same rounded card alpha, then composite the shadow and the original card onto the background. Layers must not be added on top of a rendered MP4. The manifest must record all fixed parameters of the stroke and shadow.

Intent Entry Points

Treat the following phrases as stable internal routes; do not require the user to understand script parameters:

/xhs-card-video make
/xhs-card-video make --source x-app --week auto --bgm random --confirmed-only --record
/xhs-card-video make --source <screenshot> --background <video> --bgm <bgm-id>
/xhs-card-video bgm init --count 100
/xhs-card-video bgm ingest <file-or-folder>
/xhs-card-video bgm confirm <bgm-id> --status confirmed
/xhs-card-video bgm audit
/xhs-card-video bgm pick --mood rainy --energy low-mid --seed <seed> --confirmed-only --record
/xhs-card-video audit <week-folder>
/xhs-card-video audit <week-folder> --title <title> --manifest <run-manifest.json>
/xhs-card-video audit <week-folder> --manifest <run-manifest.json>

The corresponding scripts are in the scripts/ directory of this skill. Scripts are reusable auxiliary tools; their presence does not imply that external publishing has been executed.

Local BGM Asset Library

Default Path:

{{CREATOR_ROOT}}/ExplainerXiaohongshuBGMLibrary/

Prioritize overriding with the environment variable PROOF_EXPLAINER_XHS_BGM_LIBRARY; the old variable EXPLAINER_XHS_BGM_LIBRARY is retained only for compatibility. The initial library contains 100 tracks, divided into 10 categories: Focus & Daily, Rainy Night & Weather, Atmosphere & Dream, Late Night & Neon, Warmth & Slow Tempo, Jazz & Bookstore, Easygoing & Daily, Eastern & Zen, Retro & Groove, World & Cinematic. The 100 tracks are merely a callable asset pool; they are not Xiaohongshu's Top 100 trending tracks and do not constitute a trend ranking.

Metadata Minimum Requirements

Each track in index.json must at least include:

{
  "id": "bgm-001",
  "relative_path": "audio/01_Focus_Daily/bgm-001__track.mp3",
  "source_page_url": "https://…",
  "download_url": "https://…",
  "source_platform": "openlofi|user_local|manual_other",
  "license_class": "cc0|cc_by|site_custom|user_owned|reference_only|blocked",
  "sync_allowed": true,
  "commercial_allowed": true,
  "standalone_redistribution_allowed": false,
  "license_checked_at": "YYYY-MM-DD",
  "license_snapshot_path": "licenses/…",
  "license_snapshot_sha256": "…",
  "rights_notes": "…",
  "trend_status": "verified|unverified|not_claimed",
  "duration_s": 12.3,
  "sha256": "…",
  "review_status": "approved|review|rejected",
  "human_listen_status": "pending|confirmed|rejected"
}

Only tracks with review_status=approved, sync_allowed=true, commercial_allowed=true, and a clear license class can be included in the video. reference_only is only for inspiration records; blocked must not be invoked. Audio from user-provided local videos defaults to review; only after the user confirms they own the rights or have obtained authorization can it be changed to user_owned. Permission to package/sell audio separately is different from "embedding in the video" and must not be implied by default.

The initial library uses the fixed release package of Open Lo-Fi v1.0.0, retaining the upstream catalog, README, LICENSE snapshot, and SHA-256 in the directory. The README declares CC0 1.0, but third-party samples/regional rights are not independently audited by this skill; rights_notes must retain this caveat. If the source is Pixabay, Mixkit, OpenGameArt, DOVA, etc., each official license page must be read individually; batch fetching or using preview URLs as formal authorization/download proof is prohibited. Do not download or redistribute restricted trending audio sources from XHS/TikTok/Instagram.

Selection Rules

random is not unconstrained randomness:

License and decode failure       → Eliminate
Mood match                        +4
Energy/rhythm match               +3
Duration, loopable, instrumental  +2
Recently used                     -1
Vocal conflict with card          -3

First retain the top 3–5 scoring tracks, then select 1 using a fixed seed; write the bgm_id, seed, and selection rationale into selection_history.jsonl; do not bring run logs into the weekly delivery directory.

Weekly Directory, Filename, and Status

ExplainerXiaohongshuXX/
└── WeekN/
    ├── <title>.mp4
    └── <title>.md

• WeekN defaults to the current ISO week number; when the user specifies a week number, use the user's specification.
• The filename is the confirmed title. Only replace system-prohibited characters, line breaks, and /; do not silently change it to a number.
• The weekly directory can only contain the paired MP4/Markdown files; do not place temporary assets, logs, or subdirectories. When multiple pieces of content are present, use audit_delivery.py --title <title> to audit the specified pair.
• The parent directory of the weekly directory must be exactly ExplainerXiaohongshuXX, and the week name must conform to Week1–Week53; the internal manifest is placed in {{CREATOR_ROOT}}/.xhs-card-video-runs/ (or a path outside the weekly directory as specified by the user).
• Internal status can be written as:

state: INTAKE | WAIT_DATA | WAIT_USER | WAIT_REVIEW | BUILD | AUDIT | local_ready
source_status: captured | supplied | missing
bgm_status: approved_confirmed | approved_pending_listen | review | missing
title_status: locked | draft
  publish_status: draft
  draft_upload_status: not_requested | pending | saved | blocked
  draft_upload_platform: xiaohongshu | none
  draft_upload_at: <ISO-8601 or null>
  draft_entry_identifier: <title/url/id or null>
copy_length: exact_50 | range_45_65
platform: xiaohongshu
content_review_status: pending | claude_approved | hermes_approved | rework_required
content_review_agent: claude | hermes | none
content_generation_agent: claude | hermes | none
editorial_review_status: pending | codex_approved | rework_required
editorial_review_agent: codex | none
run_manifest: <absolute path outside week folder>
delivery_path: <absolute week folder>
next_state: DONE | WAIT_DATA | WAIT_USER

Only when both final files are openable, audit_bgm.py and audit_delivery.py --manifest … all pass, and human visual/audio review has been confirmed with no external publishing action, can local_ready be reported.

Failure Handling

• Missing screenshot/background/available BGM: Report the specific gap, stop at WAIT_DATA; do not download unlicensed alternatives.
• Title would change the facts of the original post: Stop at WAIT_USER, provide the factual boundaries that need confirmation.
• Audio cannot be decoded, hash is a duplicate, or license fields are missing: Eliminate from the candidate pool, run audit_bgm.py; do not "use it first and deal with it later."
• BGM is still human_listen_status=pending, manifest is missing/is inside the weekly directory, or CC BY attribution has no placement location: Stop at WAIT_USER/AUDIT; do not report local_ready.
• Rendered aspect ratio, card readability, or audio track is unqualified: Delete the temporary output for that run, rebuild from source materials; do not apply patching layers.
• Any request for public publishing, scheduled publishing, or interaction: Keep as draft and explicitly require the user to personally confirm/execute; this skill only uploads to the Xiaohongshu draft box when the user explicitly requests it, and must stop at "Save Draft," not publish on the user's behalf.

Reference Files

• references/xhs-video-contract.md: Canvas, card, audio, and rendering constraints.
• references/bgm-library-contract.md: Directory, license, fields, and selection algorithm.
• references/delivery-checklist.md: Executable acceptance checklist before delivery.
• references/run-manifest.md: Source, license, hash, and human confirmation checklist outside the weekly directory.
• references/content-generation-contract.md: Target audience, topic scoring, Claude first draft, Codex deep editorial review, title/50-character body/5-tag mechanism, and final compliance review routing.
• scripts/install_openlofi.py: Initialize the first 100-track asset pool from the fixed official release.
• scripts/select_bgm.py: Filter and seeded-random select, does not modify audio.
• scripts/ingest_bgm.py: Place user local audio into the pending review inbox, does not grant rights by default.
• scripts/confirm_bgm.py: Record human listen pass/reject only by the user-specified ID, does not make decisions for humans.
• scripts/audit_bgm.py: Check index, paths, decoding, hashes, and license fields.
• scripts/audit_delivery.py: Check the weekly directory two-file contract, draft status, content review status, geometry evidence, and MP4 basic stream information.