visualkit 0.1.4__tar.gz → 2.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {visualkit-0.1.4 → visualkit-2.0.1}/LICENSE +1 -1
- visualkit-2.0.1/PKG-INFO +225 -0
- visualkit-2.0.1/README.md +200 -0
- visualkit-2.0.1/pyproject.toml +69 -0
- visualkit-2.0.1/src/visualkit/__init__.py +100 -0
- visualkit-2.0.1/src/visualkit/__main__.py +11 -0
- visualkit-2.0.1/src/visualkit/coded_visual/__init__.py +8 -0
- visualkit-2.0.1/src/visualkit/coded_visual/browser.py +192 -0
- visualkit-2.0.1/src/visualkit/coded_visual/capture.py +227 -0
- visualkit-2.0.1/src/visualkit/coded_visual/compiler.py +438 -0
- visualkit-2.0.1/src/visualkit/coded_visual/project.py +186 -0
- visualkit-2.0.1/src/visualkit/engine/__init__.py +8 -0
- visualkit-2.0.1/src/visualkit/engine/asset_resolver.py +54 -0
- visualkit-2.0.1/src/visualkit/engine/pipeline.py +344 -0
- visualkit-2.0.1/src/visualkit/exporters/__init__.py +9 -0
- visualkit-2.0.1/src/visualkit/exporters/base.py +63 -0
- visualkit-2.0.1/src/visualkit/exporters/resolve.py +873 -0
- visualkit-2.0.1/src/visualkit/exporters/video.py +557 -0
- visualkit-2.0.1/src/visualkit/models/__init__.py +72 -0
- visualkit-2.0.1/src/visualkit/models/clips/__init__.py +44 -0
- visualkit-2.0.1/src/visualkit/models/clips/audio.py +30 -0
- visualkit-2.0.1/src/visualkit/models/clips/base.py +88 -0
- visualkit-2.0.1/src/visualkit/models/clips/coded_visual.py +375 -0
- visualkit-2.0.1/src/visualkit/models/clips/compound.py +287 -0
- visualkit-2.0.1/src/visualkit/models/clips/media.py +43 -0
- visualkit-2.0.1/src/visualkit/models/clips/text.py +89 -0
- visualkit-2.0.1/src/visualkit/models/clips/visual.py +102 -0
- visualkit-2.0.1/src/visualkit/models/timeline.py +1049 -0
- visualkit-2.0.1/src/visualkit/models/variable.py +186 -0
- visualkit-2.0.1/src/visualkit/py.typed +0 -0
- visualkit-2.0.1/src/visualkit/utils/__init__.py +0 -0
- visualkit-2.0.1/src/visualkit/utils/base_model.py +40 -0
- visualkit-2.0.1/src/visualkit/utils/exceptions.py +71 -0
- visualkit-2.0.1/src/visualkit/utils/time.py +498 -0
- visualkit-2.0.1/src/visualkit.egg-info/PKG-INFO +225 -0
- visualkit-2.0.1/src/visualkit.egg-info/SOURCES.txt +53 -0
- visualkit-2.0.1/src/visualkit.egg-info/requires.txt +4 -0
- {visualkit-0.1.4 → visualkit-2.0.1}/src/visualkit.egg-info/top_level.txt +1 -0
- visualkit-2.0.1/tests/test_clip_editing.py +609 -0
- visualkit-2.0.1/tests/test_coded_visual_compiler.py +237 -0
- visualkit-2.0.1/tests/test_package_exports.py +28 -0
- visualkit-2.0.1/tests/test_pipeline_semantics.py +199 -0
- visualkit-2.0.1/tests/test_rendering.py +450 -0
- visualkit-2.0.1/tests/test_resolve_correctness.py +170 -0
- visualkit-2.0.1/tests/test_resolve_exporter.py +296 -0
- visualkit-2.0.1/tests/test_time_and_variables.py +235 -0
- visualkit-2.0.1/tests/test_timeline.py +116 -0
- visualkit-2.0.1/tests/test_timeline_integrity.py +241 -0
- visualkit-2.0.1/tests/test_timeline_pipeline.py +396 -0
- visualkit-2.0.1/tests/test_variable_inspection.py +91 -0
- visualkit-2.0.1/tests/test_variables_and_clips.py +236 -0
- visualkit-2.0.1/tests/test_video_exporter.py +340 -0
- visualkit-0.1.4/PKG-INFO +0 -54
- visualkit-0.1.4/README.md +0 -40
- visualkit-0.1.4/pyproject.toml +0 -23
- visualkit-0.1.4/src/visualkit/__init__.py +0 -6
- visualkit-0.1.4/src/visualkit/__main__.py +0 -5
- visualkit-0.1.4/src/visualkit/config.py +0 -26
- visualkit-0.1.4/src/visualkit/editor.py +0 -203
- visualkit-0.1.4/src/visualkit/enums.py +0 -7
- visualkit-0.1.4/src/visualkit/media_element.py +0 -1457
- visualkit-0.1.4/src/visualkit/project_creator.py +0 -144
- visualkit-0.1.4/src/visualkit/text_element.py +0 -277
- visualkit-0.1.4/src/visualkit/timeline.py +0 -47
- visualkit-0.1.4/src/visualkit/transitions.py +0 -595
- visualkit-0.1.4/src/visualkit/utils.py +0 -5
- visualkit-0.1.4/src/visualkit.egg-info/PKG-INFO +0 -54
- visualkit-0.1.4/src/visualkit.egg-info/SOURCES.txt +0 -20
- visualkit-0.1.4/src/visualkit.egg-info/requires.txt +0 -2
- {visualkit-0.1.4 → visualkit-2.0.1}/AUTHORS.rst +0 -0
- {visualkit-0.1.4 → visualkit-2.0.1}/setup.cfg +0 -0
- {visualkit-0.1.4 → visualkit-2.0.1}/src/visualkit.egg-info/dependency_links.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c)
|
|
3
|
+
Copyright (c) 2026, Suraj Airi
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
6
|
|
visualkit-2.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: visualkit
|
|
3
|
+
Version: 2.0.1
|
|
4
|
+
Summary: A programmable video-editing engine: timelines, compound clips, and code-rendered (HTML/CSS/JS) visuals, exportable to video or DaVinci Resolve.
|
|
5
|
+
Author-email: Suraj Airi <surajairi.ml@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: video,editing,timeline,ffmpeg,davinci-resolve,fcpxml,xmeml,infographics
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Topic :: Multimedia :: Video
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
License-File: AUTHORS.rst
|
|
21
|
+
Requires-Dist: pydantic>=2.13.5
|
|
22
|
+
Provides-Extra: render
|
|
23
|
+
Requires-Dist: playwright>=1.40; extra == "render"
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
# VisualKit
|
|
27
|
+
|
|
28
|
+
A Python engine for programmatically building and exporting video timelines —
|
|
29
|
+
media clips, text, audio, reusable "compound" clip templates, and
|
|
30
|
+
code-rendered visuals (infographics/animations built with HTML/CSS/JS),
|
|
31
|
+
composed on a `Timeline` and exported to a standalone video or to a project
|
|
32
|
+
file for import into DaVinci Resolve.
|
|
33
|
+
|
|
34
|
+
> **Status:** phase 1. Core timeline/clip model, coded-visual compilation,
|
|
35
|
+
> and export are implemented. Keyframes, transitions, masking/chroma-key,
|
|
36
|
+
> and other advanced editing features are on the roadmap (see `notes/`) but
|
|
37
|
+
> not yet built.
|
|
38
|
+
|
|
39
|
+
## Requirements
|
|
40
|
+
|
|
41
|
+
- Python >= 3.12
|
|
42
|
+
- [FFmpeg](https://ffmpeg.org/) on your `PATH`, for standalone video export and for
|
|
43
|
+
encoding animated coded visuals
|
|
44
|
+
- A Chrome or Chromium install, for `CodedVisualClip`s and for `TextClip`s exported
|
|
45
|
+
with `FFmpegVideoExporter`. VisualKit never bundles or downloads a browser. It
|
|
46
|
+
looks, in order, at the `VISUALKIT_CHROME` environment variable, your `PATH`,
|
|
47
|
+
the usual install locations, and browsers cached by Playwright/Puppeteer.
|
|
48
|
+
`chrome-headless-shell` is preferred when present (smaller and faster to start).
|
|
49
|
+
- Optional: `playwright` (`pip install "visualkit[render]"`), needed only to render
|
|
50
|
+
**animated** coded visuals. It is used purely as a driver for the Chrome above.
|
|
51
|
+
Still visuals, text, and everything else work without it.
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install -e . # core
|
|
57
|
+
pip install -e ".[render]" # + animated coded visuals
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
(This project isn't yet published to PyPI; install from a local checkout.)
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
import visualkit as vk
|
|
66
|
+
|
|
67
|
+
timeline = vk.Timeline()
|
|
68
|
+
|
|
69
|
+
video = vk.MediaClip(
|
|
70
|
+
id="main_video",
|
|
71
|
+
source=vk.Source(source="footage.mp4"),
|
|
72
|
+
duration=vk.Time.from_seconds(10),
|
|
73
|
+
)
|
|
74
|
+
timeline.add_clip(video, track_index=0)
|
|
75
|
+
|
|
76
|
+
title = vk.TextClip(
|
|
77
|
+
id="title",
|
|
78
|
+
text="Hello, World!",
|
|
79
|
+
timeline_start=vk.Time.from_seconds(1),
|
|
80
|
+
duration=vk.Time.from_seconds(3),
|
|
81
|
+
)
|
|
82
|
+
timeline.add_clip(title, track_index=1)
|
|
83
|
+
|
|
84
|
+
# Export to a standalone MP4 (requires ffmpeg, and Chrome for the TextClip)
|
|
85
|
+
timeline.export_to_video("output/hello.mp4")
|
|
86
|
+
|
|
87
|
+
# ...or to a DaVinci Resolve project
|
|
88
|
+
timeline.export_to_resolve("output/hello_resolve.xml")
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
See `examples/` for runnable walkthroughs of each feature area:
|
|
92
|
+
|
|
93
|
+
| Example | Covers |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `01_basic_timeline.py` | Building a timeline from media/text/audio clips, multi-track layout, exporting |
|
|
96
|
+
| `02_coded_visuals.py` | `CodedVisualClip`: a bundle with a manifest, typed variables, a still preview, and an animated render |
|
|
97
|
+
| `03_compound_clips_and_templates.py` | `CompoundClip` as a grouping/template mechanism with exposed `Variable`s |
|
|
98
|
+
| `04_asset_resolvers.py` | Resolving abstract asset references (`asset://...`) to real files at export time |
|
|
99
|
+
|
|
100
|
+
## Core concepts
|
|
101
|
+
|
|
102
|
+
**Timeline & Tracks.** A `Timeline` holds a list of video tracks and a list
|
|
103
|
+
of audio tracks (`Track[Clip]`). `timeline.add_clip(clip, track_index=N)`
|
|
104
|
+
routes a clip to the right lane automatically based on its type, creating
|
|
105
|
+
tracks up to `N` as needed. Clips can be inserted in `OVERLAP` (default) or
|
|
106
|
+
`RIPPLE` mode; ripple-inserting into a point that falls inside an existing
|
|
107
|
+
clip's span raises `InvalidTrackOperationError` rather than silently
|
|
108
|
+
producing an overlapping timeline.
|
|
109
|
+
|
|
110
|
+
**Clips.** `MediaClip` (video/image files), `AudioClip`, `TextClip`, and
|
|
111
|
+
`CodedVisualClip` all share a common `BaseClip` (id, timing, speed). Visual
|
|
112
|
+
clips (`MediaClip`, `TextClip`, `CodedVisualClip`) additionally carry a
|
|
113
|
+
`Transform` (position, scale, rotation, opacity).
|
|
114
|
+
|
|
115
|
+
**CompoundClip.** Groups a nested `Timeline` (its `inner_timeline`) into a
|
|
116
|
+
single clip on the parent timeline — useful for building reusable templates.
|
|
117
|
+
Exposed `Variable`s let a compound clip's inner text/parameters be
|
|
118
|
+
overridden per-instance (`compound.set_parameter(name, value)`) without
|
|
119
|
+
touching the inner timeline's structure. A compound's own `speed` compresses
|
|
120
|
+
its entire inner timeline proportionally when flattened.
|
|
121
|
+
|
|
122
|
+
**CodedVisualClip.** References a small HTML/CSS/JS project (a "coded visual"),
|
|
123
|
+
such as an animated infographic, either a single `.html` file or a directory
|
|
124
|
+
bundle (`index.html` + `manifest.json` + local images/SVGs/CSS/JS). It is *not*
|
|
125
|
+
itself media: `CodedVisualCompiler` renders it in headless Chrome into a real
|
|
126
|
+
file, a **PNG** for a still visual or an **MP4** for an animated one, and that file
|
|
127
|
+
is what the timeline and exporters use. See [Coded visuals](#coded-visuals) below.
|
|
128
|
+
|
|
129
|
+
**Flattening.** `timeline.flatten()` (used internally by both exporters)
|
|
130
|
+
applies template parameters, renders any `CodedVisualClip`s, and expands
|
|
131
|
+
`CompoundClip`s into plain clips with absolute timeline coordinates, giving a
|
|
132
|
+
timeline made only of `MediaClip`/`TextClip`/`AudioClip`. **It never modifies the
|
|
133
|
+
timeline you call it on**, so exporting cannot change your templates. A compound's
|
|
134
|
+
own `transform` is composed onto its children, and its content is trimmed to the
|
|
135
|
+
compound's `duration`.
|
|
136
|
+
|
|
137
|
+
## Coded visuals
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
clip = vk.CodedVisualClip(id="card", source="assets/stat_card", duration=vk.Time(4))
|
|
141
|
+
clip.load_manifest() # canvas size + variable schema from the bundle
|
|
142
|
+
clip.set_variable("title", "Active users")
|
|
143
|
+
clip.set_variable("accent", "#22c55e") # typed: a bad color raises immediately
|
|
144
|
+
timeline.add_clip(clip)
|
|
145
|
+
timeline.export_to_video("out.mp4") # renders, then composites like any media clip
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
**Design canvas and scaling.** A visual is authored against a fixed design canvas
|
|
149
|
+
(`<meta name="canvas-size" content="1920x1080">`, or `canvas_size` in `manifest.json`,
|
|
150
|
+
or set on the clip; `clip.design_size` reports the effective one; `canvas_size` itself
|
|
151
|
+
is `None` until set explicitly). Put your content inside `.visualkit-canvas`. It is
|
|
152
|
+
always rendered at exactly that size and scaled, aspect ratio preserved, to fit
|
|
153
|
+
whatever frame it lands in, so the layout never reflows. The 9:16 (vertical), 1:1 and
|
|
154
|
+
16:9 cases are all just a different design size.
|
|
155
|
+
|
|
156
|
+
**Variables and templates.** `{{ name }}` in the HTML is replaced by the
|
|
157
|
+
**HTML-escaped** value. Use `{{{ name }}}` for trusted raw HTML. The same values are
|
|
158
|
+
available to script as `window.__VARIABLES__.name`, already typed. Variable types
|
|
159
|
+
(`string`, `number`, `boolean`, `color`, `asset`, `json`) are enforced. Declare them
|
|
160
|
+
in `manifest.json` with labels and descriptions to make a bundle a reusable scene
|
|
161
|
+
template. Wrap a visual in a `CompoundClip` and `expose_parameter(...)` to drive it
|
|
162
|
+
per instance. Placeholders inside `<style>` are HTML-escaped as well, which is safe
|
|
163
|
+
for validated `color`/`number` variables but not for arbitrary strings.
|
|
164
|
+
|
|
165
|
+
**Local assets.** Images, SVGs, fonts, CSS and JS beside `index.html` load normally.
|
|
166
|
+
Editing any of them invalidates the cached render.
|
|
167
|
+
|
|
168
|
+
**Still vs. animated.** `render_mode` is `auto` by default: a page with motion becomes a
|
|
169
|
+
video, a static one a PNG. Detection uses the manifest's `animated` flag if set, else
|
|
170
|
+
renders the page at two times and compares. Animation is stepped deterministically
|
|
171
|
+
(CSS/Web Animations are seeked; `Date`, `setTimeout`, `setInterval` and
|
|
172
|
+
`requestAnimationFrame` run on a virtual clock), so output is identical on every
|
|
173
|
+
machine. Frames stream straight into FFmpeg. Pass `render_video=True`/`False` to
|
|
174
|
+
`flatten()`/`export_*()` to override.
|
|
175
|
+
|
|
176
|
+
**Limits.** Determinism is guaranteed for CSS/Web Animations and for the JavaScript timing
|
|
177
|
+
APIs listed above. Anything else that depends on real time (`<video>`/`<audio>` elements,
|
|
178
|
+
WebGL or canvas code that reads other clocks, network fetches) is **not** guaranteed to be
|
|
179
|
+
frame-exact. Pre-render such media and reference it as a normal clip instead. Only
|
|
180
|
+
HTML/CSS/JS visuals exist today; other compilers are a possible future extension.
|
|
181
|
+
|
|
182
|
+
## Exporting
|
|
183
|
+
|
|
184
|
+
- **`timeline.export_to_video(path, **kwargs)`**: renders a standalone video via
|
|
185
|
+
`FFmpegVideoExporter`. Text size is relative to a 1080p reference frame
|
|
186
|
+
(`font_size=48` is 48px at 1080p) so a 360p preview matches the 1080p render. A failed
|
|
187
|
+
encode raises `ExportError` carrying FFmpeg's own output, and the destination file is
|
|
188
|
+
only replaced on success.
|
|
189
|
+
- **`timeline.export_to_resolve(path, **kwargs)`**: writes an NLE project via
|
|
190
|
+
`DaVinciResolveExporter`. `.xml` produces FCP7 XML (XMEML), the more established path
|
|
191
|
+
for DaVinci Resolve. `.fcpxml` produces Apple FCPXML 1.10. NTSC rates (29.97, 23.976,
|
|
192
|
+
59.94) use their exact rational frame rate, and FCPXML times are frame-aligned
|
|
193
|
+
rationals.
|
|
194
|
+
|
|
195
|
+
> **Verify in your NLE.** XMEML and FCPXML *position* conventions were implemented from
|
|
196
|
+
> the format specifications and are covered by structural tests, but have **not** been
|
|
197
|
+
> checked against a live DaVinci Resolve import. Test a positioned clip before relying
|
|
198
|
+
> on it. Scale, opacity and timing are the well-trodden parts.
|
|
199
|
+
|
|
200
|
+
Both exporters accept an `asset_resolver`, a callable or an object with a
|
|
201
|
+
`.resolve(str) -> str` method, for mapping abstract source references
|
|
202
|
+
(e.g. `asset://b_roll`) to real paths or URLs at export time. See
|
|
203
|
+
`visualkit.engine.asset_resolver.DictAssetResolver` or `examples/04_asset_resolvers.py`.
|
|
204
|
+
|
|
205
|
+
## Errors
|
|
206
|
+
|
|
207
|
+
All library errors derive from `visualkit.VisualKitError`: `InvalidTimeError`,
|
|
208
|
+
`TimelineValidationError`, `TemplateParameterError` (an exposed parameter targets a
|
|
209
|
+
missing clip/property, or a protected field such as `id`), `MissingSourceError`,
|
|
210
|
+
`ExportError`, and the coded-visual family `CodedVisualError` >
|
|
211
|
+
`CodedVisualCompileError` > `BrowserNotFoundError`. Timeline edits (`split_clip`,
|
|
212
|
+
`move_clip_track`, and `add_clip`, including a batch of several clips) are atomic: a rejected
|
|
213
|
+
edit leaves the timeline exactly as it was.
|
|
214
|
+
|
|
215
|
+
## Development
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
uv sync --group dev # includes playwright + pillow so the render tests run
|
|
219
|
+
pytest
|
|
220
|
+
ruff check . && ruff format --check .
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# VisualKit
|
|
2
|
+
|
|
3
|
+
A Python engine for programmatically building and exporting video timelines —
|
|
4
|
+
media clips, text, audio, reusable "compound" clip templates, and
|
|
5
|
+
code-rendered visuals (infographics/animations built with HTML/CSS/JS),
|
|
6
|
+
composed on a `Timeline` and exported to a standalone video or to a project
|
|
7
|
+
file for import into DaVinci Resolve.
|
|
8
|
+
|
|
9
|
+
> **Status:** phase 1. Core timeline/clip model, coded-visual compilation,
|
|
10
|
+
> and export are implemented. Keyframes, transitions, masking/chroma-key,
|
|
11
|
+
> and other advanced editing features are on the roadmap (see `notes/`) but
|
|
12
|
+
> not yet built.
|
|
13
|
+
|
|
14
|
+
## Requirements
|
|
15
|
+
|
|
16
|
+
- Python >= 3.12
|
|
17
|
+
- [FFmpeg](https://ffmpeg.org/) on your `PATH`, for standalone video export and for
|
|
18
|
+
encoding animated coded visuals
|
|
19
|
+
- A Chrome or Chromium install, for `CodedVisualClip`s and for `TextClip`s exported
|
|
20
|
+
with `FFmpegVideoExporter`. VisualKit never bundles or downloads a browser. It
|
|
21
|
+
looks, in order, at the `VISUALKIT_CHROME` environment variable, your `PATH`,
|
|
22
|
+
the usual install locations, and browsers cached by Playwright/Puppeteer.
|
|
23
|
+
`chrome-headless-shell` is preferred when present (smaller and faster to start).
|
|
24
|
+
- Optional: `playwright` (`pip install "visualkit[render]"`), needed only to render
|
|
25
|
+
**animated** coded visuals. It is used purely as a driver for the Chrome above.
|
|
26
|
+
Still visuals, text, and everything else work without it.
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install -e . # core
|
|
32
|
+
pip install -e ".[render]" # + animated coded visuals
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
(This project isn't yet published to PyPI; install from a local checkout.)
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import visualkit as vk
|
|
41
|
+
|
|
42
|
+
timeline = vk.Timeline()
|
|
43
|
+
|
|
44
|
+
video = vk.MediaClip(
|
|
45
|
+
id="main_video",
|
|
46
|
+
source=vk.Source(source="footage.mp4"),
|
|
47
|
+
duration=vk.Time.from_seconds(10),
|
|
48
|
+
)
|
|
49
|
+
timeline.add_clip(video, track_index=0)
|
|
50
|
+
|
|
51
|
+
title = vk.TextClip(
|
|
52
|
+
id="title",
|
|
53
|
+
text="Hello, World!",
|
|
54
|
+
timeline_start=vk.Time.from_seconds(1),
|
|
55
|
+
duration=vk.Time.from_seconds(3),
|
|
56
|
+
)
|
|
57
|
+
timeline.add_clip(title, track_index=1)
|
|
58
|
+
|
|
59
|
+
# Export to a standalone MP4 (requires ffmpeg, and Chrome for the TextClip)
|
|
60
|
+
timeline.export_to_video("output/hello.mp4")
|
|
61
|
+
|
|
62
|
+
# ...or to a DaVinci Resolve project
|
|
63
|
+
timeline.export_to_resolve("output/hello_resolve.xml")
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
See `examples/` for runnable walkthroughs of each feature area:
|
|
67
|
+
|
|
68
|
+
| Example | Covers |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `01_basic_timeline.py` | Building a timeline from media/text/audio clips, multi-track layout, exporting |
|
|
71
|
+
| `02_coded_visuals.py` | `CodedVisualClip`: a bundle with a manifest, typed variables, a still preview, and an animated render |
|
|
72
|
+
| `03_compound_clips_and_templates.py` | `CompoundClip` as a grouping/template mechanism with exposed `Variable`s |
|
|
73
|
+
| `04_asset_resolvers.py` | Resolving abstract asset references (`asset://...`) to real files at export time |
|
|
74
|
+
|
|
75
|
+
## Core concepts
|
|
76
|
+
|
|
77
|
+
**Timeline & Tracks.** A `Timeline` holds a list of video tracks and a list
|
|
78
|
+
of audio tracks (`Track[Clip]`). `timeline.add_clip(clip, track_index=N)`
|
|
79
|
+
routes a clip to the right lane automatically based on its type, creating
|
|
80
|
+
tracks up to `N` as needed. Clips can be inserted in `OVERLAP` (default) or
|
|
81
|
+
`RIPPLE` mode; ripple-inserting into a point that falls inside an existing
|
|
82
|
+
clip's span raises `InvalidTrackOperationError` rather than silently
|
|
83
|
+
producing an overlapping timeline.
|
|
84
|
+
|
|
85
|
+
**Clips.** `MediaClip` (video/image files), `AudioClip`, `TextClip`, and
|
|
86
|
+
`CodedVisualClip` all share a common `BaseClip` (id, timing, speed). Visual
|
|
87
|
+
clips (`MediaClip`, `TextClip`, `CodedVisualClip`) additionally carry a
|
|
88
|
+
`Transform` (position, scale, rotation, opacity).
|
|
89
|
+
|
|
90
|
+
**CompoundClip.** Groups a nested `Timeline` (its `inner_timeline`) into a
|
|
91
|
+
single clip on the parent timeline — useful for building reusable templates.
|
|
92
|
+
Exposed `Variable`s let a compound clip's inner text/parameters be
|
|
93
|
+
overridden per-instance (`compound.set_parameter(name, value)`) without
|
|
94
|
+
touching the inner timeline's structure. A compound's own `speed` compresses
|
|
95
|
+
its entire inner timeline proportionally when flattened.
|
|
96
|
+
|
|
97
|
+
**CodedVisualClip.** References a small HTML/CSS/JS project (a "coded visual"),
|
|
98
|
+
such as an animated infographic, either a single `.html` file or a directory
|
|
99
|
+
bundle (`index.html` + `manifest.json` + local images/SVGs/CSS/JS). It is *not*
|
|
100
|
+
itself media: `CodedVisualCompiler` renders it in headless Chrome into a real
|
|
101
|
+
file, a **PNG** for a still visual or an **MP4** for an animated one, and that file
|
|
102
|
+
is what the timeline and exporters use. See [Coded visuals](#coded-visuals) below.
|
|
103
|
+
|
|
104
|
+
**Flattening.** `timeline.flatten()` (used internally by both exporters)
|
|
105
|
+
applies template parameters, renders any `CodedVisualClip`s, and expands
|
|
106
|
+
`CompoundClip`s into plain clips with absolute timeline coordinates, giving a
|
|
107
|
+
timeline made only of `MediaClip`/`TextClip`/`AudioClip`. **It never modifies the
|
|
108
|
+
timeline you call it on**, so exporting cannot change your templates. A compound's
|
|
109
|
+
own `transform` is composed onto its children, and its content is trimmed to the
|
|
110
|
+
compound's `duration`.
|
|
111
|
+
|
|
112
|
+
## Coded visuals
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
clip = vk.CodedVisualClip(id="card", source="assets/stat_card", duration=vk.Time(4))
|
|
116
|
+
clip.load_manifest() # canvas size + variable schema from the bundle
|
|
117
|
+
clip.set_variable("title", "Active users")
|
|
118
|
+
clip.set_variable("accent", "#22c55e") # typed: a bad color raises immediately
|
|
119
|
+
timeline.add_clip(clip)
|
|
120
|
+
timeline.export_to_video("out.mp4") # renders, then composites like any media clip
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**Design canvas and scaling.** A visual is authored against a fixed design canvas
|
|
124
|
+
(`<meta name="canvas-size" content="1920x1080">`, or `canvas_size` in `manifest.json`,
|
|
125
|
+
or set on the clip; `clip.design_size` reports the effective one; `canvas_size` itself
|
|
126
|
+
is `None` until set explicitly). Put your content inside `.visualkit-canvas`. It is
|
|
127
|
+
always rendered at exactly that size and scaled, aspect ratio preserved, to fit
|
|
128
|
+
whatever frame it lands in, so the layout never reflows. The 9:16 (vertical), 1:1 and
|
|
129
|
+
16:9 cases are all just a different design size.
|
|
130
|
+
|
|
131
|
+
**Variables and templates.** `{{ name }}` in the HTML is replaced by the
|
|
132
|
+
**HTML-escaped** value. Use `{{{ name }}}` for trusted raw HTML. The same values are
|
|
133
|
+
available to script as `window.__VARIABLES__.name`, already typed. Variable types
|
|
134
|
+
(`string`, `number`, `boolean`, `color`, `asset`, `json`) are enforced. Declare them
|
|
135
|
+
in `manifest.json` with labels and descriptions to make a bundle a reusable scene
|
|
136
|
+
template. Wrap a visual in a `CompoundClip` and `expose_parameter(...)` to drive it
|
|
137
|
+
per instance. Placeholders inside `<style>` are HTML-escaped as well, which is safe
|
|
138
|
+
for validated `color`/`number` variables but not for arbitrary strings.
|
|
139
|
+
|
|
140
|
+
**Local assets.** Images, SVGs, fonts, CSS and JS beside `index.html` load normally.
|
|
141
|
+
Editing any of them invalidates the cached render.
|
|
142
|
+
|
|
143
|
+
**Still vs. animated.** `render_mode` is `auto` by default: a page with motion becomes a
|
|
144
|
+
video, a static one a PNG. Detection uses the manifest's `animated` flag if set, else
|
|
145
|
+
renders the page at two times and compares. Animation is stepped deterministically
|
|
146
|
+
(CSS/Web Animations are seeked; `Date`, `setTimeout`, `setInterval` and
|
|
147
|
+
`requestAnimationFrame` run on a virtual clock), so output is identical on every
|
|
148
|
+
machine. Frames stream straight into FFmpeg. Pass `render_video=True`/`False` to
|
|
149
|
+
`flatten()`/`export_*()` to override.
|
|
150
|
+
|
|
151
|
+
**Limits.** Determinism is guaranteed for CSS/Web Animations and for the JavaScript timing
|
|
152
|
+
APIs listed above. Anything else that depends on real time (`<video>`/`<audio>` elements,
|
|
153
|
+
WebGL or canvas code that reads other clocks, network fetches) is **not** guaranteed to be
|
|
154
|
+
frame-exact. Pre-render such media and reference it as a normal clip instead. Only
|
|
155
|
+
HTML/CSS/JS visuals exist today; other compilers are a possible future extension.
|
|
156
|
+
|
|
157
|
+
## Exporting
|
|
158
|
+
|
|
159
|
+
- **`timeline.export_to_video(path, **kwargs)`**: renders a standalone video via
|
|
160
|
+
`FFmpegVideoExporter`. Text size is relative to a 1080p reference frame
|
|
161
|
+
(`font_size=48` is 48px at 1080p) so a 360p preview matches the 1080p render. A failed
|
|
162
|
+
encode raises `ExportError` carrying FFmpeg's own output, and the destination file is
|
|
163
|
+
only replaced on success.
|
|
164
|
+
- **`timeline.export_to_resolve(path, **kwargs)`**: writes an NLE project via
|
|
165
|
+
`DaVinciResolveExporter`. `.xml` produces FCP7 XML (XMEML), the more established path
|
|
166
|
+
for DaVinci Resolve. `.fcpxml` produces Apple FCPXML 1.10. NTSC rates (29.97, 23.976,
|
|
167
|
+
59.94) use their exact rational frame rate, and FCPXML times are frame-aligned
|
|
168
|
+
rationals.
|
|
169
|
+
|
|
170
|
+
> **Verify in your NLE.** XMEML and FCPXML *position* conventions were implemented from
|
|
171
|
+
> the format specifications and are covered by structural tests, but have **not** been
|
|
172
|
+
> checked against a live DaVinci Resolve import. Test a positioned clip before relying
|
|
173
|
+
> on it. Scale, opacity and timing are the well-trodden parts.
|
|
174
|
+
|
|
175
|
+
Both exporters accept an `asset_resolver`, a callable or an object with a
|
|
176
|
+
`.resolve(str) -> str` method, for mapping abstract source references
|
|
177
|
+
(e.g. `asset://b_roll`) to real paths or URLs at export time. See
|
|
178
|
+
`visualkit.engine.asset_resolver.DictAssetResolver` or `examples/04_asset_resolvers.py`.
|
|
179
|
+
|
|
180
|
+
## Errors
|
|
181
|
+
|
|
182
|
+
All library errors derive from `visualkit.VisualKitError`: `InvalidTimeError`,
|
|
183
|
+
`TimelineValidationError`, `TemplateParameterError` (an exposed parameter targets a
|
|
184
|
+
missing clip/property, or a protected field such as `id`), `MissingSourceError`,
|
|
185
|
+
`ExportError`, and the coded-visual family `CodedVisualError` >
|
|
186
|
+
`CodedVisualCompileError` > `BrowserNotFoundError`. Timeline edits (`split_clip`,
|
|
187
|
+
`move_clip_track`, and `add_clip`, including a batch of several clips) are atomic: a rejected
|
|
188
|
+
edit leaves the timeline exactly as it was.
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
uv sync --group dev # includes playwright + pillow so the render tests run
|
|
194
|
+
pytest
|
|
195
|
+
ruff check . && ruff format --check .
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=45", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "visualkit"
|
|
7
|
+
version = "2.0.1"
|
|
8
|
+
description = "A programmable video-editing engine: timelines, compound clips, and code-rendered (HTML/CSS/JS) visuals, exportable to video or DaVinci Resolve."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [{ name = "Suraj Airi", email = "surajairi.ml@gmail.com" }]
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
keywords = [
|
|
13
|
+
"video",
|
|
14
|
+
"editing",
|
|
15
|
+
"timeline",
|
|
16
|
+
"ffmpeg",
|
|
17
|
+
"davinci-resolve",
|
|
18
|
+
"fcpxml",
|
|
19
|
+
"xmeml",
|
|
20
|
+
"infographics",
|
|
21
|
+
]
|
|
22
|
+
classifiers = [
|
|
23
|
+
"Development Status :: 3 - Alpha",
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"License :: OSI Approved :: MIT License",
|
|
26
|
+
"Programming Language :: Python :: 3",
|
|
27
|
+
"Programming Language :: Python :: 3.10",
|
|
28
|
+
"Programming Language :: Python :: 3.11",
|
|
29
|
+
"Programming Language :: Python :: 3.12",
|
|
30
|
+
"Topic :: Multimedia :: Video",
|
|
31
|
+
"Typing :: Typed",
|
|
32
|
+
]
|
|
33
|
+
requires-python = ">=3.10"
|
|
34
|
+
dependencies = ["pydantic>=2.13.5"]
|
|
35
|
+
|
|
36
|
+
[project.optional-dependencies]
|
|
37
|
+
# Deterministic frame capture for *animated* coded visuals. VisualKit drives the
|
|
38
|
+
# Chrome/Chromium you already have installed; this does not download a browser.
|
|
39
|
+
render = ["playwright>=1.40"]
|
|
40
|
+
|
|
41
|
+
[dependency-groups]
|
|
42
|
+
dev = [
|
|
43
|
+
"notebook>=7.6.2",
|
|
44
|
+
"pyperclip>=1.11.0",
|
|
45
|
+
"pytest>=8.0.0",
|
|
46
|
+
"pytest-asyncio>=0.24.0",
|
|
47
|
+
"playwright>=1.40",
|
|
48
|
+
"pillow>=10.0",
|
|
49
|
+
"ruff>=0.12.1",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
[tool.setuptools.packages.find]
|
|
54
|
+
where = ["src"]
|
|
55
|
+
|
|
56
|
+
[tool.setuptools.package-dir]
|
|
57
|
+
"" = "src"
|
|
58
|
+
|
|
59
|
+
[tool.setuptools.package-data]
|
|
60
|
+
visualkit = ["py.typed"]
|
|
61
|
+
|
|
62
|
+
[tool.pytest.ini_options]
|
|
63
|
+
pythonpath = ["src"]
|
|
64
|
+
testpaths = ["tests"]
|
|
65
|
+
asyncio_mode = "strict"
|
|
66
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
67
|
+
markers = [
|
|
68
|
+
"browser: drives a real headless Chrome/Chromium (skipped when none is installed)",
|
|
69
|
+
]
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
2
|
+
|
|
3
|
+
from visualkit.engine import AssetResolver, DictAssetResolver, TimelinePipeline
|
|
4
|
+
from visualkit.exporters import BaseExporter, DaVinciResolveExporter, FFmpegVideoExporter
|
|
5
|
+
from visualkit.models import (
|
|
6
|
+
AudioClip,
|
|
7
|
+
AudioContent,
|
|
8
|
+
AudioProperties,
|
|
9
|
+
AudioTrack,
|
|
10
|
+
BaseClip,
|
|
11
|
+
Clip,
|
|
12
|
+
CodedVisualClip,
|
|
13
|
+
CompileStatus,
|
|
14
|
+
CompoundAudioClip,
|
|
15
|
+
CompoundClip,
|
|
16
|
+
ExposedParameter,
|
|
17
|
+
InsertMode,
|
|
18
|
+
MediaClip,
|
|
19
|
+
Position,
|
|
20
|
+
RenderMode,
|
|
21
|
+
Size,
|
|
22
|
+
Source,
|
|
23
|
+
TextClip,
|
|
24
|
+
TextStyle,
|
|
25
|
+
Timeline,
|
|
26
|
+
Track,
|
|
27
|
+
TrackKind,
|
|
28
|
+
Transform,
|
|
29
|
+
Variable,
|
|
30
|
+
VariableType,
|
|
31
|
+
VideoTrack,
|
|
32
|
+
VisualClip,
|
|
33
|
+
VisualContent,
|
|
34
|
+
)
|
|
35
|
+
from visualkit.utils.exceptions import (
|
|
36
|
+
BrowserNotFoundError,
|
|
37
|
+
CodedVisualCompileError,
|
|
38
|
+
CodedVisualError,
|
|
39
|
+
ExportError,
|
|
40
|
+
InvalidTimeError,
|
|
41
|
+
MissingSourceError,
|
|
42
|
+
TemplateParameterError,
|
|
43
|
+
TimelineValidationError,
|
|
44
|
+
VisualKitError,
|
|
45
|
+
)
|
|
46
|
+
from visualkit.utils.time import Time
|
|
47
|
+
|
|
48
|
+
try:
|
|
49
|
+
__version__ = version("visualkit")
|
|
50
|
+
except PackageNotFoundError: # running from a source checkout that is not installed
|
|
51
|
+
__version__ = "0+unknown"
|
|
52
|
+
|
|
53
|
+
__all__ = [
|
|
54
|
+
"__version__",
|
|
55
|
+
"AudioClip",
|
|
56
|
+
"AudioContent",
|
|
57
|
+
"AudioProperties",
|
|
58
|
+
"AudioTrack",
|
|
59
|
+
"BaseClip",
|
|
60
|
+
"Clip",
|
|
61
|
+
"CodedVisualClip",
|
|
62
|
+
"CompileStatus",
|
|
63
|
+
"CompoundAudioClip",
|
|
64
|
+
"CompoundClip",
|
|
65
|
+
"ExposedParameter",
|
|
66
|
+
"InsertMode",
|
|
67
|
+
"MediaClip",
|
|
68
|
+
"Position",
|
|
69
|
+
"RenderMode",
|
|
70
|
+
"Size",
|
|
71
|
+
"Source",
|
|
72
|
+
"TextClip",
|
|
73
|
+
"TextStyle",
|
|
74
|
+
"Timeline",
|
|
75
|
+
"Track",
|
|
76
|
+
"TrackKind",
|
|
77
|
+
"Transform",
|
|
78
|
+
"Variable",
|
|
79
|
+
"VariableType",
|
|
80
|
+
"VideoTrack",
|
|
81
|
+
"VisualClip",
|
|
82
|
+
"VisualContent",
|
|
83
|
+
"Time",
|
|
84
|
+
"TimelinePipeline",
|
|
85
|
+
"AssetResolver",
|
|
86
|
+
"DictAssetResolver",
|
|
87
|
+
"BaseExporter",
|
|
88
|
+
"DaVinciResolveExporter",
|
|
89
|
+
"FFmpegVideoExporter",
|
|
90
|
+
# exceptions
|
|
91
|
+
"VisualKitError",
|
|
92
|
+
"InvalidTimeError",
|
|
93
|
+
"TimelineValidationError",
|
|
94
|
+
"TemplateParameterError",
|
|
95
|
+
"MissingSourceError",
|
|
96
|
+
"CodedVisualError",
|
|
97
|
+
"ExportError",
|
|
98
|
+
"CodedVisualCompileError",
|
|
99
|
+
"BrowserNotFoundError",
|
|
100
|
+
]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""VisualKit engine library entry point."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
def main() -> None:
|
|
5
|
+
print("VisualKit is a video editing engine library.")
|
|
6
|
+
print("Usage: import visualkit as vk")
|
|
7
|
+
print("See the examples/ directory for usage demonstrations.")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
if __name__ == "__main__":
|
|
11
|
+
main()
|