book-sales-video

Book Sales Video Creation

An integrated workflow from book research to a locally editable first draft. Set up only one normal review: first automatically select the best angle and complete the voiceover and semantic storyboard; after the user confirms, automatically complete voiceover, visuals, subtitles, sound effects, motion effects, BGM, timeline, and quality check, with no further item-by-item confirmation.

Non-Negotiable Completion Line

Book facts come from WeRead; public reviews are used only to understand the reader's perspective and do not impersonate the original book's content.
When the user specifies reading copy from Feishu Base, the copy field confirmed by the user in the target record is the authoritative voiceover source; apart from trimming leading and trailing whitespace and unifying line breaks, keep the original text, and do not rewrite it without authorization, concatenate other records, or overwrite it with a research draft.
When the user provides a personal style profile and a list of prohibited expressions, they must be read before creating the voiceover; when not provided, use the voiceover reference included with this Skill, and do not guess the user's private paths or style rules.
By default, automatically form 2–3 candidate angles and score them, and directly use the comprehensively best angle to write the complete copy; do not have the user choose an angle in the early stage.
The only normal review point is after the complete voiceover and semantic storyboard. Only if the user rejects it should candidate angles be shown for selection; after selection, rewrite and directly enter production, without adding a second confirmation.
Run only once on the confirmed full text scripts/doubao_tts.py, and ultimately produce only one audio/narration.wav. For long scripts, the script may internally request and merge by sentence boundaries, but multiple voiceovers must not be manually generated per shot.
The beginning, ending, and all inter-sentence silences must be checked: ordinary inter-sentence silences must not exceed 0.45 seconds, and paragraph/visual transition silences must not exceed 0.70 seconds; the only allowed 0.80–1.20 second no-narration zone is a template carousel covered by continuous rotating sound effects.
The actual audible milliseconds of the final voiceover are the sole time basis for all visuals, subtitles, sound effects, and transitions; frame positions are converted using the timeline fps of the current OpenChatCut project.
The opening dynamic video is fixed to search via the Pexels API for book, and the keywords are not changed based on the book title or copy.
The carousel uses the OpenChatCut local library library:sound:mechanical-clicking-loop, with each effective peak hard-cutting to a different cover; finally, it enters the main book reveal through a short light dissolve.
The main book cover pop-up uses the OpenChatCut local library library:sound:cash-register-success, with visual accents aligned to sound effect anchors.
Each image in the body must have a slight breathing/push-in motion effect, and adjacent images must have transitions; static images must not simply be spliced end to end.
Both Chinese and English subtitles are white text with clear black outlines; Chinese is on top and English is below, with only one visible subtitle set retained.
The body locks in "Rough Paper Oil Painting with Margin v3": the oil painting narrative scene occupies at least 70% of the frame (default 70%–80%), extending horizontally all the way to the left and right edges; uncolored rough paper is allowed only at the top, bottom, or both top and bottom, with a total proportion of 20%–30%. Each time, use assets/visual-style/approved-rough-paper-oil-v3.png as the main anchor.
All materials enter the local OpenChatCut as independent editable items; do not pass off a locally pre-composited flat video as an editable first draft.
This Skill disables the legacy ChatCut cloud MCP, account login, cloud project linking, and credits generation routes. When local OpenChatCut is available, it must not fall back to the cloud.

First Use and Precheck

The first time this Skill is triggered in each new environment, first read the current project's AGENTS.md, then run the read-only precheck; when using the Feishu route, pass in the Base URL provided by the user as well, actually test the bot identity, Base permissions, and copy fields, and do not substitute "already configured" for verification:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/book-sales-video/scripts/check_environment.py" --json
python3 "${CODEX_HOME:-$HOME/.codex}/skills/book-sales-video/scripts/check_environment.py" \
  --json --base-url "<用户提供的飞书 Base URL>" \
  --lark-profile "<profile>" --script-field "<文案字段名>"
