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.
Files changed (74) hide show
  1. {visualkit-2.0.1 → visualkit-2.1.0}/PKG-INFO +25 -5
  2. visualkit-2.0.1/src/visualkit.egg-info/PKG-INFO → visualkit-2.1.0/README.md +19 -28
  3. {visualkit-2.0.1 → visualkit-2.1.0}/pyproject.toml +11 -2
  4. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/__init__.py +28 -0
  5. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/capture.py +78 -11
  6. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/compiler.py +215 -5
  7. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/pipeline.py +38 -5
  8. visualkit-2.1.0/src/visualkit/exporters/_ffmpeg.py +56 -0
  9. visualkit-2.1.0/src/visualkit/exporters/_render_plan.py +440 -0
  10. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/resolve.py +2 -1
  11. visualkit-2.1.0/src/visualkit/exporters/single_clip.py +188 -0
  12. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/video.py +92 -98
  13. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/__init__.py +26 -0
  14. visualkit-2.1.0/src/visualkit/models/animation.py +208 -0
  15. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/__init__.py +4 -2
  16. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/base.py +42 -0
  17. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/coded_visual.py +109 -5
  18. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/compound.py +50 -4
  19. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/media.py +42 -1
  20. visualkit-2.1.0/src/visualkit/models/clips/text.py +159 -0
  21. visualkit-2.1.0/src/visualkit/models/clips/visual.py +294 -0
  22. visualkit-2.1.0/src/visualkit/models/effects.py +266 -0
  23. visualkit-2.1.0/src/visualkit/models/keyframes.py +433 -0
  24. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/timeline.py +110 -8
  25. visualkit-2.0.1/README.md → visualkit-2.1.0/src/visualkit.egg-info/PKG-INFO +48 -3
  26. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/SOURCES.txt +17 -1
  27. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/top_level.txt +0 -1
  28. visualkit-2.1.0/tests/test_animation_presets.py +307 -0
  29. visualkit-2.1.0/tests/test_chroma_key.py +243 -0
  30. visualkit-2.1.0/tests/test_coded_visual_compiler.py +485 -0
  31. visualkit-2.1.0/tests/test_keyframe_rendering.py +487 -0
  32. visualkit-2.1.0/tests/test_keyframes.py +650 -0
  33. visualkit-2.1.0/tests/test_masks.py +252 -0
  34. visualkit-2.1.0/tests/test_positioning.py +64 -0
  35. visualkit-2.1.0/tests/test_preview_image.py +219 -0
  36. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_rendering.py +6 -3
  37. visualkit-2.1.0/tests/test_text_style.py +252 -0
  38. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline_integrity.py +35 -0
  39. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_variables_and_clips.py +115 -0
  40. visualkit-2.1.0/tests/test_video_alpha.py +185 -0
  41. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_video_exporter.py +5 -1
  42. visualkit-2.1.0/tests/test_visual_clip_fields.py +70 -0
  43. visualkit-2.0.1/src/visualkit/models/clips/text.py +0 -89
  44. visualkit-2.0.1/src/visualkit/models/clips/visual.py +0 -102
  45. visualkit-2.0.1/tests/test_coded_visual_compiler.py +0 -237
  46. {visualkit-2.0.1 → visualkit-2.1.0}/AUTHORS.rst +0 -0
  47. {visualkit-2.0.1 → visualkit-2.1.0}/LICENSE +0 -0
  48. {visualkit-2.0.1 → visualkit-2.1.0}/setup.cfg +0 -0
  49. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/__main__.py +0 -0
  50. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/__init__.py +0 -0
  51. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/browser.py +0 -0
  52. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/coded_visual/project.py +0 -0
  53. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/__init__.py +0 -0
  54. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/engine/asset_resolver.py +0 -0
  55. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/__init__.py +0 -0
  56. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/exporters/base.py +0 -0
  57. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/clips/audio.py +0 -0
  58. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/models/variable.py +0 -0
  59. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/py.typed +0 -0
  60. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/__init__.py +0 -0
  61. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/base_model.py +0 -0
  62. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/exceptions.py +0 -0
  63. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit/utils/time.py +0 -0
  64. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/dependency_links.txt +0 -0
  65. {visualkit-2.0.1 → visualkit-2.1.0}/src/visualkit.egg-info/requires.txt +0 -0
  66. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_clip_editing.py +0 -0
  67. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_package_exports.py +0 -0
  68. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_pipeline_semantics.py +0 -0
  69. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_resolve_correctness.py +0 -0
  70. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_resolve_exporter.py +0 -0
  71. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_time_and_variables.py +0 -0
  72. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline.py +0 -0
  73. {visualkit-2.0.1 → visualkit-2.1.0}/tests/test_timeline_pipeline.py +0 -0
  74. {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.1
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 :: 3 - Alpha
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. Keyframes, transitions, masking/chroma-key,
36
- > and other advanced editing features are on the roadmap (see `notes/`) but
37
- > not yet built.
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. Keyframes, transitions, masking/chroma-key,
36
- > and other advanced editing features are on the roadmap (see `notes/`) but
37
- > not yet built.
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.1"
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 :: 3 - Alpha",
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`` (H.264 MP4).
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.mp4")
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
- "-c:v",
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
  )