Skip to content
Back to search

frameweaver

Local video workspace for AI scene generation, timeline editing, speech analysis, narration, subtitles, audio mixing, and media management.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/phucnguyentvp1--frameweaver/badge.svg)](/listings/phucnguyentvp1--frameweaver)

HTML

<a href="/listings/phucnguyentvp1--frameweaver"><img src="/api/listings/phucnguyentvp1--frameweaver/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the prerequisites

The packaging checks used **Python 3.12** and **Node.js 24**. You also need Chrome, FFmpeg, and ffprobe. Install those tools before proceeding.

The commands below assume macOS or a Linux shell. Windows users can adapt them with WSL; a full Windows setup has not been verified for this preview.

2. Clone and install the backend

git clone https://github.com/phucnguyentvp1/frameweaver.git
cd frameweaver
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

Create a project in the Google Flow interface. Copy its UUID from the project URL and set `FLOW_PROJECT_ID` in `.env`. Use your own credentials for any optional providers you enable.

set -a
source .env
set +a
python -m agent.main

The backend reads shell environment variables; it does **not** load `.env` automatically. Leave this terminal running.

3. Load the extension

Open Chrome's extension manager, enable Developer mode, choose **Load unpacked**, and select this repository's `extension/` directory. Open [Google Flow](https://flow.google.com/), sign in, and leave the tab open.

For a standalone extension download, extract the ZIP first and select the folder containing `manifest.json`. Keep one bridge enabled for the same backend. An extension loaded from another copy of the project will keep using that copy's files. See the [extension installation guide](extension/README.md).

4. Start the dashboard

In a second terminal:

cd frameweaver/dashboard
npm ci
npm run dev

Open **http://127.0.0.1:5173**. The backend uses port **8100** and the extension WebSocket bridge uses **9222**. Keep these services bound to localhost for a normal desktop installation.

5. Check the connection

curl -s http://127.0.0.1:8100/health
curl -s http://127.0.0.1:8100/api/flow/status

Before generation, the health response must show `extension_connected: true`. The Flow status should identify the `batch` transport and your project UUID. `flow_key_present: false` is expected for the current browser transport.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 358 lines
  1. <p align="center">
  2. <img src="docs/images/frameweaver_banner.svg" width="880" alt="FrameWeaver — weave scenes, voices, and sound" />
  3. </p>
  4. <p align="center">
  5. <a href="LICENSE"><img src="https://img.shields.io/badge/code-MIT-2563eb" alt="Code: MIT" /></a>
  6. <img src="https://img.shields.io/badge/status-preview-f59e0b" alt="Preview release" />
  7. <img src="https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white" alt="Python 3.12" />
  8. <img src="https://img.shields.io/badge/Node.js-24-339933?logo=nodedotjs&logoColor=white" alt="Node.js 24" />
  9. <img src="https://img.shields.io/badge/Chrome-MV3-4285F4?logo=googlechrome&logoColor=white" alt="Chrome Manifest V3" />
  10. </p>
  11. <p align="center">
  12. <a href="README.vi.md">Tiếng Việt</a> ·
  13. <a href="#quick-start">Quick start</a> ·
  14. <a href="#documentation">Documentation</a> ·
  15. <a href="https://github.com/phucnguyentvp1/frameweaver/releases">Downloads</a> ·
  16. <a href="https://github.com/phucnguyentvp1/frameweaver/issues">Report an issue</a>
  17. </p>
  18. # FrameWeaver
  19. **A local video workspace for scenes, narration, audio, and timeline editing.**
  20. FrameWeaver brings a React dashboard, Python backend, and Chrome extension into
  21. one workflow. Plan scenes, reuse character references, generate through your own
  22. Google Flow session, prepare narration, and assemble clips with FFmpeg.
  23. Developed and maintained by [phucnguyentvp1](https://github.com/phucnguyentvp1),
  24. FrameWeaver combines scene production with a broader editing workspace: layered
  25. timelines, media libraries, speech analysis, narration, subtitles, and saved exports.
  26. The project is currently available as a preview release.
  27. ## macOS desktop beta
  28. **[Download FrameWeaver 1.3.1 beta 4 for Mac](https://github.com/phucnguyentvp1/frameweaver/releases/tag/v1.3.1-beta.4)**
  29. — macOS 13 or later. Choose the installer for your Mac:
  30. | Mac | Installer | Size |
  31. | --- | --- | --- |
  32. | Apple Silicon (M1 or later) | [arm64 DMG](https://github.com/phucnguyentvp1/frameweaver/releases/download/v1.3.1-beta.4/FrameWeaver-1.3.1-beta.4-macOS-arm64.dmg) | 239 MB |
  33. | Intel | [x64 DMG](https://github.com/phucnguyentvp1/frameweaver/releases/download/v1.3.1-beta.4/FrameWeaver-1.3.1-beta.4-macOS-x64.dmg) | 255 MB |
  34. Both DMGs are Developer ID signed, Apple notarized, and stapled. Open one and drag
  35. FrameWeaver into Applications; Python and FFmpeg are included. Optional AI models
  36. and provider accounts are configured separately.
  37. For Google Flow, download the **[Chrome extension ZIP (0.3.6, ~379 KB)](https://github.com/phucnguyentvp1/frameweaver/releases/download/v1.3.1-beta.4/FrameWeaver-1.3.1-beta.4-extension.zip)**,
  38. shared by both Mac editions. Extract it, open `chrome://extensions`, enable
  39. **Developer mode**, choose **Load unpacked**, and select the extracted `extension`
  40. folder. You can also get it from the app menu **Ứng dụng → Cài extension Google Flow…**.
  41. Both installers package the application snapshot from **20 October 2026**,
  42. including **one-click ChatGPT component installation**, **Reload interface**,
  43. **live extension status**, the **Google Flow connection check**, and **Muse gateway setup/autostart**. See the
  44. [beta 4 release guide](docs/releases/v1.3.1-beta.4-macos.md) for installation and
  45. verification details. The [older beta 3](https://github.com/phucnguyentvp1/frameweaver/releases/tag/v1.3.1-beta.3), [beta 2](https://github.com/phucnguyentvp1/frameweaver/releases/tag/v1.3.1-beta.2)
  46. and beta 1 remain available. Intel was tested through Rosetta, not on a physical Intel Mac.
  47. ### ChatGPT setup without Terminal
  48. Open **Settings → ChatGPT**, install the optional component if it is missing,
  49. then **Sign in with ChatGPT**. The app downloads the pinned official OpenAI
  50. Codex CLI with SHA256 verification; no Node.js or administrator installation is
  51. needed. A separate **Test AI** button sends a small request using your account's
  52. allowance. Existing Codex installations take priority. See the
  53. [ChatGPT setup guide](docs/CHATGPT-DESKTOP.md).
  54. **Reload interface** is available in the top bar. Extension status also updates
  55. immediately after a connection check and refreshes automatically on reconnect.
  56. ### Muse AI in both Mac editions
  57. Use Muse for **script planning, reference/scene images, and video from a starting
  58. image**. Open **Settings → Muse → Cài và khởi động Muse** to install and start
  59. its optional [muse2api gateway](https://github.com/crisng95/muse2api). The app saves
  60. the local key and can start the installed gateway on later launches. Status,
  61. cancel, restart/stop and logs are available in Settings; no Terminal or dashboard
  62. is needed for the normal setup. Install Chrome and connect your Muse session
  63. once in the app, then choose Muse for each Studio stage. Google Flow still uses
  64. the extension. This beta's new project screen still requires Flow connectivity.
  65. See the **[Muse setup guide](docs/MUSE.md)** ([Tiếng Việt](docs/MUSE.vi.md)).
  66. Provider model names may be gateway aliases; a text-token balance does not confirm
  67. image/video entitlement or cost. Narration still uses the existing TTS providers.
  68. **Source vs desktop:** the repository's source preview and automatic GitHub
  69. “Source code” downloads are separate from the packaged desktop snapshot. The
  70. source instructions below describe that preview; Muse instructions above apply
  71. to the **beta 4 desktop apps**. This documentation update does not add the desktop
  72. Muse or ChatGPT installer implementation to the source preview.
  73. ## Creator showcase
  74. **YouTube Shorts. Reels. Illustrated stories. Stickman explainers. 2D characters — and more.**
  75. Turn a story into scenes, add narration and subtitles, then shape the result in
  76. the timeline. These demo previews were shared by the FrameWeaver maintainer.
  77. <table>
  78. <tr>
  79. <th width="33%">Illustrated moral stories</th>
  80. <th width="33%">Stickman storytelling</th>
  81. <th width="33%">2D family stories</th>
  82. </tr>
  83. <tr>
  84. <td align="center" valign="top"><a href="docs/images/showcase/karma-story-short.png"><img src="docs/images/showcase/karma-story-short.png" width="220" alt="Vertical illustrated story with a turtle scene, title, and Vietnamese subtitles" /></a></td>
  85. <td align="center" valign="top"><a href="docs/images/showcase/stickman-family-short.png"><img src="docs/images/showcase/stickman-family-short.png" width="245" alt="Stickman family story with a father, mother, child, and narration captions" /></a></td>
  86. <td align="center" valign="top"><a href="docs/images/showcase/illustrated-family-short.png"><img src="docs/images/showcase/illustrated-family-short.png" width="245" alt="2D family story with an illustrated mother and child, title, and subtitles" /></a></td>
  87. </tr>
  88. <tr>
  89. <td>Atmospheric illustrations, a story title, and timed narration.</td>
  90. <td>Simple characters for everyday stories and explainers.</td>
  91. <td>Character-led stories with coordinated captions and audio.</td>
  92. </tr>
  93. </table>
  94. Explore the [demo and workspace gallery](docs/SHOWCASE.md) for full-size previews.
  95. ## What you can do
  96. | Workspace | Capabilities |
  97. | --- | --- |
  98. | Scene production | Projects, characters, reference images, scene prompts, image/video generation queues, and stage monitoring |
  99. | Muse AI (desktop beta 4) | Script planning, reference/scene images, and image-to-video through an optional local muse2api gateway |
  100. | Browser bridge | Chrome Manifest V3 extension for requests made inside your signed-in Google Flow tab |
  101. | Story styles | Illustrated style library, stickman and 2D characters, favorites, custom image references, and reusable production templates |
  102. | Narration and subtitles | Narration scripts, SRT editing, voice selection, and optional local TTS integrations |
  103. | Speech analysis | Optional transcription and timing tools for preparing and refining spoken content |
  104. | Audio and editing | Music and effects libraries, audio mixing, captions, frame/layout controls, and FFmpeg export |
  105. | Timeline | Drag media onto tracks, reorder and trim clips, split at the playhead, add transitions, preview, and save exports |
  106. | Media management | Local media libraries, imported videos, reusable audio, and export history |
  107. | Agent workflows | Markdown `/fk-*` recipes for compatible coding agents and configurable CLI providers |
  108. | Interface languages | English, Vietnamese, Hindi, Indonesian, Chinese, Korean, and Japanese |
  109. Optional engines need their own dependencies and model downloads. AI generation
  110. uses your service account and applicable credits; this repository does not include
  111. Google Flow or Muse access, a paid AI subscription, or provider credentials.
  112. ## Inside the workspace
  113. ### Drag-and-drop timeline
  114. <a href="docs/images/showcase/timeline-editor.png"><img src="docs/images/showcase/timeline-editor.png" width="1040" alt="FrameWeaver editing workspace with a media library, vertical preview, and separate video, narration, subtitle, and music tracks" /></a>
  115. Bring video, narration, subtitles, music, and overlays together in one edit.
  116. Drag assets from the library onto tracks, move clips into place, split at the
  117. playhead, adjust the frame, and preview before exporting. The workspace includes
  118. audio ducking, undo/redo, autosave, and saved export history.
  119. ### A visual library for your next story
  120. Choose a look before building the scenes: light or dark stickman styles, 2D
  121. characters, cinematic illustration, chibi, hand-drawn art, Vietnamese folk stories,
  122. and illustrated moral stories. Save favorites or add your own reference-based style.
  123. <details>
  124. <summary><strong>Open the style library preview</strong></summary>
  125. <p><a href="docs/images/showcase/style-library.png"><img src="docs/images/showcase/style-library.png" width="820" alt="FrameWeaver style library with stickman, 2D, cinematic, chibi, hand-drawn, folk story, and moral story presets" /></a></p>
  126. </details>
  127. <details>
  128. <summary><strong>Open the dashboard and connection guide</strong></summary>
  129. <p><img src="docs/images/frameweaver_dashboard.jpg" width="920" alt="FrameWeaver dashboard showing the setup guide and extension connection status" /></p>
  130. <p>This earlier screenshot shows <strong>FrameWeaver 0.3.5</strong>; beta 4 includes extension <strong>0.3.6</strong>. See the <a href="docs/images/frameweaver_extension.jpg">extension UI preview</a>.</p>
  131. </details>
  132. ## Quick start
  133. ### 1. Install the prerequisites
  134. The packaging checks used **Python 3.12** and **Node.js 24**. You also need Chrome,
  135. FFmpeg, and ffprobe. Install those tools before proceeding.
  136. The commands below assume macOS or a Linux shell. Windows users can adapt them
  137. with WSL; a full Windows setup has not been verified for this preview.
  138. ### 2. Clone and install the backend
  139. ```sh
  140. git clone https://github.com/phucnguyentvp1/frameweaver.git
  141. cd frameweaver
  142. python3.12 -m venv .venv
  143. source .venv/bin/activate
  144. python -m pip install -r requirements.txt
  145. cp .env.example .env
  146. ```
  147. Create a project in the Google Flow interface. Copy its UUID from the project URL
  148. and set `FLOW_PROJECT_ID` in `.env`. Use your own credentials for any optional
  149. providers you enable.
  150. ```sh
  151. set -a
  152. source .env
  153. set +a
  154. python -m agent.main
  155. ```
  156. The backend reads shell environment variables; it does **not** load `.env`
  157. automatically. Leave this terminal running.
  158. ### 3. Load the extension
  159. Open Chrome's extension manager, enable Developer mode, choose **Load unpacked**,
  160. and select this repository's `extension/` directory. Open
  161. [Google Flow](https://flow.google.com/), sign in, and leave the tab open.
  162. For a standalone extension download, extract the ZIP first and select the folder
  163. containing `manifest.json`. Keep one bridge enabled for the same backend. An
  164. extension loaded from another copy of the project will keep using that copy's
  165. files. See the [extension installation guide](extension/README.md).
  166. ### 4. Start the dashboard
  167. In a second terminal:
  168. ```sh
  169. cd frameweaver/dashboard
  170. npm ci
  171. npm run dev
  172. ```
  173. Open **http://127.0.0.1:5173**. The backend uses port **8100** and the extension
  174. WebSocket bridge uses **9222**. Keep these services bound to localhost for a
  175. normal desktop installation.
  176. ### 5. Check the connection
  177. ```sh
  178. curl -s http://127.0.0.1:8100/health
  179. curl -s http://127.0.0.1:8100/api/flow/status
  180. ```
  181. Before generation, the health response must show `extension_connected: true`.
  182. The Flow status should identify the `batch` transport and your project UUID.
  183. `flow_key_present: false` is expected for the current browser transport.
  184. ## A typical workflow
  185. 1. Create a local project and link your Google Flow project.
  186. 2. Define recurring characters, locations, and props; generate all references first.
  187. 3. Add scenes using action prompts and the relevant reference entities.
  188. 4. Generate scene images, then video clips, through the request queue.
  189. 5. Review the clips before any supported upscale operation.
  190. 6. Prepare narration, subtitles, music, and timeline edits.
  191. 7. Export a preview or final MP4 and download it.
  192. Use `POST /api/requests/batch` for bulk generation. The server handles concurrency
  193. and cooldowns. `/fk-*` recipes in [skills/](skills/README.md) describe the API
  194. workflow and its checks.
  195. ## Architecture
  196. ```text
  197. React dashboard (:5173) ── HTTP / WebSocket ── Python agent (:8100)
  198. │
  199. SQLite + FFmpeg
  200. │
  201. Extension bridge (:9222)
  202. │
  203. Signed-in Google Flow tab
  204. ```
  205. The application stores project data, generated media, and local settings on the
  206. machine running the backend. A source download contains code and bundled preview
  207. assets; each user configures their own browser session and optional providers.
  208. ## Configuration
  209. | Variable | Purpose |
  210. | --- | --- |
  211. | `FLOW_PROJECT_ID` | UUID of the Google Flow project used by browser generation |
  212. | `API_HOST`, `API_PORT` | Backend bind address and port; defaults to `127.0.0.1:8100` |
  213. | `WS_HOST`, `WS_PORT` | Extension bridge bind address and port; defaults to `127.0.0.1:9222` |
  214. | `FLOW_ALLOW_DEGRADED` | Optional fallback for unsupported Veo reference/chaining modes; default `0` |
  215. | `ANTHROPIC_API_KEY`, `SUNO_API_KEY` | Optional provider credentials; leave unset unless needed |
  216. | `VITE_MODEL_CATALOG_URL` | Optional dashboard override for the public model-catalog JSON URL |
  217. Existing `.flowkit/` paths, `FLOWKIT_*` settings, and `/fk-*` commands are retained
  218. for compatibility with the base implementation. See [BRANDING.md](BRANDING.md).
  219. ## Preview status and known limitations
  220. - **Veo video upscale, Veo reference-to-video, and Veo start/end-frame chaining**
  221. are marked unported on the migrated transport. Supported Omni modes and
  222. explicitly enabled fallbacks have different behavior; consult
  223. [the transport notes](docs/CAPTURE.md).
  224. - Generation depends on Google Flow's current browser behavior and your account.
  225. Live generation has not been re-verified for this preview release.
  226. - External macOS volumes exposed AppleDouble (`._*`) discovery and modification-time
  227. cache failures during packaging checks. For a macOS trial, use native APFS
  228. working data and temporary directories. Packaging excludes metadata files but
  229. does not repair all runtime filesystem assumptions.
  230. - TTS, speech analysis, and restoration engines are optional integrations with
  231. separate installation, model, and licensing requirements.
  232. - Saved project titles and original uploaded filenames keep their user-provided
  233. names. App-generated image/video export names use the `frameweaver-` prefix.
  234. Focused publication checks passed for backend download/editing/auth/package
  235. paths, the MV3 bootstrap test, and the dashboard production build. A clean full
  236. cross-platform test result is not claimed for this preview.
  237. ## Documentation
  238. | Guide | Contents |
  239. | --- | --- |
  240. | [ChatGPT setup (desktop beta 4)](docs/CHATGPT-DESKTOP.md) | Install the optional component, sign in, test AI and refresh status |
  241. | [Muse AI (desktop beta 4)](docs/MUSE.md) | Gateway setup, account connection, supported stages, and limitations |
  242. | [Sharing and installation](docs/SHARING.md) | Environment setup, source archives, and distribution notes |
  243. | [Demo and workspace gallery](docs/SHOWCASE.md) | Creator examples, the timeline editor, style library, and dashboard |
  244. | [Technical reference](docs/REFERENCE.md) | Detailed API and workflow reference, including historical examples |
  245. | [Timeline editor](docs/TIMELINE_EDITOR.md) | Editing controls, save behavior, and export |
  246. | [Speech analysis](docs/speech-analysis.md) | Optional speech-analysis workflow |
  247. | [Kokoro](docs/kokoro-english.md) / [Qwen3](docs/qwen3-multilingual.md) | Optional narration engines |
  248. | [Export history](docs/EXPORT_HISTORY.md) | Managing saved exports and their dependencies |
  249. | [Agent workflows](skills/README.md) | `/fk-*` recipes and setup |
  250. | [Contributing](CONTRIBUTING.md) | Development checks and contribution guidance |
  251. | [Security](SECURITY.md) | Private vulnerability reporting |
  252. ## Development
  253. ```sh
  254. source .venv/bin/activate
  255. python -m pip install -r requirements.txt -r requirements-dev.txt
  256. python -m pytest tests/unit
  257. node --test tests/*.test.cjs tests/*.test.mjs dashboard/tests/speechRepair.test.ts
  258. ```
  259. ```sh
  260. cd dashboard
  261. npm ci
  262. npm run build
  263. ```
  264. The CI workflow runs backend unit checks and a frontend build. Optional model
  265. inference and live Google Flow generation are not part of those checks.
  266. ## Roadmap
  267. The next priorities are a reproducible first-run experience, external-volume
  268. compatibility, broader platform validation, and video walkthroughs showing
  269. the FrameWeaver workflow. Proposed changes are welcome through
  270. [issues](https://github.com/phucnguyentvp1/frameweaver/issues).
  271. ## License and acknowledgements
  272. FrameWeaver is distributed under the **MIT** license. It includes code adapted
  273. from [Flow Kit](https://github.com/crisng95/flowkit); the original copyright and
  274. permission notice are preserved in [LICENSE](LICENSE) for that reused code.
  275. FrameWeaver's additional features and changes are maintained in this repository.
  276. Bundled voice previews and other third-party resources have their own terms;
  277. read [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) before redistribution or
  278. commercial use of those assets.
  279. Thanks to the [Flow Kit authors and contributors](https://github.com/crisng95/flowkit)
  280. and the projects powering the optional integrations. FrameWeaver is a community
  281. project and is not affiliated with Google, Anthropic, or OpenAI.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.