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.
- package/dist/studio/agents/claude.js +16 -0
- package/dist/studio/agents/claude.js.map +1 -1
- package/dist/studio/agents/codex.d.ts +1 -1
- package/dist/studio/agents/codex.js +44 -0
- package/dist/studio/agents/codex.js.map +1 -1
- package/dist/studio/agents/index.d.ts +2 -1
- package/dist/studio/agents/index.js +2 -0
- package/dist/studio/agents/index.js.map +1 -1
- package/dist/studio/agents/types.d.ts +30 -0
- package/dist/studio/agents/types.js +4 -1
- package/dist/studio/agents/types.js.map +1 -1
- package/dist/studio/bundler.d.ts +1 -1
- package/dist/studio/bundler.js +2 -0
- package/dist/studio/bundler.js.map +1 -1
- package/dist/studio/chat.d.ts +1 -1
- package/dist/studio/chat.js +15 -11
- package/dist/studio/chat.js.map +1 -1
- package/dist/studio/host.js +1 -1
- package/dist/studio/host.js.map +1 -1
- package/dist/studio/tools.js +7 -2
- package/dist/studio/tools.js.map +1 -1
- package/dist/studio/workspace.d.ts +3 -1
- package/dist/studio/workspace.js +46 -1
- package/dist/studio/workspace.js.map +1 -1
- package/package.json +53 -52
- package/template/components/cinematic/Cinematic.tsx +76 -28
- package/template/skill/references/sound.md +151 -148
|
@@ -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
|
-
|
|
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
|
|
459
|
-
|
|
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
|
|
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
|
-
|
|
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:
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
[0:
|
|
117
|
-
[0:
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
with
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
+
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).
|