visualkit 2.0.1__tar.gz → 3.0.0__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 (205) hide show
  1. visualkit-3.0.0/PKG-INFO +237 -0
  2. visualkit-3.0.0/README.md +192 -0
  3. visualkit-3.0.0/pyproject.toml +113 -0
  4. visualkit-3.0.0/src/visualkit/__init__.py +850 -0
  5. visualkit-3.0.0/src/visualkit/__main__.py +8 -0
  6. visualkit-3.0.0/src/visualkit/actors/__init__.py +237 -0
  7. visualkit-3.0.0/src/visualkit/actors/_server_config.py +27 -0
  8. visualkit-3.0.0/src/visualkit/actors/base.py +368 -0
  9. visualkit-3.0.0/src/visualkit/actors/builtins/__init__.py +87 -0
  10. visualkit-3.0.0/src/visualkit/actors/builtins/bg_remove/__init__.py +7 -0
  11. visualkit-3.0.0/src/visualkit/actors/builtins/bg_remove/actor.py +327 -0
  12. visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/__init__.py +11 -0
  13. visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/actor.py +491 -0
  14. visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/index.toml +65 -0
  15. visualkit-3.0.0/src/visualkit/actors/builtins/local_broll/__init__.py +7 -0
  16. visualkit-3.0.0/src/visualkit/actors/builtins/local_broll/actor.py +166 -0
  17. visualkit-3.0.0/src/visualkit/actors/builtins/media_tools/__init__.py +7 -0
  18. visualkit-3.0.0/src/visualkit/actors/builtins/media_tools/actor.py +281 -0
  19. visualkit-3.0.0/src/visualkit/actors/builtins/rembg/__init__.py +27 -0
  20. visualkit-3.0.0/src/visualkit/actors/builtins/rembg/actor.py +1114 -0
  21. visualkit-3.0.0/src/visualkit/actors/builtins/rembg/index.toml +86 -0
  22. visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/__init__.py +43 -0
  23. visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/actor.py +1075 -0
  24. visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/index.toml +82 -0
  25. visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/schema.py +195 -0
  26. visualkit-3.0.0/src/visualkit/actors/errors.py +87 -0
  27. visualkit-3.0.0/src/visualkit/actors/installer.py +342 -0
  28. visualkit-3.0.0/src/visualkit/actors/lockfile.py +312 -0
  29. visualkit-3.0.0/src/visualkit/actors/manifest.py +459 -0
  30. visualkit-3.0.0/src/visualkit/actors/marketplace.py +192 -0
  31. visualkit-3.0.0/src/visualkit/actors/materializer.py +282 -0
  32. visualkit-3.0.0/src/visualkit/actors/registry.py +480 -0
  33. visualkit-3.0.0/src/visualkit/actors/resources.py +391 -0
  34. visualkit-3.0.0/src/visualkit/actors/runners.py +515 -0
  35. visualkit-3.0.0/src/visualkit/assets/__init__.py +80 -0
  36. visualkit-3.0.0/src/visualkit/assets/base.py +108 -0
  37. visualkit-3.0.0/src/visualkit/assets/basic.py +287 -0
  38. visualkit-3.0.0/src/visualkit/assets/pin.py +541 -0
  39. visualkit-3.0.0/src/visualkit/assets/resolver/__init__.py +57 -0
  40. visualkit-3.0.0/src/visualkit/assets/resolver/errors.py +53 -0
  41. visualkit-3.0.0/src/visualkit/assets/resolver/media.py +564 -0
  42. visualkit-3.0.0/src/visualkit/assets/resolver/models.py +105 -0
  43. visualkit-3.0.0/src/visualkit/assets/resolver/paths.py +136 -0
  44. visualkit-3.0.0/src/visualkit/assets/resolver/resolver.py +1300 -0
  45. visualkit-3.0.0/src/visualkit/assets/resolver/store.py +530 -0
  46. visualkit-3.0.0/src/visualkit/assets/resolver/vfs.py +267 -0
  47. visualkit-3.0.0/src/visualkit/assets/resolver/view.py +158 -0
  48. visualkit-3.0.0/src/visualkit/cli/__init__.py +56 -0
  49. visualkit-3.0.0/src/visualkit/cli/__main__.py +9 -0
  50. visualkit-3.0.0/src/visualkit/cli/actors.py +479 -0
  51. visualkit-3.0.0/src/visualkit/cli/assets.py +948 -0
  52. visualkit-3.0.0/src/visualkit/cli/common.py +135 -0
  53. visualkit-3.0.0/src/visualkit/cli/config.py +270 -0
  54. visualkit-3.0.0/src/visualkit/cli/director.py +1127 -0
  55. visualkit-3.0.0/src/visualkit/cli/engine.py +840 -0
  56. visualkit-3.0.0/src/visualkit/cli/preview.py +353 -0
  57. visualkit-3.0.0/src/visualkit/cli/render.py +142 -0
  58. visualkit-3.0.0/src/visualkit/clips/__init__.py +528 -0
  59. visualkit-3.0.0/src/visualkit/clips/animation/__init__.py +43 -0
  60. visualkit-3.0.0/src/visualkit/clips/animation/curve.py +305 -0
  61. visualkit-3.0.0/src/visualkit/clips/animation/keyframe.py +375 -0
  62. visualkit-3.0.0/src/visualkit/clips/animation/keyframe_handler.py +1407 -0
  63. visualkit-3.0.0/src/visualkit/clips/animation/time_map.py +565 -0
  64. visualkit-3.0.0/src/visualkit/clips/base.py +223 -0
  65. visualkit-3.0.0/src/visualkit/clips/clips.py +753 -0
  66. visualkit-3.0.0/src/visualkit/clips/director.py +1628 -0
  67. visualkit-3.0.0/src/visualkit/clips/effects.py +669 -0
  68. visualkit-3.0.0/src/visualkit/clips/entities.py +379 -0
  69. visualkit-3.0.0/src/visualkit/clips/errors.py +152 -0
  70. visualkit-3.0.0/src/visualkit/clips/fusion.py +844 -0
  71. visualkit-3.0.0/src/visualkit/clips/human_props.py +369 -0
  72. visualkit-3.0.0/src/visualkit/clips/integrity.py +2608 -0
  73. visualkit-3.0.0/src/visualkit/clips/item.py +558 -0
  74. visualkit-3.0.0/src/visualkit/clips/props.py +320 -0
  75. visualkit-3.0.0/src/visualkit/clips/references.py +69 -0
  76. visualkit-3.0.0/src/visualkit/clips/style.py +511 -0
  77. visualkit-3.0.0/src/visualkit/clips/svg_path.py +339 -0
  78. visualkit-3.0.0/src/visualkit/clips/timeline.py +1622 -0
  79. visualkit-3.0.0/src/visualkit/clips/timing.py +97 -0
  80. visualkit-3.0.0/src/visualkit/clips/variables.py +1138 -0
  81. visualkit-3.0.0/src/visualkit/coded/__init__.py +46 -0
  82. visualkit-3.0.0/src/visualkit/coded/base.py +79 -0
  83. visualkit-3.0.0/src/visualkit/coded/browser.py +147 -0
  84. visualkit-3.0.0/src/visualkit/coded/caller.py +272 -0
  85. visualkit-3.0.0/src/visualkit/coded/dependencies.py +243 -0
  86. visualkit-3.0.0/src/visualkit/coded/doctor.py +180 -0
  87. visualkit-3.0.0/src/visualkit/coded/errors.py +29 -0
  88. visualkit-3.0.0/src/visualkit/coded/html/__init__.py +13 -0
  89. visualkit-3.0.0/src/visualkit/coded/html/compiler.py +672 -0
  90. visualkit-3.0.0/src/visualkit/coded/html/video.py +422 -0
  91. visualkit-3.0.0/src/visualkit/coded/params.py +188 -0
  92. visualkit-3.0.0/src/visualkit/coded/remotion/__init__.py +10 -0
  93. visualkit-3.0.0/src/visualkit/coded/remotion/compiler.py +697 -0
  94. visualkit-3.0.0/src/visualkit/coded/remotion/runner.py +343 -0
  95. visualkit-3.0.0/src/visualkit/engine/__init__.py +178 -0
  96. visualkit-3.0.0/src/visualkit/engine/claims.py +534 -0
  97. visualkit-3.0.0/src/visualkit/engine/codec.py +338 -0
  98. visualkit-3.0.0/src/visualkit/engine/director_handles.py +1183 -0
  99. visualkit-3.0.0/src/visualkit/engine/draft.py +471 -0
  100. visualkit-3.0.0/src/visualkit/engine/engine.py +3754 -0
  101. visualkit-3.0.0/src/visualkit/engine/errors.py +128 -0
  102. visualkit-3.0.0/src/visualkit/engine/export_import.py +318 -0
  103. visualkit-3.0.0/src/visualkit/engine/handles.py +3172 -0
  104. visualkit-3.0.0/src/visualkit/engine/runner.py +890 -0
  105. visualkit-3.0.0/src/visualkit/engine/session.py +299 -0
  106. visualkit-3.0.0/src/visualkit/engine/store/__init__.py +52 -0
  107. visualkit-3.0.0/src/visualkit/engine/store/diff_merge.py +641 -0
  108. visualkit-3.0.0/src/visualkit/engine/store/history.py +741 -0
  109. visualkit-3.0.0/src/visualkit/engine/store/liveness.py +37 -0
  110. visualkit-3.0.0/src/visualkit/engine/store/models.py +279 -0
  111. visualkit-3.0.0/src/visualkit/engine/store/schema.py +97 -0
  112. visualkit-3.0.0/src/visualkit/engine/store/store.py +1415 -0
  113. visualkit-3.0.0/src/visualkit/engine/store/workspaces.py +1403 -0
  114. visualkit-3.0.0/src/visualkit/export/__init__.py +88 -0
  115. visualkit-3.0.0/src/visualkit/export/base.py +154 -0
  116. visualkit-3.0.0/src/visualkit/export/ffmpeg/__init__.py +22 -0
  117. visualkit-3.0.0/src/visualkit/export/ffmpeg/effects_fusion.py +2282 -0
  118. visualkit-3.0.0/src/visualkit/export/ffmpeg/helpers.py +173 -0
  119. visualkit-3.0.0/src/visualkit/export/ffmpeg/probe.py +301 -0
  120. visualkit-3.0.0/src/visualkit/export/ffmpeg/renderer.py +3011 -0
  121. visualkit-3.0.0/src/visualkit/export/plan.py +2369 -0
  122. visualkit-3.0.0/src/visualkit/export/text.py +280 -0
  123. visualkit-3.0.0/src/visualkit/export/window.py +78 -0
  124. visualkit-3.0.0/src/visualkit/preview/__init__.py +55 -0
  125. visualkit-3.0.0/src/visualkit/preview/facade.py +398 -0
  126. visualkit-3.0.0/src/visualkit/preview/grid.py +354 -0
  127. visualkit-3.0.0/src/visualkit/preview/models.py +201 -0
  128. visualkit-3.0.0/src/visualkit/preview/service.py +1105 -0
  129. visualkit-3.0.0/src/visualkit/style/__init__.py +148 -0
  130. visualkit-3.0.0/src/visualkit/style/fonts/FONTS.md +24 -0
  131. visualkit-3.0.0/src/visualkit/style/fonts/LICENSE-NotoColorEmoji-OFL.txt +87 -0
  132. visualkit-3.0.0/src/visualkit/style/fonts/LICENSE-OFL.txt +94 -0
  133. visualkit-3.0.0/src/visualkit/style/fonts.py +559 -0
  134. visualkit-3.0.0/src/visualkit/style/raster.py +321 -0
  135. visualkit-3.0.0/src/visualkit/style/skia_raster.py +1334 -0
  136. visualkit-3.0.0/src/visualkit/style/templates.py +1092 -0
  137. visualkit-3.0.0/src/visualkit/tier1.py +77 -0
  138. visualkit-3.0.0/src/visualkit/utils/__init__.py +16 -0
  139. visualkit-3.0.0/src/visualkit/utils/base_model.py +137 -0
  140. {visualkit-2.0.1 → visualkit-3.0.0}/src/visualkit/utils/exceptions.py +29 -1
  141. visualkit-3.0.0/src/visualkit/utils/time.py +1153 -0
  142. visualkit-3.0.0/src/visualkit/utils/utility.py +118 -0
  143. visualkit-3.0.0/src/visualkit.egg-info/PKG-INFO +237 -0
  144. visualkit-3.0.0/src/visualkit.egg-info/SOURCES.txt +155 -0
  145. visualkit-3.0.0/src/visualkit.egg-info/entry_points.txt +3 -0
  146. visualkit-3.0.0/src/visualkit.egg-info/requires.txt +19 -0
  147. {visualkit-2.0.1 → visualkit-3.0.0}/src/visualkit.egg-info/top_level.txt +0 -1
  148. visualkit-3.0.0/tests/test_audit_regressions.py +303 -0
  149. visualkit-3.0.0/tests/test_pre_doc_root_fixes.py +170 -0
  150. visualkit-3.0.0/tests/test_pre_doc_stress_and_perf.py +340 -0
  151. visualkit-3.0.0/tests/test_preview_and_renderer_root_fixes.py +487 -0
  152. visualkit-3.0.0/tests/test_ux_fixes.py +297 -0
  153. visualkit-2.0.1/PKG-INFO +0 -225
  154. visualkit-2.0.1/README.md +0 -200
  155. visualkit-2.0.1/pyproject.toml +0 -69
  156. visualkit-2.0.1/src/visualkit/__init__.py +0 -100
  157. visualkit-2.0.1/src/visualkit/__main__.py +0 -11
  158. visualkit-2.0.1/src/visualkit/coded_visual/__init__.py +0 -8
  159. visualkit-2.0.1/src/visualkit/coded_visual/browser.py +0 -192
  160. visualkit-2.0.1/src/visualkit/coded_visual/capture.py +0 -227
  161. visualkit-2.0.1/src/visualkit/coded_visual/compiler.py +0 -438
  162. visualkit-2.0.1/src/visualkit/coded_visual/project.py +0 -186
  163. visualkit-2.0.1/src/visualkit/engine/__init__.py +0 -8
  164. visualkit-2.0.1/src/visualkit/engine/asset_resolver.py +0 -54
  165. visualkit-2.0.1/src/visualkit/engine/pipeline.py +0 -344
  166. visualkit-2.0.1/src/visualkit/exporters/__init__.py +0 -9
  167. visualkit-2.0.1/src/visualkit/exporters/base.py +0 -63
  168. visualkit-2.0.1/src/visualkit/exporters/resolve.py +0 -873
  169. visualkit-2.0.1/src/visualkit/exporters/video.py +0 -557
  170. visualkit-2.0.1/src/visualkit/models/__init__.py +0 -72
  171. visualkit-2.0.1/src/visualkit/models/clips/__init__.py +0 -44
  172. visualkit-2.0.1/src/visualkit/models/clips/audio.py +0 -30
  173. visualkit-2.0.1/src/visualkit/models/clips/base.py +0 -88
  174. visualkit-2.0.1/src/visualkit/models/clips/coded_visual.py +0 -375
  175. visualkit-2.0.1/src/visualkit/models/clips/compound.py +0 -287
  176. visualkit-2.0.1/src/visualkit/models/clips/media.py +0 -43
  177. visualkit-2.0.1/src/visualkit/models/clips/text.py +0 -89
  178. visualkit-2.0.1/src/visualkit/models/clips/visual.py +0 -102
  179. visualkit-2.0.1/src/visualkit/models/timeline.py +0 -1049
  180. visualkit-2.0.1/src/visualkit/models/variable.py +0 -186
  181. visualkit-2.0.1/src/visualkit/utils/__init__.py +0 -0
  182. visualkit-2.0.1/src/visualkit/utils/base_model.py +0 -40
  183. visualkit-2.0.1/src/visualkit/utils/time.py +0 -498
  184. visualkit-2.0.1/src/visualkit.egg-info/PKG-INFO +0 -225
  185. visualkit-2.0.1/src/visualkit.egg-info/SOURCES.txt +0 -53
  186. visualkit-2.0.1/src/visualkit.egg-info/requires.txt +0 -4
  187. visualkit-2.0.1/tests/test_clip_editing.py +0 -609
  188. visualkit-2.0.1/tests/test_coded_visual_compiler.py +0 -237
  189. visualkit-2.0.1/tests/test_package_exports.py +0 -28
  190. visualkit-2.0.1/tests/test_pipeline_semantics.py +0 -199
  191. visualkit-2.0.1/tests/test_rendering.py +0 -450
  192. visualkit-2.0.1/tests/test_resolve_correctness.py +0 -170
  193. visualkit-2.0.1/tests/test_resolve_exporter.py +0 -296
  194. visualkit-2.0.1/tests/test_time_and_variables.py +0 -235
  195. visualkit-2.0.1/tests/test_timeline.py +0 -116
  196. visualkit-2.0.1/tests/test_timeline_integrity.py +0 -241
  197. visualkit-2.0.1/tests/test_timeline_pipeline.py +0 -396
  198. visualkit-2.0.1/tests/test_variable_inspection.py +0 -91
  199. visualkit-2.0.1/tests/test_variables_and_clips.py +0 -236
  200. visualkit-2.0.1/tests/test_video_exporter.py +0 -340
  201. {visualkit-2.0.1 → visualkit-3.0.0}/AUTHORS.rst +0 -0
  202. {visualkit-2.0.1 → visualkit-3.0.0}/LICENSE +0 -0
  203. {visualkit-2.0.1 → visualkit-3.0.0}/setup.cfg +0 -0
  204. {visualkit-2.0.1 → visualkit-3.0.0}/src/visualkit/py.typed +0 -0
  205. {visualkit-2.0.1 → visualkit-3.0.0}/src/visualkit.egg-info/dependency_links.txt +0 -0