python3 "${CODEX_HOME:-$HOME/.codex}/skills/book-sales-video/scripts/openchatcut_mcp.py" status

Read from the precheck output checks、gates and actions. When dependencies, environment variables, apps, Skills, Feishu scopes, or resource collaborator permissions are missing, first explain in Chinese "what is missing, which stage it affects, how to install or authorize, and how to re-verify after installation," and provide the exact commands or official addresses given by the precheck; when account login, App Secret, or API Key is involved, guide the user to enter it securely on the local machine, and do not ask them to paste it into the conversation. Only install the items actually needed by the user's current route, and after installation or authorization is complete, rerun the same precheck. Before the corresponding gate passes, do not enter that stage, and do not pretend it has already been completed.

If the task uses Feishu copy input, also confirm larkBase.status is ready. App Secret may only be written into the local secure configuration via lark-cli config init --app-secret-stdin ; it must not appear in the conversation, command parameters, working directory, or logs.

Missing Item Installation and Authorization Guide

When the precheck finds missing items, only guide installation of the capabilities needed by the current route, and re-verify after completion:

Python dependencies:python3 -m pip install requests
FFmpeg: on macOS use brew install ffmpeg; on other systems use the corresponding package manager, and confirm that ffmpeg、ffprobe is executable.
Feishu official CLI:npx @larksuite/cli@latest install; then run lark-cli config init --new, and configure the enterprise self-built app through local interaction.
Feishu Base permissions: the enterprise app must have at least base:field:read、base:record:read、base:table:read、base:view:readenabled, and add the bot as a collaborator on the target multidimensional table.
WeRead capability:npx skills add Tencent/WeChatReading -g, then securely configure according to that Skill's instructions WEREAD_API_KEY。
Pexels: apply from https://www.pexels.com/api/ for an API Key to be used only on the local machine.
Doubao TTS: obtain the API Key, resource ID, and speaker from the Volcano Engine console, and save them to a secure environment or system keychain.
OpenChatCut: install the desktop version from https://github.com/0xsline/OpenChatCut/releases ; on macOS place it in /Applications. After first launch, open the target project, then re-verify the local MCP tools.

When web approval, account login, or key entry is involved, provide the minimum permissions and operation entry point, then wait for the user to complete it; do not expose credentials on the user's behalf, and do not ask them to send the Secret or API Key into the conversation.

The OpenChatCut status command will start when needed /Applications/OpenChatCut.app, automatically discover the random localhost port, and verify /api/external-mcp/mcp. Do not hard-code a particular port into the Skill or task state.

Project Connection Check After Restart: When OpenChatCut restarts, it stays by default on the "My Projects" list. This state exposes only project management tools,read_timeline、edit_item、edit_track and other full editing tools will not be registered, and may falsely report "project not connected." For an existing project, you must first check the projectId and project name saved in the task state, then have the user or Computer Use explicitly open that project; afterward, rerun list-tools and the read-only read_project, and confirm that the returned projectId、timelineId Only allowed to write when fully consistent with the task state. Stop immediately when the connection fails, the click position is uncertain, or the current project ID is inconsistent; do not click "New Project", do not call create_project, and do not create a replacement project.

Handle missing items by stage:

Stage	Required	Handling when missing
Feishu copy	`lark-cli`, an available default or named profile, the bot as a table collaborator, Base read-only permission	Stop reading and report the missing scope or resource permission; do not switch to browser copying and do not guess the copy
Research	`weread-skills`、`WEREAD_API_KEY`	Stop factual research; do not substitute unknown web pages
Voiceover	`requests`, Doubao key, resource ID, voice	Stop the voiceover; do not fall back to the editor voice
Opening	`PEXELS_API_KEY`	The copy may continue, but must not pretend that a video has been obtained
Illustrations	Codex `image_gen`	Save the storyboard and prompts, and clearly state the gaps
Local first draft	OpenChatCut Desktop, required local MCP tools, importable materials	Fix the local application or import first, then assemble; do not fall back to the cloud

