visualkit 2.1.0__tar.gz → 3.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. visualkit-3.0.1/PKG-INFO +241 -0
  2. visualkit-3.0.1/README.md +196 -0
  3. visualkit-3.0.1/pyproject.toml +113 -0
  4. visualkit-3.0.1/src/visualkit/__init__.py +850 -0
  5. visualkit-3.0.1/src/visualkit/__main__.py +8 -0
  6. visualkit-3.0.1/src/visualkit/actors/__init__.py +237 -0
  7. visualkit-3.0.1/src/visualkit/actors/_server_config.py +27 -0
  8. visualkit-3.0.1/src/visualkit/actors/base.py +368 -0
  9. visualkit-3.0.1/src/visualkit/actors/builtins/__init__.py +87 -0
  10. visualkit-3.0.1/src/visualkit/actors/builtins/bg_remove/__init__.py +7 -0
  11. visualkit-3.0.1/src/visualkit/actors/builtins/bg_remove/actor.py +327 -0
  12. visualkit-3.0.1/src/visualkit/actors/builtins/ffmpeg_lut/__init__.py +11 -0
  13. visualkit-3.0.1/src/visualkit/actors/builtins/ffmpeg_lut/actor.py +491 -0
  14. visualkit-3.0.1/src/visualkit/actors/builtins/ffmpeg_lut/index.toml +65 -0
  15. visualkit-3.0.1/src/visualkit/actors/builtins/local_broll/__init__.py +7 -0
  16. visualkit-3.0.1/src/visualkit/actors/builtins/local_broll/actor.py +166 -0
  17. visualkit-3.0.1/src/visualkit/actors/builtins/media_tools/__init__.py +7 -0
  18. visualkit-3.0.1/src/visualkit/actors/builtins/media_tools/actor.py +281 -0
  19. visualkit-3.0.1/src/visualkit/actors/builtins/rembg/__init__.py +27 -0
  20. visualkit-3.0.1/src/visualkit/actors/builtins/rembg/actor.py +1114 -0
  21. visualkit-3.0.1/src/visualkit/actors/builtins/rembg/index.toml +86 -0
  22. visualkit-3.0.1/src/visualkit/actors/builtins/transcribe/__init__.py +43 -0
  23. visualkit-3.0.1/src/visualkit/actors/builtins/transcribe/actor.py +1075 -0
  24. visualkit-3.0.1/src/visualkit/actors/builtins/transcribe/index.toml +82 -0
  25. visualkit-3.0.1/src/visualkit/actors/builtins/transcribe/schema.py +195 -0
  26. visualkit-3.0.1/src/visualkit/actors/errors.py +87 -0
  27. visualkit-3.0.1/src/visualkit/actors/installer.py +342 -0
  28. visualkit-3.0.1/src/visualkit/actors/lockfile.py +312 -0
  29. visualkit-3.0.1/src/visualkit/actors/manifest.py +459 -0
  30. visualkit-3.0.1/src/visualkit/actors/marketplace.py +192 -0
  31. visualkit-3.0.1/src/visualkit/actors/materializer.py +282 -0
  32. visualkit-3.0.1/src/visualkit/actors/registry.py +480 -0
  33. visualkit-3.0.1/src/visualkit/actors/resources.py +391 -0
  34. visualkit-3.0.1/src/visualkit/actors/runners.py +515 -0
  35. visualkit-3.0.1/src/visualkit/assets/__init__.py +80 -0
  36. visualkit-3.0.1/src/visualkit/assets/base.py +108 -0
  37. visualkit-3.0.1/src/visualkit/assets/basic.py +287 -0
  38. visualkit-3.0.1/src/visualkit/assets/pin.py +541 -0
  39. visualkit-3.0.1/src/visualkit/assets/resolver/__init__.py +57 -0
  40. visualkit-3.0.1/src/visualkit/assets/resolver/errors.py +53 -0
  41. visualkit-3.0.1/src/visualkit/assets/resolver/media.py +564 -0
  42. visualkit-3.0.1/src/visualkit/assets/resolver/models.py +105 -0
  43. visualkit-3.0.1/src/visualkit/assets/resolver/paths.py +136 -0
  44. visualkit-3.0.1/src/visualkit/assets/resolver/resolver.py +1300 -0
  45. visualkit-3.0.1/src/visualkit/assets/resolver/store.py +530 -0
  46. visualkit-3.0.1/src/visualkit/assets/resolver/vfs.py +267 -0
  47. visualkit-3.0.1/src/visualkit/assets/resolver/view.py +158 -0
  48. visualkit-3.0.1/src/visualkit/cli/__init__.py +56 -0
  49. visualkit-3.0.1/src/visualkit/cli/__main__.py +9 -0
  50. visualkit-3.0.1/src/visualkit/cli/actors.py +479 -0
  51. visualkit-3.0.1/src/visualkit/cli/assets.py +948 -0
  52. visualkit-3.0.1/src/visualkit/cli/common.py +135 -0
  53. visualkit-3.0.1/src/visualkit/cli/config.py +270 -0
  54. visualkit-3.0.1/src/visualkit/cli/director.py +1127 -0
  55. visualkit-3.0.1/src/visualkit/cli/engine.py +840 -0
  56. visualkit-3.0.1/src/visualkit/cli/preview.py +353 -0
  57. visualkit-3.0.1/src/visualkit/cli/render.py +142 -0
  58. visualkit-3.0.1/src/visualkit/clips/__init__.py +528 -0
  59. visualkit-3.0.1/src/visualkit/clips/animation/__init__.py +43 -0
  60. visualkit-3.0.1/src/visualkit/clips/animation/curve.py +305 -0
  61. visualkit-3.0.1/src/visualkit/clips/animation/keyframe.py +375 -0
  62. visualkit-3.0.1/src/visualkit/clips/animation/keyframe_handler.py +1407 -0
  63. visualkit-3.0.1/src/visualkit/clips/animation/time_map.py +565 -0
  64. visualkit-3.0.1/src/visualkit/clips/base.py +223 -0
  65. visualkit-3.0.1/src/visualkit/clips/clips.py +753 -0
  66. visualkit-3.0.1/src/visualkit/clips/director.py +1628 -0
  67. visualkit-3.0.1/src/visualkit/clips/effects.py +669 -0
  68. visualkit-3.0.1/src/visualkit/clips/entities.py +379 -0
  69. visualkit-3.0.1/src/visualkit/clips/errors.py +152 -0
  70. visualkit-3.0.1/src/visualkit/clips/fusion.py +844 -0
  71. visualkit-3.0.1/src/visualkit/clips/human_props.py +369 -0
  72. visualkit-3.0.1/src/visualkit/clips/integrity.py +2608 -0
  73. visualkit-3.0.1/src/visualkit/clips/item.py +558 -0
  74. visualkit-3.0.1/src/visualkit/clips/props.py +320 -0
  75. visualkit-3.0.1/src/visualkit/clips/references.py +69 -0
  76. visualkit-3.0.1/src/visualkit/clips/style.py +511 -0
  77. visualkit-3.0.1/src/visualkit/clips/svg_path.py +339 -0
  78. visualkit-3.0.1/src/visualkit/clips/timeline.py +1622 -0
  79. visualkit-3.0.1/src/visualkit/clips/timing.py +97 -0
  80. visualkit-3.0.1/src/visualkit/clips/variables.py +1138 -0
  81. visualkit-3.0.1/src/visualkit/coded/__init__.py +46 -0
  82. visualkit-3.0.1/src/visualkit/coded/base.py +79 -0
  83. visualkit-3.0.1/src/visualkit/coded/browser.py +147 -0
  84. visualkit-3.0.1/src/visualkit/coded/caller.py +272 -0
  85. visualkit-3.0.1/src/visualkit/coded/dependencies.py +243 -0
  86. visualkit-3.0.1/src/visualkit/coded/doctor.py +180 -0
  87. visualkit-3.0.1/src/visualkit/coded/errors.py +29 -0
  88. visualkit-3.0.1/src/visualkit/coded/html/__init__.py +13 -0
  89. visualkit-3.0.1/src/visualkit/coded/html/compiler.py +672 -0
  90. visualkit-3.0.1/src/visualkit/coded/html/video.py +422 -0
  91. visualkit-3.0.1/src/visualkit/coded/params.py +188 -0
  92. visualkit-3.0.1/src/visualkit/coded/remotion/__init__.py +10 -0
  93. visualkit-3.0.1/src/visualkit/coded/remotion/compiler.py +697 -0
  94. visualkit-3.0.1/src/visualkit/coded/remotion/runner.py +343 -0
  95. visualkit-3.0.1/src/visualkit/engine/__init__.py +178 -0
  96. visualkit-3.0.1/src/visualkit/engine/claims.py +534 -0
  97. visualkit-3.0.1/src/visualkit/engine/codec.py +338 -0
  98. visualkit-3.0.1/src/visualkit/engine/director_handles.py +1183 -0
  99. visualkit-3.0.1/src/visualkit/engine/draft.py +471 -0
  100. visualkit-3.0.1/src/visualkit/engine/engine.py +3754 -0
  101. visualkit-3.0.1/src/visualkit/engine/errors.py +128 -0
  102. visualkit-3.0.1/src/visualkit/engine/export_import.py +318 -0
  103. visualkit-3.0.1/src/visualkit/engine/handles.py +3172 -0
  104. visualkit-3.0.1/src/visualkit/engine/runner.py +890 -0
  105. visualkit-3.0.1/src/visualkit/engine/session.py +299 -0
  106. visualkit-3.0.1/src/visualkit/engine/store/__init__.py +52 -0
  107. visualkit-3.0.1/src/visualkit/engine/store/diff_merge.py +641 -0
  108. visualkit-3.0.1/src/visualkit/engine/store/history.py +741 -0
  109. visualkit-3.0.1/src/visualkit/engine/store/liveness.py +37 -0
  110. visualkit-3.0.1/src/visualkit/engine/store/models.py +279 -0
  111. visualkit-3.0.1/src/visualkit/engine/store/schema.py +97 -0
  112. visualkit-3.0.1/src/visualkit/engine/store/store.py +1415 -0
  113. visualkit-3.0.1/src/visualkit/engine/store/workspaces.py +1403 -0
  114. visualkit-3.0.1/src/visualkit/export/__init__.py +88 -0
  115. visualkit-3.0.1/src/visualkit/export/base.py +154 -0
  116. visualkit-3.0.1/src/visualkit/export/ffmpeg/__init__.py +22 -0
  117. visualkit-3.0.1/src/visualkit/export/ffmpeg/effects_fusion.py +2282 -0
  118. visualkit-3.0.1/src/visualkit/export/ffmpeg/helpers.py +173 -0
  119. visualkit-3.0.1/src/visualkit/export/ffmpeg/probe.py +301 -0
  120. visualkit-3.0.1/src/visualkit/export/ffmpeg/renderer.py +3011 -0
  121. visualkit-3.0.1/src/visualkit/export/plan.py +2369 -0
  122. visualkit-3.0.1/src/visualkit/export/text.py +280 -0
  123. visualkit-3.0.1/src/visualkit/export/window.py +78 -0
  124. visualkit-3.0.1/src/visualkit/preview/__init__.py +55 -0
  125. visualkit-3.0.1/src/visualkit/preview/facade.py +398 -0
  126. visualkit-3.0.1/src/visualkit/preview/grid.py +354 -0
  127. visualkit-3.0.1/src/visualkit/preview/models.py +201 -0
  128. visualkit-3.0.1/src/visualkit/preview/service.py +1105 -0
  129. visualkit-3.0.1/src/visualkit/style/__init__.py +148 -0
  130. visualkit-3.0.1/src/visualkit/style/fonts/FONTS.md +24 -0
  131. visualkit-3.0.1/src/visualkit/style/fonts/LICENSE-NotoColorEmoji-OFL.txt +87 -0
  132. visualkit-3.0.1/src/visualkit/style/fonts/LICENSE-OFL.txt +94 -0
  133. visualkit-3.0.1/src/visualkit/style/fonts.py +559 -0
  134. visualkit-3.0.1/src/visualkit/style/raster.py +321 -0
  135. visualkit-3.0.1/src/visualkit/style/skia_raster.py +1334 -0
  136. visualkit-3.0.1/src/visualkit/style/templates.py +1092 -0
  137. visualkit-3.0.1/src/visualkit/tier1.py +77 -0
  138. visualkit-3.0.1/src/visualkit/utils/__init__.py +16 -0
  139. visualkit-3.0.1/src/visualkit/utils/base_model.py +137 -0
  140. {visualkit-2.1.0 → visualkit-3.0.1}/src/visualkit/utils/exceptions.py +29 -1
  141. visualkit-3.0.1/src/visualkit/utils/time.py +1153 -0
  142. visualkit-3.0.1/src/visualkit/utils/utility.py +118 -0
  143. visualkit-3.0.1/src/visualkit.egg-info/PKG-INFO +241 -0
  144. visualkit-3.0.1/src/visualkit.egg-info/SOURCES.txt +155 -0
  145. visualkit-3.0.1/src/visualkit.egg-info/entry_points.txt +3 -0
  146. visualkit-3.0.1/src/visualkit.egg-info/requires.txt +19 -0
  147. visualkit-3.0.1/tests/test_audit_regressions.py +303 -0
  148. visualkit-3.0.1/tests/test_pre_doc_root_fixes.py +170 -0
  149. visualkit-3.0.1/tests/test_pre_doc_stress_and_perf.py +340 -0
  150. visualkit-3.0.1/tests/test_preview_and_renderer_root_fixes.py +487 -0
  151. visualkit-3.0.1/tests/test_ux_fixes.py +297 -0
  152. visualkit-2.1.0/PKG-INFO +0 -245
  153. visualkit-2.1.0/README.md +0 -216
  154. visualkit-2.1.0/pyproject.toml +0 -78
  155. visualkit-2.1.0/src/visualkit/__init__.py +0 -128
  156. visualkit-2.1.0/src/visualkit/__main__.py +0 -11
  157. visualkit-2.1.0/src/visualkit/coded_visual/__init__.py +0 -8
  158. visualkit-2.1.0/src/visualkit/coded_visual/browser.py +0 -192
  159. visualkit-2.1.0/src/visualkit/coded_visual/capture.py +0 -294
  160. visualkit-2.1.0/src/visualkit/coded_visual/compiler.py +0 -648
  161. visualkit-2.1.0/src/visualkit/coded_visual/project.py +0 -186
  162. visualkit-2.1.0/src/visualkit/engine/__init__.py +0 -8
  163. visualkit-2.1.0/src/visualkit/engine/asset_resolver.py +0 -54
  164. visualkit-2.1.0/src/visualkit/engine/pipeline.py +0 -377
  165. visualkit-2.1.0/src/visualkit/exporters/__init__.py +0 -9
  166. visualkit-2.1.0/src/visualkit/exporters/_ffmpeg.py +0 -56
  167. visualkit-2.1.0/src/visualkit/exporters/_render_plan.py +0 -440
  168. visualkit-2.1.0/src/visualkit/exporters/base.py +0 -63
  169. visualkit-2.1.0/src/visualkit/exporters/resolve.py +0 -874
  170. visualkit-2.1.0/src/visualkit/exporters/single_clip.py +0 -188
  171. visualkit-2.1.0/src/visualkit/exporters/video.py +0 -551
  172. visualkit-2.1.0/src/visualkit/models/__init__.py +0 -98
  173. visualkit-2.1.0/src/visualkit/models/animation.py +0 -208
  174. visualkit-2.1.0/src/visualkit/models/clips/__init__.py +0 -46
  175. visualkit-2.1.0/src/visualkit/models/clips/audio.py +0 -30
  176. visualkit-2.1.0/src/visualkit/models/clips/base.py +0 -130
  177. visualkit-2.1.0/src/visualkit/models/clips/coded_visual.py +0 -479
  178. visualkit-2.1.0/src/visualkit/models/clips/compound.py +0 -333
  179. visualkit-2.1.0/src/visualkit/models/clips/media.py +0 -84
  180. visualkit-2.1.0/src/visualkit/models/clips/text.py +0 -159
  181. visualkit-2.1.0/src/visualkit/models/clips/visual.py +0 -294
  182. visualkit-2.1.0/src/visualkit/models/effects.py +0 -266
  183. visualkit-2.1.0/src/visualkit/models/keyframes.py +0 -433
  184. visualkit-2.1.0/src/visualkit/models/timeline.py +0 -1151
  185. visualkit-2.1.0/src/visualkit/models/variable.py +0 -186
  186. visualkit-2.1.0/src/visualkit/utils/__init__.py +0 -0
  187. visualkit-2.1.0/src/visualkit/utils/base_model.py +0 -40
  188. visualkit-2.1.0/src/visualkit/utils/time.py +0 -498
  189. visualkit-2.1.0/src/visualkit.egg-info/PKG-INFO +0 -245
  190. visualkit-2.1.0/src/visualkit.egg-info/SOURCES.txt +0 -69
  191. visualkit-2.1.0/src/visualkit.egg-info/requires.txt +0 -4
  192. visualkit-2.1.0/tests/test_animation_presets.py +0 -307
  193. visualkit-2.1.0/tests/test_chroma_key.py +0 -243
  194. visualkit-2.1.0/tests/test_clip_editing.py +0 -609
  195. visualkit-2.1.0/tests/test_coded_visual_compiler.py +0 -485
  196. visualkit-2.1.0/tests/test_keyframe_rendering.py +0 -487
  197. visualkit-2.1.0/tests/test_keyframes.py +0 -650
  198. visualkit-2.1.0/tests/test_masks.py +0 -252
  199. visualkit-2.1.0/tests/test_package_exports.py +0 -28
  200. visualkit-2.1.0/tests/test_pipeline_semantics.py +0 -199
  201. visualkit-2.1.0/tests/test_positioning.py +0 -64
  202. visualkit-2.1.0/tests/test_preview_image.py +0 -219
  203. visualkit-2.1.0/tests/test_rendering.py +0 -453
  204. visualkit-2.1.0/tests/test_resolve_correctness.py +0 -170
  205. visualkit-2.1.0/tests/test_resolve_exporter.py +0 -296
  206. visualkit-2.1.0/tests/test_text_style.py +0 -252
  207. visualkit-2.1.0/tests/test_time_and_variables.py +0 -235
  208. visualkit-2.1.0/tests/test_timeline.py +0 -116
  209. visualkit-2.1.0/tests/test_timeline_integrity.py +0 -276
  210. visualkit-2.1.0/tests/test_timeline_pipeline.py +0 -396
  211. visualkit-2.1.0/tests/test_variable_inspection.py +0 -91
  212. visualkit-2.1.0/tests/test_variables_and_clips.py +0 -351
  213. visualkit-2.1.0/tests/test_video_alpha.py +0 -185
  214. visualkit-2.1.0/tests/test_video_exporter.py +0 -344
  215. visualkit-2.1.0/tests/test_visual_clip_fields.py +0 -70
  216. {visualkit-2.1.0 → visualkit-3.0.1}/AUTHORS.rst +0 -0
  217. {visualkit-2.1.0 → visualkit-3.0.1}/LICENSE +0 -0
  218. {visualkit-2.1.0 → visualkit-3.0.1}/setup.cfg +0 -0
  219. {visualkit-2.1.0 → visualkit-3.0.1}/src/visualkit/py.typed +0 -0
  220. {visualkit-2.1.0 → visualkit-3.0.1}/src/visualkit.egg-info/dependency_links.txt +0 -0
  221. {visualkit-2.1.0 → visualkit-3.0.1}/src/visualkit.egg-info/top_level.txt +0 -0
