Endless1936/book-video: a natural-language workflow for book short videos

What problem Endless1936/book-video actually solves

Making a book short video is not one task. It is book selection, a script, atmosphere images, a recorded voiceover, subtitle timing, background music, and a render. Each step has its own tool, and the handoffs are where projects die: the script drifts from the recording, the subtitles drift from the script, and a failed render leaves you unsure which artifact is still valid.

This repository treats that chain as a single workflow with a state model. The README describes it as a natural-language workflow for creating atmospheric short book videos with AI-generated visuals, HyperFrames, GSAP animation, voiceover timing, subtitles and BGM. The intended user is not a video engineer. The README states plainly that you do not need to learn code or commands first: you open Codex and describe the book video you want in natural language.

That framing matters for evaluating it. This is closer to a production playbook with executable checks than to a library you import. The repository layout supports that reading: scripts/, templates/, docs/, data/, assets/ and episodes/ sit at the top level, with AGENTS.md and docs/book-video-playbook.md holding the detailed internal rules.

The six-step pipeline and where each artifact is written

The README lays out six steps. You tell Codex which book to use, or ask it to recommend five books suited to short videos. Codex confirms title, author and edition, then shows a voiceover script in a code block, complete enough to paste into Jianying, with the book title on the first line, and saves it as a local script file. You review the copy in the conversation. On confirmation, Codex generates atmosphere images and video frames. You export a spoken MP3 from Jianying or another tool and give Codex the file path. Codex then runs ASR to produce a time reference, treats script.csv as the source of truth for subtitles, aligns the subtitles, mixes in BGM, and renders the final MP4. If you ask for new copy, images or audio, Codex produces a new candidate and replaces the old one only after it passes checks.

The state model is the part worth reading closely. Each episode keeps episodes/<book title>/workflow-state.json, which records executable, valid, degraded, awaiting-diagnosis and stale states by artifact dependency. The README says there is no terminal failure state, and that a missing or corrupted file can be rebuilt from existing artifacts. Failures are not silent: a command keeps a non-zero exit to stop a bad artifact from taking effect, emits BOOK_VIDEO_DIAGNOSTIC, and writes tmp/last-workflow-diagnostic.json. Codex uses that to inspect inputs or dependencies, fix the minimum failed step, and retry. The previous valid cut is not replaced until the new candidate passes.

Two design choices stand out. Treating the CSV script, not the ASR output, as the subtitle source of truth is the right call, because ASR timings are a reference and not a transcript. And the absence of a terminal failure state means the state file accumulates stale and degraded entries rather than declaring an episode dead. That is convenient for resumption, but it also means the state file can describe a project that no longer matches what a human would call finished.

Installing Endless1936/book-video and running a first episode

The README does not give a package installation procedure. It gives a usage procedure: open Codex, describe the video in natural language, and let Codex check and prepare the local environment on first use, asking you to confirm anything it needs. There is no published npm package name to install, and package.json marks the project private. What the repository does expose is a set of npm scripts, so a working Node setup is the practical prerequisite.

The scripts in package.json are the verification entry points. The check script runs node scripts/check.mjs and the test script runs node scripts/run-tests.mjs:

"scripts": {
  "check": "node scripts/check.mjs",
  "test": "node scripts/run-tests.mjs",
  "workflow": "node scripts/workflow-state.mjs",
  "smoke:timings": "node scripts/tests/smoke-timing-fallback.mjs"
}

The timing smoke test is separate from the test script, which suggests voiceover alignment is the part the authors expect to break. The workflow itself is a single script with subcommands, and the README gives these three forms:

npm run workflow -- status "<书名>"
npm run workflow -- next "<书名>"
npm run workflow -- repair "<书名>"

status reports the recorded state, next reports the next step, and repair re-checks artifacts. The README names two further subcommands: approve for copy confirmation, and deliver after the finished video is embedded in the conversation. Other steps are identified automatically from artifacts and validation reports, so you do not pass a step name for those. The first real use is therefore a conversation, not a command: ask Codex for five books, pick one, review the script it shows you, and only then move on to images and audio.

The failure mode the diagnostic file is designed around

The interesting limitation is not that renders fail. It is that the workflow's recovery path depends on Codex reading a diagnostic file and choosing the smallest failing step to retry. The README describes the loop as: non-zero exit, BOOK_VIDEO_DIAGNOSTIC output, tmp/last-workflow-diagnostic.json written, Codex inspects inputs or dependencies, repairs, retries. That is a sound design, but it puts a language model in the role of a build system's error handler.

