English | 中文
Local-first AI filmmaking workstation — wire text, image, and video AI into one node canvas, on your own machine.
InkFrame is a desktop workstation for AI-driven filmmaking. A node-based canvas lets you chain prompt → image → video through real providers — DashScope (Wanx), Kling, Gemini, and more (9 built-in) — while every project file and API key stays on your disk. No cloud account, no upload, no SaaS lock-in.
- 🔒 Local-first by design — projects live in an embedded PostgreSQL on your machine; keys go to the OS Keychain / Credential Manager, never a plaintext
.env. - 🕸️ Node canvas — compose shots visually: drop text / image / video nodes, wire them, and watch generation flow through the graph with live job progress.
- 🔌 Multi-provider — mix and match image/video models from different vendors in one project. Adding a new one is a single file (see
docs/PROVIDER-API.md). - 🖥️ One codebase, two desktops — macOS + Windows from a single Dart/Flutter source, frameless neutral-gray desktop UI with a single amber accent.
- 🧪 Quota-safe dev — built-in fake providers run the whole app and exercise the canvas without burning a single API credit.
flowchart LR
A["📝 Text / Prompt node"] --> B["🖼️ Image node<br/>(Wanx · Gemini)"]
B --> C["🎞️ Video node<br/>(Kling · Wanx i2v)"]
C --> D["📦 Storyboard / Export"]
subgraph Local["🔒 Your machine"]
DB[("Embedded<br/>PostgreSQL")]
KEY["🔑 OS Keychain"]
end
B -.persist.-> DB
C -.persist.-> DB
B -.auth.-> KEY
C -.auth.-> KEY
Build a shot graph on the canvas, hit generate, and InkFrame runs the jobs through your configured providers — caching results and project state locally as it goes.
| Provider | Type | Status |
|---|---|---|
| Wanx (DashScope) | image · i2v · r2v · t2v | ✅ Implemented |
| Kling V3 / V3 Omni | video | ✅ Implemented |
| Gemini Image | image | ✅ Implemented |
OpenAI GPT-Image (gpt-image-2) |
image | ✅ Implemented |
| Stability Stable Image Core | image | ✅ Implemented |
OpenAI-compatible custom endpoint (custom_providers.json) |
image | ✅ Implemented |
| Stable Diffusion (local ComfyUI) | image | 🟢 Help wanted |
| OpenAI DALL·E 3 (dedicated integration) | image | 🟢 Help wanted |
| Runway Gen-3 / Gen-4 | video | 🟢 Help wanted |
| Midjourney · Pika · Luma | image/video | 🟢 Help wanted |
Want to add one? It's the lowest-effort way to contribute — see docs/PROVIDER-API.md and the Help Wanted list.
Requirements: Flutter ≥ 3.41, Dart ≥ 3.11, PostgreSQL 17 binaries on disk. macOS also needs Xcode 16 + CocoaPods.
git clone https://github.com/KerroKapple/InkFrame.git
cd InkFrame
flutter pub get
# Run with fake providers — no API keys, no quota burn
INKFRAME_PG_BIN=/opt/homebrew/opt/postgresql@17/bin \
INKFRAME_FAKE_PROVIDERS=1 \
flutter run -d macosFor real generation, drop INKFRAME_FAKE_PROVIDERS and add keys in Settings → Providers. Keys go to Keychain / Credential Manager.
flutter analyze # 0 warnings (CI uses --fatal-infos)
flutter test # full suite
flutter test --tags pg # real-PG integration tests (need TEST_PG_URL; auto-skipped otherwise)Environment variables, key storage, and data-directory layout: see docs/ARCHITECTURE.md.
Flutter (desktop) · Riverpod (state + DI) · Freezed (immutable models) · embedded PostgreSQL via postgres · dio (provider HTTP) · flutter_secure_storage (keys) · media_kit (video playback + frame extraction) · window_manager (frameless chrome).
Alpha (v0.1.0-alpha.9). Single Dart codebase shipping on macOS + Windows. M1 ("usable") and
M2 ("what creators need" — character consistency, batch variants, prompt presets, cost estimation)
are complete with CI fully green; M3 first slices are in progress across four tracks (shot
storyboarding, custom providers, asset gallery, video export). Remaining beta gaps are tracked in
docs/BOARD.md. See ROADMAP.md for what's shipped and what's next.
InkFrame/
├── lib/ # App source (Dart)
│ ├── core/ # Shared abstractions: interfaces, models, errors, DI wiring
│ ├── features/ # Feature slices: canvas, storyboard, export, gallery, settings, studio…
│ ├── providers/ # AI provider adapters (Gemini, OpenAI, Kling, Wanx, Stability…)
│ ├── services/ # App-level services: job queue, backup/restore, ffmpeg export, updates
│ ├── storage/ # Embedded PostgreSQL: lifecycle, repositories, forward migrations
│ ├── theme/ # Design tokens + reusable Ink* components
│ └── l10n/ # ARB strings (en / zh) + generated localizations
├── test/ # Tests mirroring lib/, plus quality/ (architecture guard tests) and _harness/
├── docs/ # Documentation
│ ├── adr/ # Architecture Decision Records
│ ├── specs/ # PRD and feature specs
│ ├── design/ # Design notes and visual references
│ ├── research/ # Market / model / release-engineering research
│ └── internal/ # Maintainer notes: audits, tech debt, regression checklists
├── scripts/ # Tooling: git hooks, PG binary fetch, release, smoke, coverage
├── assets/ # Bundled fonts, license texts, sample media
├── macos/ · windows/ # Platform runners (Flutter desktop)
└── .github/ # CI, release, smoke, secret-scan workflows
- ROADMAP.md — what's shipped, what's next
- CONTRIBUTING.md — workflow, hooks, commit rules
- docs/ARCHITECTURE.md — DI, layers, error model, degradation
- docs/PROVIDER-API.md — adding a provider
- docs/DATABASE.md — schema and migrations
- docs/TESTING.md — TDD layering and mocks
- SECURITY.md — reporting and key handling
Maintainer-welcomed directions live in ROADMAP.md — providers, canvas UX,
i18n, and test infra. Please open an issue or post in Discussions
to align scope before writing a large PR. First time? Look for the
good first issue label.
Open a GitHub issue or start a Discussion.