codex-storyboard

# Codex Storyboard A local video storyboard for Codex workflows. You can maintain dialogue, shot descriptions, A-ROLL/B-ROLL, media types, and durations in the web interface, and then have Codex invoke Image Generation, HyperFrames, or Remotion to generate assets and automatically fill them in. ## Product Showcase ### Project Management  ### Storyboard Workspace  ## Features - Multi-project management: create, rename, open, and delete projects - Codex can create complete projects and all storyboards through MCP without browser control - MCP supports project search, read, modify, and delete - Supports `9:16`, `16:9`, `3:4`, `4:3`, `1:1` - Storyboard table: dialogue, shot descriptions, duration, media type, and generation method - Local image and video upload - Image/video Lightbox zoom preview - Single shot generation and batch generation queue - Codex MCP automatically claims tasks and fills in assets - Image Generation, HyperFrames, Remotion routing - Project-level `DESIGN.md` visual specification, optional import, view, replace, and remove - Image and video generation tasks automatically apply project visual specification - All projects and assets are saved locally by default ## Quick Start Requires Node.js 18 or higher. ```bash git clone https://github.com/Yuuhann1999/codex-storyboard.git cd codex-storyboard npm start ``` Open: ```text http://127.0.0.1:43218 ``` The first startup will automatically create a local data directory: ```text data/ projects.json projects/ <project-id>/ project.json DESIGN.md media/ ``` `DESIGN.md` is an optional file, and projects without imported visual specifications will not create it. ## Install Codex Plugin The repository comes with the `codex-storyboard` plugin and Marketplace configuration. ```bash codex plugin marketplace add Yuuhann1999/codex-storyboard codex plugin add codex-storyboard@codex-storyboard ``` After installation, reopen the Codex conversation and enter: ```text Create a 9:16 "Codex Sidebar 5 Usages" storyboard project and directly write to the Codex storyboard ``` Or process asset generation queues: ```text Process all asset generation queues in the Codex storyboard ``` You can also reference the plugin in Codex: ```text @codex-storyboard process all pending assets ``` The plugin will: 1. Generate a complete storyboard based on video requirements and write it to a new project through a single MCP call. 2. Search, read, modify, or delete existing projects without browser or computer use. 3. Read pending tasks from the local storyboard. 4. If the project is configured with `DESIGN.md`, read it completely and use it as a unified visual style specification. 5. Choose Image Generation, HyperFrames, or Remotion based on the `generator`. 6. Generate assets using the project's aspect ratio and output dimensions. 7. Fill in the final images or videos into the correct project and shot. > The availability of Image Generation, HyperFrames, and Remotion depends on the capabilities and plugins enabled in the current Codex environment. ## Manual Local Plugin Installation If you're modifying the plugin source code, you can register the current repository as a local Marketplace: ```bash codex plugin marketplace add . codex plugin add codex-storyboard@codex-storyboard ``` The plugin source code is located in: ```text plugins/codex-storyboard/ ├── .codex-plugin/plugin.json ├── .mcp.json ├── mcp/server.mjs ├── scripts/start-mcp.sh └── skills/ ├── manage-storyboard-projects/SKILL.md └── process-storyboard-tasks/SKILL.md ``` ## Codex Directly Create Storyboard Project The plugin calls the storyboard local API through MCP, does not directly write to `data/`, and does not use browser automation. Supports: - List projects and search by title - Read single projects and complete shots - Create projects, all shots, and optional DESIGN.md in one go - Modify project names, aspect ratios, and specified shots - Append or delete shots - Replace or remove DESIGN.md - Permanently delete projects and local assets The creation tool only returns project summaries, and complete scripts are not repeated in the tool results to reduce token consumption. ## Aspect Ratio Project aspect ratios affect: - Web asset preview box - Image Generation target ratio - HyperFrames canvas dimensions - Remotion canvas dimensions - `aspectRatio`, `width`, and `height` in MCP generation tasks ## DESIGN.md Visual Specification You can choose to import a Markdown file as the project visual specification when creating a new project, or import, view, replace, or remove it through the "Visual Specification" menu in the top right corner after entering the project. After importing, the file is uniformly saved as: ```text data/projects/<project-id>/DESIGN.md ``` Generation tasks will carry the absolute path of the file. The plugin will read it completely before generating images or videos: - The storyboard's "shot descriptions / generation prompts" determine the specific content of the current shot - `DESIGN.md` uniformly constrains visual style, color, composition, font, texture, and motion language - If the current shot's explicit requirements conflict with the general specification, the current shot's requirements take precedence - HyperFrames and Remotion projects and intermediate files are saved in the project's corresponding `generation/` directory ## Local Assets "Manual asset" shots support: - Click on the empty asset box to upload - Use the "Local Upload" button to upload - Click on existing assets to zoom in and view - Re-upload and replace in Lightbox Supports: - Images: PNG, JPEG, WebP, GIF - Videos: MP4, WebM, MOV - Single file maximum 100MB ## Project Structure ```text . ├── .agents/plugins/marketplace.json ├── plugins/codex-storyboard/ ├── public/ ├── docs/assets/ ├── server.mjs ├── package.json └── README.md ``` The web interface uses native HTML, CSS, and JavaScript, and the local service uses Node.js standard library without runtime npm dependencies. ## API Main interfaces: ```text GET /api/projects POST /api/projects GET /api/projects/:projectId PATCH /api/projects/:projectId DELETE /api/projects/:projectId GET /api/projects/:projectId/design POST /api/projects/:projectId/design DELETE /api/projects/:projectId/design POST /api/projects/:projectId/shots PATCH /api/projects/:projectId/shots/:shotId DELETE /api/projects/:projectId/shots/:shotId POST /api/projects/:projectId/shots/:shotId/media GET /api/generation/tasks POST /api/generation/tasks POST /api/generation/tasks/:taskId/claim POST /api/generation/tasks/:taskId/complete POST /api/generation/tasks/:taskId/fail ``` ## Development Check ```bash npm run check ``` Verify plugin: ```bash python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \ plugins/codex-storyboard ``` ## Privacy - Project scripts and assets are saved locally in `data/` by default. - The repository does not automatically upload project data. - When using third-party generation capabilities, prompts and input assets may be subject to the privacy terms of the corresponding service. ## License [MIT](LICENSE)