Keys are read only from a secure environment or keychain, and are not written into the working directory or logs. The Doubao variables are DOUBAO_API_KEY、DOUBAO_TTS_RESOURCE_ID、DOUBAO_TTS_SPEAKER; Pexels is PEXELS_API_KEY; WeChat Reading is WEREAD_API_KEY。

Working directory

Use project AGENTS.md 's work/ convention; a single task directory contains at least:

research.md              script.md
storyboard.json          shot-plan.json
visual-style.json        voice-timeline.json
timeline-plan.json       subtitle-pairs.json
asset-manifest.json      quality_check.json
review_report.md         visuals/
audio/

The state file saves only the currently valid state and shares the same stateRevision、projectId、timelineId and timeline fps.

Feishu Bitable copy input

When the user provides a Feishu Base link, a record link, or explicitly requests "read Feishu copy for production", first read the copy, then proceed to book fact-checking and storyboarding. The public version does not include any user table address, app ID, field ID, or record ID; on first use, the user provides the Base URL, profile name, and copy field name:

Base URL: <用户提供>
profile: <用户本机的默认配置或命名 profile>
文案字段: <用户提供，示例：文案仿写.输出结果>

Reading rules:

First use base +url-resolve to parse the link; do not guess the resource type from the URL string; confirm base_token、table_id and view_id。
Use the bot identity to execute base +field-list, and verify fields dynamically. Display names, colloquial aliases, and real field names may differ; the name or field ID returned by the live field list must prevail, and a certain user's field ID must not be hardcoded into the Skill.
By default, project only 视频标题、书名、作者 and the user-specified copy field, and limit to the view specified by the link; if a field does not exist, first have the user confirm the mapping, and do not read unrelated fields or attachments.
The record selection priority is fixed as: the record ID/record link provided by the user → 视频标题 exact match → 书名 exact match. Before matching, only removal of book-title marks and leading/trailing whitespace is allowed; do not do fuzzy containment matching.
If exact matching still yields multiple records, list each record's 视频标题、书名、作者 and record ID, and let the user choose; it is forbidden to default to the first record, the longest copy, or the latest copy.
Stop when the target field is empty; do not arbitrarily fall back to other fields or other records. After a successful read, write the original text into script.md, and in research.md record the redacted data source description, table/view/record ID, field name, and read time; do not record the full private URL, app secret, or access token.

Phase 1: Confirm the book and research

Load weread-skills, search for and locate the book; for the Feishu input route, prioritize using the 书名of the selected record, and only ask the user to choose when duplicate names or version ambiguity would affect the content.
Obtain the book title, author, introduction, category, rating, cover, table of contents, and bookId, and write facts and interpretations separately into research.md。
Collect recommended, latest, and all reviews separately, targeting 20–40 valid samples; deduplicate and filter out pure emoji, irrelevant, or extremely short reviews, and if the quantity is insufficient, use all available ones.
Extract pain points, specific situations, counterintuitive insights, emotional tension, controversies, and changes after reading.
Form 2–3 candidate angles and score them on five criteria: audience relatability, relevance to the book, evidence coverage, visualization potential, and natural purchase transition. Choose the best overall angle and record the reason, without asking the user first.

In the Feishu input route, steps 3–5 are only used for fact verification and visual understanding, and do not rewrite or replace the already-read copy, nor generate candidate copy angles again.

This phase reads references/copywriting-and-storyboard.md。

Phase 2: Copy, storyboard, and the single review

Strictly read references/reference-copy-style.md and references/copywriting-and-storyboard.md. If the user additionally provides a personal style profile or a prohibited expressions list, read those too; if they are explicitly provided but unreadable, stop creating and report the exact path, and if the user did not provide them, this is not a blocker.

Default structure:

Fixed opening: "Today I'm sharing".
A fast cover carousel with no spoken main text.
At the end, reveal on the beat and announce the "Book Title".
Enter the main text from the specific situation the audience is experiencing, and give verifiable insights, scenarios, or methods from the book.
Return to the audience's situation, explain who it suits and what it can help them see, and avoid hard promotion and abstract elevation.

