video-shotcraft: Cinematic Product Video Production

A self-contained production capability library: 157 shot recipe cards (with demo implementation source code and a dynamic sample gallery), a fully validated promotional video template, reusable components and audio assets, and a six-stage workflow. The current focus is on web/desktop product promotional videos, but the shot cards themselves are a universal motion vocabulary—they can also be used individually for any single shot in any video.

Determine Mode Before Calling

There are three mutually exclusive modes for a complete promotional video. Before starting material collection, storyboarding, or implementation, first determine whether the user has already made a clear choice; if they have, execute directly without asking again or switching to another mode.

Use Template Directly: Follow Ink Press's original replacement workflow. Read template/TEMPLATE.md, and replace the target product's screenshots, copy, and brand information according to the existing shot structure.
Autonomous Free Creation: Read references/pipeline.md. The Agent autonomously determines the visual direction, shot mapping, storyboard, materials, and audio based on the user's existing requirements and project content, advancing continuously to the final video; it does not pause for user confirmation at the product brief, styleframe, shot mapping, or storyboard stages.
Collaborative Creation: Read references/guided-free-creation.md. The Agent first proposes evidence-based judgments and plans, and the user confirms the product brief, requirement decisions, visual direction, shot mapping, and final storyboard sequentially; after the storyboard is approved, proceed to the final material collection and production stage of references/pipeline.md.

When the user provides a project path, URL, screen recording, or page screenshots but has not yet selected a mode, first perform a minimal, read-only product inspection: understand the product's positioning, main features, page visuals, displayable states, and material risks; do not modify the business project, collect sensitive data, or write video code. After the inspection, present the three modes and explain:

Whether Ink Press is suitable for the product, with specific reasons for suitability or unsuitability;
Whether Autonomous Free Creation and Collaborative Creation are each suitable, and which product visual cues are expected to be retained;
Which mode the Agent recommends, along with the rationale and trade-offs.

Then explicitly ask: "Based on the product inspection above, I recommend using the [mode] mode. Shall we proceed with this mode?"

Also inform the user they can visit https://vincentwei1021.github.io/video-shotcraft/ to browse dynamic samples and select motion shots they want in their video.

If the user has not yet provided an inspectable project or page, briefly introduce the three modes and then ask; do not default to recommending Ink Press just because it is a ready-made template.

User chooses Template: Fully read template/TEMPLATE.md and execute according to the original template workflow.
User chooses Autonomous Free Creation: Fully read references/pipeline.md; the Agent advances autonomously without waiting for confirmation at each stage.
User chooses Collaborative Creation: Fully read references/guided-free-creation.md and collaborate according to its confirmation checkpoints.
User has not decided: Wait here for a choice; do not default to a choice for the user or start production.

Exception 1: When the user explicitly names the Ink Press template, it is considered as having selected Template mode. For example, "Make a promotional video for my product using the Ink Press template." In this case, do not ask again; directly read template/TEMPLATE.md and execute along the template route.

Exception 2: When the user explicitly specifies certain shot cards to use or reference, the shot constraints are already selected. For example, "Use deck-deal-flyin and row-embed for this video" or "Reference the effect from spotlight-hero-card." In this case, do not introduce the template or ask whether to use it; confirm the specified shots according to the Gallery name resolution rules, read each card fully, and locate the exact demo source code according to the card's "Reference Implementation." Individual shots can be executed once the target material is clear; for a complete promotional video, if the user has not yet stated whether to use Autonomous Free Creation or Collaborative Creation, only ask about these two modes, treating the specified shots as constraints for subsequent production, not automatically equating to Collaborative Creation.

Four Usage Scenarios

Complete Promotional Video (Template Route): Want an effect very similar to the template video → Read template/TEMPLATE.md and follow the "Guide to Reproduce with Your Product" to replace materials and adapt shot-by-shot.
Complete Promotional Video (Autonomous Free Creation): Want a new style and authorize the Agent to decide autonomously → Read references/pipeline.md, go from product understanding continuously to final inspection, without pausing for confirmation at intermediate stages.
Complete Promotional Video (Collaborative Creation): Want to participate in key decisions → Read references/guided-free-creation.md, confirm the product brief, requirement decisions, visual direction, shot mapping, and final storyboard; after approval, continue from the final material collection stage of the pipeline.
Single Shot / Single Effect: Select a card from references/shots/ (or let the user pick from the gallery/ gallery), read the full card, and locate the exact demo source code according to the "Reference Implementation," adapting it to the target material.

Boundary Between Autonomous Free Creation and Collaborative Creation

