agentcut 0.0.0-stage → 0.1.1

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 (248) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +11 -2
  3. package/dist/bridge.d.ts +45 -0
  4. package/dist/bridge.js +691 -0
  5. package/dist/bridge.js.map +1 -0
  6. package/dist/config.d.ts +13 -0
  7. package/dist/config.js +50 -0
  8. package/dist/config.js.map +1 -0
  9. package/dist/index.d.ts +2 -0
  10. package/dist/index.js +35 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/log.d.ts +1 -0
  13. package/dist/log.js +14 -0
  14. package/dist/log.js.map +1 -0
  15. package/dist/studio/agents/claude.d.ts +7 -0
  16. package/dist/studio/agents/claude.js +155 -0
  17. package/dist/studio/agents/claude.js.map +1 -0
  18. package/dist/studio/agents/codex.d.ts +4 -0
  19. package/dist/studio/agents/codex.js +169 -0
  20. package/dist/studio/agents/codex.js.map +1 -0
  21. package/dist/studio/agents/index.d.ts +8 -0
  22. package/dist/studio/agents/index.js +50 -0
  23. package/dist/studio/agents/index.js.map +1 -0
  24. package/dist/studio/agents/types.d.ts +131 -0
  25. package/dist/studio/agents/types.js +11 -0
  26. package/dist/studio/agents/types.js.map +1 -0
  27. package/dist/studio/bundler.d.ts +29 -0
  28. package/dist/studio/bundler.js +136 -0
  29. package/dist/studio/bundler.js.map +1 -0
  30. package/dist/studio/chat.d.ts +147 -0
  31. package/dist/studio/chat.js +681 -0
  32. package/dist/studio/chat.js.map +1 -0
  33. package/dist/studio/cli.d.ts +2 -0
  34. package/dist/studio/cli.js +194 -0
  35. package/dist/studio/cli.js.map +1 -0
  36. package/dist/studio/components.d.ts +4 -0
  37. package/dist/studio/components.js +36 -0
  38. package/dist/studio/components.js.map +1 -0
  39. package/dist/studio/host.d.ts +105 -0
  40. package/dist/studio/host.js +634 -0
  41. package/dist/studio/host.js.map +1 -0
  42. package/dist/studio/http.d.ts +21 -0
  43. package/dist/studio/http.js +240 -0
  44. package/dist/studio/http.js.map +1 -0
  45. package/dist/studio/music.d.ts +35 -0
  46. package/dist/studio/music.js +130 -0
  47. package/dist/studio/music.js.map +1 -0
  48. package/dist/studio/proc.d.ts +11 -0
  49. package/dist/studio/proc.js +69 -0
  50. package/dist/studio/proc.js.map +1 -0
  51. package/dist/studio/projects.d.ts +84 -0
  52. package/dist/studio/projects.js +369 -0
  53. package/dist/studio/projects.js.map +1 -0
  54. package/dist/studio/render.d.ts +24 -0
  55. package/dist/studio/render.js +197 -0
  56. package/dist/studio/render.js.map +1 -0
  57. package/dist/studio/reveal.d.ts +7 -0
  58. package/dist/studio/reveal.js +49 -0
  59. package/dist/studio/reveal.js.map +1 -0
  60. package/dist/studio/schema.d.ts +4152 -0
  61. package/dist/studio/schema.js +358 -0
  62. package/dist/studio/schema.js.map +1 -0
  63. package/dist/studio/tools.d.ts +2 -0
  64. package/dist/studio/tools.js +165 -0
  65. package/dist/studio/tools.js.map +1 -0
  66. package/dist/studio/voice.d.ts +150 -0
  67. package/dist/studio/voice.js +434 -0
  68. package/dist/studio/voice.js.map +1 -0
  69. package/dist/studio/workspace.d.ts +31 -0
  70. package/dist/studio/workspace.js +187 -0
  71. package/dist/studio/workspace.js.map +1 -0
  72. package/package.json +50 -4
  73. package/template/AGENTS.md +13 -0
  74. package/template/components/CATALOG.md +1306 -0
  75. package/template/components/README.md +61 -0
  76. package/template/components/STYLES.md +246 -0
  77. package/template/components/arcade-title/ArcadeTitle.tsx +860 -0
  78. package/template/components/arcade-title/meta.json +28 -0
  79. package/template/components/aurora/Aurora.tsx +63 -0
  80. package/template/components/aurora/meta.json +28 -0
  81. package/template/components/bar-wipe-title/BarWipeTitle.tsx +94 -0
  82. package/template/components/bar-wipe-title/meta.json +29 -0
  83. package/template/components/before-after/BeforeAfter.tsx +89 -0
  84. package/template/components/before-after/meta.json +233 -0
  85. package/template/components/bento-grid/BentoGrid.tsx +202 -0
  86. package/template/components/bento-grid/meta.json +25 -0
  87. package/template/components/blur-in-title/BlurInTitle.tsx +121 -0
  88. package/template/components/blur-in-title/meta.json +32 -0
  89. package/template/components/catalog.json +8730 -0
  90. package/template/components/catalog.ts +103 -0
  91. package/template/components/chat-thread/ChatThread.tsx +128 -0
  92. package/template/components/chat-thread/meta.json +24 -0
  93. package/template/components/checklist/Checklist.tsx +129 -0
  94. package/template/components/checklist/meta.json +25 -0
  95. package/template/components/confetti/Confetti.tsx +109 -0
  96. package/template/components/confetti/meta.json +28 -0
  97. package/template/components/countdown/Countdown.tsx +166 -0
  98. package/template/components/countdown/meta.json +28 -0
  99. package/template/components/cut-and-paste/CutAndPaste.tsx +654 -0
  100. package/template/components/cut-and-paste/meta.json +29 -0
  101. package/template/components/decode-text/DecodeText.tsx +97 -0
  102. package/template/components/decode-text/meta.json +29 -0
  103. package/template/components/editorial-quote/EditorialQuote.tsx +122 -0
  104. package/template/components/editorial-quote/meta.json +28 -0
  105. package/template/components/glitch-title/GlitchTitle.tsx +171 -0
  106. package/template/components/glitch-title/meta.json +32 -0
  107. package/template/components/halftone-wave/HalftoneWave.tsx +106 -0
  108. package/template/components/halftone-wave/meta.json +28 -0
  109. package/template/components/highlighter/Highlighter.tsx +142 -0
  110. package/template/components/highlighter/meta.json +28 -0
  111. package/template/components/hook-card/HookCard.tsx +552 -0
  112. package/template/components/hook-card/meta.json +304 -0
  113. package/template/components/index.ts +149 -0
  114. package/template/components/iris-wipe/IrisWipe.tsx +76 -0
  115. package/template/components/iris-wipe/meta.json +24 -0
  116. package/template/components/kinetic-poster/KineticPoster.tsx +437 -0
  117. package/template/components/kinetic-poster/meta.json +31 -0
  118. package/template/components/kinetic-punch/KineticPunch.tsx +80 -0
  119. package/template/components/kinetic-punch/meta.json +30 -0
  120. package/template/components/lava-lamp/LavaLamp.tsx +92 -0
  121. package/template/components/lava-lamp/meta.json +28 -0
  122. package/template/components/letter-cascade/LetterCascade.tsx +102 -0
  123. package/template/components/letter-cascade/meta.json +29 -0
  124. package/template/components/lib.ts +179 -0
  125. package/template/components/light-leak/LightLeakTransition.tsx +43 -0
  126. package/template/components/light-leak/meta.json +74 -0
  127. package/template/components/line-diagram/LineDiagram.tsx +205 -0
  128. package/template/components/line-diagram/meta.json +217 -0
  129. package/template/components/list-card/ListCard.tsx +104 -0
  130. package/template/components/list-card/meta.json +232 -0
  131. package/template/components/logo-sting/LogoSting.tsx +129 -0
  132. package/template/components/logo-sting/meta.json +29 -0
  133. package/template/components/looks.tsx +1447 -0
  134. package/template/components/lower-third/LowerThird.tsx +100 -0
  135. package/template/components/lower-third/meta.json +24 -0
  136. package/template/components/marquee/Marquee.tsx +100 -0
  137. package/template/components/marquee/meta.json +30 -0
  138. package/template/components/notification/Notification.tsx +115 -0
  139. package/template/components/notification/meta.json +27 -0
  140. package/template/components/outline-fill/OutlineFill.tsx +106 -0
  141. package/template/components/outline-fill/meta.json +28 -0
  142. package/template/components/panel-sweep/PanelSweep.tsx +86 -0
  143. package/template/components/panel-sweep/meta.json +25 -0
  144. package/template/components/prompt-box/PromptBox.tsx +131 -0
  145. package/template/components/prompt-box/meta.json +24 -0
  146. package/template/components/props.ts +73 -0
  147. package/template/components/quote-card/QuoteCard.tsx +71 -0
  148. package/template/components/quote-card/meta.json +216 -0
  149. package/template/components/shape-shift/ShapeShift.tsx +420 -0
  150. package/template/components/shape-shift/meta.json +31 -0
  151. package/template/components/slide-zoom-message/SlideZoomMessage.tsx +179 -0
  152. package/template/components/slide-zoom-message/meta.json +199 -0
  153. package/template/components/social-post/SocialPost.tsx +185 -0
  154. package/template/components/social-post/meta.json +30 -0
  155. package/template/components/split-flap/SplitFlap.tsx +191 -0
  156. package/template/components/split-flap/meta.json +29 -0
  157. package/template/components/spotlight-grid/SpotlightGrid.tsx +84 -0
  158. package/template/components/spotlight-grid/meta.json +25 -0
  159. package/template/components/stat-counter/StatCounter.tsx +117 -0
  160. package/template/components/stat-counter/meta.json +27 -0
  161. package/template/components/sticker-badge/StickerBadge.tsx +46 -0
  162. package/template/components/sticker-badge/meta.json +220 -0
  163. package/template/components/sticker-slam/StickerSlam.tsx +941 -0
  164. package/template/components/sticker-slam/meta.json +34 -0
  165. package/template/components/style-layer.tsx +233 -0
  166. package/template/components/styles.json +762 -0
  167. package/template/components/styles.ts +113 -0
  168. package/template/components/target-lock/TargetLock.tsx +662 -0
  169. package/template/components/target-lock/meta.json +32 -0
  170. package/template/components/text-reveal/TextReveal.tsx +99 -0
  171. package/template/components/text-reveal/meta.json +28 -0
  172. package/template/components/tile-wipe/TileWipe.tsx +75 -0
  173. package/template/components/tile-wipe/meta.json +24 -0
  174. package/template/components/type-zoom/TypeZoom.tsx +103 -0
  175. package/template/components/type-zoom/meta.json +27 -0
  176. package/template/components/types.ts +66 -0
  177. package/template/components/typewriter/Typewriter.tsx +112 -0
  178. package/template/components/typewriter/meta.json +29 -0
  179. package/template/components/word-pop/WordPop.tsx +59 -0
  180. package/template/components/word-pop/meta.json +237 -0
  181. package/template/components/word-stack/WordStack.tsx +122 -0
  182. package/template/components/word-stack/meta.json +27 -0
  183. package/template/components/word-swap/WordSwap.tsx +127 -0
  184. package/template/components/word-swap/meta.json +30 -0
  185. package/template/presets/charcoal-sketch/PROMPT.md +48 -0
  186. package/template/presets/charcoal-sketch/assets/paper/grain-0.png +0 -0
  187. package/template/presets/charcoal-sketch/assets/paper/grain-1.png +0 -0
  188. package/template/presets/charcoal-sketch/assets/paper/grain-2.png +0 -0
  189. package/template/presets/charcoal-sketch/assets/paper/sketch-paper.jpg +0 -0
  190. package/template/presets/charcoal-sketch/assets/paper/smudge.png +0 -0
  191. package/template/presets/charcoal-sketch/poster.jpg +0 -0
  192. package/template/presets/charcoal-sketch/preset.json +17 -0
  193. package/template/presets/charcoal-sketch/preview.mp4 +0 -0
  194. package/template/presets/charcoal-sketch/scenes/Grain.tsx +23 -0
  195. package/template/presets/charcoal-sketch/scenes/Paper.tsx +17 -0
  196. package/template/presets/charcoal-sketch/scenes/examples/Agents.tsx +100 -0
  197. package/template/presets/charcoal-sketch/scenes/examples/Approvals.tsx +110 -0
  198. package/template/presets/charcoal-sketch/scenes/examples/Blog.tsx +105 -0
  199. package/template/presets/charcoal-sketch/scenes/examples/EndCard.tsx +41 -0
  200. package/template/presets/charcoal-sketch/scenes/examples/Hook.tsx +130 -0
  201. package/template/presets/charcoal-sketch/scenes/examples/Ideas.tsx +92 -0
  202. package/template/presets/charcoal-sketch/scenes/examples/Posting.tsx +128 -0
  203. package/template/presets/charcoal-sketch/scenes/lib/painfix.tsx +119 -0
  204. package/template/presets/charcoal-sketch/scenes/lib/sketch.tsx +291 -0
  205. package/template/presets/charcoal-sketch/scripts/build_layers.example.py +193 -0
  206. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -0
  207. package/template/presets/charcoal-sketch/scripts/make_textures.py +93 -0
  208. package/template/presets/punk-cut-paper/PROMPT.md +37 -0
  209. package/template/presets/punk-cut-paper/assets/paper/desk-cream.jpg +0 -0
  210. package/template/presets/punk-cut-paper/assets/paper/grain-overlay.png +0 -0
  211. package/template/presets/punk-cut-paper/assets/paper/halftone-black.png +0 -0
  212. package/template/presets/punk-cut-paper/assets/paper/halftone-red.png +0 -0
  213. package/template/presets/punk-cut-paper/assets/paper/halftone-yellow.png +0 -0
  214. package/template/presets/punk-cut-paper/assets/paper/kraft.jpg +0 -0
  215. package/template/presets/punk-cut-paper/assets/paper/newsprint.jpg +0 -0
  216. package/template/presets/punk-cut-paper/assets/paper/paper-cream.jpg +0 -0
  217. package/template/presets/punk-cut-paper/assets/paper/paper-white.jpg +0 -0
  218. package/template/presets/punk-cut-paper/assets/paper/tape.png +0 -0
  219. package/template/presets/punk-cut-paper/build_layers.example.py +150 -0
  220. package/template/presets/punk-cut-paper/poster.jpg +0 -0
  221. package/template/presets/punk-cut-paper/preset.json +15 -0
  222. package/template/presets/punk-cut-paper/preview.mp4 +0 -0
  223. package/template/presets/punk-cut-paper/scenes/Backdrop.tsx +76 -0
  224. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -0
  225. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -0
  226. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -0
  227. package/template/presets/punk-cut-paper/scenes/Xerox.tsx +31 -0
  228. package/template/presets/punk-cut-paper/scenes/lib/punk.tsx +208 -0
  229. package/template/runtime/composition.tsx +920 -0
  230. package/template/runtime/helpers.tsx +228 -0
  231. package/template/runtime/index.tsx +22 -0
  232. package/template/runtime/types.ts +248 -0
  233. package/template/skill/SKILL.md +149 -0
  234. package/template/skill/references/browser-export.md +61 -0
  235. package/template/skill/references/components.md +38 -0
  236. package/template/skill/references/craft.md +53 -0
  237. package/template/skill/references/cursor.md +91 -0
  238. package/template/skill/references/footage.md +73 -0
  239. package/template/skill/references/format.md +140 -0
  240. package/template/skill/references/presets.md +56 -0
  241. package/template/skill/references/sound.md +128 -0
  242. package/template/starter/.studio/chat.json +1 -0
  243. package/template/starter/assets/.keep +0 -0
  244. package/template/starter/layers.json +46 -0
  245. package/template/starter/notes.md +4 -0
  246. package/template/starter/project.json +13 -0
  247. package/template/starter/renders/.keep +0 -0
  248. package/template/starter/scenes/Title.tsx +38 -0
