agentcut 0.2.26 → 0.2.27

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 (94) hide show
  1. package/README.md +177 -177
  2. package/dist/studio/agents/claude.js +3 -2
  3. package/dist/studio/agents/claude.js.map +1 -1
  4. package/dist/studio/chat.js +1 -1
  5. package/dist/studio/chat.js.map +1 -1
  6. package/dist/studio/cli.js +24 -24
  7. package/dist/studio/download.d.ts +24 -0
  8. package/dist/studio/download.js +234 -0
  9. package/dist/studio/download.js.map +1 -0
  10. package/dist/studio/host.js +8 -0
  11. package/dist/studio/host.js.map +1 -1
  12. package/dist/studio/housekeeping.d.ts +2 -2
  13. package/dist/studio/housekeeping.js +18 -17
  14. package/dist/studio/housekeeping.js.map +1 -1
  15. package/dist/studio/release-cursor.js +21 -21
  16. package/dist/studio/release-video.js +10 -10
  17. package/dist/studio/tools.js +7 -0
  18. package/dist/studio/tools.js.map +1 -1
  19. package/package.json +56 -56
  20. package/template/AGENTS.md +14 -14
  21. package/template/components/README.md +70 -70
  22. package/template/components/before-after/BeforeAfter.tsx +89 -89
  23. package/template/components/catalog.ts +107 -107
  24. package/template/components/cinematic/Device3D.tsx +324 -324
  25. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  26. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  27. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  28. package/template/components/cinematic/devices3d/models.ts +657 -657
  29. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  30. package/template/components/cinematic/math.ts +100 -100
  31. package/template/components/color/grade-effect.ts +650 -650
  32. package/template/components/color/grade.ts +512 -512
  33. package/template/components/color/looks.ts +154 -154
  34. package/template/components/countdown/Countdown.tsx +166 -166
  35. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  36. package/template/components/dot-trace-title/meta.json +51 -51
  37. package/template/components/generate/GenerateReveal.tsx +381 -381
  38. package/template/components/hook-card/HookCard.tsx +554 -554
  39. package/template/components/index.ts +199 -199
  40. package/template/components/lib.ts +191 -191
  41. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  42. package/template/components/line-diagram/meta.json +215 -215
  43. package/template/components/list-card/ListCard.tsx +104 -104
  44. package/template/components/live-clip.ts +75 -75
  45. package/template/components/looks.tsx +1447 -1447
  46. package/template/components/loops/LoopCanvas.tsx +132 -132
  47. package/template/components/loops/engine.ts +184 -184
  48. package/template/components/loops/library.ts +667 -667
  49. package/template/components/loops/library2.ts +777 -777
  50. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  51. package/template/components/motion-loop/meta.json +311 -311
  52. package/template/components/props.ts +73 -73
  53. package/template/components/quote-card/QuoteCard.tsx +71 -71
  54. package/template/components/style-layer.tsx +233 -233
  55. package/template/components/styles.ts +113 -113
  56. package/template/components/types.ts +66 -66
  57. package/template/components/word-pop/WordPop.tsx +59 -59
  58. package/template/components/word-stack/WordStack.tsx +122 -122
  59. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  60. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  61. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  62. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  63. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  64. package/template/runtime/composition.tsx +1189 -1189
  65. package/template/runtime/helpers.tsx +230 -230
  66. package/template/runtime/index.tsx +22 -22
  67. package/template/runtime/types.ts +315 -315
  68. package/template/skill/SKILL.md +186 -187
  69. package/template/skill/references/broll.md +44 -44
  70. package/template/skill/references/browser-export.md +61 -61
  71. package/template/skill/references/cinematic.md +206 -206
  72. package/template/skill/references/color.md +79 -79
  73. package/template/skill/references/craft.md +97 -97
  74. package/template/skill/references/editing-styles.md +57 -57
  75. package/template/skill/references/feature-launch.md +34 -34
  76. package/template/skill/references/footage.md +72 -72
  77. package/template/skill/references/format.md +142 -142
  78. package/template/skill/references/how-to.md +146 -146
  79. package/template/skill/references/launch-direction.md +89 -89
  80. package/template/skill/references/loops.md +151 -151
  81. package/template/skill/references/mcp-external.md +19 -19
  82. package/template/skill/references/performance.md +93 -93
  83. package/template/skill/references/person-cutout.md +19 -19
  84. package/template/skill/references/presets.md +60 -60
  85. package/template/skill/references/product-launch.md +134 -134
  86. package/template/skill/references/release-capture.md +53 -53
  87. package/template/skill/references/sound.md +167 -166
  88. package/template/skill/references/style-spy.md +160 -160
  89. package/template/skill/references/website-howto.md +45 -45
  90. package/template/starter/.studio/chat.json +1 -1
  91. package/template/starter/layers.json +46 -46
  92. package/template/starter/notes.md +4 -4
  93. package/template/starter/project.json +13 -13
  94. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,166 +1,167 @@
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 under a name you choose, 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
- ## Local voice default
75
-
76
- Generic voice-over requests use **Kokoro**, even if paid keys are configured. Use paid generation only when the user explicitly requests or selects a paid provider. Preserve explicit provider, voice, language, gender and accent choices. Use `agentcut_voice_options` with provider `kokoro`: its 28 English voices share verified IDs with the human preview samples. `localVoices` includes authored female/male labels, language/accent and preview URLs. `suggestedUses` comes from ScreenSlick's director playbook: Heart for tutorials, Emma for walkthroughs, Bella for demos, Puck for launches and Michael for sales. These are editorial defaults, not measured tone. Do not invent calm/energetic labels. Audition or measure a sample when tone matters; honor constraints before these defaults.
77
-
78
- The first local generation downloads about 93 MB plus support files. Later calls reuse the model cache. This runtime supports English only, speed 0.5–2, and no style instructions. For setup/offline/language errors, state the error and offer a retry, an English script, or an explicit provider choice. Never silently call paid. WAV output uses the same media-info, transcription, Voice track and word-timed caption workflow below.
79
-
80
- ## Optional Ming voices
81
-
82
- Use `provider: "ming"` only when selected by the user. Check installation with `agentcut_voice_options`. CPU generation can take minutes; prefer short scripts. The integration uses Ming 3.0 0.5B on CPU or a compatible NVIDIA CUDA GPU and currently supports English. Setup: `agentcut --setup-ming --ming-dir <folder> --ming-device cpu` (or `cuda`). All model files, Python packages, caches and temporary generation files stay in that folder. A small location pointer is saved under the user's `.agentcut` folder. MIT permits commercial use; retain upstream license notices when distributing model/runtime files.
83
-
84
- Choose one mode per generation:
85
- - Named voice: `US_Emma`, `UK_George`, or `UK_Charlotte`. Do not supply `style`.
86
- - Voice and delivery instructions: `voice: "freeform"`, with required `style`, such as "A warm American female narrator, excited and playful, with a quick pace." This does not preserve a named voice.
87
- - Voice design: `voice: "voice_design"`, with required `style` describing the voice.
88
-
89
- Use pace and emotion words in freeform style. Do not combine modes. Numeric speed changes, inline laughter/sigh tags, reference-voice cloning, and other languages are not exposed by this integration. Spell numbers, dates and abbreviations as they should be spoken: automatic text normalization is disabled for portable setup. Check generated words and delivery before using audio. Local failures must not call another provider. Kokoro remains the default.
90
-
91
- ## Voice-overs
92
-
93
- Kokoro is available without credentials. Optional paid providers are ElevenLabs, Gemini, OpenAI and Grok/xAI. The helper adds their keys only for explicitly selected paid generation.
94
-
95
- 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
96
- ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. Local Kokoro requires no key.
97
- 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
98
- 3. `agentcut_generate_voice` with Kokoro unless the user explicitly selected a paid provider. Honor their voice/model choice. Generate 2 takes
99
- for anything that matters. Delivery notes:
100
- - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
101
- action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
102
- Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
103
- - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
104
- - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
105
- 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
106
- word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
107
- to its word timings.
108
- 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
109
- voice the user has set up.
110
-
111
- ## Music
112
-
113
- Where a song comes from, in order (never download music from the web: it's slow and fails often):
114
-
115
- 1. **A file the user gives you** (in `assets/`, or one they point at): use it.
116
- 2. **The Agentcut music library** unless the user asks for a new song: 224 licensed tracks, each
117
- measured (tempo, energy 1–5, intro length, drops, ending, shape) and tagged (moods, genres,
118
- instruments, vocals). Search `agentcut_music_catalog` in plain words for the video's feel
119
- ("high energy no vocals", "calm 90 bpm", "cinematic dark", "playful") with `minSeconds` = video
120
- length; pick 3–6 candidates whose energy and shape fit the edit (a drop near the reveal, an intro
121
- you can trim, `vocals: false` under a voice-over), `agentcut_add_catalog_music`, then rank them with
122
- `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
123
- the other candidates from `assets/music/`, and say which song you used and why.
124
- 3. **Lyria (Google)** when the user asks for a new song, or the library isn't available or has nothing
125
- that fits, and `agentcut_music_options` says it's available (the user's Gemini key). Write the prompt like a brief:
126
-
127
- ```
128
- Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
129
- A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
130
- a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
131
- [0:00 - 0:06] Intro: <what happens, how it feels>
132
- [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
133
- [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
134
- [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
135
- [0:45 - 0:48] The last chord rings out softly and fades to silence.
136
- ```
137
-
138
- Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
139
- written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
140
- `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
141
- `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
142
- `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
143
- with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
144
- 4. **Composed in code** when neither the library nor Lyria is available (or the user asks for code):
145
- write a synthesis script in the project's `scripts/` folder and run it.
146
- - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
147
- otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
148
- - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
149
- which bars play under which scene, with a build and a gap before the drop on the reveal.
150
- - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
151
- hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
152
- reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
153
- the kick. Normalize to about −14 LUFS.
154
- - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
155
- in code (royalty-free, no samples).
156
- Mention once that a Gemini key under Voices gives them Lyria songs instead.
157
-
158
- Never put a Suno artist tag or account name anywhere visible.
159
-
160
- ## Making sound effects
161
-
162
- Only when the library and Openverse have nothing that fits (rank z < 1.5), or the user asks for a made
163
- sound: synthesize it in a script (same runtime rules as music) into `assets/sfx/<name>.wav`: whooshes from
164
- band-passed noise with a sweep and fade, pops from a short pitched sine with a fast decay, clicks from a
165
- few ms of filtered noise, risers from noise + rising tone. Rank and measure it like any candidate and say
166
- 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
+ - Save each result's `url` with `agentcut_download` and `folder: "sfx"`, rank and check them with the listen tools,
61
+ delete the ones you don't keep, and record `foreign_landing_url` in notes.md.
62
+ - Anonymous limits: 20 requests/minute, 200/day. Space requests ≥ 4 s apart (HTTP 429 → wait).
63
+
64
+ ## Check the mix
65
+
66
+ `agentcut_listen_critique` mixes the project exactly as the export will and reports loudness vs
67
+ −14 LUFS, true peak, clipping, silent gaps, voice-over-music balance (voice should sit ≥ 6 LU above music
68
+ where both play) and SFX cue timing (onset vs nearest scene start/marker). Fix and run it again. The export
69
+ masters the rendered audio to −14 LUFS with a true-peak limiter (≤ −1 dBTP after encoding) and reports
70
+ what it did (`mastering`: rendered loudness, gain, limiter reduction). Large limiter reduction (> 3 dB)
71
+ means a few sounds are far louder than the rest: turn those clips down instead of relying on the limiter.
72
+
73
+ ## Local voice default
74
+
75
+ Generic voice-over requests use **Kokoro**, even if paid keys are configured. Use paid generation only when the user explicitly requests or selects a paid provider. Preserve explicit provider, voice, language, gender and accent choices. Use `agentcut_voice_options` with provider `kokoro`: its 28 English voices share verified IDs with the human preview samples. `localVoices` includes authored female/male labels, language/accent and preview URLs. `suggestedUses` comes from ScreenSlick's director playbook: Heart for tutorials, Emma for walkthroughs, Bella for demos, Puck for launches and Michael for sales. These are editorial defaults, not measured tone. Do not invent calm/energetic labels. Audition or measure a sample when tone matters; honor constraints before these defaults.
76
+
77
+ The first local generation downloads about 93 MB plus support files. Later calls reuse the model cache. This runtime supports English only, speed 0.5–2, and no style instructions. For setup/offline/language errors, state the error and offer a retry, an English script, or an explicit provider choice. Never silently call paid. WAV output uses the same media-info, transcription, Voice track and word-timed caption workflow below.
78
+
79
+ ## Optional Ming voices
80
+
81
+ Use `provider: "ming"` only when selected by the user. Check installation with `agentcut_voice_options`. CPU generation can take minutes; prefer short scripts. The integration uses Ming 3.0 0.5B on CPU or a compatible NVIDIA CUDA GPU and currently supports English. Setup: `agentcut --setup-ming --ming-dir <folder> --ming-device cpu` (or `cuda`). All model files, Python packages, caches and temporary generation files stay in that folder. A small location pointer is saved under the user's `.agentcut` folder. MIT permits commercial use; retain upstream license notices when distributing model/runtime files.
82
+
83
+ Choose one mode per generation:
84
+ - Named voice: `US_Emma`, `UK_George`, or `UK_Charlotte`. Do not supply `style`.
85
+ - Voice and delivery instructions: `voice: "freeform"`, with required `style`, such as "A warm American female narrator, excited and playful, with a quick pace." This does not preserve a named voice.
86
+ - Voice design: `voice: "voice_design"`, with required `style` describing the voice.
87
+
88
+ Use pace and emotion words in freeform style. Do not combine modes. Numeric speed changes, inline laughter/sigh tags, reference-voice cloning, and other languages are not exposed by this integration. Spell numbers, dates and abbreviations as they should be spoken: automatic text normalization is disabled for portable setup. Check generated words and delivery before using audio. Local failures must not call another provider. Kokoro remains the default.
89
+
90
+ ## Voice-overs
91
+
92
+ Kokoro is available without credentials. Optional paid providers are ElevenLabs, Gemini, OpenAI and Grok/xAI. The helper adds their keys only for explicitly selected paid generation.
93
+
94
+ 1. `agentcut_voice_options`: which providers are set up, the default, models and voices. For
95
+ ElevenLabs pass `provider: "elevenlabs"` to get the account's voice ids. Local Kokoro requires no key.
96
+ 2. Write the script in `notes.md` first (one line per beat). Keep the spoken text clean: no stage directions.
97
+ 3. `agentcut_generate_voice` with Kokoro unless the user explicitly selected a paid provider. Honor their voice/model choice. Generate 2 takes
98
+ for anything that matters. Delivery notes:
99
+ - Gemini, OpenAI: `style` ("confident tech launch announcer, upbeat, quick pace, smile on the call to
100
+ action"; pronunciations like "say V2 as 'vee two'"). Gemini voices: Puck (upbeat), Kore (firm),
101
+ Charon (informative), Zephyr (bright), Fenrir (excitable)… OpenAI: marin, cedar (best).
102
+ - ElevenLabs v3/v4: audio tags inside the text (`[excited]`, `[whispers]`, `[pause]`).
103
+ - Grok: inline tags (`[pause]`, `[laugh]`, `<whisper>…</whisper>`) and `speed` 0.7–1.5.
104
+ 4. Check every take: `agentcut_media_info` (length) and `agentcut_transcribe` (each
105
+ word said right, nothing invented). Keep the best take, put it on the Voice track, time scenes and captions
106
+ to its word timings.
107
+ 5. If a provider call fails (quota, bad voice id), say what failed in one line and offer another provider or
108
+ voice the user has set up.
109
+
110
+ ## Music
111
+
112
+ Where a song comes from, in order (never go looking for music on the web: it's slow and fails often):
113
+
114
+ 1. **A song the user gives you**: a file in `assets/`, a file they point at (copy it into `assets/music/`), or a link to the
115
+ file (`agentcut_download` with `audioOnly: true`). Use it. A Suno link can't be fetched: ask them to use Download in
116
+ Suno, then drop the file in the chat or tell you where it saved.
117
+ 2. **The Agentcut music library** unless the user asks for a new song: 224 licensed tracks, each
118
+ measured (tempo, energy 1–5, intro length, drops, ending, shape) and tagged (moods, genres,
119
+ instruments, vocals). Search `agentcut_music_catalog` in plain words for the video's feel
120
+ ("high energy no vocals", "calm 90 bpm", "cinematic dark", "playful") with `minSeconds` = video
121
+ length; pick 3–6 candidates whose energy and shape fit the edit (a drop near the reveal, an intro
122
+ you can trim, `vocals: false` under a voice-over), `agentcut_add_catalog_music`, then rank them with
123
+ `agentcut_listen_rank` / `_tags` against a plain description of the mood, keep the best, delete
124
+ the other candidates from `assets/music/`, and say which song you used and why.
125
+ 3. **Lyria (Google)** when the user asks for a new song, or the library isn't available or has nothing
126
+ that fits, and `agentcut_music_options` says it's available (the user's Gemini key). Write the prompt like a brief:
127
+
128
+ ```
129
+ Instrumental only, no vocals, no singing, no humming. Total length: 48 seconds.
130
+ A happy, warm and professional music bed for <what the video is>. <mood words>. Key of D major,
131
+ a steady 112 BPM from start to end. Instruments: <4–8 instruments>. Clean modern mix, no lo-fi crackle.
132
+ [0:00 - 0:06] Intro: <what happens, how it feels>
133
+ [0:06 - 0:15] <section>: … a soft rising swell in the last two seconds.
134
+ [0:15 - 0:28] The groove starts: full groove kicks in on the downbeat at 0:15 …
135
+ [0:38 - 0:45] Final chorus: biggest part, then a clean final hit on the downbeat at 0:44.
136
+ [0:45 - 0:48] The last chord rings out softly and fades to silence.
137
+ ```
138
+
139
+ Put the section times on the video's beats (the reveal, the drop, the end card), so the music is
140
+ written for the cut. Match the look of the app/brand in the mood words. Never name artists or songs.
141
+ `agentcut_generate_music` with `takes: 2`, then for each take: `agentcut_media_info`,
142
+ `agentcut_analyze_audio` (tempo, beats, where the drop really lands) and
143
+ `agentcut_listen_tags` (no vocals if you asked for none). Keep the best take, line its drop up
144
+ with the reveal (move the clip or nudge the cuts to its beats), and tell the user which take and why.
145
+ 4. **Composed in code** when neither the library nor Lyria is available (or the user asks for code):
146
+ write a synthesis script in the project's `scripts/` folder and run it.
147
+ - Python with numpy/scipy if `python -c "import numpy, scipy"` works (try `python3` and `py` too);
148
+ otherwise a Node script (`node scripts/make_music.mjs`) that writes a 16-bit 44.1 kHz WAV itself.
149
+ - Plan the song map in the script's header first: BPM (120 → 1 beat = 15 frames at 30 fps), bars, and
150
+ which bars play under which scene, with a build and a gap before the drop on the reveal.
151
+ - Make it sound produced, not like beeps: layered drums (kick with pitch drop, snare = noise + tone,
152
+ hats from filtered noise), a bass line, chords with detuned voices and soft attacks, a melody/hook,
153
+ reverb (convolve with a short decaying-noise impulse) and a gentle limiter; sidechain the chords to
154
+ the kick. Normalize to about −14 LUFS.
155
+ - Write it to `assets/music/<name>.wav`, then check it like a Lyria take. Tell the user it's composed
156
+ in code (royalty-free, no samples).
157
+ Mention once that a Gemini key under Voices gives them Lyria songs instead.
158
+
159
+ Never put a Suno artist tag or account name anywhere visible.
160
+
161
+ ## Making sound effects
162
+
163
+ Only when the library and Openverse have nothing that fits (rank z < 1.5), or the user asks for a made
164
+ sound: synthesize it in a script (same runtime rules as music) into `assets/sfx/<name>.wav`: whooshes from
165
+ band-passed noise with a sweep and fade, pops from a short pitched sine with a fast decay, clicks from a
166
+ few ms of filtered noise, risers from noise + rising tone. Rank and measure it like any candidate and say
167
+ in notes.md that it's synthesized (`listen_realness` will be low; that's expected for a made sound).