The above default structure only constrains newly created copy. The Feishu input route directly uses the full text of the selected record: preserve paragraphs, word order, and wording, and only generate semantic storyboards, bilingual subtitle drafts, and the estimated number of visuals based on that full text. If the book title or author in the copy conflicts with the WeRead verification result, stop and clearly point out the discrepancy, and do not silently correct the original text.

Complete script.md、storyboard.json and draft status subtitle-pairs.json. Split the storyboard by semantic, action, scene, or emotional changes, not by averaging shots according to periods. Give the main angle, scoring summary, complete spoken script, storyboard summary, estimated number of images, and subsequent automatic generation scope to the user for review all at once.

After the user confirms, this authorizes the complete local production of that video. If the user is dissatisfied, show the candidate angles and rewrite according to their choice; after the rewrite is complete, proceed directly to production without adding another confirmation gate.

Phase 3: Generate the complete voiceover in one pass

For a new task with no project in the status, only then call once via the local bridge create_project, explicitly specify 1080×1920, 30fps, and save the real project and timeline ID; when continuing an existing task, you must reconnect to the same saved project, and calling create_projectis prohibited. It is also prohibited to reuse a project already confirmed as failed, and to create a replacement project again in later phases.

Save the confirmed draft as audio/narration.txt, and run only once:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/book-sales-video/scripts/doubao_tts.py" \
  --text-file audio/narration.txt --output audio/narration.wav \
  --report audio/narration.wav.json

Use ffmpeg/ffprobe and audition evidence to check the beginning and end, the boundaries of the first and second sentences, the longest pause between sentences, paragraph boundaries, and the ending. If there is an anomaly, first trim or rerun this complete voiceover; if it fails, do not generate images or assemble.
Import the single WAV into A1 through an OpenChatCut local upload session. Do not call the editor TTS, and do not split it again into multiple narration assets.
Prefer to read the sentence-segment time ledger generated in the same doubao_tts.py , derive semantic audioAssetId from the same voiceUnitId, and generate voice-timeline.json. This ledger records the true PCM duration of each trimmed segment and the concatenated silence as verifiable alignment evidence; it does not depend on OpenChatCut transcription. Only when the ledger is missing should you attempt authorized ASR; you must not fabricate word timings.

Specific MCP calls, imports, and track structure reading references/openchatcut-build.md。

Phase 4: Generate all visuals according to the voiceover

Opening and cover

Run scripts/search_pexels_videos.py --page 1 --per-page 20, fixed book, vertical screen, medium size; actually view the candidates before choosing, and record the Pexels page, creator, file, and attribution.
Display "今天分享的是 / Today, I'd like to share" in the center of the opening, and do not repeat this sentence as a subtitle at the bottom.
Exclude the current main book from the carousel cover, and deduplicate by content fingerprint. First read the true peak of the mechanical sound effect, then decide the number of covers and cut points; do not preset 6.
Use the real WeRead cover for the current book cover, as an ordinary image item placed on V2 (directly above the V1 reveal background); use AI images only for the V1 reveal background, and do not let the model redraw the book title. It is forbidden to create a full-canvas Motion Graphic for a single main book cover: it introduces secondary scaling of the local canvas and timeline, causing the cover to be too small, offset, or not intuitively selectable on the timeline.
When the main book cover pops up, V3 simultaneously shows 《书名》 and 作者 / 著; it lasts from the start of the reveal to the end of the video, and when the body image changes, the text content, position, and style remain unchanged. If the spoken narration in the reveal segment only repeats the book title and author, the top persistent title can replace the repeated bottom subtitle to avoid two sets of identical information appearing on the same screen.

Body images