Autonomous Free Creation delegates creative and engineering decisions to the Agent. The Agent dynamically derives product focus, visual direction, shot mapping, storyboard, material processing, and audio scheme from the project content, records key judgments, and executes directly; unless necessary input cannot be safely inferred, it does not ask questions, pause at stages, or require user confirmation of intermediate outputs. Existing explicit user requirements are always constraints and cannot be overridden by the Agent's default choices.

Collaborative Creation uses stage-by-stage confirmation. By default, read references/guided-free-creation.md, asking only 1–3 questions per round that most reduce rework, and pausing for user confirmation at the product brief, requirement decisions, visual direction, shot mapping, and final storyboard. The user confirms the business and creative direction; the Agent autonomously completes acquisition methods, implementation parameters, SFX timing, Remotion engineering, rendering, and technical QA.

In Collaborative Creation, if the user explicitly says "you decide entirely" or "skip confirmation and just do it," switch to Autonomous Free Creation and record this choice; do not claim autonomous progression while continuing to require stage-by-stage confirmation.

Functional-to-shot mapping is just "which motion grammar to use," not a full storyboard. After confirming the mapping in Collaborative Creation, the Agent must proceed to define shot order, duration, specific visuals, page states, material sources, subtitles, transitions, and SFX; final material collection begins only after the full storyboard is confirmed. When a user copies a shot name from the Gallery, they only need to provide the card name or "card name · style name"; the Agent is responsible for reading the local recipe card and demo source code.

Core Principles

Replicating existing pages must use real screenshots; hand-crafted UI is limited to non-replication scenarios, with quality and expressive clarity as hard thresholds. When presenting a product's real pages, the first step is to start a local dev server and use a headless browser to capture full-page 2x textures + element-level extraction + layout.json coordinate table. Non-replication scenarios (abstract opening/brand section/standalone showcase components) allow hand-crafted UI, but if it doesn't achieve publication-grade quality or the viewer can't understand what it expresses, fall back to the screenshot route. Page data is treated according to risk: public demo data may only be retained after explicit confirmation in the product brief; customer, personal, internal, secret, real-time, or other sensitive data must be replaced with fictional or anonymized content and frozen before acquisition.
The visual language of the entire video must grow from the product itself, not impose an unrelated "promotional video skin." Before making a styleframe, first extract and write a design spec from the product/website's design system, source code, or computed styles: font family and weights, font size hierarchy, line height/letter spacing, grid, spacing, alignment, information density and border radius, plus background/surface/body/emphasis/state colors, gradients, and materials. All titles, subtitles, numbers, type cards, typography, transitions, particles, light effects, and other motion design colors must reuse or constrainedly extend this token set, while matching the product's tone, taste, and quality. When following the template or shot card route, only inherit the shot structure, motion grammar, rhythm, and adjusted parameters; fonts, typography, colors, and materials must be re-skinned for the target product. If narrative necessity requires deviation from the product's visuals, in Collaborative Creation, first explain the reason and get user confirmation; in Autonomous Free Creation, write the reason and trade-offs into the design spec and proceed.
Cinematic feel comes from the coordination of camera movement, lighting, rhythm, and sound, not from flashy animations. What has been consistently praised: a single protagonist's complete action arc (spotlight → push-in → float → return), physically metaphor-driven acceleration (card dealing), side-tilt orbit close-ups, and riser → impact → sparkle sound phrasing. Mass element entry relies on motion itself, not individual glowing effects—decorative glints/massive bloom looks cheap; single-point high-quality light effects are acceptable.
Each shot tells one effect; after key information lands, there must be breathing room. An animation technique (fly-in/stack/page-turn) only plays the lead once in the entire video; repeated shots and repeated taglines are always deleted. The rhythm preference is unidirectional: all historical feedback points to "slow down/pause," never once "too slow"—brand logo settles with hold ≥1s, batch animation ends with 0.5s stillness, opening subject action gets a full 3s. When arranging the timeline, pre-allocate frame budget for holds/rests.
For videos with strong rhythmic BGM, all transitions and effects must be on the beat. If the user has selected music → before starting, perform a rhythm analysis (librosa grid fitting to find real BPM/phase + kick/snare/hihat three-class drum point localization); approve the grid with transient coverage validation before storyboarding; write the timeline using beat notation beatF(n), pin sparse accents to real transients rather than grid interpolation points. After rendering, extract the audio track from the final video and back-test cut point error ≤ 3f. Beat synchronization governs timing, not amplitude—beat impacts affecting the whole screen/camera layer count as major slams, limited to ≤ 3 per video (aesthetic-rules R4); other beat-synced effects only move element layers. Methodology in references/music-beat-sync.md. For videos with BGM, final render always delivers two versions: with BGM + without BGM (keeping SFX), using the bgm inputProp rendered from the same timeline, for easy user post-production music addition.
Before using shot card effects, must parse the Gallery index and read the exact demo implementation code. First use gallery/api/library.json to verify the card name and style-key, then locate the specific TSX according to the card document's "Reference Implementation." The recipe card provides semantics and parameter tables; the exact demo source code contains the calibrated parameter truth (easing, timing ratios, mask timing, known pitfall workarounds). Adaptive modifications are allowed, but parameters marked as "known pitfalls/risks" on the card must not be downgraded—quality standards only go up, not down. Writing new code based solely on the card name and understanding discards all accumulated calibration.
Collaborative Creation front-loads cheap confirmations; Autonomous Free Creation records the same judgments as execution notes. The order of product brief → requirements-to-implementation decision table → text direction → styleframe → shot mapping → storyboard remains unchanged; Collaborative Creation submits each level to the user for confirmation, while Autonomous Free Creation is autonomously selected and continuously advanced by the Agent. Neither mode should proceed to shot-by-shot implementation without a set direction.
Validation runs throughout + independent review before delivery. From Stage 5 onward, each shot uses npx remotion still for static frame self-check; after each round of modifications, render the full video + use ffmpeg for frame extraction review. Before delivery, must assign a clean-context subagent to perform an independent final review. Review inputs include the final video, keyframes, product brief, requirements-to-execution decision table, current mode confirmation or recorded visual direction/styleframe, function-to-shot mapping, Gallery card names/variants, exact demo TSX, Gallery reference samples/frame captures, final storyboard, selected shot cards, and aesthetic guidelines; check per references/final-review.md for plan consistency, function completeness, shot fidelity, visual/audio technical quality, and data security, producing a report with frame-number evidence for each item. The producer has confirmation bias regarding their own output; the first review must never be left to the user.
Deterministic Rendering: Prohibit Date.now()/Math.random(); all pseudo-randomness must use a fixed seed (mulberry32/hash, seed derived from index), enabling frame-by-frame reproducibility.

