agentcut 0.2.6 → 0.2.8

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.
@@ -36,7 +36,7 @@ export const DEVICE_FINISHES: Record<string, string> = {
36
36
  starlight: "#d9cdb6",
37
37
  "space-gray": "#6f7174",
38
38
  // The deep anodised black of the current MacBook Pro (matched to a reference model).
39
- "space-black": "#565457",
39
+ "space-black": "#3d3c40",
40
40
  // Colour iPhone finishes (iphone-color), most with calibrated logo tints in iphone-model.ts.
41
41
  lavender: "#c5a4df",
42
42
  "mist-blue": "#829dce",
@@ -246,29 +246,33 @@ function createLogoGeometry(width: number) {
246
246
  function createMaterials(finishColor: THREE.ColorRepresentation) {
247
247
  const finish = new THREE.Color(finishColor);
248
248
  const { l: lightness } = finish.getHSL({ h: 0, s: 0, l: 0 });
249
- const isDark = lightness < 0.35;
249
+ // Space black and darker finishes count as dark.
250
+ const isDark = lightness < 0.4;
250
251
  return {
251
252
  // Bead-blasted anodised aluminium: soft, wide highlights, the finish's own colour in the shadows.
253
+ // Dark finishes (space black) reflect much less of the studio, like real dark anodising: otherwise a
254
+ // low camera facing the deck sees the bright environment and the black washes out to light grey.
252
255
  aluminum: new THREE.MeshPhysicalMaterial({
253
256
  color: finish,
254
- metalness: 0.85,
255
- roughness: 0.34,
256
- clearcoat: 0.18,
257
+ metalness: isDark ? 0.55 : 0.85,
258
+ roughness: isDark ? 0.48 : 0.34,
259
+ clearcoat: isDark ? 0.04 : 0.18,
257
260
  clearcoatRoughness: 0.4,
258
- envMapIntensity: 0.75,
261
+ envMapIntensity: isDark ? 0.3 : 0.75,
259
262
  }),
260
263
  edge: new THREE.MeshPhysicalMaterial({
261
264
  color: finish.clone().lerp(new THREE.Color(0xffffff), isDark ? 0.08 : 0.2),
262
- metalness: 1,
263
- roughness: 0.22,
265
+ metalness: isDark ? 0.85 : 1,
266
+ roughness: isDark ? 0.3 : 0.22,
267
+ envMapIntensity: isDark ? 0.55 : 1,
264
268
  }),
265
269
  trackpad: new THREE.MeshPhysicalMaterial({
266
- color: finish.clone().lerp(new THREE.Color(0x000000), 0.06),
267
- metalness: 0.5,
268
- roughness: 0.28,
269
- clearcoat: 0.6,
270
+ color: finish.clone().lerp(new THREE.Color(0x000000), isDark ? 0.12 : 0.06),
271
+ metalness: isDark ? 0.4 : 0.5,
272
+ roughness: isDark ? 0.36 : 0.28,
273
+ clearcoat: isDark ? 0.25 : 0.6,
270
274
  clearcoatRoughness: 0.18,
271
- envMapIntensity: 0.6,
275
+ envMapIntensity: isDark ? 0.28 : 0.6,
272
276
  }),
273
277
  well: new THREE.MeshStandardMaterial({
274
278
  color: 0x050506,
@@ -40,7 +40,7 @@ narrower moves).
40
40
  tilt small (5–20) with some `turn` and `roll`.
41
41
  - `fov`: 15–25 flat telephoto (default 24, product look), 35 natural, 50–70 dramatic close-ups.
42
42
  - `focus`: a world point `[x, y, z]` (put it ON the thing that matters) or px toward the camera from
43
- the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2 macro. Focus and aperture animate: a rack
43
+ the target. `aperture`: 0 none, 0.4 subtle, 1 strong, 2.5–4 macro (see Macro focus), 6+ a razor line. Focus and aperture animate: a rack
44
44
  focus is two keys with different `focus` points.
45
45
  - `shiftX`, `shiftY`: move the subject off-center (fractions of the frame) to leave room for a title.
46
46
  - `float` 0–1: handheld drift (0.3–0.6 on holds keeps them alive). `motionBlur` 0–1: blur on fast moves.
@@ -126,6 +126,7 @@ narrower moves).
126
126
  | Hero push | same angle, zoom +15–25 % over the shot, `inOut`, `float 0.4` |
127
127
  | Rack focus | camera still or drifting; `focus` from region A to B over 20–30 f, `aperture 0.9–1.3` |
128
128
  | Lift-out | `Device3D` `lifts` (or `Lift` on a flat Screen) z 0→80–140, scale →1.08, `back` or `expo`, focus moves to the lift |
129
+ | Macro focus | see "Macro focus" below: a flat screen seen at a grazing angle, one line sharp, everything else melted; slow drift only |
129
130
  | Push to detail | zoom 1→2.2–3 on a hero region (`x, y` = its world center), aperture up as you go in |
130
131
  | Fly-over | low `tilt 55–65`, camera `y` travels down the page, `fov 35`, long screenshot with `scroll` |
131
132
  | Orbit | `Device3D` iPhone: camera `turn` −35 → +25, `tilt` 5–12, `fov 28–32`, a dark backdrop with a glow behind |
@@ -146,6 +147,27 @@ Find the brand colours first (logo, UI, website) and build the palette from them
146
147
  and type, not only in camera moves: write the rotation in the shot list, and check notes.md for what
147
148
  the last take used.
148
149
 
150
+ ## Macro focus (an occasional signature shot)
151
+
152
+ The extreme close-up where the camera skims the screen, one line of UI is crisp and everything in front
153
+ and behind melts into blur (the look of a macro lens). Use it **once or twice per film at most**, for a
154
+ detail worth savouring: a key number, a headline, a list. It is not the default framing.
155
+
156
+ - **Keep the screen flat** (no `tilt` on the Screen/Group) and get the angle from the **camera**:
157
+ `tilt 60–70`, `turn ±15–30`, `roll ±10–20`, `fov 30–36`, `zoom 2.5–3.2`, `aperture 2.5–4`
158
+ (6+ shrinks the sharp band to a line, only for a brief accent).
159
+ - **Focus on the surface:** `x, y` and `focus: [x, y, 0]` = the world point of the hero line on the flat
160
+ screen (measure it from the screenshot like a hero region). With a tilted screen a point `[x, y, 0]` is
161
+ off the surface and nothing comes out sharp.
162
+ - **The sharp area is a band, not a dot:** real depth of field is a slice across the surface at one
163
+ distance. Aim the band along the line of text you want (turn/roll set its direction). **Never** cut a
164
+ plane into tiles or stack copies to fake a focus point: the blurred tiles leave a visible grid.
165
+ - **Move slowly.** A macro shot is a slow, almost still drift: over 3–5 s, the camera's `x`/`y` travel at
166
+ most 60–120 world px and its angles at most 3–5°, with `inOut` or `linear` keys (no `expo`, `back`
167
+ or `whip`), `float 0.2–0.4`, no motion blur. Optionally a slow rack: `focus` slides 80–200 px along the
168
+ line over the whole shot. Fast moves at this magnification look like a glitch, not a lens.
169
+ - Cut into and out of it on a calm beat; the shots around it should be wider so the close-up lands.
170
+
149
171
  ## Taste rules
150
172
 
151
173
  - **The hero is always sharp.** Put `focus` on it; blur is for what's around it. Never blur text the
@@ -1,128 +1,148 @@
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).
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. Filter by words ("soft whoosh",
21
+ "logo sting", "success") and/or category: click, pop, swoosh, whoosh, impact, riser, sting, notify,
22
+ shimmer, glitch, typing, foley, divider. Each entry says what it sounds like, what it's for, `onsetS`,
23
+ `peakS` and a `volume` that evens out its loudness.
24
+ - `recorded: true` (source `agentcut`, 55 sounds): original real recordings. **Prefer these** when one
25
+ fits. Their descriptions were measured by ear-models (earshot), so trust them over the file name:
26
+ several "click-tech" sounds are tonal chimes and plucks, the "scramble" dividers are glassy rattles.
27
+ - `recorded: false` (source `earshot`, 221 sounds): designed in code by earshot, including what the
28
+ recordings don't cover: risers and downlifters, logo stings, sub drops, shimmers, notification
29
+ chimes, glitches, typing runs, camera shutters. Several variants per family: use different ones so
30
+ repeated cues don't sound identical.
31
+ Add picks with `agentcut_add_sfx` (they land in `assets/sfx/`).
32
+ 2. **The project's own `assets/` and the workspace `library:`** files.
33
+ 3. **CC0 downloads** (Openverse, below) only when nothing above fits.
34
+
35
+ Then for the sounds you pick:
36
+
37
+ 1. With several candidates, describe the sound plainly (source + action + character: "a single crisp
38
+ computer mouse click", "a short airy whoosh moving left to right") and `agentcut_listen_rank` them.
39
+ Prefer **z >= 3** ("strong").
40
+ 2. Place it: clip `from` = the cue frame (press frame, pop-in start, cut) **minus `onsetS` in frames**. For
41
+ whooshes and risers put `peakS` on the cut: taps and clicks lead the cut slightly, whoosh peaks land
42
+ just after it, a riser stops on its loudest moment at the cut. Trim a long sound with the clip's
43
+ duration rather than stretching it. Start from the catalog `volume`, then balance with the critique.
44
+ Add a `note` with the cue and numbers.
45
+ 3. Vary: never the same effect twice in a row.
46
+
47
+ Never synthesize sound effects yourself when the library has one: hand-made oscillator beeps read as cheap.
48
+
49
+ ## Finding new files: Openverse (CC0)
50
+
51
+ Openverse is the WordPress project's open media search (read-only HTTPS API):
52
+
53
+ ```
54
+ curl -G https://api.openverse.org/v1/audio/ --data-urlencode "q=whoosh" -d license=cc0 -d length=shortest -d page_size=12
55
+ ```
56
+
57
+ - `length`: `shortest` (< 30 s), `short`, `medium`, `long`. Only `license=cc0` (no credit needed).
58
+ - Download each result's `url` into a new empty folder, check with ffprobe if available, copy the ones you
59
+ keep into `assets/sfx/`, rank and check them with the listen tools, and record `foreign_landing_url` in
60
+ notes.md.
61
+ - Anonymous limits: 20 requests/minute, 200/day. Space requests ≥ 4 s apart (HTTP 429 → wait).
62
+
63
+ ## Check the mix
64
+
65
+ `agentcut_listen_critique` mixes the project exactly as the export will and reports loudness vs
66
+ −14 LUFS, true peak, clipping, silent gaps, voice-over-music balance (voice should sit ≥ 6 LU above music
67
+ where both play) and SFX cue timing (onset vs nearest scene start/marker). Fix and run it again. The export
68
+ masters the rendered audio to −14 LUFS with a true-peak limiter (≤ −1 dBTP after encoding) and reports
69
+ what it did (`mastering`: rendered loudness, gain, limiter reduction). Large limiter reduction (> 3 dB)
70
+ means a few sounds are far louder than the rest: turn those clips down instead of relying on the limiter.
71
+
72
+ ## Voice-overs
73
+
74
+ The user connects their own voice provider under **Voices** in the studio header (ElevenLabs, Google
75
+ Gemini, OpenAI or Grok/xAI). You never see, ask for or mention API keys: the helper adds them.
76
+
77
+ 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
78
+ ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. If nothing is set up, ask the user
79
+ to open **Voices** and add a key, and stop there.
80
+ 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
81
+ 3. `agentcut_generate_voice` with the user's provider/model/voice (or the default). Generate 2 takes
82
+ for anything that matters. Delivery notes:
83
+ - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
84
+ action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
85
+ Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
86
+ - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
87
+ - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
88
+ 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
89
+ word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
90
+ to its word timings.
91
+ 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
92
+ voice the user has set up.
93
+
94
+ ## Music
95
+
96
+ Where a song comes from, in order:
97
+
98
+ 1. **A file the user gives you** (in `assets/`, or one they point at): use it.
99
+ 2. **The Agentcut music library** when the user asks for "a library song", "a song from the
100
+ library/editor", or just "a song" without asking for a new one: 200+ licensed tracks.
101
+ `agentcut_music_catalog` (filter by category and `minSeconds` = video length), pick 3–6
102
+ candidates from names that fit the vibe, `agentcut_add_catalog_music`, then rank them with
103
+ `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
104
+ the other candidates from `assets/music/`, and say which song you used and why.
105
+ 3. **Lyria (Google), when the user asks for a new/original/generated song** and
106
+ `agentcut_music_options` says it's available. Write the prompt like a brief:
107
+
108
+ ```
109
+ Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
110
+ A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
111
+ a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
112
+ [0:00 - 0:06] Intro: <what happens, how it feels>
113
+ [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
114
+ [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
115
+ [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
116
+ [0:45 - 0:48] The last chord rings out softly and fades to silence.
117
+ ```
118
+
119
+ Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
120
+ written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
121
+ `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
122
+ `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
123
+ `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
124
+ with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
125
+ 4. **Composed in code, when the user asks for a made song and Lyria isn't set up** (or they ask for code):
126
+ write a synthesis script in the project's `scripts/` folder and run it.
127
+ - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
128
+ otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
129
+ - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
130
+ which bars play under which scene, with a build and a gap before the drop on the reveal.
131
+ - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
132
+ hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
133
+ reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
134
+ the kick. Normalize to about −14 LUFS.
135
+ - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
136
+ in code (royalty-free, no samples).
137
+ 5. **CC0 music from Openverse** (as for sound effects) only when nothing above fits. Offer Lyria (a
138
+ Gemini key under Voices) if they want an original song.
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).