visualkit 2.0.1__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.
- {visualkit-2.0.1 → visualkit-2.1.0}/PKG-INFO +25 -5
- visualkit-2.0.1/src/visualkit.egg-info/PKG-INFO → visualkit-2.1.0/README.md +19 -28
- {visualkit-2.0.1 → visualkit-2.1.0}/pyproject.toml +11 -2
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/__init__.py +28 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/capture.py +78 -11
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/compiler.py +215 -5
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/pipeline.py +38 -5
- visualkit-2.1.0/src/visualkit/exporters/_ffmpeg.py +56 -0
- visualkit-2.1.0/src/visualkit/exporters/_render_plan.py +440 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/resolve.py +2 -1
- visualkit-2.1.0/src/visualkit/exporters/single_clip.py +188 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/video.py +92 -98
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/__init__.py +26 -0
- visualkit-2.1.0/src/visualkit/models/animation.py +208 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/__init__.py +4 -2
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/base.py +42 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/coded_visual.py +109 -5
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/compound.py +50 -4
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/media.py +42 -1
- visualkit-2.1.0/src/visualkit/models/clips/text.py +159 -0
- visualkit-2.1.0/src/visualkit/models/clips/visual.py +294 -0
- visualkit-2.1.0/src/visualkit/models/effects.py +266 -0
- visualkit-2.1.0/src/visualkit/models/keyframes.py +433 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/timeline.py +110 -8
- visualkit-2.0.1/README.md → visualkit-2.1.0/src/visualkit.egg-info/PKG-INFO +48 -3
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/SOURCES.txt +17 -1
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/top_level.txt +0 -1
- visualkit-2.1.0/tests/test_animation_presets.py +307 -0
- visualkit-2.1.0/tests/test_chroma_key.py +243 -0
- visualkit-2.1.0/tests/test_coded_visual_compiler.py +485 -0
- visualkit-2.1.0/tests/test_keyframe_rendering.py +487 -0
- visualkit-2.1.0/tests/test_keyframes.py +650 -0
- visualkit-2.1.0/tests/test_masks.py +252 -0
- visualkit-2.1.0/tests/test_positioning.py +64 -0
- visualkit-2.1.0/tests/test_preview_image.py +219 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_rendering.py +6 -3
- visualkit-2.1.0/tests/test_text_style.py +252 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline_integrity.py +35 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_variables_and_clips.py +115 -0
- visualkit-2.1.0/tests/test_video_alpha.py +185 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_video_exporter.py +5 -1
- visualkit-2.1.0/tests/test_visual_clip_fields.py +70 -0
- visualkit-2.0.1/src/visualkit/models/clips/text.py +0 -89
- visualkit-2.0.1/src/visualkit/models/clips/visual.py +0 -102
- visualkit-2.0.1/tests/test_coded_visual_compiler.py +0 -237
- {visualkit-2.0.1 → visualkit-2.1.0}/AUTHORS.rst +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/LICENSE +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/setup.cfg +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/__main__.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/__init__.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/browser.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/project.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/__init__.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/asset_resolver.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/__init__.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/base.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/audio.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/variable.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/py.typed +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/__init__.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/base_model.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/exceptions.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/time.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/dependency_links.txt +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/requires.txt +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_clip_editing.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_package_exports.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_pipeline_semantics.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_resolve_correctness.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_resolve_exporter.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_time_and_variables.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline_pipeline.py +0 -0
- {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_variable_inspection.py +0 -0
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: visualkit
|
|
3
|
-
Version: 2.0
|
|
3
|
+
Version: 2.1.0
|
|
4
4
|
Summary: A programmable video-editing engine: timelines, compound clips, and code-rendered (HTML/CSS/JS) visuals, exportable to video or DaVinci Resolve.
|
|
5
5
|
Author-email: Suraj Airi <surajairi.ml@gmail.com>
|
|
6
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
|
|
7
11
|
Keywords: video,editing,timeline,ffmpeg,davinci-resolve,fcpxml,xmeml,infographics
|
|
8
|
-
Classifier: Development Status ::
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
13
|
Classifier: Intended Audience :: Developers
|
|
10
14
|
Classifier: License :: OSI Approved :: MIT License
|
|
11
15
|
Classifier: Programming Language :: Python :: 3
|
|
@@ -32,9 +36,25 @@ composed on a `Timeline` and exported to a standalone video or to a project
|
|
|
32
36
|
file for import into DaVinci Resolve.
|
|
33
37
|
|
|
34
38
|
> **Status:** phase 1. Core timeline/clip model, coded-visual compilation,
|
|
35
|
-
> and export are implemented.
|
|
36
|
-
>
|
|
37
|
-
>
|
|
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/).
|
|
38
58
|
|
|
39
59
|
## Requirements
|
|
40
60
|
|
|
@@ -1,28 +1,3 @@
|
|
|
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
1
|
# VisualKit
|
|
27
2
|
|
|
28
3
|
A Python engine for programmatically building and exporting video timelines —
|
|
@@ -32,9 +7,25 @@ composed on a `Timeline` and exported to a standalone video or to a project
|
|
|
32
7
|
file for import into DaVinci Resolve.
|
|
33
8
|
|
|
34
9
|
> **Status:** phase 1. Core timeline/clip model, coded-visual compilation,
|
|
35
|
-
> and export are implemented.
|
|
36
|
-
>
|
|
37
|
-
>
|
|
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/).
|
|
38
29
|
|
|
39
30
|
## Requirements
|
|
40
31
|
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "visualkit"
|
|
7
|
-
version = "2.0
|
|
7
|
+
version = "2.1.0"
|
|
8
8
|
description = "A programmable video-editing engine: timelines, compound clips, and code-rendered (HTML/CSS/JS) visuals, exportable to video or DaVinci Resolve."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
authors = [{ name = "Suraj Airi", email = "surajairi.ml@gmail.com" }]
|
|
@@ -20,7 +20,7 @@ keywords = [
|
|
|
20
20
|
"infographics",
|
|
21
21
|
]
|
|
22
22
|
classifiers = [
|
|
23
|
-
"Development Status ::
|
|
23
|
+
"Development Status :: 4 - Beta",
|
|
24
24
|
"Intended Audience :: Developers",
|
|
25
25
|
"License :: OSI Approved :: MIT License",
|
|
26
26
|
"Programming Language :: Python :: 3",
|
|
@@ -47,7 +47,9 @@ dev = [
|
|
|
47
47
|
"playwright>=1.40",
|
|
48
48
|
"pillow>=10.0",
|
|
49
49
|
"ruff>=0.12.1",
|
|
50
|
+
"mkdocs-material>=9.7.7",
|
|
50
51
|
]
|
|
52
|
+
docs = ["mkdocs-material>=9.7.7"]
|
|
51
53
|
|
|
52
54
|
|
|
53
55
|
[tool.setuptools.packages.find]
|
|
@@ -67,3 +69,10 @@ asyncio_default_fixture_loop_scope = "function"
|
|
|
67
69
|
markers = [
|
|
68
70
|
"browser: drives a real headless Chrome/Chromium (skipped when none is installed)",
|
|
69
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"
|
|
@@ -3,24 +3,37 @@ from importlib.metadata import PackageNotFoundError, version
|
|
|
3
3
|
from visualkit.engine import AssetResolver, DictAssetResolver, TimelinePipeline
|
|
4
4
|
from visualkit.exporters import BaseExporter, DaVinciResolveExporter, FFmpegVideoExporter
|
|
5
5
|
from visualkit.models import (
|
|
6
|
+
KEYFRAMEABLE_PROPERTIES,
|
|
7
|
+
MASK_PROPERTIES,
|
|
8
|
+
AddClipResult,
|
|
9
|
+
AnimationPreset,
|
|
6
10
|
AudioClip,
|
|
7
11
|
AudioContent,
|
|
8
12
|
AudioProperties,
|
|
9
13
|
AudioTrack,
|
|
10
14
|
BaseClip,
|
|
15
|
+
ChromaKey,
|
|
11
16
|
Clip,
|
|
17
|
+
ClipAnimation,
|
|
12
18
|
CodedVisualClip,
|
|
13
19
|
CompileStatus,
|
|
14
20
|
CompoundAudioClip,
|
|
15
21
|
CompoundClip,
|
|
22
|
+
CurveSpec,
|
|
23
|
+
Easing,
|
|
16
24
|
ExposedParameter,
|
|
17
25
|
InsertMode,
|
|
26
|
+
Keyframe,
|
|
27
|
+
LintIssue,
|
|
28
|
+
Mask,
|
|
18
29
|
MediaClip,
|
|
19
30
|
Position,
|
|
31
|
+
PropertyCurve,
|
|
20
32
|
RenderMode,
|
|
21
33
|
Size,
|
|
22
34
|
Source,
|
|
23
35
|
TextClip,
|
|
36
|
+
TextGradient,
|
|
24
37
|
TextStyle,
|
|
25
38
|
Timeline,
|
|
26
39
|
Track,
|
|
@@ -31,6 +44,7 @@ from visualkit.models import (
|
|
|
31
44
|
VideoTrack,
|
|
32
45
|
VisualClip,
|
|
33
46
|
VisualContent,
|
|
47
|
+
color_to_rgb,
|
|
34
48
|
)
|
|
35
49
|
from visualkit.utils.exceptions import (
|
|
36
50
|
BrowserNotFoundError,
|
|
@@ -52,6 +66,7 @@ except PackageNotFoundError: # running from a source checkout that is not insta
|
|
|
52
66
|
|
|
53
67
|
__all__ = [
|
|
54
68
|
"__version__",
|
|
69
|
+
"AddClipResult",
|
|
55
70
|
"AudioClip",
|
|
56
71
|
"AudioContent",
|
|
57
72
|
"AudioProperties",
|
|
@@ -64,6 +79,7 @@ __all__ = [
|
|
|
64
79
|
"CompoundClip",
|
|
65
80
|
"ExposedParameter",
|
|
66
81
|
"InsertMode",
|
|
82
|
+
"LintIssue",
|
|
67
83
|
"MediaClip",
|
|
68
84
|
"Position",
|
|
69
85
|
"RenderMode",
|
|
@@ -97,4 +113,16 @@ __all__ = [
|
|
|
97
113
|
"ExportError",
|
|
98
114
|
"CodedVisualCompileError",
|
|
99
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",
|
|
100
128
|
]
|
|
@@ -77,6 +77,27 @@ def frame_times(duration: float, fps: float) -> list[float]:
|
|
|
77
77
|
return [i / fps for i in range(count)]
|
|
78
78
|
|
|
79
79
|
|
|
80
|
+
def encoder_args(alpha: bool, width: int = 0, height: int = 0) -> list[str]:
|
|
81
|
+
"""Output codec arguments (everything between the input and the output path)."""
|
|
82
|
+
if alpha:
|
|
83
|
+
# Lossless and keeps partial alpha. 4:2:0 subsamples chroma over 2x2 blocks, so an odd
|
|
84
|
+
# last row/column would share a block with a padding pixel and come back with a wrong
|
|
85
|
+
# colour; odd sizes therefore use 4:4:4 (exact, and no padding to change the size).
|
|
86
|
+
odd = bool(width % 2 or height % 2)
|
|
87
|
+
return ["-c:v", "ffv1", "-level", "3", "-pix_fmt", "yuva444p" if odd else "yuva420p"]
|
|
88
|
+
return [
|
|
89
|
+
"-c:v",
|
|
90
|
+
"libx264",
|
|
91
|
+
"-pix_fmt",
|
|
92
|
+
"yuv420p",
|
|
93
|
+
"-movflags",
|
|
94
|
+
"+faststart",
|
|
95
|
+
# yuv420p needs even dimensions.
|
|
96
|
+
"-vf",
|
|
97
|
+
"pad=ceil(iw/2)*2:ceil(ih/2)*2",
|
|
98
|
+
]
|
|
99
|
+
|
|
100
|
+
|
|
80
101
|
def capture_video(
|
|
81
102
|
*,
|
|
82
103
|
html_path: Path,
|
|
@@ -87,8 +108,16 @@ def capture_video(
|
|
|
87
108
|
fps: float,
|
|
88
109
|
ffmpeg: str = "ffmpeg",
|
|
89
110
|
timeout: float = 300.0,
|
|
111
|
+
alpha: bool = True,
|
|
90
112
|
) -> None:
|
|
91
|
-
"""Render ``html_path`` for ``duration`` seconds at ``fps`` into ``out_file
|
|
113
|
+
"""Render ``html_path`` for ``duration`` seconds at ``fps`` into ``out_file``.
|
|
114
|
+
|
|
115
|
+
With ``alpha=True`` (the default) the video is lossless FFV1 in Matroska
|
|
116
|
+
(``yuva420p``, or ``yuva444p`` for odd sizes), so a transparent page background stays transparent and
|
|
117
|
+
chroma-key/mask edges are not smeared by compression. ``alpha=False`` writes
|
|
118
|
+
the previous flat H.264 MP4 (transparency flattened to black), which is what
|
|
119
|
+
the DaVinci Resolve export keeps using. ``out_file``'s suffix should match
|
|
120
|
+
(``.mkv`` / ``.mp4``).
|
|
92
121
|
|
|
93
122
|
Frames are streamed straight into ffmpeg's stdin as PNGs; nothing is written
|
|
94
123
|
to disk per frame. Raises `CodedVisualCompileError` (with ffmpeg's stderr) on failure.
|
|
@@ -97,7 +126,7 @@ def capture_video(
|
|
|
97
126
|
out_file.parent.mkdir(parents=True, exist_ok=True)
|
|
98
127
|
if out_file.exists():
|
|
99
128
|
out_file.unlink()
|
|
100
|
-
tmp_out = out_file.with_suffix(".part.
|
|
129
|
+
tmp_out = out_file.with_suffix(f".part{out_file.suffix}")
|
|
101
130
|
|
|
102
131
|
times = frame_times(duration, fps)
|
|
103
132
|
cmd = [
|
|
@@ -114,15 +143,7 @@ def capture_video(
|
|
|
114
143
|
"png",
|
|
115
144
|
"-i",
|
|
116
145
|
"-",
|
|
117
|
-
|
|
118
|
-
"libx264",
|
|
119
|
-
"-pix_fmt",
|
|
120
|
-
"yuv420p",
|
|
121
|
-
"-movflags",
|
|
122
|
-
"+faststart",
|
|
123
|
-
# yuv420p needs even dimensions.
|
|
124
|
-
"-vf",
|
|
125
|
-
"pad=ceil(iw/2)*2:ceil(ih/2)*2",
|
|
146
|
+
*encoder_args(alpha, width, height),
|
|
126
147
|
str(tmp_out),
|
|
127
148
|
]
|
|
128
149
|
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
|
|
@@ -184,6 +205,52 @@ def _abort(proc: subprocess.Popen, partial: Path) -> None:
|
|
|
184
205
|
partial.unlink()
|
|
185
206
|
|
|
186
207
|
|
|
208
|
+
def capture_frame(
|
|
209
|
+
html_path: Path,
|
|
210
|
+
out_png: Path,
|
|
211
|
+
width: int,
|
|
212
|
+
height: int,
|
|
213
|
+
*,
|
|
214
|
+
time: float = 0.0,
|
|
215
|
+
timeout: float = 60.0,
|
|
216
|
+
) -> None:
|
|
217
|
+
"""Render a single frame of `html_path` at virtual time `time` (seconds) to `out_png`.
|
|
218
|
+
|
|
219
|
+
Unlike `visualkit.coded_visual.browser.screenshot` (which always captures
|
|
220
|
+
at t=0 via the Chrome CLI), this seeks the page's virtual clock and every
|
|
221
|
+
CSS/Web Animation to `time` first -- the same deterministic stepping
|
|
222
|
+
`capture_video` uses per-frame -- so it can preview any instant of an
|
|
223
|
+
animated visual, not just its first frame. Needs the optional
|
|
224
|
+
``playwright`` package; raises `CodedVisualCompileError` if it is missing
|
|
225
|
+
or the capture fails.
|
|
226
|
+
"""
|
|
227
|
+
sync_playwright = _require_playwright()
|
|
228
|
+
out_png.parent.mkdir(parents=True, exist_ok=True)
|
|
229
|
+
# page.clock.run_for only accepts int (whole) ticks -- see capture_video's
|
|
230
|
+
# identical rounding, which avoids passing a bare float here.
|
|
231
|
+
ms = int(round(max(0.0, time) * 1000.0))
|
|
232
|
+
|
|
233
|
+
with sync_playwright() as pw:
|
|
234
|
+
pw_browser = _launch(pw)
|
|
235
|
+
try:
|
|
236
|
+
context, page = _new_page(pw_browser, html_path, width, height)
|
|
237
|
+
try:
|
|
238
|
+
if ms > 0:
|
|
239
|
+
page.clock.run_for(ms)
|
|
240
|
+
page.evaluate(_SEEK_JS, float(ms))
|
|
241
|
+
png = page.screenshot(type="png", omit_background=True, animations="allow")
|
|
242
|
+
finally:
|
|
243
|
+
context.close()
|
|
244
|
+
except Exception as err:
|
|
245
|
+
raise CodedVisualCompileError(
|
|
246
|
+
f"Failed to capture frame of {html_path.name} at t={time}s: {err}"
|
|
247
|
+
) from err
|
|
248
|
+
finally:
|
|
249
|
+
pw_browser.close()
|
|
250
|
+
|
|
251
|
+
out_png.write_bytes(png)
|
|
252
|
+
|
|
253
|
+
|
|
187
254
|
def detect_motion(html_path: Path, width: int, height: int, *, timeout: float = 120.0) -> bool:
|
|
188
255
|
"""True if the page renders differently at two virtual times (i.e. it is animated).
|
|
189
256
|
|
|
@@ -29,18 +29,45 @@ from visualkit.models.clips.base import Size
|
|
|
29
29
|
from visualkit.models.clips.coded_visual import (
|
|
30
30
|
CodedVisualClip,
|
|
31
31
|
CompileStatus,
|
|
32
|
+
LintIssue,
|
|
32
33
|
RenderMode,
|
|
33
34
|
aspect_ratio_for,
|
|
34
35
|
parse_aspect_ratio,
|
|
35
36
|
)
|
|
36
|
-
from visualkit.utils.exceptions import CodedVisualCompileError
|
|
37
|
+
from visualkit.utils.exceptions import CodedVisualCompileError, CodedVisualError
|
|
37
38
|
|
|
38
39
|
_PLACEHOLDER = re.compile(r"\{\{\s*([A-Za-z_][\w.\-]*)\s*\}\}")
|
|
39
40
|
_RAW_PLACEHOLDER = re.compile(r"\{\{\{\s*([A-Za-z_][\w.\-]*)\s*\}\}\}")
|
|
40
41
|
_HEAD_OPEN = re.compile(r"<head(\s[^>]*)?>", re.IGNORECASE)
|
|
41
42
|
_HTML_OPEN = re.compile(r"<html(\s[^>]*)?>", re.IGNORECASE)
|
|
43
|
+
_CANVAS_CLASS = re.compile(r'class\s*=\s*["\'][^"\']*\bvisualkit-canvas\b[^"\']*["\']', re.IGNORECASE)
|
|
42
44
|
_STILL_IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp"}
|
|
43
45
|
|
|
46
|
+
# What validate_bundle() treats as "a reference to a local file": the usual
|
|
47
|
+
# HTML attributes that load an asset, and CSS url(...). Regex-based, like
|
|
48
|
+
# every other check in this file -- not a full HTML/CSS parser, so an
|
|
49
|
+
# unusual construct (e.g. a URL built up by JavaScript) can be missed.
|
|
50
|
+
_LOCAL_ASSET_ATTR = re.compile(
|
|
51
|
+
r'\b(?:src|href|poster)\s*=\s*(?P<q>["\'])(?P<url>[^"\']+)(?P=q)', re.IGNORECASE
|
|
52
|
+
)
|
|
53
|
+
_CSS_URL = re.compile(r'url\(\s*(?P<q>["\']?)(?P<url>[^"\')]+)(?P=q)\s*\)', re.IGNORECASE)
|
|
54
|
+
_URL_HAS_SCHEME = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*:")
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _is_local_reference(url: str) -> bool:
|
|
58
|
+
"""True if `url` looks like a relative reference to a file next to the
|
|
59
|
+
bundle's entrypoint, rather than a remote URL, a data URI, an anchor,
|
|
60
|
+
or an unresolved `{{ variable }}`."""
|
|
61
|
+
url = url.strip()
|
|
62
|
+
if not url or url.startswith("#"):
|
|
63
|
+
return False
|
|
64
|
+
if _PLACEHOLDER.search(url) or _RAW_PLACEHOLDER.search(url):
|
|
65
|
+
return False # substituted at render time; nothing to check here yet
|
|
66
|
+
if url.startswith("//") or _URL_HAS_SCHEME.match(url):
|
|
67
|
+
return False # protocol-relative or scheme:// (http, https, data, mailto, ...)
|
|
68
|
+
return True
|
|
69
|
+
|
|
70
|
+
|
|
44
71
|
# Files inside a bundle that affect rendering; hashed into the cache key.
|
|
45
72
|
_BUNDLE_HASH_LIMIT_BYTES = 64 * 1024 * 1024
|
|
46
73
|
|
|
@@ -68,6 +95,12 @@ def _stringify(value: Any) -> str:
|
|
|
68
95
|
return str(value)
|
|
69
96
|
|
|
70
97
|
|
|
98
|
+
#: Bumped whenever the encoded *format* of a rendered video changes (codec, pixel format,
|
|
99
|
+
#: container). The cache key otherwise hashes only the inputs, so without this a stale render in
|
|
100
|
+
#: an old format could be served after an upgrade.
|
|
101
|
+
VIDEO_FORMAT_VERSION = "2-ffv1-yuva420p"
|
|
102
|
+
|
|
103
|
+
|
|
71
104
|
class CodedVisualCompiler:
|
|
72
105
|
"""Renders `CodedVisualClip`s to PNG (still) or video (animated) media."""
|
|
73
106
|
|
|
@@ -105,7 +138,7 @@ class CodedVisualCompiler:
|
|
|
105
138
|
hasher.update(
|
|
106
139
|
f"{canvas_size.width:g}x{canvas_size.height:g}|{aspect_ratio}|{fps:g}|{duration:g}".encode()
|
|
107
140
|
)
|
|
108
|
-
hasher.update(f"|{render_mode}|{bundle_digest}".encode())
|
|
141
|
+
hasher.update(f"|{render_mode}|{bundle_digest}|{VIDEO_FORMAT_VERSION}".encode())
|
|
109
142
|
return hasher.hexdigest()
|
|
110
143
|
|
|
111
144
|
@staticmethod
|
|
@@ -324,6 +357,126 @@ class CodedVisualCompiler:
|
|
|
324
357
|
)
|
|
325
358
|
return target_html, cache_key
|
|
326
359
|
|
|
360
|
+
# ------------------------------------------------------------------ lint
|
|
361
|
+
def validate_bundle(self, clip: CodedVisualClip) -> list[LintIssue]:
|
|
362
|
+
"""Check that every local asset the bundle's HTML/CSS references
|
|
363
|
+
(an `<img src="logo.svg">`, a CSS `url(chart.js)`, ...) actually
|
|
364
|
+
exists next to the entrypoint. Pure Python, no Chrome.
|
|
365
|
+
|
|
366
|
+
A no-op (always `[]`) for a single-file HTML source -- there's
|
|
367
|
+
nothing beside it to reference. For a directory bundle, a missing
|
|
368
|
+
asset otherwise only surfaces as a broken `<img>`/404 in the
|
|
369
|
+
render, not an error.
|
|
370
|
+
|
|
371
|
+
Only scans the entrypoint HTML itself, not files it links to --
|
|
372
|
+
`url(...)` inside a separately-linked `style.css` isn't followed,
|
|
373
|
+
so a bad reference three files deep can still slip through.
|
|
374
|
+
"""
|
|
375
|
+
issues: list[LintIssue] = []
|
|
376
|
+
try:
|
|
377
|
+
info = self._resolve_inputs(clip)
|
|
378
|
+
except CodedVisualError as err:
|
|
379
|
+
issues.append(LintIssue(severity="error", code="resolve_failed", message=str(err)))
|
|
380
|
+
return issues
|
|
381
|
+
|
|
382
|
+
if not Path(clip.source.source).expanduser().resolve().is_dir():
|
|
383
|
+
return issues
|
|
384
|
+
|
|
385
|
+
bundle_dir = info["entrypoint"].parent
|
|
386
|
+
raw_html = info["raw_html"]
|
|
387
|
+
checked: set[str] = set()
|
|
388
|
+
for pattern in (_LOCAL_ASSET_ATTR, _CSS_URL):
|
|
389
|
+
for match in pattern.finditer(raw_html):
|
|
390
|
+
url = match.group("url")
|
|
391
|
+
if not _is_local_reference(url) or url in checked:
|
|
392
|
+
continue
|
|
393
|
+
checked.add(url)
|
|
394
|
+
relative_path = url.split("?", 1)[0].split("#", 1)[0]
|
|
395
|
+
asset_path = (bundle_dir / relative_path).resolve()
|
|
396
|
+
if not asset_path.exists():
|
|
397
|
+
issues.append(
|
|
398
|
+
LintIssue(
|
|
399
|
+
severity="error",
|
|
400
|
+
code="missing_asset",
|
|
401
|
+
message=(
|
|
402
|
+
f"Referenced local asset '{url}' does not exist (expected at "
|
|
403
|
+
f"{asset_path}, alongside {info['entrypoint'].name})."
|
|
404
|
+
),
|
|
405
|
+
)
|
|
406
|
+
)
|
|
407
|
+
return issues
|
|
408
|
+
|
|
409
|
+
def lint(self, clip: CodedVisualClip) -> list[LintIssue]:
|
|
410
|
+
"""Pure-Python pre-flight checks for `clip`, independent of Chrome.
|
|
411
|
+
|
|
412
|
+
Catches the majority of agent-authoring mistakes before spending a
|
|
413
|
+
browser launch on them: a missing `.visualkit-canvas` wrapper, a
|
|
414
|
+
`{{ variable }}`/`{{{ variable }}}` that doesn't match any declared
|
|
415
|
+
variable, a referenced local asset that doesn't exist (see
|
|
416
|
+
`validate_bundle`), or a source/manifest that fails to load at
|
|
417
|
+
all. Returns a list of `LintIssue`s (empty means nothing was
|
|
418
|
+
found); never raises for anything a real compile could hit --
|
|
419
|
+
those become an "error"-severity issue instead.
|
|
420
|
+
"""
|
|
421
|
+
issues: list[LintIssue] = []
|
|
422
|
+
try:
|
|
423
|
+
info = self._resolve_inputs(clip)
|
|
424
|
+
except CodedVisualError as err:
|
|
425
|
+
issues.append(LintIssue(severity="error", code="resolve_failed", message=str(err)))
|
|
426
|
+
return issues
|
|
427
|
+
|
|
428
|
+
raw_html = info["raw_html"]
|
|
429
|
+
variables = info["variables"]
|
|
430
|
+
|
|
431
|
+
if not _CANVAS_CLASS.search(raw_html):
|
|
432
|
+
issues.append(
|
|
433
|
+
LintIssue(
|
|
434
|
+
severity="error",
|
|
435
|
+
code="missing_canvas",
|
|
436
|
+
message=(
|
|
437
|
+
'No element with class="visualkit-canvas" found. Without it, '
|
|
438
|
+
"auto-scaling/fit has nothing to act on and the render is likely "
|
|
439
|
+
"blank or wrongly sized. Wrap the visual's root element, e.g. "
|
|
440
|
+
'<div class="visualkit-canvas">...</div>.'
|
|
441
|
+
),
|
|
442
|
+
)
|
|
443
|
+
)
|
|
444
|
+
|
|
445
|
+
referenced: set[str] = set()
|
|
446
|
+
for pattern, braces in ((_RAW_PLACEHOLDER, "{{{ }}}"), (_PLACEHOLDER, "{{ }}")):
|
|
447
|
+
for match in pattern.finditer(raw_html):
|
|
448
|
+
name = match.group(1)
|
|
449
|
+
referenced.add(name)
|
|
450
|
+
if name not in variables:
|
|
451
|
+
issues.append(
|
|
452
|
+
LintIssue(
|
|
453
|
+
severity="error",
|
|
454
|
+
code="unresolved_variable",
|
|
455
|
+
message=(
|
|
456
|
+
f"{braces} placeholder references '{name}', which is not a "
|
|
457
|
+
"declared clip or manifest variable -- it will render "
|
|
458
|
+
f"literally as '{match.group(0)}' instead of being substituted."
|
|
459
|
+
),
|
|
460
|
+
)
|
|
461
|
+
)
|
|
462
|
+
|
|
463
|
+
unused = sorted(set(variables) - referenced)
|
|
464
|
+
if unused:
|
|
465
|
+
issues.append(
|
|
466
|
+
LintIssue(
|
|
467
|
+
severity="warning",
|
|
468
|
+
code="unused_variable",
|
|
469
|
+
message=(
|
|
470
|
+
f"Declared variable(s) {', '.join(unused)} aren't referenced by any "
|
|
471
|
+
"{{ }}/{{{ }}} placeholder in the HTML. Fine if they're read from "
|
|
472
|
+
"window.__VARIABLES__ in JavaScript instead."
|
|
473
|
+
),
|
|
474
|
+
)
|
|
475
|
+
)
|
|
476
|
+
|
|
477
|
+
issues.extend(self.validate_bundle(clip))
|
|
478
|
+
return issues
|
|
479
|
+
|
|
327
480
|
# ------------------------------------------------------------------ rendering
|
|
328
481
|
@staticmethod
|
|
329
482
|
def _find_chrome_executable() -> str | None:
|
|
@@ -342,20 +495,51 @@ class CodedVisualCompiler:
|
|
|
342
495
|
clip.compile_status = CompileStatus.READY
|
|
343
496
|
return out
|
|
344
497
|
|
|
498
|
+
def preview_image(self, clip: CodedVisualClip, *, force: bool = False) -> Path:
|
|
499
|
+
"""Render `clip` as a single still frame and return its PNG path,
|
|
500
|
+
without recording it as the clip's compiled media -- unlike
|
|
501
|
+
`render_to_image`, `clip.media_source`/`compile_status` are left
|
|
502
|
+
exactly as they were before the call.
|
|
503
|
+
|
|
504
|
+
This is the same lightweight Chrome-CLI screenshot `render_to_image`
|
|
505
|
+
uses (no `playwright` dependency), so it's the cheapest possible
|
|
506
|
+
correctness check for a coded visual's own HTML/CSS/variables --
|
|
507
|
+
e.g. a missing `.visualkit-canvas` wrapper or a malformed
|
|
508
|
+
`{{ variable }}` -- before spending a real `compile()` or timeline
|
|
509
|
+
round trip on it.
|
|
510
|
+
|
|
511
|
+
For an *animated* visual this is not a guaranteed frame-0 capture:
|
|
512
|
+
Chrome is given a `--virtual-time-budget` to run in before the
|
|
513
|
+
screenshot (see `browser.screenshot`), so an in-progress animation
|
|
514
|
+
may show partway through, same as `render_to_image` itself. Use
|
|
515
|
+
`preview_frame(0.0)` instead if you need a deterministic first
|
|
516
|
+
frame of an animated visual.
|
|
517
|
+
"""
|
|
518
|
+
prev_status, prev_media = clip.compile_status, clip.media_source
|
|
519
|
+
try:
|
|
520
|
+
return self.render_to_image(clip, force=force)
|
|
521
|
+
finally:
|
|
522
|
+
clip.compile_status, clip.media_source = prev_status, prev_media
|
|
523
|
+
|
|
345
524
|
def render_to_video(
|
|
346
525
|
self,
|
|
347
526
|
clip: CodedVisualClip,
|
|
348
527
|
output_path: str | Path | None = None,
|
|
349
528
|
fps: float | None = None,
|
|
350
529
|
force: bool = False,
|
|
530
|
+
alpha: bool = True,
|
|
351
531
|
) -> Path:
|
|
352
|
-
"""Render `clip`'s animation to a video file (see `visualkit.coded_visual.capture`).
|
|
532
|
+
"""Render `clip`'s animation to a video file (see `visualkit.coded_visual.capture`).
|
|
533
|
+
|
|
534
|
+
``alpha=True`` (default) writes ``render.mkv`` (lossless FFV1 with transparency);
|
|
535
|
+
``alpha=False`` writes the flat H.264 ``render.mp4``.
|
|
536
|
+
"""
|
|
353
537
|
from visualkit.coded_visual.capture import capture_video
|
|
354
538
|
|
|
355
539
|
info = self._resolve_inputs(clip)
|
|
356
540
|
target_html, cache_key = self._write_bundle(clip, info)
|
|
357
541
|
bundle_dir = target_html.parent
|
|
358
|
-
cached = bundle_dir / "render.mp4"
|
|
542
|
+
cached = bundle_dir / ("render.mkv" if alpha else "render.mp4")
|
|
359
543
|
|
|
360
544
|
if force or not cached.exists():
|
|
361
545
|
if shutil.which(self.ffmpeg) is None:
|
|
@@ -369,6 +553,7 @@ class CodedVisualCompiler:
|
|
|
369
553
|
fps=fps or info["fps"],
|
|
370
554
|
ffmpeg=self.ffmpeg,
|
|
371
555
|
timeout=self.render_timeout,
|
|
556
|
+
alpha=alpha,
|
|
372
557
|
)
|
|
373
558
|
|
|
374
559
|
out = cached
|
|
@@ -380,6 +565,30 @@ class CodedVisualCompiler:
|
|
|
380
565
|
clip.compile_status = CompileStatus.READY
|
|
381
566
|
return out
|
|
382
567
|
|
|
568
|
+
def preview_frame(self, clip: CodedVisualClip, time: float = 0.0, *, force: bool = False) -> Path:
|
|
569
|
+
"""Render a single frame of `clip` at virtual time `time` seconds, without
|
|
570
|
+
encoding a video and without affecting `clip.media_source`/`compile_status`.
|
|
571
|
+
|
|
572
|
+
Cheap way to check an individual instant of an animated coded visual
|
|
573
|
+
(e.g. mid-way through its motion) before committing to a full
|
|
574
|
+
`render_to_video`/`compile()` call. Needs the optional `playwright`
|
|
575
|
+
package, same as `render_to_video`; still visuals can also just use
|
|
576
|
+
`render_to_image` (no browser-clock stepping needed for a static page).
|
|
577
|
+
Cached per `(cache_key, time)` under the bundle dir, so repeated
|
|
578
|
+
previews of the same frame are free.
|
|
579
|
+
"""
|
|
580
|
+
from visualkit.coded_visual.capture import capture_frame
|
|
581
|
+
|
|
582
|
+
info = self._resolve_inputs(clip)
|
|
583
|
+
target_html, cache_key = self._write_bundle(clip, info)
|
|
584
|
+
# Slug the timestamp into the filename (3dp is sub-frame precision at any
|
|
585
|
+
# realistic fps) so distinct preview times don't collide or overwrite.
|
|
586
|
+
out = target_html.parent / f"preview_{max(0.0, time):.3f}.png"
|
|
587
|
+
if force or not out.exists():
|
|
588
|
+
width, height = int(info["canvas"].width), int(info["canvas"].height)
|
|
589
|
+
capture_frame(target_html, out, width, height, time=time, timeout=self.render_timeout)
|
|
590
|
+
return out
|
|
591
|
+
|
|
383
592
|
def is_animated(self, clip: CodedVisualClip) -> bool:
|
|
384
593
|
"""Decide whether `clip` needs video (True) or a still image (False).
|
|
385
594
|
|
|
@@ -410,6 +619,7 @@ class CodedVisualCompiler:
|
|
|
410
619
|
clip: CodedVisualClip,
|
|
411
620
|
force: bool = False,
|
|
412
621
|
render_video: bool | None = None,
|
|
622
|
+
alpha: bool = True,
|
|
413
623
|
) -> str:
|
|
414
624
|
"""Render `clip` to media and return the media path.
|
|
415
625
|
|
|
@@ -425,7 +635,7 @@ class CodedVisualCompiler:
|
|
|
425
635
|
else:
|
|
426
636
|
animated = render_video
|
|
427
637
|
path = (
|
|
428
|
-
self.render_to_video(clip, force=force)
|
|
638
|
+
self.render_to_video(clip, force=force, alpha=alpha)
|
|
429
639
|
if animated
|
|
430
640
|
else self.render_to_image(clip, force=force)
|
|
431
641
|
)
|