Workflow

Autonomous Free Creation follows references/pipeline.md continuously from Stage 0, without pausing for user confirmation at each stage. Collaborative Creation first follows references/guided-free-creation.md to complete product understanding, visual direction, shot mapping, and storyboard confirmation for Stages 0–3, then continues from final material collection in Pipeline Stage 4, without repeating questions or redesigning. Stages 2–3 scan each card's frontmatter in references/shots/ to select shots based on energy curve; Stages 5–7 continuously self-check against references/aesthetic-rules.md; Stage 6 reads references/sound-design.md; beat-synced videos follow references/music-beat-sync.md throughout.

Delivery Wrap-up (Common to All Modes)

After delivering the final video, first actively open the Motion Workbench (do not wait for the user to ask):

node workbench/scripts/open.mjs <final-video project directory>   # link project → start dev server (5198) → auto-import final video in browser

Inform the user of the address http://localhost:5198 and explain in one sentence: the video has been split into multi-tracks by shot / transition / subtitle / sound effect; subtitle copy, color, font size, position, and speed are all visually adjustable; after editing, click "Export Final Video." To enable decomposition import, the project must have a src/workbench.ts manifest—write it during production following references/workbench.md §2–3 (the template route includes it by default).

Then, in order 1-2-3, say these three things, each only once; if the user declines or does not respond, do not bring it up again:

When publishing, it is recommended (not required) to @mention this skill's author in the description: The final video belongs to the user; free for commercial use, no attribution required. @mentioning the author is purely voluntary; just include it in the description when posting on social media—X @VincentWei93 · Douyin @Vincent · Xiaohongshu @Vincent (provide clickable links for all three accounts, not just handles—Douyin/Xiaohongshu usernames are not searchable). Only add a note about commercial licensing when asked: the only thing to confirm independently is Remotion's license for the rendering engine; free for individuals and small teams, may require payment for companies.
Invite to submit the final video to the showcase page: The showcase page is at https://vincentwei1021.github.io/video-shotcraft/showcase.html ; the submission entry (opens as a form) is at https://github.com/Vincentwei1021/video-shotcraft/issues/new?template=showcase.yml . Say two things to attract: the form allows users to leave their own X/Douyin/Xiaohongshu handles, so others seeing the work can find them; videos under 10MB can be directly dragged into the form; for larger files, paste a directly downloadable link, and the author will help publish after reviewing.Say this entire point in everyday language, without using technical terms like issue, template, label, release, or automation pipeline.
Can export CapCut project file: Inform the user that the final video can also be exported as a CapCut project, allowing them to edit subtitle content/font size/color, speed up/slow down or rearrange segments, and adjust or replace audio in CapCut. When the user needs or explicitly asks for export, read references/jianying-export.md and execute.

