agentcut 0.2.12 → 0.2.14

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.
@@ -5,7 +5,7 @@
5
5
  // browser export draws it through WebGL, so the two match. Never put CSS `perspective` or
6
6
  // `preserve-3d` around it: the stage already projects every plane itself.
7
7
  import { Video } from "@remotion/media";
8
- import { createContext, useContext, useId, type ComponentProps, type CSSProperties, type ReactNode } from "react";
8
+ import { createContext, useContext, useId, useState, type ComponentProps, type CSSProperties, type ReactNode } from "react";
9
9
  import { AbsoluteFill, Img, interpolate, useCurrentFrame, useRemotionEnvironment, useVideoConfig } from "remotion";
10
10
  import { alpha, glowStyle } from "../lib";
11
11
  import {
@@ -415,7 +415,9 @@ function stackAlphas(weights: number[], opacity: number) {
415
415
 
416
416
  // Blur plus a no-op shadow: the browser export then blurs the copy as one picture, so its soft edge
417
417
  // spills past the rounded box as in the preview instead of being cut at it.
418
- const groupBlur = (px: number) => (px > 0.05 ? `blur(${px.toFixed(2)}px) drop-shadow(0 0 0 rgba(0,0,0,0))` : undefined);
418
+ // `keep` leaves the filter on at blur(0) (the live preview, see PlaneBody).
419
+ const groupBlur = (px: number, keep = false) =>
420
+ px > 0.05 || keep ? `blur(${Math.max(0, px).toFixed(2)}px) drop-shadow(0 0 0 rgba(0,0,0,0))` : undefined;
419
421
  const padFor = (px: number) => (px > 0.05 ? Math.ceil(px * 3) + 1 : 0);
420
422
 
421
423
  const PlaneCopyCtx = createContext(false);
@@ -455,11 +457,8 @@ export function Plane({
455
457
  ...placement
456
458
  }: PlaneProps) {
457
459
  const ctx = useStageContext("Plane");
458
- const env = useRemotionEnvironment();
459
- // The live preview draws two copies for a depth blur instead of three (captures and exports get three).
460
- const lightPreview = env.isPlayer && !env.isRendering;
461
- const model = mul(ctx.model, basis ?? placementMatrix(placement));
462
- const camModel = mul(ctx.view, model, translate(-width / 2, -height / 2, 0));
460
+ const own = basis ?? placementMatrix(placement);
461
+ const camModel = mul(ctx.view, ctx.model, own, translate(-width / 2, -height / 2, 0));
463
462
  // A plane reaching behind the camera can't be projected as a whole: below, only its part in front of
464
463
  // the lens is drawn. Big surfaces (Floor) are also tiled.
465
464
  const nearest = Math.min(
@@ -470,6 +469,7 @@ export function Plane({
470
469
  );
471
470
  if (opacity <= 0) return null;
472
471
  const near = ctx.D * 0.04;
472
+ let [x0, y0, x1, y1] = [0, 0, width, height];
473
473
  if (nearest < near) {
474
474
  // The plane passes the lens (macro close-ups, low fly-overs). Keep the part in front of the camera:
475
475
  // the largest edge-aligned rectangle whose corners are all safely in front, redrawn as a smaller
@@ -479,7 +479,6 @@ export function Plane({
479
479
  const gy = (distAt(camModel, ctx.D, 0, height) - d00) / Math.max(1, height);
480
480
  const dist = (x: number, y: number) => d00 + gx * x + gy * y;
481
481
  const safe = near * 1.5;
482
- let [x0, y0, x1, y1] = [0, 0, width, height];
483
482
  for (let i = 0; i < 40; i++) {
484
483
  const corners: [number, number][] = [[x0, y0], [x1, y0], [x0, y1], [x1, y1]];
485
484
  const worst = corners.reduce((a, c) => (dist(c[0], c[1]) < dist(a[0], a[1]) ? c : a));
@@ -499,30 +498,72 @@ export function Plane({
499
498
  const sh = y1 - y0;
500
499
  const ok = [[x0, y0], [x1, y0], [x0, y1], [x1, y1]].every(([x, y]) => dist(x, y) >= near);
501
500
  if (!ok || sw < 2 || sh < 2) return null;
502
- const subBasis = mul(basis ?? placementMatrix(placement), translate(x0 + sw / 2 - width / 2, y0 + sh / 2 - height / 2, 0));
503
- return (
504
- <Plane
505
- basis={subBasis}
506
- width={sw}
507
- height={sh}
508
- radius={radius}
509
- background={background}
510
- opacity={opacity}
511
- dof={dof}
512
- rim={rim}
513
- blur={blur}
514
- style={style}
515
- >
516
- <div style={{ position: "absolute", left: -x0, top: -y0, width, height }}>{children}</div>
517
- </Plane>
518
- );
519
501
  }
502
+ const clipped = nearest < near;
503
+ const sw = x1 - x0;
504
+ const sh = y1 - y0;
505
+ // The whole plane and its part in front of the lens draw through the same body, with the content in the
506
+ // same wrapper, so a camera crossing the lens (scrubbing a macro shot) updates the copies instead of
507
+ // rebuilding them and everything inside.
508
+ return (
509
+ <PlaneBody
510
+ basis={clipped ? mul(own, translate(x0 + sw / 2 - width / 2, y0 + sh / 2 - height / 2, 0)) : own}
511
+ width={sw}
512
+ height={sh}
513
+ radius={radius}
514
+ background={background}
515
+ opacity={opacity}
516
+ shadow={clipped ? 0 : shadow}
517
+ shadowDepth={shadowDepth}
518
+ reflection={clipped ? 0 : reflection}
519
+ dof={dof}
520
+ rim={rim}
521
+ blur={blur}
522
+ style={style}
523
+ >
524
+ <div style={clipped ? { position: "absolute", left: -x0, top: -y0, width, height } : { display: "contents" }}>{children}</div>
525
+ </PlaneBody>
526
+ );
527
+ }
528
+
529
+ function PlaneBody({
530
+ width,
531
+ height,
532
+ radius,
533
+ background,
534
+ opacity,
535
+ shadow,
536
+ shadowDepth,
537
+ reflection,
538
+ dof,
539
+ rim,
540
+ blur,
541
+ basis,
542
+ children,
543
+ style,
544
+ }: Required<Omit<PlaneProps, keyof Placement | "children" | "style" | "background">> &
545
+ Pick<PlaneProps, "children" | "style" | "background">) {
546
+ const ctx = useStageContext("Plane");
547
+ const env = useRemotionEnvironment();
548
+ // The live preview draws two copies for a depth blur instead of three (captures and exports get three).
549
+ const lightPreview = env.isPlayer && !env.isRendering;
550
+ // Once a plane in the live preview has been blurred it keeps its filter on (blur(0) while sharp), and once
551
+ // it has drawn a depth blur it keeps the same copies (hidden by their masks when unused) for as long as
552
+ // it's mounted: scrubbing across a rack or an aperture change then only updates styles, instead of
553
+ // mounting and dropping blurred copies of the content (and their GPU layers) frame after frame, which made
554
+ // the whole studio flicker. Captures and exports draw as before.
555
+ const [was, setWas] = useState({ filter: false, copies: false });
556
+ const model = mul(ctx.model, basis);
557
+ const camModel = mul(ctx.view, model, translate(-width / 2, -height / 2, 0));
520
558
 
521
559
  // Extra softness asked for in world px, in this plane's local px.
522
560
  const extra = (blur * ctx.u) / localScale(camModel);
523
561
  const withExtra = (b: number) => Math.hypot(b, extra);
524
562
  const matrix = (m: M4) => toCss(mul(ctx.project, m));
525
563
  const focus = dof ? planeFocus(ctx, camModel, width, height) : ({ kind: "sharp" } as const);
564
+ const copies = lightPreview && (was.copies || focus.kind === "gradient");
565
+ const steady = { copies, filter: lightPreview && (was.filter || copies || focus.kind === "uniform" || extra > 0.05) };
566
+ if (steady.copies !== was.copies || steady.filter !== was.filter) setWas(steady);
526
567
  const surface: CSSProperties = {
527
568
  position: "absolute",
528
569
  left: 0,
@@ -571,7 +612,7 @@ export function Plane({
571
612
  ...o.mask,
572
613
  }}
573
614
  >
574
- <div style={{ position: "absolute", left: o.pad, top: o.pad, width, height, filter: groupBlur(o.blur) }}>
615
+ <div style={{ position: "absolute", left: o.pad, top: o.pad, width, height, filter: groupBlur(o.blur, steady.filter) }}>
575
616
  <div style={{ ...surface, opacity: o.opacity }}>
576
617
  <PlaneCopyCtx.Provider value={o.copy}>{o.body ?? content}</PlaneCopyCtx.Provider>
577
618
  </div>
@@ -633,7 +674,13 @@ export function Plane({
633
674
 
634
675
  // The main copy is always last and keyed "main", so its content never remounts when the focus changes
635
676
  // (videos keep playing, loaded images stay); the blurred copies come and go under it.
636
- if (focus.kind === "sharp") {
677
+ if (focus.kind !== "gradient" && steady.copies) {
678
+ // The preview's two depth copies stay mounted under the main copy, masked out.
679
+ const b = focus.kind === "uniform" ? withExtra(focus.blur) : extra;
680
+ const pad = padFor(b);
681
+ for (const key of ["blur2", "blur1"]) layers.push(copyOf(key, camModel, { blur: b, pad, mask: maskFrom(0, [0, 0]), opacity: 1, copy: true }));
682
+ layers.push(copyOf("main", camModel, { blur: b, pad, mask: maskFrom(0, [1, 1]), opacity, copy: false }));
683
+ } else if (focus.kind === "sharp") {
637
684
  layers.push(copyOf("main", camModel, { blur: extra, pad: padFor(extra), opacity, copy: false }));
638
685
  } else if (focus.kind === "uniform") {
639
686
  const b = withExtra(focus.blur);
@@ -645,7 +692,8 @@ export function Plane({
645
692
  // copy can't follow; macro close-ups need the full ladder. The preview climbs fewer rungs.
646
693
  const { max, angle } = focus;
647
694
  // Enough rungs to reach ~1 px, so the in-focus band resolves cleanly (capped for cost).
648
- const rungs = Math.max(1, Math.min(lightPreview ? 2 : 6, Math.ceil(Math.log(Math.max(1.01, max / 0.9)) / Math.log(2.2))));
695
+ // (The preview always climbs two, so the same two copies stay mounted while the blur grows and shrinks.)
696
+ const rungs = Math.max(lightPreview ? 2 : 1, Math.min(lightPreview ? 2 : 6,Math.ceil(Math.log(Math.max(1.01, max / 0.9)) / Math.log(2.2))));
649
697
  const levels = [0];
650
698
  for (let i = rungs - 1; i >= 0; i--) levels.push(max / Math.pow(2.2, i));
651
699
  const pad = padFor(withExtra(max));
@@ -1,148 +1,151 @@
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
- The library first: real recordings sound expensive, and it has a sound for nearly every cue.
19
-
20
- 1. **`agentcut_sfx_catalog`**: 276 effects, nothing to install. **One call with no filters** returns a
21
- compact index of every sound (id, category, recorded, length, what it sounds like): plan from it, then
22
- call once more with `ids: [...]` for the full details of your picks (what it's for, `onsetS`, `peakS`
23
- and a `volume` that evens out its loudness). A query ("soft whoosh", "logo sting") or category (click,
24
- pop, swoosh, whoosh, impact, riser, sting, notify, shimmer, glitch, typing, foley, divider) that matches
25
- 40 or fewer also returns full details. Don't page through the categories one by one.
26
- - `recorded: true` (source `agentcut`, 55 sounds): original real recordings. **Prefer these** when one
27
- fits. Their descriptions were measured by ear-models (earshot), so trust them over the file name:
28
- several "click-tech" sounds are tonal chimes and plucks, the "scramble" dividers are glassy rattles.
29
- - `recorded: false` (source `earshot`, 221 sounds): designed in code by earshot, including what the
30
- recordings don't cover: risers and downlifters, logo stings, sub drops, shimmers, notification
31
- chimes, glitches, typing runs, camera shutters. Several variants per family: use different ones so
32
- repeated cues don't sound identical.
33
- Add picks with `agentcut_add_sfx` (they land in `assets/sfx/`).
34
- 2. **The project's own `assets/` and the workspace `library:`** files.
35
- 3. **CC0 downloads** (Openverse, below) only when nothing above fits.
36
-
37
- Then for the sounds you pick:
38
-
39
- 1. With several candidates, describe the sound plainly (source + action + character: "a single crisp
40
- computer mouse click", "a short airy whoosh moving left to right") and `agentcut_listen_rank` them.
41
- Prefer **z >= 3** ("strong").
42
- 2. Place it: clip `from` = the cue frame (press frame, pop-in start, cut) **minus `onsetS` in frames**. For
43
- whooshes and risers put `peakS` on the cut: taps and clicks lead the cut slightly, whoosh peaks land
44
- just after it, a riser stops on its loudest moment at the cut. Trim a long sound with the clip's
45
- duration rather than stretching it. Start from the catalog `volume`, then balance with the critique.
46
- Add a `note` with the cue and numbers.
47
- 3. Vary: never the same effect twice in a row.
48
-
49
- Never synthesize sound effects yourself when the library has one: hand-made oscillator beeps read as cheap.
50
-
51
- ## Finding new files: Openverse (CC0)
52
-
53
- Openverse is the WordPress project's open media search (read-only HTTPS API):
54
-
55
- ```
56
- curl -G https://api.openverse.org/v1/audio/ --data-urlencode "q=whoosh" -d license=cc0 -d length=shortest -d page_size=12
57
- ```
58
-
59
- - `length`: `shortest` (< 30 s), `short`, `medium`, `long`. Only `license=cc0` (no credit needed).
60
- - Download each result's `url` into a new empty folder, check with ffprobe if available, copy the ones you
61
- keep into `assets/sfx/`, rank and check them with the listen tools, and record `foreign_landing_url` in
62
- notes.md.
63
- - Anonymous limits: 20 requests/minute, 200/day. Space requests ≥ 4 s apart (HTTP 429 → wait).
64
-
65
- ## Check the mix
66
-
67
- `agentcut_listen_critique` mixes the project exactly as the export will and reports loudness vs
68
- −14 LUFS, true peak, clipping, silent gaps, voice-over-music balance (voice should sit ≥ 6 LU above music
69
- where both play) and SFX cue timing (onset vs nearest scene start/marker). Fix and run it again. The export
70
- masters the rendered audio to −14 LUFS with a true-peak limiter (≤ −1 dBTP after encoding) and reports
71
- what it did (`mastering`: rendered loudness, gain, limiter reduction). Large limiter reduction (> 3 dB)
72
- means a few sounds are far louder than the rest: turn those clips down instead of relying on the limiter.
73
-
74
- ## Voice-overs
75
-
76
- The user connects their own voice provider under **Voices** in the studio header (ElevenLabs, Google
77
- Gemini, OpenAI or Grok/xAI). You never see, ask for or mention API keys: the helper adds them.
78
-
79
- 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
80
- ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. If nothing is set up, ask the user
81
- to open **Voices** and add a key, and stop there.
82
- 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
83
- 3. `agentcut_generate_voice` with the user's provider/model/voice (or the default). Generate 2 takes
84
- for anything that matters. Delivery notes:
85
- - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
86
- action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
87
- Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
88
- - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
89
- - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
90
- 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
91
- word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
92
- to its word timings.
93
- 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
94
- voice the user has set up.
95
-
96
- ## Music
97
-
98
- Where a song comes from, in order (never download music from the web: it's slow and fails often):
99
-
100
- 1. **A file the user gives you** (in `assets/`, or one they point at): use it.
101
- 2. **The Agentcut music library** unless the user asks for a new song: 200+ licensed tracks.
102
- `agentcut_music_catalog` (filter by category and `minSeconds` = video length), pick 3–6
103
- candidates from names that fit the vibe, `agentcut_add_catalog_music`, then rank them with
104
- `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
105
- the other candidates from `assets/music/`, and say which song you used and why.
106
- 3. **Lyria (Google)** when the user asks for a new song, or the library isn't available or has nothing
107
- that fits, and `agentcut_music_options` says it's available (the user's Gemini key). Write the prompt like a brief:
108
-
109
- ```
110
- Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
111
- A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
112
- a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
113
- [0:00 - 0:06] Intro: <what happens, how it feels>
114
- [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
115
- [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
116
- [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
117
- [0:45 - 0:48] The last chord rings out softly and fades to silence.
118
- ```
119
-
120
- Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
121
- written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
122
- `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
123
- `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
124
- `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
125
- with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
126
- 4. **Composed in code** when neither the library nor Lyria is available (or the user asks for code):
127
- write a synthesis script in the project's `scripts/` folder and run it.
128
- - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
129
- otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
130
- - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
131
- which bars play under which scene, with a build and a gap before the drop on the reveal.
132
- - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
133
- hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
134
- reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
135
- the kick. Normalize to about −14 LUFS.
136
- - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
137
- in code (royalty-free, no samples).
138
- Mention once that a Gemini key under Voices gives them Lyria songs instead.
139
-
140
- Never put a Suno artist tag or account name anywhere visible.
141
-
142
- ## Making sound effects
143
-
144
- Only when the library and Openverse have nothing that fits (rank z < 1.5), or the user asks for a made
145
- sound: synthesize it in a script (same runtime rules as music) into `assets/sfx/<name>.wav`: whooshes from
146
- band-passed noise with a sweep and fade, pops from a short pitched sine with a fast decay, clicks from a
147
- few ms of filtered noise, risers from noise + rising tone. Rank and measure it like any candidate and say
148
- in notes.md that it's synthesized (`listen_realness` will be low; that's expected for a made sound).
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
+ The library first: real recordings sound expensive, and it has a sound for nearly every cue.
19
+
20
+ 1. **`agentcut_sfx_catalog`**: 276 effects, nothing to install. **One call with no filters** returns a
21
+ compact index of every sound (id, category, recorded, length, what it sounds like): plan from it, then
22
+ call once more with `ids: [...]` for the full details of your picks (what it's for, `onsetS`, `peakS`
23
+ and a `volume` that evens out its loudness). A query ("soft whoosh", "logo sting") or category (click,
24
+ pop, swoosh, whoosh, impact, riser, sting, notify, shimmer, glitch, typing, foley, divider) that matches
25
+ 40 or fewer also returns full details. Don't page through the categories one by one.
26
+ - `recorded: true` (source `agentcut`, 55 sounds): original real recordings. **Prefer these** when one
27
+ fits. Their descriptions were measured by ear-models (earshot), so trust them over the file name:
28
+ several "click-tech" sounds are tonal chimes and plucks, the "scramble" dividers are glassy rattles.
29
+ - `recorded: false` (source `earshot`, 221 sounds): designed in code by earshot, including what the
30
+ recordings don't cover: risers and downlifters, logo stings, sub drops, shimmers, notification
31
+ chimes, glitches, typing runs, camera shutters. Several variants per family: use different ones so
32
+ repeated cues don't sound identical.
33
+ Add picks with `agentcut_add_sfx` (they land in `assets/sfx/`).
34
+ 2. **The project's own `assets/` and the workspace `library:`** files.
35
+ 3. **CC0 downloads** (Openverse, below) only when nothing above fits.
36
+
37
+ Then for the sounds you pick:
38
+
39
+ 1. With several candidates, describe the sound plainly (source + action + character: "a single crisp
40
+ computer mouse click", "a short airy whoosh moving left to right") and `agentcut_listen_rank` them.
41
+ Prefer **z >= 3** ("strong").
42
+ 2. Place it: clip `from` = the cue frame (press frame, pop-in start, cut) **minus `onsetS` in frames**. For
43
+ whooshes and risers put `peakS` on the cut: taps and clicks lead the cut slightly, whoosh peaks land
44
+ just after it, a riser stops on its loudest moment at the cut. Trim a long sound with the clip's
45
+ duration rather than stretching it. Start from the catalog `volume`, then balance with the critique.
46
+ Add a `note` with the cue and numbers.
47
+ 3. Vary: never the same effect twice in a row.
48
+
49
+ Never synthesize sound effects yourself when the library has one: hand-made oscillator beeps read as cheap.
50
+
51
+ ## Finding new files: Openverse (CC0)
52
+
53
+ Openverse is the WordPress project's open media search (read-only HTTPS API):
54
+
55
+ ```
56
+ curl -G https://api.openverse.org/v1/audio/ --data-urlencode "q=whoosh" -d license=cc0 -d length=shortest -d page_size=12
57
+ ```
58
+
59
+ - `length`: `shortest` (< 30 s), `short`, `medium`, `long`. Only `license=cc0` (no credit needed).
60
+ - Download each result's `url` into a new empty folder, check with ffprobe if available, copy the ones you
61
+ keep into `assets/sfx/`, rank and check them with the listen tools, and record `foreign_landing_url` in
62
+ notes.md.
63
+ - Anonymous limits: 20 requests/minute, 200/day. Space requests ≥ 4 s apart (HTTP 429 → wait).
64
+
65
+ ## Check the mix
66
+
67
+ `agentcut_listen_critique` mixes the project exactly as the export will and reports loudness vs
68
+ −14 LUFS, true peak, clipping, silent gaps, voice-over-music balance (voice should sit ≥ 6 LU above music
69
+ where both play) and SFX cue timing (onset vs nearest scene start/marker). Fix and run it again. The export
70
+ masters the rendered audio to −14 LUFS with a true-peak limiter (≤ −1 dBTP after encoding) and reports
71
+ what it did (`mastering`: rendered loudness, gain, limiter reduction). Large limiter reduction (> 3 dB)
72
+ means a few sounds are far louder than the rest: turn those clips down instead of relying on the limiter.
73
+
74
+ ## Voice-overs
75
+
76
+ The user connects their own voice provider under **Voices** in the studio header (ElevenLabs, Google
77
+ Gemini, OpenAI or Grok/xAI). You never see, ask for or mention API keys: the helper adds them.
78
+
79
+ 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
80
+ ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. If nothing is set up, ask the user
81
+ to open **Voices** and add a key, and stop there.
82
+ 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
83
+ 3. `agentcut_generate_voice` with the user's provider/model/voice (or the default). Generate 2 takes
84
+ for anything that matters. Delivery notes:
85
+ - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
86
+ action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
87
+ Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
88
+ - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
89
+ - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
90
+ 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
91
+ word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
92
+ to its word timings.
93
+ 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
94
+ voice the user has set up.
95
+
96
+ ## Music
97
+
98
+ Where a song comes from, in order (never download music from the web: it's slow and fails often):
99
+
100
+ 1. **A file the user gives you** (in `assets/`, or one they point at): use it.
101
+ 2. **The Agentcut music library** unless the user asks for a new song: 224 licensed tracks, each
102
+ measured (tempo, energy 1–5, intro length, drops, ending, shape) and tagged (moods, genres,
103
+ instruments, vocals). Search `agentcut_music_catalog` in plain words for the video's feel
104
+ ("high energy no vocals", "calm 90 bpm", "cinematic dark", "playful") with `minSeconds` = video
105
+ length; pick 3–6 candidates whose energy and shape fit the edit (a drop near the reveal, an intro
106
+ you can trim, `vocals: false` under a voice-over), `agentcut_add_catalog_music`, then rank them with
107
+ `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
108
+ the other candidates from `assets/music/`, and say which song you used and why.
109
+ 3. **Lyria (Google)** when the user asks for a new song, or the library isn't available or has nothing
110
+ that fits, and `agentcut_music_options` says it's available (the user's Gemini key). Write the prompt like a brief:
111
+
112
+ ```
113
+ Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
114
+ A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
115
+ a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
116
+ [0:00 - 0:06] Intro: <what happens, how it feels>
117
+ [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
118
+ [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
119
+ [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
120
+ [0:45 - 0:48] The last chord rings out softly and fades to silence.
121
+ ```
122
+
123
+ Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
124
+ written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
125
+ `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
126
+ `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
127
+ `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
128
+ with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
129
+ 4. **Composed in code** when neither the library nor Lyria is available (or the user asks for code):
130
+ write a synthesis script in the project's `scripts/` folder and run it.
131
+ - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
132
+ otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
133
+ - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
134
+ which bars play under which scene, with a build and a gap before the drop on the reveal.
135
+ - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
136
+ hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
137
+ reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
138
+ the kick. Normalize to about −14 LUFS.
139
+ - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
140
+ in code (royalty-free, no samples).
141
+ Mention once that a Gemini key under Voices gives them Lyria songs instead.
142
+
143
+ Never put a Suno artist tag or account name anywhere visible.
144
+
145
+ ## Making sound effects
146
+
147
+ Only when the library and Openverse have nothing that fits (rank z < 1.5), or the user asks for a made
148
+ sound: synthesize it in a script (same runtime rules as music) into `assets/sfx/<name>.wav`: whooshes from
149
+ band-passed noise with a sweep and fade, pops from a short pitched sine with a fast decay, clicks from a
150
+ few ms of filtered noise, risers from noise + rising tone. Rank and measure it like any candidate and say
151
+ in notes.md that it's synthesized (`listen_realness` will be low; that's expected for a made sound).