scenescript 0.1.0__py3-none-any.whl
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.
- scenescript/__init__.py +3 -0
- scenescript/_readme.md +526 -0
- scenescript/animation.py +43 -0
- scenescript/audio.py +144 -0
- scenescript/backgrounds.py +54 -0
- scenescript/cli.py +136 -0
- scenescript/colors.py +28 -0
- scenescript/easing.py +40 -0
- scenescript/encoder.py +108 -0
- scenescript/errors.py +28 -0
- scenescript/geometry.py +70 -0
- scenescript/mcp_server.py +174 -0
- scenescript/probe.py +69 -0
- scenescript/progress.py +42 -0
- scenescript/renderer.py +94 -0
- scenescript/scenes.py +140 -0
- scenescript/spec.py +607 -0
- scenescript/sprites.py +109 -0
- scenescript/timeline.py +97 -0
- scenescript/transitions.py +84 -0
- scenescript/validation.py +177 -0
- scenescript/videoreader.py +96 -0
- scenescript-0.1.0.dist-info/METADATA +546 -0
- scenescript-0.1.0.dist-info/RECORD +27 -0
- scenescript-0.1.0.dist-info/WHEEL +4 -0
- scenescript-0.1.0.dist-info/entry_points.txt +3 -0
- scenescript-0.1.0.dist-info/licenses/LICENSE +21 -0
scenescript/__init__.py
ADDED
scenescript/_readme.md
ADDED
|
@@ -0,0 +1,526 @@
|
|
|
1
|
+
# SceneScript
|
|
2
|
+
|
|
3
|
+
SceneScript is a Python command-line tool that renders complete videos from declarative JSON files. One JSON document describes the whole video: text overlays, backgrounds, inserted video clips, images, shapes, scene transitions, and audio tracks.
|
|
4
|
+
|
|
5
|
+
The same JSON always produces the same video. There are no LLMs in the pipeline, and no video-editing frameworks (no MoviePy, no editly, no Remotion). Frames are composed directly with Pillow and numpy; ffmpeg is used only as the encoder/muxer at the edges of the pipeline.
|
|
6
|
+
|
|
7
|
+
## How It Works
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
video.json ──► parse & validate ──► compose frames ──► encode ──► mix audio ──► output.mp4
|
|
11
|
+
(schema check, (Pillow/numpy, (frames (tracks,
|
|
12
|
+
asset check) scene by scene) piped to fades,
|
|
13
|
+
ffmpeg) volume)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
1. **Parse & validate.** The JSON is checked against the schema, and every referenced asset (clips, images, fonts, audio) must exist before any rendering starts.
|
|
17
|
+
2. **Compose frames.** Each scene is rendered frame-by-frame: background first, then elements in document order, with per-frame animation values applied. Transitions blend the boundary frames of adjacent scenes.
|
|
18
|
+
3. **Encode.** Raw frames are piped straight into ffmpeg. No intermediate image files are written.
|
|
19
|
+
4. **Mix audio.** Audio tracks, plus audio from inserted clips, are trimmed, faded, volume-adjusted, and mixed into the final container.
|
|
20
|
+
|
|
21
|
+
## Requirements
|
|
22
|
+
|
|
23
|
+
- Python 3.11+
|
|
24
|
+
- [ffmpeg](https://ffmpeg.org/) available on your `PATH`
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
git clone <this repository>
|
|
30
|
+
cd SceneScript
|
|
31
|
+
pip install .
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
Create `video.json`:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"output": { "width": 1920, "height": 1080, "fps": 30 },
|
|
41
|
+
"scenes": [
|
|
42
|
+
{
|
|
43
|
+
"duration": 4,
|
|
44
|
+
"background": { "type": "color", "color": "#1a1a2e" },
|
|
45
|
+
"elements": [
|
|
46
|
+
{
|
|
47
|
+
"type": "text",
|
|
48
|
+
"content": "Hello, world",
|
|
49
|
+
"start": 0.5,
|
|
50
|
+
"end": 3.5,
|
|
51
|
+
"position": "center",
|
|
52
|
+
"size": 96,
|
|
53
|
+
"color": "#ffffff"
|
|
54
|
+
}
|
|
55
|
+
],
|
|
56
|
+
"transition": { "type": "fade", "duration": 1.0 }
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
"duration": 8,
|
|
60
|
+
"elements": [
|
|
61
|
+
{ "type": "video", "src": "assets/clip.mp4", "fit": "cover" }
|
|
62
|
+
]
|
|
63
|
+
}
|
|
64
|
+
],
|
|
65
|
+
"audio": [
|
|
66
|
+
{ "src": "assets/music.mp3", "start": 0, "volume": 0.6, "fade_out": 2.0 }
|
|
67
|
+
]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Render it:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
scenescript render video.json -o output.mp4
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## JSON Reference
|
|
78
|
+
|
|
79
|
+
### Top Level
|
|
80
|
+
|
|
81
|
+
| Key | Type | Required | Description |
|
|
82
|
+
|----------|--------|----------|-------------|
|
|
83
|
+
| `output` | object | no | Output settings. Defaults: `1920×1080`, `30` fps, `mp4`. |
|
|
84
|
+
| `scenes` | array | yes | Ordered list of scenes, played back to back. |
|
|
85
|
+
| `defs` | object | no | Named, reusable element groups (see [Reusable Elements](#reusable-elements)). |
|
|
86
|
+
| `audio` | array | no | Global audio tracks spanning the whole video. |
|
|
87
|
+
|
|
88
|
+
#### `output`
|
|
89
|
+
|
|
90
|
+
```json
|
|
91
|
+
{ "width": 1920, "height": 1080, "fps": 30, "format": "mp4" }
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
| Key | Type | Default | Description |
|
|
95
|
+
|----------|--------|----------|-------------|
|
|
96
|
+
| `width` | int | `1920` | Frame width in pixels. |
|
|
97
|
+
| `height` | int | `1080` | Frame height in pixels. |
|
|
98
|
+
| `fps` | int | `30` | Frames per second. |
|
|
99
|
+
| `format` | string | `"mp4"` | Container format: `mp4`, `mkv`, or `webm`. |
|
|
100
|
+
|
|
101
|
+
### Scenes
|
|
102
|
+
|
|
103
|
+
A scene is a self-contained span of time with its own background and elements. Scenes play in document order; the video's total duration is the sum of scene durations (transitions overlap scene boundaries and do not add time).
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"duration": 5,
|
|
108
|
+
"background": { "type": "color", "color": "#1a1a2e" },
|
|
109
|
+
"elements": [ ... ],
|
|
110
|
+
"transition": { "type": "fade", "duration": 1.0 }
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
| Key | Type | Required | Description |
|
|
115
|
+
|--------------|--------|----------|-------------|
|
|
116
|
+
| `duration` | number | yes | Scene length in seconds. |
|
|
117
|
+
| `background` | object | no | Scene background (defaults to black). |
|
|
118
|
+
| `elements` | array | no | Elements drawn over the background, in document order (later = on top). |
|
|
119
|
+
| `transition` | object | no | Transition into the *next* scene (ignored on the last scene). Defaults to a hard cut. |
|
|
120
|
+
|
|
121
|
+
#### Backgrounds
|
|
122
|
+
|
|
123
|
+
Solid color:
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{ "type": "color", "color": "#1a1a2e" }
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Linear gradient:
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{ "type": "gradient", "from": "#1a1a2e", "to": "#16213e", "angle": 45 }
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Full-frame image:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{ "type": "image", "src": "assets/backdrop.png", "fit": "cover" }
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Elements
|
|
142
|
+
|
|
143
|
+
All element types share these keys:
|
|
144
|
+
|
|
145
|
+
| Key | Type | Default | Description |
|
|
146
|
+
|--------------|---------------|----------------|-------------|
|
|
147
|
+
| `type` | string | — | `text`, `video`, `image`, `shape`, or `ref` (see [Reusable Elements](#reusable-elements)). |
|
|
148
|
+
| `start` | number | `0` | Seconds into the scene when the element appears. |
|
|
149
|
+
| `end` | number | scene duration | Seconds into the scene when the element disappears. |
|
|
150
|
+
| `position` | string/object | `"center"` | Named anchor (`center`, `top`, `bottom`, `top-left`, `top-right`, `bottom-left`, `bottom-right`) or explicit `{ "x": 100, "y": 200 }` pixel coordinates of the element's center. |
|
|
151
|
+
| `opacity` | number | `1.0` | `0.0`–`1.0`. |
|
|
152
|
+
| `animations` | array | `[]` | Keyframed property animations (see [Animations](#animations)). |
|
|
153
|
+
|
|
154
|
+
#### `text`
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"type": "text",
|
|
159
|
+
"content": "Chapter One",
|
|
160
|
+
"start": 0.5,
|
|
161
|
+
"end": 4.0,
|
|
162
|
+
"position": "center",
|
|
163
|
+
"font": "assets/fonts/Inter-Bold.ttf",
|
|
164
|
+
"size": 96,
|
|
165
|
+
"color": "#ffffff",
|
|
166
|
+
"align": "center",
|
|
167
|
+
"max_width": 1600
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
| Key | Type | Default | Description |
|
|
172
|
+
|-------------|--------|----------------|-------------|
|
|
173
|
+
| `content` | string | — | The text to display. Supports `\n` for manual line breaks. |
|
|
174
|
+
| `font` | string | bundled default | Path to a `.ttf`/`.otf` file. |
|
|
175
|
+
| `size` | int | `48` | Font size in pixels. |
|
|
176
|
+
| `color` | string | `"#ffffff"` | Hex color. |
|
|
177
|
+
| `align` | string | `"center"` | `left`, `center`, or `right` (for multi-line text). |
|
|
178
|
+
| `max_width` | int | frame width | Wrap text to fit this pixel width. |
|
|
179
|
+
|
|
180
|
+
#### `video`
|
|
181
|
+
|
|
182
|
+
Inserts a video clip as an element. A clip covering the full frame for the full scene is the common case, but clips can also be positioned and timed like any other element (picture-in-picture).
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
{
|
|
186
|
+
"type": "video",
|
|
187
|
+
"src": "assets/clip.mp4",
|
|
188
|
+
"trim": { "start": 2.0, "end": 10.0 },
|
|
189
|
+
"fit": "cover",
|
|
190
|
+
"volume": 1.0
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
| Key | Type | Default | Description |
|
|
195
|
+
|----------|--------|-----------|-------------|
|
|
196
|
+
| `src` | string | — | Path to the clip, relative to the JSON file. |
|
|
197
|
+
| `trim` | object | full clip | Portion of the source clip to use, in source seconds. |
|
|
198
|
+
| `fit` | string | `"cover"` | `cover` (fill, cropping as needed), `contain` (letterbox), or `stretch`. |
|
|
199
|
+
| `scale` | number | `1.0` | Uniform scale applied after `fit` (useful for picture-in-picture). |
|
|
200
|
+
| `volume` | number | `1.0` | The clip's own audio level; `0` mutes it. |
|
|
201
|
+
|
|
202
|
+
If the trimmed clip is shorter than its element window, it holds its last frame; if longer, it is cut off at `end`.
|
|
203
|
+
|
|
204
|
+
#### `image`
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
{
|
|
208
|
+
"type": "image",
|
|
209
|
+
"src": "assets/logo.png",
|
|
210
|
+
"position": "top-right",
|
|
211
|
+
"scale": 0.5
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
| Key | Type | Default | Description |
|
|
216
|
+
|---------|--------|---------|-------------|
|
|
217
|
+
| `src` | string | — | Path to a PNG/JPEG (PNG alpha is respected). |
|
|
218
|
+
| `scale` | number | `1.0` | Uniform scale relative to the source's native size. |
|
|
219
|
+
| `fit` | string | none | Optional `cover`/`contain`/`stretch` to size against the full frame instead of `scale`. |
|
|
220
|
+
|
|
221
|
+
#### `shape`
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"type": "shape",
|
|
226
|
+
"shape": "rect",
|
|
227
|
+
"width": 800,
|
|
228
|
+
"height": 4,
|
|
229
|
+
"fill": "#e94560",
|
|
230
|
+
"position": { "x": 960, "y": 700 }
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
| Key | Type | Default | Description |
|
|
235
|
+
|----------------|--------|---------|-------------|
|
|
236
|
+
| `shape` | string | — | `rect`, `ellipse`, or `line`. |
|
|
237
|
+
| `width`/`height` | int | — | Dimensions in pixels (`line` uses `x2`/`y2` endpoints instead). |
|
|
238
|
+
| `fill` | string | none | Fill color. |
|
|
239
|
+
| `stroke` | string | none | Stroke color. |
|
|
240
|
+
| `stroke_width` | int | `1` | Stroke thickness in pixels. |
|
|
241
|
+
| `radius` | int | `0` | Corner radius for `rect`. |
|
|
242
|
+
|
|
243
|
+
### Reusable Elements
|
|
244
|
+
|
|
245
|
+
Define a group of elements once under the top-level `defs` key, then insert it anywhere with a `ref` element. This suits composites you use in many scenes — a mock IDE window, a lower third, a watermark block:
|
|
246
|
+
|
|
247
|
+
```json
|
|
248
|
+
{
|
|
249
|
+
"defs": {
|
|
250
|
+
"ide": [
|
|
251
|
+
{ "type": "shape", "shape": "rect", "position": { "x": 960, "y": 540 }, "width": 1800, "height": 1000, "fill": "#1e1e1e", "radius": 12 },
|
|
252
|
+
{ "type": "shape", "shape": "rect", "position": { "x": 960, "y": 80 }, "width": 1800, "height": 80, "fill": "#2d2d2d" },
|
|
253
|
+
{ "type": "text", "content": "main.py", "position": { "x": 960, "y": 80 }, "size": 28 }
|
|
254
|
+
]
|
|
255
|
+
},
|
|
256
|
+
"scenes": [
|
|
257
|
+
{
|
|
258
|
+
"duration": 8,
|
|
259
|
+
"elements": [
|
|
260
|
+
{ "type": "ref", "name": "ide" },
|
|
261
|
+
{ "type": "text", "content": "def render():", "position": { "x": 300, "y": 200 } }
|
|
262
|
+
]
|
|
263
|
+
}
|
|
264
|
+
]
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
| Key | Type | Required | Description |
|
|
269
|
+
|----------|--------|----------|-------------|
|
|
270
|
+
| `name` | string | yes | The def to insert. |
|
|
271
|
+
| `offset` | object | no | `{ "x": dx, "y": dy }` added to every inserted element's position (after named anchors resolve). Defaults to no shift. |
|
|
272
|
+
|
|
273
|
+
A `ref` splices the def's elements in place, keeping layer order: the def's elements draw in their own order, and anything listed after the ref draws on top — so a def works naturally as a background composite under per-scene content. Defs may reference other defs (offsets accumulate); circular references are a validation error. A def element that omits `end` runs to the end of whichever scene uses it. Every def is validated once at its own path (problems read `defs.ide[2].size: ...`), whether or not it is used.
|
|
274
|
+
|
|
275
|
+
### Animations
|
|
276
|
+
|
|
277
|
+
Any element can animate `position`, `opacity`, or `scale` with keyframes. Times are in seconds relative to the element's `start`. Values between keyframes are interpolated; before the first and after the last keyframe, the boundary value holds.
|
|
278
|
+
|
|
279
|
+
```json
|
|
280
|
+
{
|
|
281
|
+
"type": "text",
|
|
282
|
+
"content": "Sliding in",
|
|
283
|
+
"start": 1.0,
|
|
284
|
+
"end": 5.0,
|
|
285
|
+
"animations": [
|
|
286
|
+
{
|
|
287
|
+
"property": "position",
|
|
288
|
+
"keyframes": [
|
|
289
|
+
{ "time": 0.0, "value": { "x": -400, "y": 540 }, "easing": "ease_out" },
|
|
290
|
+
{ "time": 0.8, "value": { "x": 960, "y": 540 } }
|
|
291
|
+
]
|
|
292
|
+
},
|
|
293
|
+
{
|
|
294
|
+
"property": "opacity",
|
|
295
|
+
"keyframes": [
|
|
296
|
+
{ "time": 0.0, "value": 0.0 },
|
|
297
|
+
{ "time": 0.8, "value": 1.0 }
|
|
298
|
+
]
|
|
299
|
+
}
|
|
300
|
+
]
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
| Key | Type | Description |
|
|
305
|
+
|------------|--------|-------------|
|
|
306
|
+
| `property` | string | `position`, `opacity`, or `scale`. |
|
|
307
|
+
| `keyframes`| array | Two or more `{ time, value, easing }` points. |
|
|
308
|
+
| `easing` | string | Interpolation *out of* this keyframe: `linear` (default), `ease_in`, `ease_out`, `ease_in_out`. |
|
|
309
|
+
|
|
310
|
+
A slow position/scale drift on an image gives you the Ken Burns effect:
|
|
311
|
+
|
|
312
|
+
```json
|
|
313
|
+
{
|
|
314
|
+
"property": "scale",
|
|
315
|
+
"keyframes": [
|
|
316
|
+
{ "time": 0.0, "value": 1.0 },
|
|
317
|
+
{ "time": 8.0, "value": 1.15 }
|
|
318
|
+
]
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
### Transitions
|
|
323
|
+
|
|
324
|
+
A scene's `transition` describes how it hands off to the next scene. During the transition, the tail of the outgoing scene and the head of the incoming scene render simultaneously and are blended.
|
|
325
|
+
|
|
326
|
+
```json
|
|
327
|
+
{ "type": "wipe", "duration": 0.75, "direction": "left" }
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
| Type | Description | Extra keys |
|
|
331
|
+
|-------------|-------------|------------|
|
|
332
|
+
| `cut` | Hard cut (the default). | — |
|
|
333
|
+
| `fade` | Outgoing scene fades to black, incoming fades in from black. | — |
|
|
334
|
+
| `crossfade` | Outgoing scene dissolves directly into the incoming one. | — |
|
|
335
|
+
| `wipe` | Incoming scene is revealed by a moving edge. | `direction`: `left`, `right`, `up`, `down` |
|
|
336
|
+
| `slide` | Incoming scene pushes the outgoing one off-frame. | `direction`: `left`, `right`, `up`, `down` |
|
|
337
|
+
|
|
338
|
+
`duration` is in seconds and is capped at the shorter of the two adjacent scenes.
|
|
339
|
+
|
|
340
|
+
### Audio
|
|
341
|
+
|
|
342
|
+
Global audio tracks are timed against the whole video, independent of scene boundaries. Multiple tracks are mixed together, along with any audio from `video` elements.
|
|
343
|
+
|
|
344
|
+
```json
|
|
345
|
+
{
|
|
346
|
+
"src": "assets/music.mp3",
|
|
347
|
+
"start": 0,
|
|
348
|
+
"end": 30,
|
|
349
|
+
"volume": 0.6,
|
|
350
|
+
"fade_in": 1.0,
|
|
351
|
+
"fade_out": 2.0,
|
|
352
|
+
"loop": false
|
|
353
|
+
}
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
| Key | Type | Default | Description |
|
|
357
|
+
|------------|---------|--------------|-------------|
|
|
358
|
+
| `src` | string | — | Path to an audio file (mp3, wav, flac, ogg). |
|
|
359
|
+
| `start` | number | `0` | Seconds into the *video* when the track starts. |
|
|
360
|
+
| `end` | number | video end | Seconds into the video when the track stops. |
|
|
361
|
+
| `trim` | object | full file | Portion of the source file to use, in source seconds. |
|
|
362
|
+
| `volume` | number | `1.0` | Track gain. |
|
|
363
|
+
| `fade_in` | number | `0` | Fade-in length in seconds. |
|
|
364
|
+
| `fade_out` | number | `0` | Fade-out length in seconds. |
|
|
365
|
+
| `loop` | boolean | `false` | Repeat the track to fill its window. |
|
|
366
|
+
|
|
367
|
+
## Full Example
|
|
368
|
+
|
|
369
|
+
A 20-second video: a title card, a narrated clip with a lower-third and logo, then a closing card. Music runs underneath the whole thing.
|
|
370
|
+
|
|
371
|
+
```json
|
|
372
|
+
{
|
|
373
|
+
"output": { "width": 1920, "height": 1080, "fps": 30 },
|
|
374
|
+
"scenes": [
|
|
375
|
+
{
|
|
376
|
+
"duration": 4,
|
|
377
|
+
"background": { "type": "gradient", "from": "#1a1a2e", "to": "#16213e", "angle": 90 },
|
|
378
|
+
"elements": [
|
|
379
|
+
{
|
|
380
|
+
"type": "text",
|
|
381
|
+
"content": "Weekly Update",
|
|
382
|
+
"position": { "x": 960, "y": 480 },
|
|
383
|
+
"font": "assets/fonts/Inter-Bold.ttf",
|
|
384
|
+
"size": 120,
|
|
385
|
+
"animations": [
|
|
386
|
+
{
|
|
387
|
+
"property": "opacity",
|
|
388
|
+
"keyframes": [
|
|
389
|
+
{ "time": 0.0, "value": 0.0 },
|
|
390
|
+
{ "time": 0.6, "value": 1.0 }
|
|
391
|
+
]
|
|
392
|
+
}
|
|
393
|
+
]
|
|
394
|
+
},
|
|
395
|
+
{
|
|
396
|
+
"type": "shape",
|
|
397
|
+
"shape": "rect",
|
|
398
|
+
"width": 500,
|
|
399
|
+
"height": 6,
|
|
400
|
+
"fill": "#e94560",
|
|
401
|
+
"position": { "x": 960, "y": 580 },
|
|
402
|
+
"start": 0.4
|
|
403
|
+
}
|
|
404
|
+
],
|
|
405
|
+
"transition": { "type": "crossfade", "duration": 0.75 }
|
|
406
|
+
},
|
|
407
|
+
{
|
|
408
|
+
"duration": 12,
|
|
409
|
+
"elements": [
|
|
410
|
+
{
|
|
411
|
+
"type": "video",
|
|
412
|
+
"src": "assets/interview.mp4",
|
|
413
|
+
"trim": { "start": 3.0, "end": 15.0 },
|
|
414
|
+
"fit": "cover",
|
|
415
|
+
"volume": 1.0
|
|
416
|
+
},
|
|
417
|
+
{
|
|
418
|
+
"type": "text",
|
|
419
|
+
"content": "Dana Reyes\nProduct Lead",
|
|
420
|
+
"start": 1.0,
|
|
421
|
+
"end": 6.0,
|
|
422
|
+
"position": { "x": 400, "y": 920 },
|
|
423
|
+
"size": 42,
|
|
424
|
+
"align": "left"
|
|
425
|
+
},
|
|
426
|
+
{
|
|
427
|
+
"type": "image",
|
|
428
|
+
"src": "assets/logo.png",
|
|
429
|
+
"position": "top-right",
|
|
430
|
+
"scale": 0.4,
|
|
431
|
+
"opacity": 0.8
|
|
432
|
+
}
|
|
433
|
+
],
|
|
434
|
+
"transition": { "type": "fade", "duration": 1.0 }
|
|
435
|
+
},
|
|
436
|
+
{
|
|
437
|
+
"duration": 4,
|
|
438
|
+
"background": { "type": "color", "color": "#1a1a2e" },
|
|
439
|
+
"elements": [
|
|
440
|
+
{
|
|
441
|
+
"type": "text",
|
|
442
|
+
"content": "See you next week",
|
|
443
|
+
"position": "center",
|
|
444
|
+
"size": 80
|
|
445
|
+
}
|
|
446
|
+
]
|
|
447
|
+
}
|
|
448
|
+
],
|
|
449
|
+
"audio": [
|
|
450
|
+
{
|
|
451
|
+
"src": "assets/music.mp3",
|
|
452
|
+
"start": 0,
|
|
453
|
+
"volume": 0.35,
|
|
454
|
+
"fade_in": 1.0,
|
|
455
|
+
"fade_out": 2.5,
|
|
456
|
+
"loop": true
|
|
457
|
+
}
|
|
458
|
+
]
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
```bash
|
|
463
|
+
scenescript render weekly-update.json -o weekly-update.mp4
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## CLI Reference
|
|
467
|
+
|
|
468
|
+
### `scenescript render`
|
|
469
|
+
|
|
470
|
+
Render a JSON file to a video.
|
|
471
|
+
|
|
472
|
+
```bash
|
|
473
|
+
scenescript render <input.json> -o <output>
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
| Option | Description |
|
|
477
|
+
|---------------------|-------------|
|
|
478
|
+
| `-o, --output PATH` | Output file path. Extension may override `output.format`. |
|
|
479
|
+
| `--overwrite` | Replace the output file if it already exists. |
|
|
480
|
+
| `-q, --quiet` | Suppress the progress display. |
|
|
481
|
+
|
|
482
|
+
### `scenescript validate`
|
|
483
|
+
|
|
484
|
+
Check a JSON file without rendering: schema correctness, asset paths, timing sanity (elements within scene bounds, transitions not longer than their scenes).
|
|
485
|
+
|
|
486
|
+
```bash
|
|
487
|
+
scenescript validate <input.json>
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
Exits non-zero with a list of problems, or prints a summary of the video (scene count, total duration, assets used) when valid.
|
|
491
|
+
|
|
492
|
+
## MCP Server
|
|
493
|
+
|
|
494
|
+
SceneScript ships an optional [MCP](https://modelcontextprotocol.io) server so AI agents can author and render videos through tool calls.
|
|
495
|
+
|
|
496
|
+
```bash
|
|
497
|
+
pip install "scenescript[mcp]"
|
|
498
|
+
scenescript-mcp
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
The server speaks stdio. To register it with Claude Code:
|
|
502
|
+
|
|
503
|
+
```bash
|
|
504
|
+
claude mcp add scenescript -- scenescript-mcp
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Three tools:
|
|
508
|
+
|
|
509
|
+
| Tool | What it does |
|
|
510
|
+
|---|---|
|
|
511
|
+
| `get_format_reference` | Returns this document, so an agent can learn the JSON format before authoring a spec. |
|
|
512
|
+
| `validate_video` | Checks a spec without rendering. Pass the spec inline as `spec` (asset paths resolve against `assets_dir`) or as `spec_path` (a JSON file; asset paths resolve beside it). |
|
|
513
|
+
| `render_video` | Renders a spec to `output_path`. The extension picks the container; an existing file is only replaced when `overwrite` is true. |
|
|
514
|
+
|
|
515
|
+
Validation problems come back as data rather than tool errors, so an agent can fix its spec and call again. Rendering takes roughly the video's duration.
|
|
516
|
+
|
|
517
|
+
## Design Principles
|
|
518
|
+
|
|
519
|
+
- **The JSON is the video.** The input file fully determines the output: no hidden state, no interactive editing, no generation step. Version-control your JSON and you've version-controlled your video.
|
|
520
|
+
- **Deterministic.** The same JSON and assets always render the same output. That makes SceneScript safe to drop into automated pipelines that write JSON from data.
|
|
521
|
+
- **No editing frameworks.** Composition happens directly on Pillow/numpy frame buffers. ffmpeg is used strictly at the boundaries: decoding inserted clips, encoding the frame stream, and mixing audio.
|
|
522
|
+
- **Fail before rendering.** Validation runs up front so a typo in scene 9 doesn't surface after eight scenes have already rendered.
|
|
523
|
+
|
|
524
|
+
## License
|
|
525
|
+
|
|
526
|
+
MIT
|
scenescript/animation.py
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""Keyframe interpolation.
|
|
2
|
+
|
|
3
|
+
Keyframe values are either floats (opacity, scale) or (x, y) tuples (position).
|
|
4
|
+
Before the first keyframe and after the last, the boundary value holds. The
|
|
5
|
+
easing named on a keyframe shapes the segment leaving it [source: README.md].
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
|
|
12
|
+
from .easing import apply_easing
|
|
13
|
+
|
|
14
|
+
Value = float | tuple[float, float]
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class Keyframe:
|
|
19
|
+
time: float
|
|
20
|
+
value: Value
|
|
21
|
+
easing: str = "linear"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _lerp(a: Value, b: Value, p: float) -> Value:
|
|
25
|
+
if isinstance(a, tuple):
|
|
26
|
+
assert isinstance(b, tuple)
|
|
27
|
+
return (a[0] + (b[0] - a[0]) * p, a[1] + (b[1] - a[1]) * p)
|
|
28
|
+
assert not isinstance(b, tuple)
|
|
29
|
+
return a + (b - a) * p
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def sample_keyframes(keyframes: list[Keyframe], t: float) -> Value:
|
|
33
|
+
kfs = sorted(keyframes, key=lambda k: k.time)
|
|
34
|
+
if t <= kfs[0].time:
|
|
35
|
+
return kfs[0].value
|
|
36
|
+
if t >= kfs[-1].time:
|
|
37
|
+
return kfs[-1].value
|
|
38
|
+
for a, b in zip(kfs, kfs[1:]):
|
|
39
|
+
if a.time <= t <= b.time:
|
|
40
|
+
span = b.time - a.time
|
|
41
|
+
p = (t - a.time) / span if span else 1.0
|
|
42
|
+
return _lerp(a.value, b.value, apply_easing(a.easing, p))
|
|
43
|
+
raise AssertionError("unreachable: t inside keyframe range but no segment found")
|