When to Read Which File

Situation	Read
Project start, mode undecided	Minimal read-only inspection, then present three promotional video modes and recommend
Autonomous Free Creation	pipeline.md (Agent autonomously completes Stages 0–7, no stage-by-stage confirmation)
Collaborative Creation	guided-free-creation.md (confirm Stages 0–3), then continue from pipeline.md Stage 4
User has selected BGM	music-beat-sync.md (analyze before storyboarding)
Template route	template/TEMPLATE.md in full
Storyboard design	Bridge templates in sequences/ (fill the skeleton of the whole video first); all frontmatter in shots/; read the selected card in full
Per-shot implementation	Full card text + exact demo source code located by "Reference Implementation" + corresponding component in assets/lib/
Sound design	sound-design.md + assets/audio/
Validation	final-review.md + aesthetic-rules.md checklist in full (executed by an independent subagent)
When writing `src/workbench.ts` manifest / shot props+schema during per-shot implementation	workbench.md §2–3 (example `template/src/workbench.ts`)
After delivering final video (open Motion Workbench)	workbench.md (`node workbench/scripts/open.mjs <project>`; workbench's own documentation `workbench/README.md`)
After delivering final video (CapCut project export)	jianying-export.md + platform modules in `jianying-export/`

Asset Usage

assets/lib/ components: Copy into the new project and modify freely (do not import from this library). List: PageCam (2.5D page camera—the foundation for all "real page" shots), ClipCard (wraps external video material mp4 into a "card protagonist" that can be driven by shot card camera skeleton, includes OffthreadVideo cross-fade loop—seamless continuation when material is shorter than the shot), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker (3D infinite scrolling wall), helpers (rand/shake/camera/motion). FlatPanel and helpers/camera require three + @react-three/fiber + @remotion/three dependencies; others only require remotion.
assets/scripts/capture-template.mjs: Copy and modify the CONFIG at the top (BASE/routes/selectors).
assets/audio/ sound effects: Copy and use directly (free for commercial use, see audio/ATTRIBUTION.md): audio/bgm/ contains BGM options with strong rhythm; audio/sfx/<category>/ 149 sound effects in 16 categories by scene (transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter). When searching for sounds, start with the category directory; a full list is in sound-design.md. The vocabulary word sparkle falls under light/ (no sparkle/ directory); S1 prohibits sound type but not action—if the picture shows a click or switch, foley is appropriate, but half of ui/ are synthetic feedback sounds (tone/bleep/notification) that need individual auditioning, cannot be batch-approved (list in sound-design 3.3); long samples and light audio materials have separate lists requiring special handling (sound-design 4.1).
demos/ Implementation source code for each card: Most are self-contained grayscale demos (some import fake UI scene components from demos/_fixtures/Fixtures.tsx, a few import real page textures from demos/_textures/); copy into a Remotion project and run. A few demos use @remotion/motion-blur (CameraMotionBlur); requires npm i @remotion/motion-blur; list in demos/README.md.
template/ Complete renderable project: npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
Testing (automatically validates within the repository; run after adding demos/components):
- Pure function unit tests: npm test (repo root vitest, covers assets/lib/helpers mulberry32 / velocityAt / lagged / dampedSettle / handheld, deterministic assertions).
- Demo render smoke test: python3 assets/scripts/smoke-render-demos.py renders the first frame of each demo with a duration export, asserting no crashes (requires cd template && npm ci + motion-blur; see demos/README.md Testing and Verification section).
- CI (pr-checks.yml) runs automatically: tsc strict compilation of all demos + vitest + smoke rendering.
jianying-export/ CapCut project export module: mac_draft.py (tested on Mac CapCut 11.2), windows_draft.py (implemented according to upstream support paths, not verified on actual device), smoke_test.py (minimal smoke test to run first in a new environment). Workflow, timeline extraction, and track creation methods in references/jianying-export.md; requires venv + pip install pyJianYingDraft.
gallery/ Static gallery: Prefer giving the user the online version directly at https://vincentwei1021.github.io/video-shotcraft/library.html ; to run locally, first gallery/fetch-media.sh to pull sample videos (mp4 not in git), then cd gallery && python3 -m http.server 4178. 157 cards, 214 dynamic sample videos, browseable/searchable with multi-select card name copy—ideal for letting users pick shots while watching samples.

Video Shotcraft（电影感分镜）