Read references/body-visual-style.md and references/shot-planning.md, first fully generate shot-plan.json。
Each image defines narrative function, subject action, shot size, perspective, composition, top and bottom rough-paper ratio, unified subtitle frame, and visual contrast with the previous image. Adjacent images must not have the same shot size or perspective; for six or more images, use at least four shot sizes and four perspectives.
Run scripts/validate_shot_plan.py shot-plan.json; only after passing may you call image_gen。
Each image generation uses the approved main anchor, clearly making the scene at least 70%, filling the left and right edges, leaving rough paper only at the top and bottom, and having no subtitles/book title/logo/watermark in the image.
Check all thumbnails side by side; regenerate only images that deviate from the shot plan or style.

Phase 5: Local OpenChatCut automatic assembly

Before execution, read references/openchatcut-build.md、references/editing-effects-and-rhythm.md and references/bilingual-subtitles.md。

All MCP calls pass through scripts/openchatcut_mcp.py, dynamically discovering the local port each time; tool parameters are subject to the current list-tools schema.
Track roles: V1 opening/carousel/reveal background/body; V2 only this one ordinary image item for the real main book cover; V3 editable text overlay layers such as book title, author, and subtitles; A1 complete voiceover; A2 BGM; A3 mechanical carousel sound effect; A4 reveal sound effect.
The main book cover is first shown with type:"image" Place into V2, then use instance keyframes for positioning; do not replace with a flat precomposition or full-canvas MG. The final image must be accepted starting at approximately 52%–60% of the frame width for the cover, horizontally centered, with a normal blank space below the book title and margins on both left and right, rather than trusting only CSS or the asset's natural size. Using the currently verified vertical cover as the baseline:x=0、y≈8、scale≈0.56, but each book must be fine-tuned based on the actual rendered image.
The main book cover uses only one simple entrance: within about 0.23 seconds opacity 0→1、scale 0.42→0.60→最终值、y 16→最终值, then remains still; continuous breathing, horizontal movement, rotation, or additional complex motion effects are prohibited. The accent of the cash register success sound lands at the start of this entrance.
Hard cuts within the carousel; use about a 0.10-second light dissolve from the last image to the reveal; use about a 0.20-second cross dissolve from the reveal to the body and between adjacent body images.
Add exactly one subtle breathing/push-in motion effect to each body image. By default, use a single breathing motion with no displacement and about 10% slower than usual:x=0、y=0 fixed,scale from 1.02(starting point) slowly to 1.085(at 55% of the clip), then softly fall back to 1.035(at the end of the clip). Do not repeat a second breath in the same image, and do not suddenly scale down just to return to zero at the end of the clip. Prefer using locally verified builtin:zoom slow push-in or equivalent keyframes; you must check that the subject and subtitle safe area are not cropped badly after enlargement.
The mechanical carousel sound effect uses library:sound:mechanical-clicking-loop as one continuous asset; the reveal sound effect uses library:sound:cash-register-success once. Do not regenerate replacement sound effects.
BGM starts from frame 0; prefer OpenChatCut local/traceable music; vocals take priority, BGM volume is lowered or ducked. When no suitable music is available, generate one track only if the sole review has disclosed and authorized it, and do not create batch variants.
Chinese and English correspond semantically card by card, with consistent timing. Subtitles must first determine sentence and clause boundaries according to punctuation such as periods, question marks, exclamation marks, semicolons, and commas, and then be subdivided by complete semantic groups; do not first split into fixed character counts, and do not cram the opening word of the next clause into the previous card. The maximum of 11 valid Chinese characters per card is only a length limit after splitting and cannot override semantic boundaries. Default Chinese 76px/800, English 42px/600, both white fill with black stroke. When native subtitles cannot be implemented precisely, use an editable bilingual Motion Graphic for the entire segment, and do not leave two visible subtitle sets.
For complex batch edits, first validateOnly, then commit atomically; if a request times out, first read back the project to determine whether it was already written, and do not blindly repeat.

Phase Six: Quality Check and Delivery

Structure first, then image, then sound.quality_check.json At minimum include and pass:

