visualkit 2.1.0__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.
- visualkit-3.0.0/PKG-INFO +237 -0
- visualkit-3.0.0/README.md +192 -0
- visualkit-3.0.0/pyproject.toml +113 -0
- visualkit-3.0.0/src/visualkit/__init__.py +850 -0
- visualkit-3.0.0/src/visualkit/__main__.py +8 -0
- visualkit-3.0.0/src/visualkit/actors/__init__.py +237 -0
- visualkit-3.0.0/src/visualkit/actors/_server_config.py +27 -0
- visualkit-3.0.0/src/visualkit/actors/base.py +368 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/__init__.py +87 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/bg_remove/__init__.py +7 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/bg_remove/actor.py +327 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/__init__.py +11 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/actor.py +491 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/ffmpeg_lut/index.toml +65 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/local_broll/__init__.py +7 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/local_broll/actor.py +166 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/media_tools/__init__.py +7 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/media_tools/actor.py +281 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/rembg/__init__.py +27 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/rembg/actor.py +1114 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/rembg/index.toml +86 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/__init__.py +43 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/actor.py +1075 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/index.toml +82 -0
- visualkit-3.0.0/src/visualkit/actors/builtins/transcribe/schema.py +195 -0
- visualkit-3.0.0/src/visualkit/actors/errors.py +87 -0
- visualkit-3.0.0/src/visualkit/actors/installer.py +342 -0
- visualkit-3.0.0/src/visualkit/actors/lockfile.py +312 -0
- visualkit-3.0.0/src/visualkit/actors/manifest.py +459 -0
- visualkit-3.0.0/src/visualkit/actors/marketplace.py +192 -0
- visualkit-3.0.0/src/visualkit/actors/materializer.py +282 -0
- visualkit-3.0.0/src/visualkit/actors/registry.py +480 -0
- visualkit-3.0.0/src/visualkit/actors/resources.py +391 -0
- visualkit-3.0.0/src/visualkit/actors/runners.py +515 -0
- visualkit-3.0.0/src/visualkit/assets/__init__.py +80 -0
- visualkit-3.0.0/src/visualkit/assets/base.py +108 -0
- visualkit-3.0.0/src/visualkit/assets/basic.py +287 -0
- visualkit-3.0.0/src/visualkit/assets/pin.py +541 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/__init__.py +57 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/errors.py +53 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/media.py +564 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/models.py +105 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/paths.py +136 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/resolver.py +1300 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/store.py +530 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/vfs.py +267 -0
- visualkit-3.0.0/src/visualkit/assets/resolver/view.py +158 -0
- visualkit-3.0.0/src/visualkit/cli/__init__.py +56 -0
- visualkit-3.0.0/src/visualkit/cli/__main__.py +9 -0
- visualkit-3.0.0/src/visualkit/cli/actors.py +479 -0
- visualkit-3.0.0/src/visualkit/cli/assets.py +948 -0
- visualkit-3.0.0/src/visualkit/cli/common.py +135 -0
- visualkit-3.0.0/src/visualkit/cli/config.py +270 -0
- visualkit-3.0.0/src/visualkit/cli/director.py +1127 -0
- visualkit-3.0.0/src/visualkit/cli/engine.py +840 -0
- visualkit-3.0.0/src/visualkit/cli/preview.py +353 -0
- visualkit-3.0.0/src/visualkit/cli/render.py +142 -0
- visualkit-3.0.0/src/visualkit/clips/__init__.py +528 -0
- visualkit-3.0.0/src/visualkit/clips/animation/__init__.py +43 -0
- visualkit-3.0.0/src/visualkit/clips/animation/curve.py +305 -0
- visualkit-3.0.0/src/visualkit/clips/animation/keyframe.py +375 -0
- visualkit-3.0.0/src/visualkit/clips/animation/keyframe_handler.py +1407 -0
- visualkit-3.0.0/src/visualkit/clips/animation/time_map.py +565 -0
- visualkit-3.0.0/src/visualkit/clips/base.py +223 -0
- visualkit-3.0.0/src/visualkit/clips/clips.py +753 -0
- visualkit-3.0.0/src/visualkit/clips/director.py +1628 -0
- visualkit-3.0.0/src/visualkit/clips/effects.py +669 -0
- visualkit-3.0.0/src/visualkit/clips/entities.py +379 -0
- visualkit-3.0.0/src/visualkit/clips/errors.py +152 -0
- visualkit-3.0.0/src/visualkit/clips/fusion.py +844 -0
- visualkit-3.0.0/src/visualkit/clips/human_props.py +369 -0
- visualkit-3.0.0/src/visualkit/clips/integrity.py +2608 -0
- visualkit-3.0.0/src/visualkit/clips/item.py +558 -0
- visualkit-3.0.0/src/visualkit/clips/props.py +320 -0
- visualkit-3.0.0/src/visualkit/clips/references.py +69 -0
- visualkit-3.0.0/src/visualkit/clips/style.py +511 -0
- visualkit-3.0.0/src/visualkit/clips/svg_path.py +339 -0
- visualkit-3.0.0/src/visualkit/clips/timeline.py +1622 -0
- visualkit-3.0.0/src/visualkit/clips/timing.py +97 -0
- visualkit-3.0.0/src/visualkit/clips/variables.py +1138 -0
- visualkit-3.0.0/src/visualkit/coded/__init__.py +46 -0
- visualkit-3.0.0/src/visualkit/coded/base.py +79 -0
- visualkit-3.0.0/src/visualkit/coded/browser.py +147 -0
- visualkit-3.0.0/src/visualkit/coded/caller.py +272 -0
- visualkit-3.0.0/src/visualkit/coded/dependencies.py +243 -0
- visualkit-3.0.0/src/visualkit/coded/doctor.py +180 -0
- visualkit-3.0.0/src/visualkit/coded/errors.py +29 -0
- visualkit-3.0.0/src/visualkit/coded/html/__init__.py +13 -0
- visualkit-3.0.0/src/visualkit/coded/html/compiler.py +672 -0
- visualkit-3.0.0/src/visualkit/coded/html/video.py +422 -0
- visualkit-3.0.0/src/visualkit/coded/params.py +188 -0
- visualkit-3.0.0/src/visualkit/coded/remotion/__init__.py +10 -0
- visualkit-3.0.0/src/visualkit/coded/remotion/compiler.py +697 -0
- visualkit-3.0.0/src/visualkit/coded/remotion/runner.py +343 -0
- visualkit-3.0.0/src/visualkit/engine/__init__.py +178 -0
- visualkit-3.0.0/src/visualkit/engine/claims.py +534 -0
- visualkit-3.0.0/src/visualkit/engine/codec.py +338 -0
- visualkit-3.0.0/src/visualkit/engine/director_handles.py +1183 -0
- visualkit-3.0.0/src/visualkit/engine/draft.py +471 -0
- visualkit-3.0.0/src/visualkit/engine/engine.py +3754 -0
- visualkit-3.0.0/src/visualkit/engine/errors.py +128 -0
- visualkit-3.0.0/src/visualkit/engine/export_import.py +318 -0
- visualkit-3.0.0/src/visualkit/engine/handles.py +3172 -0
- visualkit-3.0.0/src/visualkit/engine/runner.py +890 -0
- visualkit-3.0.0/src/visualkit/engine/session.py +299 -0
- visualkit-3.0.0/src/visualkit/engine/store/__init__.py +52 -0
- visualkit-3.0.0/src/visualkit/engine/store/diff_merge.py +641 -0
- visualkit-3.0.0/src/visualkit/engine/store/history.py +741 -0
- visualkit-3.0.0/src/visualkit/engine/store/liveness.py +37 -0
- visualkit-3.0.0/src/visualkit/engine/store/models.py +279 -0
- visualkit-3.0.0/src/visualkit/engine/store/schema.py +97 -0
- visualkit-3.0.0/src/visualkit/engine/store/store.py +1415 -0
- visualkit-3.0.0/src/visualkit/engine/store/workspaces.py +1403 -0
- visualkit-3.0.0/src/visualkit/export/__init__.py +88 -0
- visualkit-3.0.0/src/visualkit/export/base.py +154 -0
- visualkit-3.0.0/src/visualkit/export/ffmpeg/__init__.py +22 -0
- visualkit-3.0.0/src/visualkit/export/ffmpeg/effects_fusion.py +2282 -0
- visualkit-3.0.0/src/visualkit/export/ffmpeg/helpers.py +173 -0
- visualkit-3.0.0/src/visualkit/export/ffmpeg/probe.py +301 -0
- visualkit-3.0.0/src/visualkit/export/ffmpeg/renderer.py +3011 -0
- visualkit-3.0.0/src/visualkit/export/plan.py +2369 -0
- visualkit-3.0.0/src/visualkit/export/text.py +280 -0
- visualkit-3.0.0/src/visualkit/export/window.py +78 -0
- visualkit-3.0.0/src/visualkit/preview/__init__.py +55 -0
- visualkit-3.0.0/src/visualkit/preview/facade.py +398 -0
- visualkit-3.0.0/src/visualkit/preview/grid.py +354 -0
- visualkit-3.0.0/src/visualkit/preview/models.py +201 -0
- visualkit-3.0.0/src/visualkit/preview/service.py +1105 -0
- visualkit-3.0.0/src/visualkit/style/__init__.py +148 -0
- visualkit-3.0.0/src/visualkit/style/fonts/FONTS.md +24 -0
- visualkit-3.0.0/src/visualkit/style/fonts/LICENSE-NotoColorEmoji-OFL.txt +87 -0
- visualkit-3.0.0/src/visualkit/style/fonts/LICENSE-OFL.txt +94 -0
- visualkit-3.0.0/src/visualkit/style/fonts.py +559 -0
- visualkit-3.0.0/src/visualkit/style/raster.py +321 -0
- visualkit-3.0.0/src/visualkit/style/skia_raster.py +1334 -0
- visualkit-3.0.0/src/visualkit/style/templates.py +1092 -0
- visualkit-3.0.0/src/visualkit/tier1.py +77 -0
- visualkit-3.0.0/src/visualkit/utils/__init__.py +16 -0
- visualkit-3.0.0/src/visualkit/utils/base_model.py +137 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/src/visualkit/utils/exceptions.py +29 -1
- visualkit-3.0.0/src/visualkit/utils/time.py +1153 -0
- visualkit-3.0.0/src/visualkit/utils/utility.py +118 -0
- visualkit-3.0.0/src/visualkit.egg-info/PKG-INFO +237 -0
- visualkit-3.0.0/src/visualkit.egg-info/SOURCES.txt +155 -0
- visualkit-3.0.0/src/visualkit.egg-info/entry_points.txt +3 -0
- visualkit-3.0.0/src/visualkit.egg-info/requires.txt +19 -0
- visualkit-3.0.0/tests/test_audit_regressions.py +303 -0
- visualkit-3.0.0/tests/test_pre_doc_root_fixes.py +170 -0
- visualkit-3.0.0/tests/test_pre_doc_stress_and_perf.py +340 -0
- visualkit-3.0.0/tests/test_preview_and_renderer_root_fixes.py +487 -0
- visualkit-3.0.0/tests/test_ux_fixes.py +297 -0
- visualkit-2.1.0/PKG-INFO +0 -245
- visualkit-2.1.0/README.md +0 -216
- visualkit-2.1.0/pyproject.toml +0 -78
- visualkit-2.1.0/src/visualkit/__init__.py +0 -128
- visualkit-2.1.0/src/visualkit/__main__.py +0 -11
- visualkit-2.1.0/src/visualkit/coded_visual/__init__.py +0 -8
- visualkit-2.1.0/src/visualkit/coded_visual/browser.py +0 -192
- visualkit-2.1.0/src/visualkit/coded_visual/capture.py +0 -294
- visualkit-2.1.0/src/visualkit/coded_visual/compiler.py +0 -648
- visualkit-2.1.0/src/visualkit/coded_visual/project.py +0 -186
- visualkit-2.1.0/src/visualkit/engine/__init__.py +0 -8
- visualkit-2.1.0/src/visualkit/engine/asset_resolver.py +0 -54
- visualkit-2.1.0/src/visualkit/engine/pipeline.py +0 -377
- visualkit-2.1.0/src/visualkit/exporters/__init__.py +0 -9
- visualkit-2.1.0/src/visualkit/exporters/_ffmpeg.py +0 -56
- visualkit-2.1.0/src/visualkit/exporters/_render_plan.py +0 -440
- visualkit-2.1.0/src/visualkit/exporters/base.py +0 -63
- visualkit-2.1.0/src/visualkit/exporters/resolve.py +0 -874
- visualkit-2.1.0/src/visualkit/exporters/single_clip.py +0 -188
- visualkit-2.1.0/src/visualkit/exporters/video.py +0 -551
- visualkit-2.1.0/src/visualkit/models/__init__.py +0 -98
- visualkit-2.1.0/src/visualkit/models/animation.py +0 -208
- visualkit-2.1.0/src/visualkit/models/clips/__init__.py +0 -46
- visualkit-2.1.0/src/visualkit/models/clips/audio.py +0 -30
- visualkit-2.1.0/src/visualkit/models/clips/base.py +0 -130
- visualkit-2.1.0/src/visualkit/models/clips/coded_visual.py +0 -479
- visualkit-2.1.0/src/visualkit/models/clips/compound.py +0 -333
- visualkit-2.1.0/src/visualkit/models/clips/media.py +0 -84
- visualkit-2.1.0/src/visualkit/models/clips/text.py +0 -159
- visualkit-2.1.0/src/visualkit/models/clips/visual.py +0 -294
- visualkit-2.1.0/src/visualkit/models/effects.py +0 -266
- visualkit-2.1.0/src/visualkit/models/keyframes.py +0 -433
- visualkit-2.1.0/src/visualkit/models/timeline.py +0 -1151
- visualkit-2.1.0/src/visualkit/models/variable.py +0 -186
- visualkit-2.1.0/src/visualkit/utils/__init__.py +0 -0
- visualkit-2.1.0/src/visualkit/utils/base_model.py +0 -40
- visualkit-2.1.0/src/visualkit/utils/time.py +0 -498
- visualkit-2.1.0/src/visualkit.egg-info/PKG-INFO +0 -245
- visualkit-2.1.0/src/visualkit.egg-info/SOURCES.txt +0 -69
- visualkit-2.1.0/src/visualkit.egg-info/requires.txt +0 -4
- visualkit-2.1.0/tests/test_animation_presets.py +0 -307
- visualkit-2.1.0/tests/test_chroma_key.py +0 -243
- visualkit-2.1.0/tests/test_clip_editing.py +0 -609
- visualkit-2.1.0/tests/test_coded_visual_compiler.py +0 -485
- visualkit-2.1.0/tests/test_keyframe_rendering.py +0 -487
- visualkit-2.1.0/tests/test_keyframes.py +0 -650
- visualkit-2.1.0/tests/test_masks.py +0 -252
- visualkit-2.1.0/tests/test_package_exports.py +0 -28
- visualkit-2.1.0/tests/test_pipeline_semantics.py +0 -199
- visualkit-2.1.0/tests/test_positioning.py +0 -64
- visualkit-2.1.0/tests/test_preview_image.py +0 -219
- visualkit-2.1.0/tests/test_rendering.py +0 -453
- visualkit-2.1.0/tests/test_resolve_correctness.py +0 -170
- visualkit-2.1.0/tests/test_resolve_exporter.py +0 -296
- visualkit-2.1.0/tests/test_text_style.py +0 -252
- visualkit-2.1.0/tests/test_time_and_variables.py +0 -235
- visualkit-2.1.0/tests/test_timeline.py +0 -116
- visualkit-2.1.0/tests/test_timeline_integrity.py +0 -276
- visualkit-2.1.0/tests/test_timeline_pipeline.py +0 -396
- visualkit-2.1.0/tests/test_variable_inspection.py +0 -91
- visualkit-2.1.0/tests/test_variables_and_clips.py +0 -351
- visualkit-2.1.0/tests/test_video_alpha.py +0 -185
- visualkit-2.1.0/tests/test_video_exporter.py +0 -344
- visualkit-2.1.0/tests/test_visual_clip_fields.py +0 -70
- {visualkit-2.1.0 → visualkit-3.0.0}/AUTHORS.rst +0 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/LICENSE +0 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/setup.cfg +0 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/src/visualkit/py.typed +0 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/src/visualkit.egg-info/dependency_links.txt +0 -0
- {visualkit-2.1.0 → visualkit-3.0.0}/src/visualkit.egg-info/top_level.txt +0 -0
visualkit-3.0.0/PKG-INFO
ADDED
|
@@ -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"
|