@@ -0,0 +1,241 @@
1
+ Metadata-Version: 2.4
2
+ Name: visualkit
3
+ Version: 3.0.1
4
+ Summary: Programmable, local-first video editing engine for developers and AI agents: versioned SQLite timelines, exact rational clocks, Fusion node graphs, motion graphics, local actors, multi-agent claimed regions, and FFmpeg rendering.
5
+ Author-email: Suraj Airi <surajairi.ml@gmail.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://visualkit.hyekai.com
8
+ Project-URL: Documentation, https://visualkit.hyekai.com/docs
9
+ Project-URL: Repository, https://github.com/surajairi/visualkit
10
+ Project-URL: Issues, https://github.com/surajairi/visualkit/issues
11
+ Keywords: video-editing,ai-agents,programmatic-video,motion-graphics,ffmpeg,compositing,node-graph,timeline,keyframes,remotion,skia,sqlite
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Multimedia :: Video
22
+ Classifier: Topic :: Multimedia :: Video :: Non-Linear Editor
23
+ Classifier: Topic :: Multimedia :: Graphics
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ License-File: AUTHORS.rst
30
+ Requires-Dist: pydantic>=2.13.5
31
+ Requires-Dist: typing-extensions>=4.16.0
32
+ Requires-Dist: tomli>=2.0.1; python_version < "3.11"
33
+ Provides-Extra: render
34
+ Requires-Dist: playwright>=1.40.0; extra == "render"
35
+ Provides-Extra: style
36
+ Requires-Dist: skia-python>=144.1; extra == "style"
37
+ Provides-Extra: dev
38
+ Requires-Dist: mypy>=2.4.1; extra == "dev"
39
+ Requires-Dist: notebook>=7.6.2; extra == "dev"
40
+ Requires-Dist: pyright>=1.1.414; extra == "dev"
41
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
42
+ Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
43
+ Requires-Dist: ruff>=0.12.1; extra == "dev"
44
+ Dynamic: license-file
45
+
46
+ # VisualKit
47
+
48
+ **A programmable, local-first video editing engine built for developers and AI agents.**
49
+
50
+ [Website](https://visualkit.hyekai.com) · [Documentation](https://visualkit.hyekai.com/docs) · [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference) · [Agent Skills](https://visualkit.hyekai.com/docs/skills)
51
+
52
+ ---
53
+
54
+ VisualKit replaces brittle FFmpeg command strings and GUI-only timelines with a strictly typed Python engine backed by a versioned SQLite project store. Every edit is validated atomically before hitting disk, every timestamp uses exact rational arithmetic (`Fraction`), and multiple AI agents can edit disjoint windows of the same timeline in parallel without merge conflicts.
55
+
56
+ ## Why VisualKit
57
+
58
+ - **Git-like versioned timeline store**: Projects live in a single SQLite file (`project.visualkit`) with content-addressed revisions, checkpoints, undo/redo, branches, 3-way entity merges, and Git-diffable canonical JSON export/import.
59
+ - **Multi-agent claimed regions**: Lock disjoint `[start, end)` time windows on the same branch so parallel agents edit in claim-local `0.0s` coordinates with automatic downstream ripple on release.
60
+ - **Exact rational clocks & commit-time integrity**: Typed time domains (`Time`, `TimelineTime`, `ClipTime`, `SourceTime`, `AnimTime`) eliminate float drift; overlaps, out-of-bounds trims, DAG cycles, and dangling references fail atomically before commit.
61
+ - **Compositing, motion graphics & local actors**: Combine built-in visual/audio effects, track-wide adjustment clips, DAG-based Fusion node graphs, Skia-styled text/shapes/templates, and 6 local-first media actors (`ffmpeg_lut`, `bg_remove`, `rembg`, `transcribe`, `media_tools`, `local_broll`).
62
+ - **Agent-native ergonomics**: Structured `--format json` CLI output, deterministic exit codes (`0–4`), `--dry-run` validation, fast frame/grid visual previews, and ready-to-use Agent Skills (`visualkit-editing`, `visualkit-collab`).
63
+
64
+ ## Installation
65
+
66
+ Requires **Python 3.10+** and **FFmpeg / FFprobe** on `PATH`.
67
+
68
+ ```bash
69
+ # With uv (recommended)
70
+ uv add visualkit
71
+
72
+ # Or with pip
73
+ pip install visualkit
74
+ ```
75
+
76
+ ### Optional Extras
77
+
78
+ | Extra | Command | What it enables |
79
+ | --- | --- | --- |
80
+ | `style` | `uv add "visualkit[style]"` | Skia vector rasterization — **required** for `ShapeClip` and shape-based templates (without it, `TextClip` falls back to basic FFmpeg `drawtext`) |
81
+ | `render` | `uv add "visualkit[render]"` | Playwright browser automation for HTML coded visual assets |
82
+ | Both | `uv add "visualkit[style,render]"` | Full vector styling + HTML coded visuals |
83
+
84
+ For coded visual compilers (HTML and Remotion), check local dependencies with `visualkit-doctor check`.
85
+
86
+ ## 60-Second Quickstart
87
+
88
+ ### CLI Workflow (`init` → `exec` → `preview` → `render`)
89
+
90
+ ```bash
91
+ # 1. Initialize a versioned project store
92
+ visualkit init demo.visualkit --title "Launch Teaser" --fps 30 --width 1920 --height 1080 --format json
93
+
94
+ # 2. Scan media from your project folder (auto-mounted at /proj)
95
+ export VISUALKIT_PROJECT_DIR=./media
96
+ visualkit asset scan /proj --recursive --format json
97
+ ```
98
+
99
+ Write an editing script (`edit.py`) — `visualkit exec` injects `engine` (`VisualkitEngine`) and commits atomically on exit:
100
+
101
+ ```python
102
+ from visualkit import Geometry, Shadow
103
+
104
+ with engine.edit(label="create intro"):
105
+ v_bg = engine.create_track("visual", name="Background")
106
+ v_fg = engine.create_track("visual", name="Titles")
107
+
108
+ engine.add_shape(
109
+ Geometry.rect(1920, 1080),
110
+ visual_track_id=v_bg.id,
111
+ start_ts=0.0,
112
+ duration=4.0,
113
+ fill="#0F172A",
114
+ )
115
+
116
+ title = engine.add_text(
117
+ "Built with VisualKit",
118
+ visual_track_id=v_fg.id,
119
+ start_ts=0.3,
120
+ duration=3.4,
121
+ font_size=96,
122
+ color="#F8FAFC",
123
+ font_weight=700,
124
+ shadow=Shadow.drop(),
125
+ )
126
+ title.place_at(960, 540)
127
+ title.fade_in(0.4).pop_in(from_scale=0.92, duration=0.4).fade_out(0.4)
128
+ ```
129
+
130
+ ```bash
131
+ # 3. Validate without writing, then commit
132
+ visualkit exec edit.py --db demo.visualkit --dry-run --format json
133
+ visualkit exec edit.py --db demo.visualkit --format json
134
+
135
+ # 4. Preview a contact sheet before full export, then render
136
+ visualkit preview grid --db demo.visualkit --frames 6 --cols 3 -o preview.jpg --format json
137
+ visualkit render out.mp4 --db demo.visualkit --format json
138
+ ```
139
+
140
+ ### Direct Python API
141
+
142
+ ```python
143
+ from visualkit import FfmpegRenderer, RenderOptions, VisualkitEngine
144
+
145
+ with VisualkitEngine.open("demo.visualkit", fps=30, resolution=(1920, 1080)) as engine:
146
+ with engine.edit(label="add title"):
147
+ v1 = engine.create_track("visual", name="V1")
148
+ clip = engine.add_text("Hello World", visual_track_id=v1.id, start_ts=0.0, duration=3.0, font_size=72)
149
+ clip.fade_in(0.3).fade_out(0.3)
150
+
151
+ engine.save(label="initial cut")
152
+ engine.preview_grid("timeline", num_frames=4, out_path="preview.jpg")
153
+ result = FfmpegRenderer().render(engine.store, "out.mp4", options=RenderOptions())
154
+ ```
155
+
156
+ ## Core Capabilities
157
+
158
+ ### Timeline, Clips, Cropping & Speed Curves
159
+ - **Clip types**: `MediaClip`, `AudioClip`, `TextClip`, `ShapeClip`, `CodedVisualClip`, `AdjustmentClipVisual`/`Audio`, `FusionClipVisual`/`Audio`, `CompoundClipVisual`/`Audio`, and `TemplateClipVisual`/`Audio`.
160
+ - **Non-linear editing**: `move`, `trim_head`, `trim_tail`, `split(TimelineTime(...))`, `split_all`, `ripple_insert`, `ripple_delete`, `close_gap`, `shift_items`, `engine.snap(t)` for exact frame-grid snapping, and linked A/V preservation.
161
+ - **Cropping & color**: Keyframable `Transform.crop` (`crop_to` with `FitMode`, `CropAlignment`, and `source_position`), signed-offset `set_human_props(...)`, and `AudioClip.equalizer`.
162
+ - **Speed ramping**: Constant speed (`set_speed(2.0, shrink_to_fit=True)`) and piecewise speed curves (`set_speed_curve([SpeedPoint(at=..., speed=..., interpolation=LINEAR|HOLD)])`) with exact rational integration.
163
+
164
+ ### Two-Layer Keyframes, Vector Styling & Templates
165
+ - **Two-layer animation**: `Layer.PRE` (source time, replaces static base and stretches with `TimeMap`) and `Layer.POST` (cut-relative time, combines onto `PRE`/static via `ADD`, `MULTIPLY`, or `REPLACE`).
166
+ - **Motion presets**: Chainable `fade_in`, `fade_out`, `slide_in`, `slide_out`, `pop_in`, and `draw_in`, plus `LINEAR`, `HOLD`, `EASE_IN`, `EASE_OUT`, `EASE_IN_OUT`, and custom cubic `BEZIER` curves.
167
+ - **Styling & built-in templates**: Full `TextStyle`, `Geometry`, `Paint`, `Stroke`, `Shadow`, managed SIL OFL Noto fonts (downloaded on first use; see the fonts note in the style guide), and 5 parameterized templates (`title_card`, `lower_third`, `subtitle`, `callout`, `progress_ring`).
168
+
169
+ ### Effects, Adjustment Clips & Fusion Node Graphs
170
+ - **Per-clip & track-wide effects**: `GaussianBlurEffect`, `DropShadowEffect`, `GlowEffect`, `SharpenEffect`, `PixelateEffect`, `VignetteEffect`, `ChromaKeyEffect`, `MaskEffect`, `CompressorEffect`, `ReverbEffect`, `EchoEffect`, `DistortionEffect`, `PanEffect`, and `AdjustmentClip`.
171
+ - **Fusion DAGs**: Build validated acyclic node graphs (`FusionInputNode`, `FusionGeneratorNode`, `FusionEffectNode`, `FusionColorGradeNode`, `FusionMaskNode`, `FusionApplyMaskNode`, `FusionMergeNode`, `FusionPluginNode`, `FusionAudioMixNode`, `FusionOutputNode`) usable as standalone `FusionClip`s or reusable single-input `graph.as_effect()` stacks.
172
+
173
+ ### Compound Clips & Template Repeaters
174
+ - Package reusable nested sequences as `CompoundClip`s with typed exposed `VariableSpec`s (`string`, `number`, `integer`, `boolean`, `json`, `asset`).
175
+ - Drive staggered lists, bullet overlays, and lower-third sequences with `SequenceHandle.set_repeater(...)` and `engine.add_template_clip(...)`.
176
+
177
+ ### Built-in Local Actors
178
+
179
+ Local-first media plugins accessible via `visualkit actor <slug> ...`, `visualkit actors run`, and `FusionPluginNode` (pass `--save-asset` to auto-register outputs into `AssetResolver`):
180
+
181
+ | Actor | Surfaces | Purpose |
182
+ | --- | --- | --- |
183
+ | `ffmpeg_lut` | CLI, Fusion (native) | 3D `.cube` LUT grading (`teal_orange`, `cinematic_warm`, `noir_bw`, `vintage_fade`, `crisp_daylight`, `kodak_2383_d65`, or custom `.cube`) with RGBA intensity blending |
184
+ | `bg_remove` | CLI, Fusion (native) | Fast zero-dependency FFmpeg chroma-key removal with alpha-only `feather` |
185
+ | `rembg` | CLI, Fusion | Local AI subject segmentation via ONNX (CPU/CUDA/CoreML, raw FFmpeg pipe streaming) |
186
+ | `transcribe` | CLI | Unified local ASR (`faster_whisper`, `whisperx`, `insanely_fast_whisper`) with word-level JSON/SRT/VTT output |
187
+ | `media_tools` | CLI | Fast FFmpeg/FFprobe helpers: `probe`, `extract-frames`, `detect-scenes`, and `trim` |
188
+ | `local_broll` | CLI | Offline synthetic B-roll MP4 generator for rapid prototyping and tests |
189
+
190
+ ### Director's Cut, Assets & Collaboration
191
+ - **Director's Cut**: Non-rendered `EditingPlan`, project stage registry, nested `StoryboardClip`s with per-stage hints, and time- or item-anchored `DirectorMarker`s that ripple with edits.
192
+ - **Assets & Coded Visuals**: `AssetResolver` with virtual mounts (`/proj`, `/home`, `/global`, plus custom mounts), proxy variants, FTS5 search, path-free `AssetPin` staleness checks, and cached HTML/Remotion coded visuals.
193
+ - **Collaboration & Claimed Regions**: Checkpoints (`checkpoint`, `diff`, `restore`, `revert`), branches & 3-way merge (`branch`, `merge`), bound sessions (`workspace`), and disjoint parallel editing (`workspace new --claim START END --on-straddle split`, `claim release`, `claim abort`).
194
+
195
+ ## Built for AI Agents
196
+
197
+ VisualKit ships two structured Agent Skills under [skills/](https://github.com/SurajAiri/visualkit/tree/main/skills) designed for progressive disclosure:
198
+
199
+ - [skills/visualkit-editing/SKILL.md](https://visualkit.hyekai.com/downloads/skills/visualkit-editing.zip) — End-to-end editing playbook plus focused references for effects/Fusion, compound/repeaters, and Director's Cut/coded visuals.
200
+ - [skills/visualkit-collab/SKILL.md](https://visualkit.hyekai.com/downloads/skills/visualkit-collab.zip) — Checkpoints, branching, 3-way merges, workspaces, and multi-agent claimed regions.
201
+
202
+ New to directing an agent? [Getting Started (Human)](https://visualkit.hyekai.com/docs/getting-started-human) walks through importing the skills, pointing the agent at your footage, and reviewing previews before you render.
203
+
204
+ Every CLI command supports `--format json` with deterministic exit codes (`0=ok`, `1=validation_error`, `2=script_crash`, `3=merge_conflict`, `4=claim_refused`).
205
+
206
+ ## Documentation
207
+
208
+ Full guides live in [docs/](https://visualkit.hyekai.com/docs):
209
+
210
+ | Guide | Topic |
211
+ | --- | --- |
212
+ | [Getting Started](https://visualkit.hyekai.com/docs/getting-started) | Installation, FFmpeg/extras, and your first 5-minute project |
213
+ | [Getting Started (Human)](https://visualkit.hyekai.com/docs/getting-started-human) | Directing an AI agent (Claude Code, Codex, Cursor, Gemini CLI): import the skills, give it your assets, review previews, and render |
214
+ | [Agent Skills](https://visualkit.hyekai.com/docs/skills) | Download `visualkit-editing` and `visualkit-collab`, and where each agent expects them |
215
+ | [Core Concepts](https://visualkit.hyekai.com/docs/core-concepts) | Exact rational clocks, flat entities, transactions, validation |
216
+ | [Assets \& Coded Visuals](https://visualkit.hyekai.com/docs/assets) | Virtual mounts (`/proj`), variants, `AssetPin`, HTML & Remotion |
217
+ | [Clips \& Timeline Editing](https://visualkit.hyekai.com/docs/clips-and-timeline) | Tracks, cropping, human color scales, speed curves, NLE & ripple ops |
218
+ | [Keyframes \& Animation](https://visualkit.hyekai.com/docs/keyframes-and-animation) | `PRE`/`POST` layers, `Combine` semantics, Bezier & motion presets |
219
+ | [Style, Text, Shapes \& Templates](https://visualkit.hyekai.com/docs/style-text-shapes-templates) | `TextClip`, `ShapeClip`, `Geometry`, `Paint`, Skia & templates |
220
+ | [Effects \& Fusion Graphs](https://visualkit.hyekai.com/docs/effects-and-fusion) | Visual/audio effects, adjustment clips, Fusion DAGs & `as_effect()` |
221
+ | [Compound \& Template Clips](https://visualkit.hyekai.com/docs/compound-and-template-clips) | Nested sequences, exposed variables, and repeater templates |
222
+ | [Director's Cut](https://visualkit.hyekai.com/docs/director-cut) | Stages, storyboards, markers, and non-rendered review layer |
223
+ | [Built-in \& Local Actors](https://visualkit.hyekai.com/docs/actors) | All 6 local-first actors, CLI subcommands, and Fusion integration |
224
+ | [Preview \& Rendering](https://visualkit.hyekai.com/docs/preview-and-rendering) | Frame/grid/video/compare previews and FFmpeg rendering |
225
+ | [Version Control \& Collaboration](https://visualkit.hyekai.com/docs/version-control-and-collaboration) | Checkpoints, branching, 3-way merge, workspaces, claimed regions |
226
+ | [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference) | Full `visualkit` & `visualkit-doctor` CLI reference and exit codes |
227
+
228
+ ## Development
229
+
230
+ ```bash
231
+ uv sync --group dev
232
+ uv run pytest tests -ra
233
+ uv run ruff check src tests
234
+ uv run mypy src
235
+ uv run pyright src
236
+ mkdocs build --strict
237
+ ```
238
+
239
+ ## License
240
+
241
+ MIT — see [LICENSE](https://github.com/surajairi/visualkit/blob/main/LICENSE).
@@ -0,0 +1,196 @@
1
+ # VisualKit
2
+
3
+ **A programmable, local-first video editing engine built for developers and AI agents.**
4
+
5
+ [Website](https://visualkit.hyekai.com) · [Documentation](https://visualkit.hyekai.com/docs) · [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference) · [Agent Skills](https://visualkit.hyekai.com/docs/skills)
6
+
7
+ ---
8
+
9
+ VisualKit replaces brittle FFmpeg command strings and GUI-only timelines with a strictly typed Python engine backed by a versioned SQLite project store. Every edit is validated atomically before hitting disk, every timestamp uses exact rational arithmetic (`Fraction`), and multiple AI agents can edit disjoint windows of the same timeline in parallel without merge conflicts.
10
+
11
+ ## Why VisualKit
12
+
13
+ - **Git-like versioned timeline store**: Projects live in a single SQLite file (`project.visualkit`) with content-addressed revisions, checkpoints, undo/redo, branches, 3-way entity merges, and Git-diffable canonical JSON export/import.
14
+ - **Multi-agent claimed regions**: Lock disjoint `[start, end)` time windows on the same branch so parallel agents edit in claim-local `0.0s` coordinates with automatic downstream ripple on release.
15
+ - **Exact rational clocks & commit-time integrity**: Typed time domains (`Time`, `TimelineTime`, `ClipTime`, `SourceTime`, `AnimTime`) eliminate float drift; overlaps, out-of-bounds trims, DAG cycles, and dangling references fail atomically before commit.
16
+ - **Compositing, motion graphics & local actors**: Combine built-in visual/audio effects, track-wide adjustment clips, DAG-based Fusion node graphs, Skia-styled text/shapes/templates, and 6 local-first media actors (`ffmpeg_lut`, `bg_remove`, `rembg`, `transcribe`, `media_tools`, `local_broll`).
17
+ - **Agent-native ergonomics**: Structured `--format json` CLI output, deterministic exit codes (`0–4`), `--dry-run` validation, fast frame/grid visual previews, and ready-to-use Agent Skills (`visualkit-editing`, `visualkit-collab`).
18
+
19
+ ## Installation
20
+
21
+ Requires **Python 3.10+** and **FFmpeg / FFprobe** on `PATH`.
22
+
23
+ ```bash
24
+ # With uv (recommended)
25
+ uv add visualkit
26
+
27
+ # Or with pip
28
+ pip install visualkit
29
+ ```
30
+
31
+ ### Optional Extras
32
+
33
+ | Extra | Command | What it enables |
34
+ | --- | --- | --- |
35
+ | `style` | `uv add "visualkit[style]"` | Skia vector rasterization — **required** for `ShapeClip` and shape-based templates (without it, `TextClip` falls back to basic FFmpeg `drawtext`) |
36
+ | `render` | `uv add "visualkit[render]"` | Playwright browser automation for HTML coded visual assets |
37
+ | Both | `uv add "visualkit[style,render]"` | Full vector styling + HTML coded visuals |
38
+
39
+ For coded visual compilers (HTML and Remotion), check local dependencies with `visualkit-doctor check`.
40
+
41
+ ## 60-Second Quickstart
42
+
43
+ ### CLI Workflow (`init` → `exec` → `preview` → `render`)
44
+
45
+ ```bash
46
+ # 1. Initialize a versioned project store
47
+ visualkit init demo.visualkit --title "Launch Teaser" --fps 30 --width 1920 --height 1080 --format json
48
+
49
+ # 2. Scan media from your project folder (auto-mounted at /proj)
50
+ export VISUALKIT_PROJECT_DIR=./media
51
+ visualkit asset scan /proj --recursive --format json
52
+ ```
53
+
54
+ Write an editing script (`edit.py`) — `visualkit exec` injects `engine` (`VisualkitEngine`) and commits atomically on exit:
55
+
56
+ ```python
57
+ from visualkit import Geometry, Shadow
58
+
59
+ with engine.edit(label="create intro"):
60
+ v_bg = engine.create_track("visual", name="Background")
61
+ v_fg = engine.create_track("visual", name="Titles")
62
+
63
+ engine.add_shape(
64
+ Geometry.rect(1920, 1080),
65
+ visual_track_id=v_bg.id,
66
+ start_ts=0.0,
67
+ duration=4.0,
68
+ fill="#0F172A",
69
+ )
70
+
71
+ title = engine.add_text(
72
+ "Built with VisualKit",
73
+ visual_track_id=v_fg.id,
74
+ start_ts=0.3,
75
+ duration=3.4,
76
+ font_size=96,
77
+ color="#F8FAFC",
78
+ font_weight=700,
79
+ shadow=Shadow.drop(),
80
+ )
81
+ title.place_at(960, 540)
82
+ title.fade_in(0.4).pop_in(from_scale=0.92, duration=0.4).fade_out(0.4)
83
+ ```
84
+
85
+ ```bash
86
+ # 3. Validate without writing, then commit
87
+ visualkit exec edit.py --db demo.visualkit --dry-run --format json
88
+ visualkit exec edit.py --db demo.visualkit --format json
89
+
90
+ # 4. Preview a contact sheet before full export, then render
91
+ visualkit preview grid --db demo.visualkit --frames 6 --cols 3 -o preview.jpg --format json
92
+ visualkit render out.mp4 --db demo.visualkit --format json
93
+ ```
94
+
95
+ ### Direct Python API
96
+
97
+ ```python
98
+ from visualkit import FfmpegRenderer, RenderOptions, VisualkitEngine
99
+
100
+ with VisualkitEngine.open("demo.visualkit", fps=30, resolution=(1920, 1080)) as engine:
101
+ with engine.edit(label="add title"):
102
+ v1 = engine.create_track("visual", name="V1")
103
+ clip = engine.add_text("Hello World", visual_track_id=v1.id, start_ts=0.0, duration=3.0, font_size=72)
104
+ clip.fade_in(0.3).fade_out(0.3)
105
+
106
+ engine.save(label="initial cut")
107
+ engine.preview_grid("timeline", num_frames=4, out_path="preview.jpg")
108
+ result = FfmpegRenderer().render(engine.store, "out.mp4", options=RenderOptions())
109
+ ```
110
+
111
+ ## Core Capabilities
112
+
113
+ ### Timeline, Clips, Cropping & Speed Curves
114
+ - **Clip types**: `MediaClip`, `AudioClip`, `TextClip`, `ShapeClip`, `CodedVisualClip`, `AdjustmentClipVisual`/`Audio`, `FusionClipVisual`/`Audio`, `CompoundClipVisual`/`Audio`, and `TemplateClipVisual`/`Audio`.
115
+ - **Non-linear editing**: `move`, `trim_head`, `trim_tail`, `split(TimelineTime(...))`, `split_all`, `ripple_insert`, `ripple_delete`, `close_gap`, `shift_items`, `engine.snap(t)` for exact frame-grid snapping, and linked A/V preservation.
116
+ - **Cropping & color**: Keyframable `Transform.crop` (`crop_to` with `FitMode`, `CropAlignment`, and `source_position`), signed-offset `set_human_props(...)`, and `AudioClip.equalizer`.
117
+ - **Speed ramping**: Constant speed (`set_speed(2.0, shrink_to_fit=True)`) and piecewise speed curves (`set_speed_curve([SpeedPoint(at=..., speed=..., interpolation=LINEAR|HOLD)])`) with exact rational integration.
118
+
119
+ ### Two-Layer Keyframes, Vector Styling & Templates
120
+ - **Two-layer animation**: `Layer.PRE` (source time, replaces static base and stretches with `TimeMap`) and `Layer.POST` (cut-relative time, combines onto `PRE`/static via `ADD`, `MULTIPLY`, or `REPLACE`).
121
+ - **Motion presets**: Chainable `fade_in`, `fade_out`, `slide_in`, `slide_out`, `pop_in`, and `draw_in`, plus `LINEAR`, `HOLD`, `EASE_IN`, `EASE_OUT`, `EASE_IN_OUT`, and custom cubic `BEZIER` curves.
122
+ - **Styling & built-in templates**: Full `TextStyle`, `Geometry`, `Paint`, `Stroke`, `Shadow`, managed SIL OFL Noto fonts (downloaded on first use; see the fonts note in the style guide), and 5 parameterized templates (`title_card`, `lower_third`, `subtitle`, `callout`, `progress_ring`).
123
+
124
+ ### Effects, Adjustment Clips & Fusion Node Graphs
125
+ - **Per-clip & track-wide effects**: `GaussianBlurEffect`, `DropShadowEffect`, `GlowEffect`, `SharpenEffect`, `PixelateEffect`, `VignetteEffect`, `ChromaKeyEffect`, `MaskEffect`, `CompressorEffect`, `ReverbEffect`, `EchoEffect`, `DistortionEffect`, `PanEffect`, and `AdjustmentClip`.
126
+ - **Fusion DAGs**: Build validated acyclic node graphs (`FusionInputNode`, `FusionGeneratorNode`, `FusionEffectNode`, `FusionColorGradeNode`, `FusionMaskNode`, `FusionApplyMaskNode`, `FusionMergeNode`, `FusionPluginNode`, `FusionAudioMixNode`, `FusionOutputNode`) usable as standalone `FusionClip`s or reusable single-input `graph.as_effect()` stacks.
127
+
128
+ ### Compound Clips & Template Repeaters
129
+ - Package reusable nested sequences as `CompoundClip`s with typed exposed `VariableSpec`s (`string`, `number`, `integer`, `boolean`, `json`, `asset`).
130
+ - Drive staggered lists, bullet overlays, and lower-third sequences with `SequenceHandle.set_repeater(...)` and `engine.add_template_clip(...)`.
131
+
132
+ ### Built-in Local Actors
133
+
134
+ Local-first media plugins accessible via `visualkit actor <slug> ...`, `visualkit actors run`, and `FusionPluginNode` (pass `--save-asset` to auto-register outputs into `AssetResolver`):
135
+
136
+ | Actor | Surfaces | Purpose |
137
+ | --- | --- | --- |
138
+ | `ffmpeg_lut` | CLI, Fusion (native) | 3D `.cube` LUT grading (`teal_orange`, `cinematic_warm`, `noir_bw`, `vintage_fade`, `crisp_daylight`, `kodak_2383_d65`, or custom `.cube`) with RGBA intensity blending |
139
+ | `bg_remove` | CLI, Fusion (native) | Fast zero-dependency FFmpeg chroma-key removal with alpha-only `feather` |
140
+ | `rembg` | CLI, Fusion | Local AI subject segmentation via ONNX (CPU/CUDA/CoreML, raw FFmpeg pipe streaming) |
141
+ | `transcribe` | CLI | Unified local ASR (`faster_whisper`, `whisperx`, `insanely_fast_whisper`) with word-level JSON/SRT/VTT output |
142
+ | `media_tools` | CLI | Fast FFmpeg/FFprobe helpers: `probe`, `extract-frames`, `detect-scenes`, and `trim` |
143
+ | `local_broll` | CLI | Offline synthetic B-roll MP4 generator for rapid prototyping and tests |
144
+
145
+ ### Director's Cut, Assets & Collaboration
146
+ - **Director's Cut**: Non-rendered `EditingPlan`, project stage registry, nested `StoryboardClip`s with per-stage hints, and time- or item-anchored `DirectorMarker`s that ripple with edits.
147
+ - **Assets & Coded Visuals**: `AssetResolver` with virtual mounts (`/proj`, `/home`, `/global`, plus custom mounts), proxy variants, FTS5 search, path-free `AssetPin` staleness checks, and cached HTML/Remotion coded visuals.
148
+ - **Collaboration & Claimed Regions**: Checkpoints (`checkpoint`, `diff`, `restore`, `revert`), branches & 3-way merge (`branch`, `merge`), bound sessions (`workspace`), and disjoint parallel editing (`workspace new --claim START END --on-straddle split`, `claim release`, `claim abort`).
149
+
150
+ ## Built for AI Agents
151
+
152
+ VisualKit ships two structured Agent Skills under [skills/](https://github.com/SurajAiri/visualkit/tree/main/skills) designed for progressive disclosure:
153
+
154
+ - [skills/visualkit-editing/SKILL.md](https://visualkit.hyekai.com/downloads/skills/visualkit-editing.zip) — End-to-end editing playbook plus focused references for effects/Fusion, compound/repeaters, and Director's Cut/coded visuals.
155
+ - [skills/visualkit-collab/SKILL.md](https://visualkit.hyekai.com/downloads/skills/visualkit-collab.zip) — Checkpoints, branching, 3-way merges, workspaces, and multi-agent claimed regions.
156
+
157
+ New to directing an agent? [Getting Started (Human)](https://visualkit.hyekai.com/docs/getting-started-human) walks through importing the skills, pointing the agent at your footage, and reviewing previews before you render.
158
+
159
+ Every CLI command supports `--format json` with deterministic exit codes (`0=ok`, `1=validation_error`, `2=script_crash`, `3=merge_conflict`, `4=claim_refused`).
160
+
161
+ ## Documentation
162
+
163
+ Full guides live in [docs/](https://visualkit.hyekai.com/docs):
164
+
165
+ | Guide | Topic |
166
+ | --- | --- |
167
+ | [Getting Started](https://visualkit.hyekai.com/docs/getting-started) | Installation, FFmpeg/extras, and your first 5-minute project |
168
+ | [Getting Started (Human)](https://visualkit.hyekai.com/docs/getting-started-human) | Directing an AI agent (Claude Code, Codex, Cursor, Gemini CLI): import the skills, give it your assets, review previews, and render |
169
+ | [Agent Skills](https://visualkit.hyekai.com/docs/skills) | Download `visualkit-editing` and `visualkit-collab`, and where each agent expects them |
170
+ | [Core Concepts](https://visualkit.hyekai.com/docs/core-concepts) | Exact rational clocks, flat entities, transactions, validation |
171
+ | [Assets \& Coded Visuals](https://visualkit.hyekai.com/docs/assets) | Virtual mounts (`/proj`), variants, `AssetPin`, HTML & Remotion |
172
+ | [Clips \& Timeline Editing](https://visualkit.hyekai.com/docs/clips-and-timeline) | Tracks, cropping, human color scales, speed curves, NLE & ripple ops |
173
+ | [Keyframes \& Animation](https://visualkit.hyekai.com/docs/keyframes-and-animation) | `PRE`/`POST` layers, `Combine` semantics, Bezier & motion presets |
174
+ | [Style, Text, Shapes \& Templates](https://visualkit.hyekai.com/docs/style-text-shapes-templates) | `TextClip`, `ShapeClip`, `Geometry`, `Paint`, Skia & templates |
175
+ | [Effects \& Fusion Graphs](https://visualkit.hyekai.com/docs/effects-and-fusion) | Visual/audio effects, adjustment clips, Fusion DAGs & `as_effect()` |
176
+ | [Compound \& Template Clips](https://visualkit.hyekai.com/docs/compound-and-template-clips) | Nested sequences, exposed variables, and repeater templates |
177
+ | [Director's Cut](https://visualkit.hyekai.com/docs/director-cut) | Stages, storyboards, markers, and non-rendered review layer |
178
+ | [Built-in \& Local Actors](https://visualkit.hyekai.com/docs/actors) | All 6 local-first actors, CLI subcommands, and Fusion integration |
179
+ | [Preview \& Rendering](https://visualkit.hyekai.com/docs/preview-and-rendering) | Frame/grid/video/compare previews and FFmpeg rendering |
180
+ | [Version Control \& Collaboration](https://visualkit.hyekai.com/docs/version-control-and-collaboration) | Checkpoints, branching, 3-way merge, workspaces, claimed regions |
181
+ | [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference) | Full `visualkit` & `visualkit-doctor` CLI reference and exit codes |
182
+
183
+ ## Development
184
+
185
+ ```bash
186
+ uv sync --group dev
187
+ uv run pytest tests -ra
188
+ uv run ruff check src tests
189
+ uv run mypy src
190
+ uv run pyright src
191
+ mkdocs build --strict
192
+ ```
193
+
194
+ ## License
195
+
196
+ MIT — see [LICENSE](https://github.com/surajairi/visualkit/blob/main/LICENSE).
@@ -0,0 +1,113 @@
1
+ [build-system]
2
+ requires = ["setuptools>=45", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "visualkit"
7
+ version = "3.0.1"
8
+ description = "Programmable, local-first video editing engine for developers and AI agents: versioned SQLite timelines, exact rational clocks, Fusion node graphs, motion graphics, local actors, multi-agent claimed regions, and FFmpeg rendering."
9
+ readme = "README.md"
10
+ authors = [{ name = "Suraj Airi", email = "surajairi.ml@gmail.com" }]
11
+ license = { text = "MIT" }
12
+ keywords = [
13
+ "video-editing",
14
+ "ai-agents",
15
+ "programmatic-video",
16
+ "motion-graphics",
17
+ "ffmpeg",
18
+ "compositing",
19
+ "node-graph",
20
+ "timeline",
21
+ "keyframes",
22
+ "remotion",
23
+ "skia",
24
+ "sqlite",
25
+ ]
26
+ classifiers = [
27
+ "Development Status :: 4 - Beta",
28
+ "Environment :: Console",
29
+ "Intended Audience :: Developers",
30
+ "License :: OSI Approved :: MIT License",
31
+ "Operating System :: OS Independent",
32
+ "Programming Language :: Python :: 3",
33
+ "Programming Language :: Python :: 3.10",
34
+ "Programming Language :: Python :: 3.11",
35
+ "Programming Language :: Python :: 3.12",
36
+ "Topic :: Multimedia :: Video",
37
+ "Topic :: Multimedia :: Video :: Non-Linear Editor",
38
+ "Topic :: Multimedia :: Graphics",
39
+ "Topic :: Software Development :: Libraries :: Python Modules",
40
+ "Typing :: Typed",
41
+ ]
42
+ requires-python = ">=3.10"
43
+ # Python-side only. The Remotion compiler additionally needs Node.js + a few npm packages + a browser; those are
44
+ # not pip-installable, so they are checked/installed by `visualkit-doctor` (see below) instead of being listed here.
45
+ dependencies = [
46
+ "pydantic>=2.13.5",
47
+ "typing-extensions>=4.16.0",
48
+ "tomli>=2.0.1; python_version < '3.11'",
49
+ ]
50
+
51
+ [project.optional-dependencies]
52
+ render = ["playwright>=1.40.0"]
53
+ style = ["skia-python>=144.1"]
54
+ dev = [
55
+ "mypy>=2.4.1",
56
+ "notebook>=7.6.2",
57
+ "pyright>=1.1.414",
58
+ "pytest>=8.0.0",
59
+ "pytest-asyncio>=0.24.0",
60
+ "ruff>=0.12.1",
61
+ ]
62
+
63
+ [project.scripts]
64
+ visualkit = "visualkit.cli:main"
65
+ # Check whether the coded-asset compilers are ready and install what is missing:
66
+ # visualkit-doctor list | check [SLUG] [--deep] | install [SLUG] [--dry-run] | steps SLUG
67
+ visualkit-doctor = "visualkit.coded.doctor:main"
68
+
69
+ [dependency-groups]
70
+ dev = [
71
+ "mypy>=2.4.1",
72
+ "notebook>=7.6.2",
73
+ "numpy>=2.2.6",
74
+ "pillow>=12.3.0",
75
+ "pyright>=1.1.414",
76
+ "pytest>=8.0.0",
77
+ "pytest-asyncio>=0.24.0",
78
+ "ruff>=0.12.1",
79
+ ]
80
+
81
+
82
+ [tool.setuptools.packages.find]
83
+ where = ["src"]
84
+
85
+ [tool.setuptools.package-dir]
86
+ "" = "src"
87
+
88
+ [tool.setuptools.package-data]
89
+ visualkit = [
90
+ "py.typed",
91
+ "style/fonts/*.txt",
92
+ "style/fonts/*.md",
93
+ "actors/builtins/*/*.toml",
94
+ ]
95
+
96
+ [tool.pytest.ini_options]
97
+ pythonpath = ["src"]
98
+ testpaths = ["tests"]
99
+ asyncio_mode = "strict"
100
+ asyncio_default_fixture_loop_scope = "function"
101
+ markers = [
102
+ "browser: drives a real headless Chrome/Chromium via Playwright (skipped when unavailable)",
103
+ "video: renders real HTML video via Playwright, Chrome/Chromium, and ffmpeg (skipped when unavailable)",
104
+ "network: downloads from npm (and maybe the browser); only runs when VISUALKIT_TEST_INSTALL=1",
105
+ "remotion: needs Node.js, the Remotion npm packages and a browser; slow, ~20 s per distinct scene (skipped when not ready)",
106
+ ]
107
+
108
+
109
+ [project.urls]
110
+ Homepage = "https://visualkit.hyekai.com"
111
+ Documentation = "https://visualkit.hyekai.com/docs"
112
+ Repository = "https://github.com/surajairi/visualkit"
113
+ Issues = "https://github.com/surajairi/visualkit/issues"