If the diagnostic is ambiguous, or if the failure is environmental rather than artifact-related, the loop has no documented escalation. The README does not describe what happens when a retry keeps failing, nor does it document a manual override that forces a candidate to be accepted. It also does not document rollback beyond the statement that the previous valid cut is not replaced until the new candidate passes. If you need to revert to an earlier accepted version after a successful replacement, the README is silent on the procedure.

The state file has a related cost. Because it records stale and degraded states and explicitly has no terminal failure, nothing in the model tells you an episode is abandoned. You have to read the state and decide. For a solo creator running a handful of episodes that is fine. For a team sharing a repository, an episode directory that is permanently degraded looks the same as one that is merely paused.

How it differs from driving a video editor directly

The obvious alternative is to do the same work by hand in Jianying, which the README already assumes you have, since it asks you to export the spoken MP3 from Jianying or another tool and hand over the path. The difference is not the editing capability. It is where the source of truth lives.

In a manual edit, the timeline is the source of truth. Subtitle timing, image placement and music are whatever the project file says, and the script is a separate document that may or may not match. Here, script.csv is declared the subtitle source of truth and ASR output is only a time reference. That inverts the usual relationship. It makes the copy authoritative and the audio a measurement against it, which is the correct model when the copy is the thing being reviewed and approved in a conversation.

The second difference is the state file. A video editor remembers your timeline; it does not remember which artifacts passed validation. episodes/<book title>/workflow-state.json does, and the repair subcommand can re-derive it from existing artifacts. If you already have a stable manual process and one person doing every step, the state model adds bookkeeping without adding much. If several steps are automated and you need to know which outputs are still trustworthy after a failure, it is the reason to use this instead.

Licence, bundled audio and upgrade cost

The README states that the project's code, documentation and reusable templates are released under Apache-2.0, with copyright held by prototech (organization) and endless (screen name). The LICENSE file is present at the top level. Note that the repository metadata reports the licence as NOASSERTION, which does not match the Apache-2.0 claim in the README, so if licence terms matter to your use, read LICENSE itself rather than either summary.

The README is unusually direct about the boundary of that licence. Apache-2.0 does not automatically cover third-party tools, fonts, models, image generation services or media assets. Four default BGM tracks sit in assets/bgm/: 城南花已开.mp3, 红色高跟鞋.mp3, 起风了.mp3 and 如愿.mp3. The README says they are included only as material for project learning and exchange, that Apache-2.0 does not apply to them, and that rights belong to the respective holders, so you must confirm you have permission before using or redistributing them. For any published video, that is the first thing to resolve, and it is a rights question rather than a code question.

Upgrade cost is hard to judge from the available information. There are no releases, the repository is not archived, and the last push was on 2026-07-25. The workflow state format is versionless in the README's description, so a future change to workflow-state.json could affect existing episode directories. Since the state can be rebuilt from artifacts, the practical exposure is lower than for a database migration, but any episode whose artifacts have been deleted cannot be reconstructed.

Who should adopt it, and what to verify first

Adopt it if you already work in Codex and want the book-video chain to be repeatable rather than reinvented per episode. The combination of a CSV subtitle source of truth, a diagnostic file at tmp/last-workflow-diagnostic.json, and a per-episode state file you can query with the status subcommand is a real answer to the problem of not knowing which artifact survived a failure. The natural-language entry point also lowers the barrier for people who would not otherwise touch a render pipeline.

Do not adopt it if you want a standalone application. There is no homepage, no published package, and the README's install story is "open Codex and let it prepare the environment." Do not adopt it if you need a documented rollback path after a successful replacement, or a manual way to force acceptance when the repair loop stalls; neither is described. And do not adopt it for a commercial release until the BGM rights question is settled, because the four bundled tracks are explicitly outside the Apache-2.0 grant.

Before the first episode, verify three things: that the check and test scripts both pass on your machine, that the status subcommand returns a readable state for an existing episode directory, and that your Codex environment can actually run the environment preparation the README promises on first use. If any of those three fails, the rest of the pipeline is untested for you regardless of what the repository contains.

Editorial conclusion

Adopt it if you already work inside Codex and want a repeatable book-video pipeline with a resumable state file and diagnostic output. Do not adopt it if you expect a standalone GUI, a hosted service, or a one-command install that pulls every dependency. Before committing, check that Node is available for the npm scripts, that your Codex environment can run the workflow, and that you have cleared rights for the four bundled BGM tracks, which are not covered by Apache-2.0.

Frequently asked questions

Official sources

1. Endless1936/book-video on GitHub
2. Issues
3. README