visualkit 0.1.1__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.
Files changed (72) hide show
  1. {visualkit-0.1.1 → visualkit-2.0.1}/LICENSE +1 -1
  2. visualkit-2.0.1/PKG-INFO +225 -0
  3. visualkit-2.0.1/README.md +200 -0
  4. visualkit-2.0.1/pyproject.toml +69 -0
  5. visualkit-2.0.1/src/visualkit/__init__.py +100 -0
  6. visualkit-2.0.1/src/visualkit/__main__.py +11 -0
  7. visualkit-2.0.1/src/visualkit/coded_visual/__init__.py +8 -0
  8. visualkit-2.0.1/src/visualkit/coded_visual/browser.py +192 -0
  9. visualkit-2.0.1/src/visualkit/coded_visual/capture.py +227 -0
  10. visualkit-2.0.1/src/visualkit/coded_visual/compiler.py +438 -0
  11. visualkit-2.0.1/src/visualkit/coded_visual/project.py +186 -0
  12. visualkit-2.0.1/src/visualkit/engine/__init__.py +8 -0
  13. visualkit-2.0.1/src/visualkit/engine/asset_resolver.py +54 -0
  14. visualkit-2.0.1/src/visualkit/engine/pipeline.py +344 -0
  15. visualkit-2.0.1/src/visualkit/exporters/__init__.py +9 -0
  16. visualkit-2.0.1/src/visualkit/exporters/base.py +63 -0
  17. visualkit-2.0.1/src/visualkit/exporters/resolve.py +873 -0
  18. visualkit-2.0.1/src/visualkit/exporters/video.py +557 -0
  19. visualkit-2.0.1/src/visualkit/models/__init__.py +72 -0
  20. visualkit-2.0.1/src/visualkit/models/clips/__init__.py +44 -0
  21. visualkit-2.0.1/src/visualkit/models/clips/audio.py +30 -0
  22. visualkit-2.0.1/src/visualkit/models/clips/base.py +88 -0
  23. visualkit-2.0.1/src/visualkit/models/clips/coded_visual.py +375 -0
  24. visualkit-2.0.1/src/visualkit/models/clips/compound.py +287 -0
  25. visualkit-2.0.1/src/visualkit/models/clips/media.py +43 -0
  26. visualkit-2.0.1/src/visualkit/models/clips/text.py +89 -0
  27. visualkit-2.0.1/src/visualkit/models/clips/visual.py +102 -0
  28. visualkit-2.0.1/src/visualkit/models/timeline.py +1049 -0
  29. visualkit-2.0.1/src/visualkit/models/variable.py +186 -0
  30. visualkit-2.0.1/src/visualkit/py.typed +0 -0
  31. visualkit-2.0.1/src/visualkit/utils/__init__.py +0 -0
  32. visualkit-2.0.1/src/visualkit/utils/base_model.py +40 -0
  33. visualkit-2.0.1/src/visualkit/utils/exceptions.py +71 -0
  34. visualkit-2.0.1/src/visualkit/utils/time.py +498 -0
  35. visualkit-2.0.1/src/visualkit.egg-info/PKG-INFO +225 -0
  36. visualkit-2.0.1/src/visualkit.egg-info/SOURCES.txt +53 -0
  37. visualkit-2.0.1/src/visualkit.egg-info/requires.txt +4 -0
  38. {visualkit-0.1.1 → visualkit-2.0.1}/src/visualkit.egg-info/top_level.txt +1 -0
  39. visualkit-2.0.1/tests/test_clip_editing.py +609 -0
  40. visualkit-2.0.1/tests/test_coded_visual_compiler.py +237 -0
  41. visualkit-2.0.1/tests/test_package_exports.py +28 -0
  42. visualkit-2.0.1/tests/test_pipeline_semantics.py +199 -0
  43. visualkit-2.0.1/tests/test_rendering.py +450 -0
  44. visualkit-2.0.1/tests/test_resolve_correctness.py +170 -0
  45. visualkit-2.0.1/tests/test_resolve_exporter.py +296 -0
  46. visualkit-2.0.1/tests/test_time_and_variables.py +235 -0
  47. visualkit-2.0.1/tests/test_timeline.py +116 -0
  48. visualkit-2.0.1/tests/test_timeline_integrity.py +241 -0
  49. visualkit-2.0.1/tests/test_timeline_pipeline.py +396 -0
  50. visualkit-2.0.1/tests/test_variable_inspection.py +91 -0
  51. visualkit-2.0.1/tests/test_variables_and_clips.py +236 -0
  52. visualkit-2.0.1/tests/test_video_exporter.py +340 -0
  53. visualkit-0.1.1/PKG-INFO +0 -53
  54. visualkit-0.1.1/README.md +0 -40
  55. visualkit-0.1.1/pyproject.toml +0 -23
  56. visualkit-0.1.1/src/visualkit/__init__.py +0 -6
  57. visualkit-0.1.1/src/visualkit/__main__.py +0 -5
  58. visualkit-0.1.1/src/visualkit/config.py +0 -26
  59. visualkit-0.1.1/src/visualkit/editor.py +0 -183
  60. visualkit-0.1.1/src/visualkit/enums.py +0 -7
  61. visualkit-0.1.1/src/visualkit/media_element.py +0 -1356
  62. visualkit-0.1.1/src/visualkit/project_creator.py +0 -144
  63. visualkit-0.1.1/src/visualkit/text_element.py +0 -277
  64. visualkit-0.1.1/src/visualkit/timeline.py +0 -47
  65. visualkit-0.1.1/src/visualkit/transitions.py +0 -595
  66. visualkit-0.1.1/src/visualkit/utils.py +0 -5
  67. visualkit-0.1.1/src/visualkit.egg-info/PKG-INFO +0 -53
  68. visualkit-0.1.1/src/visualkit.egg-info/SOURCES.txt +0 -20
  69. visualkit-0.1.1/src/visualkit.egg-info/requires.txt +0 -1
  70. {visualkit-0.1.1 → visualkit-2.0.1}/AUTHORS.rst +0 -0
  71. {visualkit-0.1.1 → visualkit-2.0.1}/setup.cfg +0 -0
  72. {visualkit-0.1.1 → 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) 2025, Suraj Airi
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
 
@@ -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()
@@ -0,0 +1,8 @@
1
+ from .compiler import CodedVisualCompiler
2
+ from .project import CodedVisualManifest, load_coded_visual
3
+
4
+ __all__ = [
5
+ "CodedVisualCompiler",
6
+ "CodedVisualManifest",
7
+ "load_coded_visual",
8
+ ]