Content
# Director's Desk
**A local AI short film "Director's Desk / Ledger" - managing creative structure and file handling, outsourcing GPU-intensive generation to your existing web-based video generation platforms (e.g., Seedance, Kling, etc.).**
<!--
📸 Screenshot placeholder
Place a clean interface screenshot here: docs/screenshot.png
· Before taking the screenshot, clear/change the "Watch download folder" and "Platform URL" fields to avoid capturing real paths/URLs
· Use a demo project or neutral content
Once placed, the image will be displayed automatically. Recommended width: ~1400px.
-->
---
## Two Core Principles (Design Foundation)
1. **Never generate content.** No video generation or LLM API integration; generation is always handled by web platforms.
2. **Never automate browsers.** Only use `shell.openExternal` to open the **system default browser** (preserving login state and proxy chain); do not perform clicks, fill out forms, or scrape web pages; the App only interacts with **files already downloaded to your system**.
All features are extensions of these two principles.
---
## Core Features
- **Infinite Canvas · Hierarchical Timeline** — `Scene → Shot`, based on [tldraw](https://tldraw.dev). Scenes and shots are **freely positioned** (drag to any location); scene order is automatically derived from vertical position, and shot order from horizontal position.
- **Structured Shot Cards** — each shot includes 8 elements (duration, shot type, composition, camera angle, camera movement, content, sound effects, dialogue), video generation **prompts**, `@` asset references, and generated video variations.
- **State Machine + Expiration Detection** — each shot automatically derives its state (`empty → pending → filmed → finalized`). If the prompt is changed but the generated video is older than the change, the shot is marked **⚠️ expired**.
- **Main Workflow: Idle → Capture** — click **Generate** on a shot: copy the prompt to the clipboard, mark the shot as "pending" (**no automatic actions**). You then paste the prompt into the platform, generate and download the video; the file watcher ([chokidar](https://github.com/paulmillr/chokidar)) captures the new video and automatically attaches it to the pending shot as a variation. Audio files go into the **Sound Rack**; videos captured without a pending shot go into the **Inbox**.
- **Non-Destructive** — captured files are **copied** into the project's `media/` folder; original files in the download folder are never moved or deleted; undo only removes the variation and the copied file.
- **Sequential Preview** — play back finalized variations of shots in order of scene and shot hierarchy. (Actual stitching/export is a future feature.)
- **Full-Screen Canvas** — a toggle button (or `⌘\`) collapses the side panels to make the canvas full-screen; state is preserved when reopening.
- **A Second Face for AI** — a local MCP server allows AI clients to read and write the same project data, with every write requiring a **preview + confirmation** step (see below).
---
## Architecture — One Core, Two Faces
Separate the **core** (data, rules, and file routing decisions) from the interface. The GUI is the first consumer of the core; the MCP server is the second — both reuse the same core, with no duplicated business logic.
```
src/core/ Pure logic (TypeScript, independent of Electron/DOM):
Data models, state machine, expiration calculation, watcher routing decisions
src/services/ Shared orchestration for both faces (file ingestion, MCP tool implementation):
Pure functions + injected side effects, independent of Electron/fs/React
src/main/ Electron main process: chokidar watcher, file copying, clipboard,
shell.openExternal, MCP socket bridge
src/renderer/ First face — React interface: tldraw canvas, shot cards, side panels, proposal cards
src/mcp/ Second face — local stdio MCP server (thin adapter to the core)
src/shared/ Shared types
```
- **First Face · GUI**: Electron/React application.
- **Second Face · MCP**: a stdio server that forwards tool calls via local Unix socket to the **running App** — data is authoritative in the App, and write operations never bypass your on-screen confirmation.
Project data is stored **outside the repository**, in `~/DirectorDesk/<project name>/`, as `project.json` and a `media/` folder (small enough to be archived with Git).
---
## Installation / Running
**Platform:** macOS. (MCP bridge uses a Unix socket in `~/Library/Application Support/`, and the build target is macOS `.app`.)
**Dependencies:** Node.js 18+ and npm.
```bash
git clone <repository URL> ~/director-desk
cd ~/director-desk
npm install
# Development (hot reloading)
npm run dev
# Run tests (pure core/services/canvas layout)
npm test
# Build into a double-clickable macOS app, output in release/mac-arm64/
npm run dist
```
After building, drag the app in `release/mac-arm64/` into the "Applications" folder for double-click use. Build details (icon, app name locking, etc.) see [docs/BUILD.md](docs/BUILD.md).
Projects are created and saved in `~/DirectorDesk/`; the App automatically reopens the last project on launch.
---
## MCP — Let AI Clients Drive Director's Desk
A local **stdio** MCP server exposes **16 tools** (6 read, 10 write). Read tools can be called freely; **each write tool pops up a proposal card in the App, requiring your confirmation** before writing — decline with ✗ to leave unchanged. Before each confirmation, a snapshot of `project.json` is saved for one-click rollback.
Tools cover: listing/reading shots and scenes, finding expired shots, asset lookup, inbox management; and (requiring confirmation) creating scenes/shots, changing prompts/elements, binding assets, moving shots, organizing media, selecting final versions, and filling thought board text boxes.
By design, the MCP server **does not** expose generation, browser automation, file capture, or destructive file operations — these are left to your hands or automated watchers.
👉 Complete tool list, registration snippets, and transmission design: **[docs/MCP.md](docs/MCP.md)**.
---
## Tech Stack
Electron 31 · React 18 · TypeScript · [tldraw](https://tldraw.dev) 5 (canvas) · [chokidar](https://github.com/paulmillr/chokidar) (watcher) · [zustand](https://github.com/pmndrs/zustand) (interface state) · [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) · electron-builder (packaging).
## Status
Early/personal tooling stage (`v0.1`). Main workflow (canvas + idle + file capture + persistence) and MCP second face are functional. TODO: complete thought board, complete asset system, final video stitching/export.
## Licensing and Dependencies
- **This project is MIT-licensed** (MIT © yyhuiru091005-cmyk, see [LICENSE](LICENSE)). However, this license **only covers the project's own code**, not the terms of third-party dependencies like tldraw.
- **Canvas functionality is based on the open-source library [tldraw](https://tldraw.dev)**, which uses tldraw's own licensing (not MIT). This project currently uses the **free tier** (free version displays a "Get a license for production" watermark on the canvas).
- **This project is for personal use and learning only.** For **commercial use**, please purchase the corresponding license from [tldraw's official website](https://tldraw.dev); users are responsible for adhering to the licensing terms of tldraw and other third-party dependencies.