@@ -0,0 +1,61 @@
1
+ # Browser export: what the renderer can draw
2
+
3
+ Captures (`agentcut_capture_frames`, `_contact_sheet`) and the export use Remotion's web renderer
4
+ (`@remotion/web-renderer`, encoding with Mediabunny). It walks the DOM and draws each element onto a canvas,
5
+ so it supports a **subset** of CSS. The live preview (Remotion Player) is a normal browser page and shows
6
+ everything — so a scene can look right in the preview and wrong in the export. Always judge by captures.
7
+
8
+ ## Replace these
9
+
10
+ | Don't use | Use instead |
11
+ |---|---|
12
+ | `z-index` | order elements back to front in the DOM (later = on top) |
13
+ | `background: radial-gradient(…)` / `conic-gradient` | `<RadialGlow x y radius color opacity />` from `agentcut`, or an inline `<svg>` with `<radialGradient>` |
14
+ | `background-image: url()` | `<Img>` or an image clip |
15
+ | `mix-blend-mode`, `background-blend-mode` | pre-blended colors, opacity, or an SVG with the effect baked in |
16
+ | `backdrop-filter` (glass blur) | a semi-opaque fill + a blurred copy of the background behind it |
17
+ | `box-shadow: inset …`, shadow spread | an inner element with a gradient/border, or an outer shadow without spread |
18
+ | `object-position` | position the `<Img>` inside an `overflow: hidden` box with transforms |
19
+ | `perspective`, `transform-style: preserve-3d` | 2D transforms (scale/skew/rotate) faking depth |
20
+ | `mask-image` with radial/SVG masks | linear-gradient masks, or `clip-path` shapes (`inset`, `circle`, `polygon`) |
21
+ | `clip-path: url(#svgClip)` | `clip-path: polygon(…)` / `circle(…)` |
22
+ | `OffthreadVideo`, `Html5Video`, `Html5Audio` | `<Video>` / `<Audio>` from `@remotion/media` (or video/audio clips) |
23
+ | `writing-mode`, wavy `text-decoration` | rotated boxes, SVG paths |
24
+ | fonts from CSS `@import` / `<link>` in scenes | `project.json` → `fonts` |
25
+
26
+ Supported and safe: flexbox/grid layout, `transform` (2D), `opacity`, `filter` (blur, brightness…; not in
27
+ Safari), `linear-gradient` backgrounds, `border-radius`, borders, outer `box-shadow`, `text-shadow`,
28
+ `clip-path` shapes, inline SVG (gradients, paths, filters inside the SVG), `<Img>`, canvas.
29
+
30
+ Text inside SVG `<text>` or `foreignObject` doesn't get project fonts: prefer HTML text.
31
+
32
+ ## Checklist after writing a scene
33
+
34
+ 1. `agentcut_status` → no build errors.
35
+ 2. Capture its entrance, hold and exit in both variants.
36
+ 3. Compare with what you meant. Missing glow, wrong stacking, hard edges where a blend was → one of the
37
+ properties above.
38
+ 4. If an effect can't be done within these rules and the user wants it, say so: the "Render on this
39
+ computer" export (classic Remotion renderer) draws full CSS, but the captures won't show it.
40
+
41
+ Shader transitions (`@remotion/transitions` zoom-blur, film-burn, …) use WebGL: they render in the browser
42
+ but slowly; check a capture of a transition frame before relying on one.
43
+
44
+ ## WebGL / three.js scenes
45
+
46
+ - Create the `<canvas>` **inside** the effect (`document.createElement("canvas")`, append it to a container
47
+ `<div ref>`), and remove it in the cleanup. Never call `renderer.forceContextLoss()` on a canvas React
48
+ keeps: the dev server mounts every component twice, and the second mount gets a dead context
49
+ ("Cannot read properties of null (reading 'precision')").
50
+ - `preserveDrawingBuffer: true` so captures and the export can read the pixels; render synchronously for the
51
+ current frame (`useCurrentFrame()`), never in `requestAnimationFrame`.
52
+ - One renderer per scene, sized to the composition (`useVideoConfig()`), `setPixelRatio(1)`. Dispose
53
+ geometries, materials, textures and the renderer in the cleanup. Browsers allow ~16 live WebGL contexts.
54
+ - Keep the live preview smooth. The Player draws 30 frames a second on the page's main thread; when a
55
+ frame takes longer, it skips frames, and the user sees stutters and jumps. Use `usePreviewQuality()` from
56
+ `agentcut`: `renderer.setPixelRatio(q.pixelRatio)`, `shadow.mapSize.set(q.shadowMapSize, …)`,
57
+ and redraw big canvas textures (`needsUpdate`) only every `q.textureEvery` frames. Captures and the export
58
+ always get full quality.
59
+ - Call `renderer.compile(scene, camera)` at the end of setup so shaders compile while the scene is
60
+ premounted (clips mount 1 s early in the preview), not on its first visible frame.
61
+ - Capture a frame of every 3D scene in both variants before moving on.
@@ -0,0 +1,38 @@
1
+ # The Agentcut component library
2
+
3
+ Ready-made, tested animations: titles, lower thirds, stat counters, an AI prompt box, and more over
4
+ time. They follow the export rules, work in wide and mobile, and fit any clip length (enter at the start,
5
+ exit at the end). The user edits their props in the inspector, so a component clip is something you and
6
+ the user both tune; a scene file is only editable by code.
7
+
8
+ ## Use them first
9
+
10
+ Before writing an effect yourself, call `agentcut_components` with a few words ("title",
11
+ "speaker name", "percentage", "chat"). If one fits, use it; combine several (a Text Reveal over footage,
12
+ then a Stat Counter) before writing a scene. Write a scene only for what the library can't do, and say
13
+ so in one line ("no library component draws a 3D orbit, so I wrote scenes/Orbit.tsx").
14
+
15
+ ## Put one on the timeline
16
+
17
+ 1. `agentcut_components` with `id` gives the props (types, defaults, limits), examples and a
18
+ ready clip.
19
+ 2. Add the clip to a scene track (a track named "Motion" for overlays, above the footage):
20
+ `{ "id": "title-1", "from": 0, "duration": 90, "component": "text-reveal", "props": { "lines": ["Make videos", "with *Claude*"] } }`
21
+ Put only the props you change; the rest use their defaults.
22
+ 3. Check with `agentcut_status` (it flags unknown components and props out of range) and
23
+ `agentcut_capture_frames` (look at the frame).
24
+
25
+ Rules:
26
+ - Match the project. With a project `style` set, leave out the props it controls (listed in
27
+ `.agentcut/components/STYLES.md`): they follow the style. Without one, pass the brand colors
28
+ (`accent`, `color`, `background`) and fonts the project uses.
29
+ - `layer: "overlay"` components are transparent: put them on a track above the content they sit on.
30
+ - Timing: the clip's `duration` is the component's length. Keep the suggested `durationInFrames` unless
31
+ the edit needs it longer or shorter; line `from` up with beats and cuts like any clip.
32
+ - When the user changes a prop by hand, keep it.
33
+
34
+ ## Suggest new ones
35
+
36
+ When you build an effect that would be useful again (it's not tied to this one video), tell the user in one
37
+ line: "This would make a good library component." The library lives in the Agentcut repo
38
+ (`motion/components`); its README explains how to add one.
@@ -0,0 +1,53 @@
1
+ # Craft: how the owner's videos are made
2
+
3
+ The reference library is the owner's hand-made Remotion studio (`video-studio`). New Studio videos should
4
+ match it. What makes those videos work:
5
+
6
+ ## Structure
7
+
8
+ - **One idea per beat**, 2–6 s each. A 60 s launch spot has ~10 beats: pain → reveal → 3–6 feature beats →
9
+ proof/flow → end card (logo, URL, "now live").
10
+ - **The voice drives the cuts.** Every scene starts a few frames (≈ 8 f at 30 fps) before the word it
11
+ illustrates; on-screen elements pop on their keyword's start frame. Keep a word-index cue table in
12
+ notes.md (`reveal = word "meet" − 8f`). With no voice, the music's beats and sections drive it.
13
+ - **Music has a shape**: quiet intro under the hook, a drop on the reveal, a final chord on the end card.
14
+ Put markers on the drop and the final hit; cut and flash on them.
15
+ - **Wide and mobile are designed, not cropped**: both at 1080 px on the short side. Stack horizontally in
16
+ wide, vertically in mobile; bigger type in mobile; keep important content out of the bottom 18% and top
17
+ 10% of mobile (platform UI).
18
+
19
+ ## Motion
20
+
21
+ - Entrances: springs. `pop` (scale 0.6→1 + rise + fade over ~5 f), `rise` (fade + 30 px rise), `land` for
22
+ heavy titles. Stagger lists by 3–6 frames.
23
+ - Exits: short eased fades with a slight scale-down / rise and blur (≈ 7 frames), overlapping the next
24
+ scene's entrance.
25
+ - After the drop, a **beat pulse** (0..1 decaying over ~8 f on each beat) drives subtle scale/brightness of
26
+ backgrounds and accents — never the text you need to read.
27
+ - Flashes: brief white overlay (opacity ≤ 0.35, ~10 f) on the drop and the final hit only.
28
+ - Camera moves over rebuilt UI: ease in/out between framings, hold long enough to read (≥ 1.2 s per line of
29
+ text the viewer must read).
30
+
31
+ ## Visuals
32
+
33
+ - **Rebuild product UI as live components** (real layout, labels, brand colors) on a fixed canvas, and move a
34
+ camera (scale/translate) over it. Never zoom into screenshots: they blur.
35
+ - Brand palette in one constant object; one gradient for accents; dark backgrounds with radial glows
36
+ (`RadialGlow`) for depth.
37
+ - Generous type: titles 110–150 px wide / 120–170 px mobile at 1080 short side; body ≥ 40 px.
38
+ - Icons as inline SVG strokes (24×24 viewBox, round caps), not emoji.
39
+ - Abstract props only: no drawn hands, bodies or figure-like shapes.
40
+ - Lyric videos: one phrase per layout, accent words highlighted, kicker words smaller; the look follows the
41
+ genre (night-station LED, xerox art-punk, pastel line diagrams, tattoo flash…).
42
+
43
+ ## Captions
44
+
45
+ Word-by-word for talking-head and voice-driven pieces: 2–4 words per line, the active word highlighted,
46
+ lines break at pauses. Check fast passages by capture; Whisper can merge or drop words.
47
+
48
+ ## Before calling it done
49
+
50
+ - Contact sheet of each variant: no clipped text, no empty frames between scenes, consistent margins.
51
+ - `agentcut_listen_critique`: loudness near −14 LUFS after export normalization, voice clearly above
52
+ music, every SFX on its cue.
53
+ - notes.md updated: cue sheet, sound choices with their numbers, anything the user should know.
@@ -0,0 +1,91 @@
1
+ # Cursor and clicks (ScreenSlick Companion recordings)
2
+
3
+ Screen recordings made with ScreenSlick Companion come with a `<video>.cursor.json` next to the video
4
+ (`assets/screen.webm` → `assets/screen.cursor.json`): where the mouse was, every click and every scroll.
5
+ It tells you what the user *did*, so you can edit around the action instead of guessing from frames.
6
+
7
+ Start with `agentcut_media_info` on the screen video. When the file exists you get a `cursor`
8
+ summary:
9
+
10
+ - `clicks`, `scrolls`: counts.
11
+ - `busiest`: up to 3 stretches with the most clicks (`from`/`to` in seconds, `fromFrame`/`toFrame`), and
12
+ `around`: the average click position (0–1 of the video). These are your zoom candidates.
13
+ - `idle`: stretches of 3 s or more with no movement, clicks or scrolls. Cut candidates.
14
+ - `typing`: a text cursor that stays put for 1.5 s or more. Speed-up candidates.
15
+
16
+ Read the JSON itself only for exact click positions. Never edit it.
17
+
18
+ ## The file
19
+
20
+ ```json
21
+ {
22
+ "version": 1, "fps": 30, "durationInFrames": 14400, "width": 2560, "height": 1440,
23
+ "space": "video",
24
+ "cursorInVideo": false,
25
+ "path": [[0, 0.41, 0.33], [12, 0.43, 0.35], [40, null, null]],
26
+ "kinds": [[0, "arrow"], [310, "text"]],
27
+ "clicks": [{ "frame": 95, "x": 0.62, "y": 0.18, "button": "left" }],
28
+ "scrolls": [{ "frame": 400, "x": 0.5, "y": 0.6, "dy": 240 }]
29
+ }
30
+ ```
31
+
32
+ - Frames are frames **of the video file** at `fps`: the same units as a clip's `trimStart`.
33
+ - `x`/`y` are 0–1 of the video's picture. `null` means the pointer was off the recorded screen.
34
+ - `space: "source"` (a rendered edit from the editor): clicks are timed to the edit, but positions are on
35
+ the original screen, not the edited frame (it may be zoomed or padded). Use them for timing and rough
36
+ side (left/right, top/bottom) only. These files have no `path`.
37
+
38
+ A click lands on the timeline of a piece at `from + (click.frame − trimStart) / (playbackRate ?? 1)`, if
39
+ that is inside the piece.
40
+
41
+ ## Drawing the cursor
42
+
43
+ The `cursor` field on a video clip draws the recorded pointer inside that clip:
44
+
45
+ ```json
46
+ "cursor": { "src": "assets/screen.cursor.json", "style": "classic", "size": 100, "clicks": true, "smoothing": 0.3 }
47
+ ```
48
+
49
+ - `style`: `classic` (white), `accent` (green), `spotlight` (green ring), `hand` (👆), `hidden` (no
50
+ pointer, click rings still work).
51
+ - `size`: % of the default (50–200). `clicks`: a ring spreads from each click. `smoothing`: 0 follows the
52
+ recorded path, 1 glides.
53
+ - It follows the clip's `trimStart`, `playbackRate` and `box`, so cuts, speed-ups and zooms keep it in
54
+ place. When you split a screen clip, **copy `cursor` to every piece** (like `grade`).
55
+ - `cursorInVideo: false` means the recording has no pointer of its own: the import already set
56
+ `style: "classic"`. Never remove it, or the video has no mouse. `cursorInVideo: true`: the import set
57
+ `style: "hidden"` with `clicks: false`; turn `clicks` on for rings over the real pointer.
58
+ - The user can change all of this in the inspector's Cursor section.
59
+
60
+ ## What to do with it
61
+
62
+ **Zoom where the action is.** For each `busiest` stretch (or a single important click), split the screen
63
+ piece around it (start ~0.5 s before the first click, end ~0.5 s after the last) and give that piece a
64
+ bigger `box` centered on `around` (cx, cy). For zoom `z` (1.5–2):
65
+
66
+ ```
67
+ box = { width: z, height: z, x: clamp(0.5 − cx·z, 1 − z, 0), y: clamp(0.5 − cy·z, 1 − z, 0) }
68
+ ```
69
+
70
+ (clamping keeps the frame covered). This assumes the screen fills the frame; with letterboxing, map the
71
+ point into the frame first. The cursor zooms with the picture automatically.
72
+
73
+ **Highlight clicks.** Keep `clicks: true` on the pieces that matter (or all of them). For a click that
74
+ starts a key step, add a callout (text clip or library component) near it: frame position =
75
+ `box.x + x·box.width`, `box.y + y·box.height`. Keep it on the side away from the pointer, 1.5–3 s.
76
+
77
+ **Cut dead time.** An `idle` stretch with no speech (check `agentcut_transcribe`) is waiting:
78
+ cut it, keeping ~0.3 s on each side. Idle *with* speech is the user explaining: keep it, maybe zoom on
79
+ what they talk about.
80
+
81
+ **Snap cuts to clicks.** When choosing between nearby cut points, put the cut 0.3–0.5 s before a click,
82
+ so each new section opens on the action.
83
+
84
+ **Speed up typing.** A `typing` stretch with no speech can play at `playbackRate` 2–4 on its own piece
85
+ (split it out). With speech over it, leave it at 1×.
86
+
87
+ **Scrolls.** A scroll right after a click often means "now look here": a slower zoom-out or a hold works
88
+ better than a zoom-in.
89
+
90
+ Check every change with `agentcut_capture_frames` at the click frames: the pointer should sit
91
+ on what was clicked.
@@ -0,0 +1,73 @@
1
+ # Footage sent from the editor
2
+
3
+ "Send to Agentcut" in the ScreenSlick editor renders the user's edit and opens it here as a new
4
+ project sized to the video:
5
+
6
+ - **Footage** track: one video clip `footage` with `src: "assets/footage.<ext>"`, `fit: "contain"`,
7
+ covering the whole project. Its audio is the user's voice and the editor mix.
8
+ - **Captions** track (when the edit had subtitles): one captions clip with the editor's words, timed in
9
+ frames. Restyle it with `style`; don't retype the words.
10
+ - `notes.md` says what came over.
11
+
12
+ The user finishes the video here: cuts, color, motion graphics, sound, then exports from the studio.
13
+
14
+ ## Remove silences / tighten pacing
15
+
16
+ 1. `agentcut_transcribe` on `assets/footage.<ext>` for word timings (or
17
+ `agentcut_analyze_audio` for per-frame energy when there is no speech).
18
+ 2. Find gaps longer than ~0.6 s between words (keep ~0.15 s of air before and after each word; never cut
19
+ inside a word). Keep breaths that land on a beat or a reveal.
20
+ 3. Replace the single footage clip with one clip per kept range, back to back on the Footage track:
21
+ each clip has `src` of the footage, `trimStart` = range start (frames in the file), `from` = where it
22
+ lands on the timeline, `duration` = range length. Give them ids `footage-1`, `footage-2`, …
23
+ 4. Move every caption word with its range (subtract the time removed before it), drop words in removed
24
+ ranges, and set the project `durationInFrames` to the new end.
25
+ 5. Tell the user how much you cut ("removed 14 pauses, 0:52 → 0:41"), then check the cut points with
26
+ `agentcut_capture_frames` and `agentcut_listen_critique`.
27
+
28
+ Cuts "by transcript" ("remove the part where I say …") work the same way: find the words, cut their range.
29
+
30
+ ## Color
31
+
32
+ Use the `grade` field on each footage clip (copy it to every piece after a cut). Small moves: contrast
33
+ 1.05–1.15, saturation 1.05–1.2 for punch, warmth 0.1–0.25 for warmer skin, 0.8–0.9 saturation for a
34
+ muted look. Check with `agentcut_capture_frames` before and after.
35
+
36
+ ## Motion graphics over footage
37
+
38
+ Add tracks above Footage (text, scenes, images) and keep the footage readable: lower thirds and callouts
39
+ at the edges, punch-in zooms by splitting the footage and giving that piece a bigger `box`, never covering
40
+ the speaker's face for long.
41
+
42
+ ## Raw takes
43
+
44
+ "Send to Agentcut → Raw takes" sends the untouched recordings instead of a render. The project is
45
+ sized to the screen recording:
46
+
47
+ - **Screen** track: one clip per take (`screen`, or `screen-1`, `screen-2`, … back to back), `src:
48
+ "assets/screen.<ext>"`, `fit: "contain"`. Its audio is the user's voice: the only audio in the project.
49
+ - **Camera** track (when they recorded one): clip `camera`, `src: "assets/camera.<ext>"`, `fit: "cover"`,
50
+ a `box` where the editor showed it and a `radius` for its rounded corners. It is `muted` (the voice is on
51
+ the screen file) and already synced: its `from`/`trimStart` line it up with the screen. Keep it muted.
52
+ - **Captions** track (when the editor had subtitles): words timed to the raw recording.
53
+ - **Cursor** (Companion recordings): `assets/screen.cursor.json` with the mouse path, clicks and scrolls,
54
+ and a `cursor` field on the screen clip that draws the pointer. Copy that field to every piece you cut.
55
+ See `references/cursor.md`; it also finds zoom, cut and speed-up candidates for step 1.
56
+ - `notes.md` lists the files and whether the user had the camera mirrored.
57
+
58
+ Nothing is cut yet, so a raw take is usually long. Ask what the video is for when it isn't clear, then:
59
+
60
+ 1. **Cut both tracks together.** Work out the kept ranges on the screen take (silences, retakes, "by
61
+ transcript" cuts, as above). For every range, add a screen piece *and* a camera piece with the same
62
+ `from` and `duration`. With the range start `R` in frames on the *original* timeline, the screen
63
+ piece's `trimStart` is `R` − its take's original `from`, and the camera piece's `trimStart` is
64
+ `R` − camera's original `from` + camera's original `trimStart` (skip camera pieces where that is
65
+ negative: the camera wasn't rolling yet). Ids: `screen-1…`, `camera-1…`. Move the captions with the cuts.
66
+ Spot-check sync after cutting with `agentcut_capture_frames` (lips vs. the voice).
67
+ 2. **Frame the screen.** A `box` is fixed for the whole clip, so a zoom is a cut: split the screen piece
68
+ where the action starts and give that piece a bigger box (width/height 1.5–2, x/y negative to keep the
69
+ area of interest in frame), then cut back. Hold each zoom long enough to read.
70
+ 3. **Place the camera.** Bubble in a corner (keep `radius` at half the short side for a circle), full frame
71
+ for an intro or outro (camera `box` to the whole frame; the Camera track sits above Screen), or
72
+ side by side (shrink the screen `box`, give the camera the rest). Change layouts at cuts, not mid-sentence.
73
+ 4. Then grade, captions, music and motion graphics as for any footage.
@@ -0,0 +1,140 @@
1
+ # Project format (v1)
2
+
3
+ All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
+ starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
+ **relative to the clip start**.
6
+
7
+ ## project.json
8
+
9
+ ```json
10
+ {
11
+ "version": 1,
12
+ "name": "Rolino launch",
13
+ "fps": 30,
14
+ "durationInFrames": 1800,
15
+ "background": "#060a16",
16
+ "variants": {
17
+ "wide": { "width": 1920, "height": 1080 },
18
+ "mobile": { "width": 1080, "height": 1920 }
19
+ },
20
+ "defaultVariant": "wide",
21
+ "fonts": [
22
+ "Inter:400;600;800",
23
+ { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
+ ]
25
+ }
26
+ ```
27
+
28
+ - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
+ - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
+ then never depend on Google Fonts). Reference them by `family` in styles.
31
+
32
+ ## layers.json
33
+
34
+ ```json
35
+ {
36
+ "version": 1,
37
+ "tracks": [
38
+ { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
+ { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
+ { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
+ { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
+ { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
+ { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
+ { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
+ ],
46
+ "markers": [
47
+ { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
+ { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
+ ]
50
+ }
51
+ ```
52
+
53
+ `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
+ `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
+
56
+ Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
+ (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
+
59
+ Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
+ on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
+
62
+ ### Clip fields (all kinds)
63
+
64
+ | field | |
65
+ |---|---|
66
+ | `id` | unique in the project, stable, readable |
67
+ | `name` | timeline label (optional) |
68
+ | `from`, `duration` | frames |
69
+ | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
+ | `opacity` | 0..1 (visual clips) |
71
+ | `note` | why the clip is there (cue reason) |
72
+ | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
+
74
+ `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
+
76
+ ### Kinds
77
+
78
+ **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
+ `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
+ see `references/components.md`).
81
+
82
+ **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
+ `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
+ clip's `from` is the cue frame minus the file's onset (see sound.md).
85
+
86
+ **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
+ `grade` — `{ "brightness": 1, "contrast": 1, "saturation": 1, "warmth": 0, "hue": 0 }` (neutral values;
88
+ brightness/contrast/saturation 0–3, warmth −1…1, hue −180…180 degrees). Leave out what you don't change.
89
+ Footage from the editor: see `references/footage.md`.
90
+
91
+ **image** — `{ "src", "fit", "box", "radius" }`.
92
+
93
+ **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
94
+
95
+ **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
96
+ Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
97
+ (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
98
+
99
+ `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
100
+ allow CORS).
101
+
102
+ ## Scenes
103
+
104
+ ```tsx
105
+ // scenes/Hook.tsx
106
+ import { AbsoluteFill, useCurrentFrame } from "remotion";
107
+ import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
108
+
109
+ type Props = SceneProps & { title: string; accent: string };
110
+
111
+ export default function Hook({ title, accent, width, height, clip }: Props) {
112
+ const f = useCurrentFrame(); // 0 at the clip start
113
+ const vertical = height > width;
114
+ const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
115
+ const out = ease(f, clip.duration - 8, clip.duration);
116
+ return (
117
+ <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
118
+ <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
119
+ <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
120
+ <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
121
+ transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
122
+ </AbsoluteFill>
123
+ </AbsoluteFill>
124
+ );
125
+ }
126
+ ```
127
+
128
+ Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
129
+ `width`, `height`, `fps`.
130
+
131
+ `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
132
+ (cheaper drawing in the live preview, full quality in captures/export),
133
+ `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
134
+ `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
135
+ `<RadialGlow>`, `<FrameBox>`, and the format types.
136
+
137
+ Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
138
+ Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
139
+ `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
140
+ workspace root and it gets bundled.
@@ -0,0 +1,56 @@
1
+ # Video style presets
2
+
3
+ A video style is a recipe for a whole video that isn't a talking head: a music or lyric video, an explainer, a
4
+ promo look. It lives in the workspace library, one folder per preset:
5
+
6
+ ```
7
+ library/presets/<id>/
8
+ PROMPT.md the recipe: what to copy, the look, the workflow. Blanks in [brackets].
9
+ preset.json name, description, kind, preview/poster file names, and the blanks as form fields
10
+ preview.mp4 ~10 s of a video made with it (16:9, 960×540, no audio needed)
11
+ poster.jpg one strong frame from it
12
+ scenes/ the scene files the recipe copies into a project
13
+ assets/ textures, fonts and other files the scenes need
14
+ *.example.* optional: a script or layers.json that seeds the first timeline
15
+ ```
16
+
17
+ The style gallery (Styles tab → Video styles) lists every folder with a PROMPT.md, plays its preview, and shows a
18
+ form built from `preset.json` fields. When the user fills it in, you get a message like:
19
+
20
+ > Make a video with the "Punk Cut-Paper" video style: read library/presets/punk-cut-paper/PROMPT.md and follow it,
21
+ > with these values for its blanks: - Song: assets/song.mp3 - Photos: … - Lyrics: transcribe them. Make it as a new
22
+ > project.
23
+
24
+ ## Using a preset
25
+
26
+ 1. Read the preset's PROMPT.md and fill its blanks with the values given (ask only for what's missing and needed).
27
+ 2. "As a new project": create it with `agentcut_create_project`, then copy the preset's `scenes/` and
28
+ `assets/` into it (and any song/photos the user picked from another project or the library). "In this project":
29
+ copy them into the open project and replace its timeline.
30
+ 3. Follow the recipe's look and workflow exactly; it was written from a finished video, so don't improvise a new look.
31
+
32
+ ## Saving a video style
33
+
34
+ When the user asks to save the open video's style ("save this as a preset", the gallery's Save style button):
35
+
36
+ 1. Copy the project's scene files and the assets the look needs (textures, fonts, overlays: not the user's song or
37
+ personal photos) into `library/presets/<id>/`. Make the scenes generic: no names, personal facts or lyrics baked in
38
+ (put example content in an `*.example.*` file).
39
+ 2. Write PROMPT.md: what to copy, fonts for project.json, every rule of the look (layout, motion, timing to beats or
40
+ words, colors, overlays), and the workflow. Put what changes per video in [brackets] (song, photos, title, about,
41
+ lyrics, …).
42
+ 3. Write preset.json:
43
+ ```json
44
+ { "name": "Punk Cut-Paper", "description": "One sentence on the look.", "kind": "Music video",
45
+ "preview": "preview.mp4", "poster": "poster.jpg",
46
+ "fields": [
47
+ { "id": "song", "label": "Song", "type": "audio", "required": true },
48
+ { "id": "photos", "label": "Photos", "type": "images" },
49
+ { "id": "title", "label": "Title", "type": "text", "placeholder": "HAPPY BIRTHDAY SAM" },
50
+ { "id": "lyrics", "label": "Lyrics", "type": "longtext", "placeholder": "Paste the lyrics, or leave empty" }
51
+ ] }
52
+ ```
53
+ Field types: `text`, `longtext`, `audio` (the user picks an audio file), `images` (the user picks photos).
54
+ 4. preview.mp4 and poster.jpg: cut ~10 s from the latest render in `renders/` (960×540, H.264, no audio) and grab one
55
+ frame, choosing a stretch without personal photos when you can. With no render yet, export one first or ask.
56
+ 5. Tell the user it's in the Styles tab under Video styles.
@@ -0,0 +1,128 @@
1
+ # Sound
2
+
3
+ You cannot hear. Every claim that a sound fits, lands on time or sits right in the mix needs a number from
4
+ the listen tools, written into notes.md (z, p_real, LUFS, onset).
5
+
6
+ ## Layers
7
+
8
+ - **voice** track: one clip per take/line, `role: "voice"`, volume 1. Get word timings with
9
+ `agentcut_transcribe` (model `small` for important cuts).
10
+ - **music** track: `role: "music"`, volume ≈ 0.25–0.4 under voice (check with critique), `fadeIn`/`fadeOut`
11
+ of 10–30 frames, `loop` only for beds that loop cleanly. `agentcut_analyze_audio` gives tempo,
12
+ beat frames, downbeats and per-frame energy; put markers on the drop and final hit.
13
+ - **sfx** track(s): one clip per hit. Keep hits sparse and meaningful (cuts, pops, the reveal, the end card),
14
+ vary them, and keep them under the voice (volume 0.1–0.25 typical).
15
+
16
+ ## Choosing a sound effect
17
+
18
+ 1. Describe the sound plainly: source + action + character — "a single crisp computer mouse click",
19
+ "a short airy whoosh moving left to right", "a soft glass ding".
20
+ 2. Candidates: the project's `assets/`, the workspace `library:` files, then CC0 downloads (below).
21
+ 3. `agentcut_listen_rank` with that description over the candidates. Prefer **z ≥ 3** ("strong").
22
+ 4. `agentcut_listen_realness` on the file (or trim) you'll use. Prefer **p_real ≥ 0.5** — real or
23
+ pro-produced recordings. Synthesized sounds (`p_real < 0.2`) when the user asks for made sounds or nothing
24
+ real fits (see "Making sound effects").
25
+ 5. `agentcut_listen_measure` for its `onsetS` (silence before the sound starts) and loudness.
26
+ 6. Place it: clip `from` = the cue frame (press frame, pop-in start, cut) **minus the onset in frames**.
27
+ Add a `note` with the cue and numbers.
28
+
29
+ ## Finding new files: Openverse (CC0)
30
+
31
+ Openverse is the WordPress project's open media search (read-only HTTPS API):
32
+
33
+ ```
34
+ curl -G https://api.openverse.org/v1/audio/ --data-urlencode "q=whoosh" -d license=cc0 -d length=shortest -d page_size=12
35
+ ```
36
+
37
+ - `length`: `shortest` (< 30 s), `short`, `medium`, `long`. Only `license=cc0` (no credit needed).
38
+ - Download each result's `url` into a new empty folder, check with ffprobe if available, copy the ones you
39
+ keep into `assets/sfx/`, rank and check them with the listen tools, and record `foreign_landing_url` in
40
+ notes.md.
41
+ - Anonymous limits: 20 requests/minute, 200/day. Space requests ≥ 4 s apart (HTTP 429 → wait).
42
+
43
+ ## Check the mix
44
+
45
+ `agentcut_listen_critique` mixes the project exactly as the export will and reports loudness vs
46
+ −14 LUFS, true peak, clipping, silent gaps, voice-over-music balance (voice should sit ≥ 6 LU above music
47
+ where both play) and SFX cue timing (onset vs nearest scene start/marker). Fix and run it again. The export
48
+ masters the rendered audio to −14 LUFS with a true-peak limiter (≤ −1 dBTP after encoding) and reports
49
+ what it did (`mastering`: rendered loudness, gain, limiter reduction). Large limiter reduction (> 3 dB)
50
+ means a few sounds are far louder than the rest: turn those clips down instead of relying on the limiter.
51
+
52
+ ## Voice-overs
53
+
54
+ The user connects their own voice provider under **Voices** in the studio header (ElevenLabs, Google
55
+ Gemini, OpenAI or Grok/xAI). You never see, ask for or mention API keys: the helper adds them.
56
+
57
+ 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
58
+ ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. If nothing is set up, ask the user
59
+ to open **Voices** and add a key, and stop there.
60
+ 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
61
+ 3. `agentcut_generate_voice` with the user's provider/model/voice (or the default). Generate 2 takes
62
+ for anything that matters. Delivery notes:
63
+ - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
64
+ action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
65
+ Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
66
+ - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
67
+ - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
68
+ 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
69
+ word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
70
+ to its word timings.
71
+ 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
72
+ voice the user has set up.
73
+
74
+ ## Music
75
+
76
+ Where a song comes from, in order:
77
+
78
+ 1. **A file the user gives you** (in `assets/`, or one they point at): use it.
79
+ 2. **The Agentcut music library** when the user asks for "a library song", "a song from the
80
+ library/editor", or just "a song" without asking for a new one: 200+ licensed tracks.
81
+ `agentcut_music_catalog` (filter by category and `minSeconds` = video length), pick 3–6
82
+ candidates from names that fit the vibe, `agentcut_add_catalog_music`, then rank them with
83
+ `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
84
+ the other candidates from `assets/music/`, and say which song you used and why.
85
+ 3. **Lyria (Google), when the user asks for a new/original/generated song** and
86
+ `agentcut_music_options` says it's available. Write the prompt like a brief:
87
+
88
+ ```
89
+ Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
90
+ A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
91
+ a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
92
+ [0:00 - 0:06] Intro: <what happens, how it feels>
93
+ [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
94
+ [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
95
+ [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
96
+ [0:45 - 0:48] The last chord rings out softly and fades to silence.
97
+ ```
98
+
99
+ Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
100
+ written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
101
+ `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
102
+ `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
103
+ `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
104
+ with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
105
+ 4. **Composed in code, when the user asks for a made song and Lyria isn't set up** (or they ask for code):
106
+ write a synthesis script in the project's `scripts/` folder and run it.
107
+ - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
108
+ otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
109
+ - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
110
+ which bars play under which scene, with a build and a gap before the drop on the reveal.
111
+ - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
112
+ hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
113
+ reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
114
+ the kick. Normalize to about −14 LUFS.
115
+ - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
116
+ in code (royalty-free, no samples).
117
+ 5. **CC0 music from Openverse** (as for sound effects) only when nothing above fits. Offer Lyria (a
118
+ Gemini key under Voices) if they want an original song.
119
+
120
+ Never put a Suno artist tag or account name anywhere visible.
121
+
122
+ ## Making sound effects
123
+
124
+ When nothing in the project, the library or Openverse fits (rank z < 1.5), or the user asks for a made
125
+ sound: synthesize it in a script (same runtime rules as music) into `assets/sfx/<name>.wav`: whooshes from
126
+ band-passed noise with a sweep and fade, pops from a short pitched sine with a fast decay, clicks from a
127
+ few ms of filtered noise, risers from noise + rising tone. Then rank and measure it like any candidate and
128
+ say in notes.md that it's synthesized (`listen_realness` will be low; that's expected for a made sound).