@@ -0,0 +1,237 @@
1
+ Metadata-Version: 2.4
2
+ Name: visualkit
3
+ Version: 3.0.0
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://surajairi.github.io/visualkit/
8
+ Project-URL: Documentation, https://surajairi.github.io/visualkit/
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) · [Issues](https://github.com/surajairi/visualkit/issues)
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://visualkit.com/docs/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
+ Every CLI command supports `--format json` with deterministic exit codes (`0=ok`, `1=validation_error`, `2=script_crash`, `3=merge_conflict`, `4=claim_refused`).
203
+
204
+ ## Documentation
205
+
206
+ Full guides live in [docs/](https://visualkit.hyekai.com/docs):
207
+
208
+ | Guide | Topic |
209
+ | --- | --- |
210
+ | [Getting Started](https://visualkit.hyekai.com/docs/getting-started.md) | Installation, FFmpeg/extras, and your first 5-minute project |
211
+ | [Core Concepts](https://visualkit.hyekai.com/docs/core-concepts.md) | Exact rational clocks, flat entities, transactions, validation |
212
+ | [Assets \& Coded Visuals](https://visualkit.hyekai.com/docs/assets.md) | Virtual mounts (`/proj`), variants, `AssetPin`, HTML & Remotion |
213
+ | [Clips \& Timeline Editing](https://visualkit.hyekai.com/docs/clips-and-timeline.md) | Tracks, cropping, human color scales, speed curves, NLE & ripple ops |
214
+ | [Keyframes \& Animation](https://visualkit.hyekai.com/docs/keyframes-and-animation.md) | `PRE`/`POST` layers, `Combine` semantics, Bezier & motion presets |
215
+ | [Style, Text, Shapes \& Templates](https://visualkit.hyekai.com/docs/style-text-shapes-templates.md) | `TextClip`, `ShapeClip`, `Geometry`, `Paint`, Skia & templates |
216
+ | [Effects \& Fusion Graphs](https://visualkit.hyekai.com/docs/effects-and-fusion.md) | Visual/audio effects, adjustment clips, Fusion DAGs & `as_effect()` |
217
+ | [Compound \& Template Clips](https://visualkit.hyekai.com/docs/compound-and-template-clips.md) | Nested sequences, exposed variables, and repeater templates |
218
+ | [Director's Cut](https://visualkit.hyekai.com/docs/director-cut.md) | Stages, storyboards, markers, and non-rendered review layer |
219
+ | [Built-in \& Local Actors](https://visualkit.hyekai.com/docs/actors.md) | All 6 local-first actors, CLI subcommands, and Fusion integration |
220
+ | [Preview \& Rendering](https://visualkit.hyekai.com/docs/preview-and-rendering.md) | Frame/grid/video/compare previews and FFmpeg rendering |
221
+ | [Version Control \& Collaboration](https://visualkit.hyekai.com/docs/version-control-and-collaboration.md) | Checkpoints, branching, 3-way merge, workspaces, claimed regions |
222
+ | [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference.md) | Full `visualkit` & `visualkit-doctor` CLI reference and exit codes |
223
+
224
+ ## Development
225
+
226
+ ```bash
227
+ uv sync --group dev
228
+ uv run pytest tests -ra
229
+ uv run ruff check src tests
230
+ uv run mypy src
231
+ uv run pyright src
232
+ mkdocs build --strict
233
+ ```
234
+
235
+ ## License
236
+
237
+ MIT — see [LICENSE](https://github.com/surajairi/visualkit/blob/main/LICENSE).
@@ -0,0 +1,192 @@
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) · [Issues](https://github.com/surajairi/visualkit/issues)
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://visualkit.com/docs/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
+ Every CLI command supports `--format json` with deterministic exit codes (`0=ok`, `1=validation_error`, `2=script_crash`, `3=merge_conflict`, `4=claim_refused`).
158
+
159
+ ## Documentation
160
+
161
+ Full guides live in [docs/](https://visualkit.hyekai.com/docs):
162
+
163
+ | Guide | Topic |
164
+ | --- | --- |
165
+ | [Getting Started](https://visualkit.hyekai.com/docs/getting-started.md) | Installation, FFmpeg/extras, and your first 5-minute project |
166
+ | [Core Concepts](https://visualkit.hyekai.com/docs/core-concepts.md) | Exact rational clocks, flat entities, transactions, validation |
167
+ | [Assets \& Coded Visuals](https://visualkit.hyekai.com/docs/assets.md) | Virtual mounts (`/proj`), variants, `AssetPin`, HTML & Remotion |
168
+ | [Clips \& Timeline Editing](https://visualkit.hyekai.com/docs/clips-and-timeline.md) | Tracks, cropping, human color scales, speed curves, NLE & ripple ops |
169
+ | [Keyframes \& Animation](https://visualkit.hyekai.com/docs/keyframes-and-animation.md) | `PRE`/`POST` layers, `Combine` semantics, Bezier & motion presets |
170
+ | [Style, Text, Shapes \& Templates](https://visualkit.hyekai.com/docs/style-text-shapes-templates.md) | `TextClip`, `ShapeClip`, `Geometry`, `Paint`, Skia & templates |
171
+ | [Effects \& Fusion Graphs](https://visualkit.hyekai.com/docs/effects-and-fusion.md) | Visual/audio effects, adjustment clips, Fusion DAGs & `as_effect()` |
172
+ | [Compound \& Template Clips](https://visualkit.hyekai.com/docs/compound-and-template-clips.md) | Nested sequences, exposed variables, and repeater templates |
173
+ | [Director's Cut](https://visualkit.hyekai.com/docs/director-cut.md) | Stages, storyboards, markers, and non-rendered review layer |
174
+ | [Built-in \& Local Actors](https://visualkit.hyekai.com/docs/actors.md) | All 6 local-first actors, CLI subcommands, and Fusion integration |
175
+ | [Preview \& Rendering](https://visualkit.hyekai.com/docs/preview-and-rendering.md) | Frame/grid/video/compare previews and FFmpeg rendering |
176
+ | [Version Control \& Collaboration](https://visualkit.hyekai.com/docs/version-control-and-collaboration.md) | Checkpoints, branching, 3-way merge, workspaces, claimed regions |
177
+ | [CLI Reference](https://visualkit.hyekai.com/docs/cli-reference.md) | Full `visualkit` & `visualkit-doctor` CLI reference and exit codes |
178
+
179
+ ## Development
180
+
181
+ ```bash
182
+ uv sync --group dev
183
+ uv run pytest tests -ra
184
+ uv run ruff check src tests
185
+ uv run mypy src
186
+ uv run pyright src
187
+ mkdocs build --strict
188
+ ```
189
+
190
+ ## License
191
+
192
+ 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.0"
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://surajairi.github.io/visualkit/"
111
+ Documentation = "https://surajairi.github.io/visualkit/"
112
+ Repository = "https://github.com/surajairi/visualkit"
113
+ Issues = "https://github.com/surajairi/visualkit/issues"