visualkit 0.1.4__tar.gz → 2.1.0__tar.gz

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