bookFacts、voiceContinuity、timelineStructure、carouselRhythm、bookReveal、bodyMotion、transitions、subtitles、bgmMix、visualStyle、frameReview。

Must verify item by item:

Opening, carousel, reveal, and body are continuous, with no black frames, empty tracks, incorrect overlaps, or truncation.
Mechanical sound effects have one peak per image; the final beat accurately enters the main book, and the cash register success sound is synchronized with the book cover pop-out and appears only once.
Each body image has exactly one breathing/push-in motion effect; all specified boundaries have correct transitions.
Voiceover pauses meet the threshold, and the image, subtitles, transitions, BGM, and sound effects have been rearranged according to the same trimmed timeline.
Chinese and English white text with black stroke, semantically consistent, a single visible set, no overflow, no occlusion, and no crossing beyond its belonging voiceUnitId。
Read back the subtitle cards sentence by sentence, and confirm that each new sense group after every period, question mark, exclamation mark, semicolon, and comma starts on a new card; spot checks must not show fixed-character hard cuts, the previous card carrying the beginning of the next clause, or the reveal segment repeatedly displaying the book title and author.
From the stable frame of the main book cover to the last frame, the V3 book title and author must remain continuously visible with unchanged content, position, and style; separately check the reveal stable frame, the first body frame, the middle section, and the last frame.
BGM starts from frame 0 and does not cover the voiceover.
The body image reaches more than 70% of the frame, is full width on the left and right, with thick paper only at the top and bottom; the actual shot matches shot-plan.json。
Use OpenChatCut read_project/read_timeline to read back the structure, and check the opening, the carousel midpoint, the entrance/middle/stable three frames of the main book reveal, every body boundary, and the last frame. Acceptance of the main book cover also requires: V2 has one visible segment of kind:"image" , the segment can be directly selected on the timeline, and in the rendered frame the cover is centered, not cropped at the edges, and does not cover the book title and author.

Any structural modification will make the old check become stale. After fixing, you must re-read the project, spot-check the frames, and listen to the audio. Run:

python3 scripts/validate_subtitle_cards.py subtitle-pairs.json --voice-timeline voice-timeline.json --strict
python3 scripts/validate_delivery_state.py .

After all checks pass, deliver: the editable project in local OpenChatCut, the copy, the subtitle comparison, the storyboard, the status file, and review_report.md. By default, stop at the editable draft for the user to check; only after the user explicitly requests or confirms the final version, call the local export, and verify the export history and the actual file.

Failure handling

OpenChatCut is not installed: report that /Applications/OpenChatCut.app is missing and stop local assembly.
The application is not running: the bridge script automatically starts and waits for a limited time; if it is still unreachable, report the local process and port discovery results.
MCP tool missing or schema changed: first list-tools, adjust the call according to the current schema; do not fall back to the old cloud interface.
Local asset upload failed: read the upload session and asset list to determine whether it has already been imported; do not upload repeatedly before confirming.
If Doubao, Pexels, WeChat Reading, or image generation fails: keep the completed status and the exact gap, and do not substitute fictional assets.
If any one of the sound effects, motion effects, transitions, bilingual subtitle style, BGM, or keyframe checks is missing, the status must be blocked-not-deliverable, and it must not be called a "reviewable draft".

Resource routing

Reference rhythm:references/reference-style.md
Voiceover language:references/reference-copy-style.md
Research, angle, copy, and storyboard:references/copywriting-and-storyboard.md
Body visuals:references/body-visual-style.md
Shot planning:references/shot-planning.md
Bilingual subtitles:references/bilingual-subtitles.md
Motion effects and rhythm:references/editing-effects-and-rhythm.md
Local project, import, timeline, and export:references/openchatcut-build.md
Local MCP:scripts/openchatcut_mcp.py
Environment check:scripts/check_environment.py
Full voiceover:scripts/doubao_tts.py
Pexels search:scripts/search_pexels_videos.py
Validation:scripts/validate_shot_plan.py、scripts/validate_subtitle_cards.py、scripts/validate_delivery_state.py