agentcut 0.2.15 → 0.2.18

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 (152) hide show
  1. package/README.md +127 -0
  2. package/dist/bridge.d.ts +1 -0
  3. package/dist/bridge.js +9 -4
  4. package/dist/bridge.js.map +1 -1
  5. package/dist/index.js +3 -1
  6. package/dist/index.js.map +1 -1
  7. package/dist/log.js +6 -1
  8. package/dist/log.js.map +1 -1
  9. package/dist/studio/agents/claude.d.ts +22 -1
  10. package/dist/studio/agents/claude.js +89 -3
  11. package/dist/studio/agents/claude.js.map +1 -1
  12. package/dist/studio/agents/types.d.ts +6 -0
  13. package/dist/studio/chat.d.ts +2 -0
  14. package/dist/studio/chat.js +13 -10
  15. package/dist/studio/chat.js.map +1 -1
  16. package/dist/studio/cli.js +43 -21
  17. package/dist/studio/cli.js.map +1 -1
  18. package/dist/studio/editing-styles.d.ts +26 -0
  19. package/dist/studio/editing-styles.js +84 -0
  20. package/dist/studio/editing-styles.js.map +1 -0
  21. package/dist/studio/host.d.ts +13 -2
  22. package/dist/studio/host.js +140 -9
  23. package/dist/studio/host.js.map +1 -1
  24. package/dist/studio/housekeeping.d.ts +16 -0
  25. package/dist/studio/housekeeping.js +152 -0
  26. package/dist/studio/housekeeping.js.map +1 -0
  27. package/dist/studio/http.d.ts +3 -0
  28. package/dist/studio/http.js +25 -0
  29. package/dist/studio/http.js.map +1 -1
  30. package/dist/studio/mcp-files.d.ts +34 -0
  31. package/dist/studio/mcp-files.js +159 -0
  32. package/dist/studio/mcp-files.js.map +1 -0
  33. package/dist/studio/mcp-guides.d.ts +4 -0
  34. package/dist/studio/mcp-guides.js +93 -0
  35. package/dist/studio/mcp-guides.js.map +1 -0
  36. package/dist/studio/projects.d.ts +1 -1
  37. package/dist/studio/providers/http.d.ts +4 -0
  38. package/dist/studio/providers/http.js +23 -0
  39. package/dist/studio/providers/http.js.map +1 -0
  40. package/dist/studio/providers/settings.d.ts +20 -0
  41. package/dist/studio/providers/settings.js +84 -0
  42. package/dist/studio/providers/settings.js.map +1 -0
  43. package/dist/studio/proxies.d.ts +45 -0
  44. package/dist/studio/proxies.js +263 -0
  45. package/dist/studio/proxies.js.map +1 -0
  46. package/dist/studio/references.d.ts +18 -0
  47. package/dist/studio/references.js +21 -4
  48. package/dist/studio/references.js.map +1 -1
  49. package/dist/studio/release-browser.d.ts +25 -0
  50. package/dist/studio/release-browser.js +191 -0
  51. package/dist/studio/release-browser.js.map +1 -0
  52. package/dist/studio/release-cursor.d.ts +3 -0
  53. package/dist/studio/release-cursor.js +27 -0
  54. package/dist/studio/release-cursor.js.map +1 -0
  55. package/dist/studio/release-edit.d.ts +34 -0
  56. package/dist/studio/release-edit.js +183 -0
  57. package/dist/studio/release-edit.js.map +1 -0
  58. package/dist/studio/release-recorder.d.ts +30 -0
  59. package/dist/studio/release-recorder.js +273 -0
  60. package/dist/studio/release-recorder.js.map +1 -0
  61. package/dist/studio/release-video.d.ts +693 -0
  62. package/dist/studio/release-video.js +616 -0
  63. package/dist/studio/release-video.js.map +1 -0
  64. package/dist/studio/render.d.ts +2 -0
  65. package/dist/studio/render.js +33 -15
  66. package/dist/studio/render.js.map +1 -1
  67. package/dist/studio/reveal.d.ts +3 -1
  68. package/dist/studio/reveal.js +26 -8
  69. package/dist/studio/reveal.js.map +1 -1
  70. package/dist/studio/schema.d.ts +23535 -1480
  71. package/dist/studio/schema.js +71 -4
  72. package/dist/studio/schema.js.map +1 -1
  73. package/dist/studio/share.d.ts +2 -0
  74. package/dist/studio/share.js +7 -1
  75. package/dist/studio/share.js.map +1 -1
  76. package/dist/studio/tools.d.ts +4 -0
  77. package/dist/studio/tools.js +113 -8
  78. package/dist/studio/tools.js.map +1 -1
  79. package/dist/studio/transcription/assemblyai.d.ts +11 -0
  80. package/dist/studio/transcription/assemblyai.js +123 -0
  81. package/dist/studio/transcription/assemblyai.js.map +1 -0
  82. package/dist/studio/transcription/local.d.ts +2 -0
  83. package/dist/studio/transcription/local.js +57 -0
  84. package/dist/studio/transcription/local.js.map +1 -0
  85. package/dist/studio/transcription/registry.d.ts +3 -0
  86. package/dist/studio/transcription/registry.js +5 -0
  87. package/dist/studio/transcription/registry.js.map +1 -0
  88. package/dist/studio/transcription/service.d.ts +130 -0
  89. package/dist/studio/transcription/service.js +236 -0
  90. package/dist/studio/transcription/service.js.map +1 -0
  91. package/dist/studio/transcription/types.d.ts +68 -0
  92. package/dist/studio/transcription/types.js +2 -0
  93. package/dist/studio/transcription/types.js.map +1 -0
  94. package/dist/studio/voice/audio.d.ts +1 -0
  95. package/dist/studio/voice/audio.js +18 -0
  96. package/dist/studio/voice/audio.js.map +1 -0
  97. package/dist/studio/voice/elevenlabs.d.ts +2 -0
  98. package/dist/studio/voice/elevenlabs.js +76 -0
  99. package/dist/studio/voice/elevenlabs.js.map +1 -0
  100. package/dist/studio/voice/gemini.d.ts +2 -0
  101. package/dist/studio/voice/gemini.js +95 -0
  102. package/dist/studio/voice/gemini.js.map +1 -0
  103. package/dist/studio/voice/openai.d.ts +2 -0
  104. package/dist/studio/voice/openai.js +75 -0
  105. package/dist/studio/voice/openai.js.map +1 -0
  106. package/dist/studio/voice/registry.d.ts +4 -0
  107. package/dist/studio/voice/registry.js +18 -0
  108. package/dist/studio/voice/registry.js.map +1 -0
  109. package/dist/studio/voice/types.d.ts +42 -0
  110. package/dist/studio/voice/types.js +2 -0
  111. package/dist/studio/voice/types.js.map +1 -0
  112. package/dist/studio/voice/xai.d.ts +2 -0
  113. package/dist/studio/voice/xai.js +80 -0
  114. package/dist/studio/voice/xai.js.map +1 -0
  115. package/dist/studio/voice.d.ts +32 -58
  116. package/dist/studio/voice.js +52 -308
  117. package/dist/studio/voice.js.map +1 -1
  118. package/dist/studio/workspace.d.ts +1 -0
  119. package/dist/studio/workspace.js +1 -0
  120. package/dist/studio/workspace.js.map +1 -1
  121. package/package.json +2 -1
  122. package/template/AGENTS.md +1 -0
  123. package/template/components/CATALOG.md +2 -0
  124. package/template/components/STYLES.md +108 -7
  125. package/template/components/catalog.json +29 -0
  126. package/template/components/color/grade-effect.ts +650 -0
  127. package/template/components/color/grade.ts +512 -0
  128. package/template/components/color/looks.ts +154 -0
  129. package/template/components/hook-card/HookCard.tsx +11 -5
  130. package/template/components/hook-card/meta.json +29 -0
  131. package/template/components/index.ts +14 -0
  132. package/template/components/live-clip.ts +75 -0
  133. package/template/components/sticker-badge/StickerBadge.tsx +4 -2
  134. package/template/components/styles.json +354 -3
  135. package/template/runtime/composition.tsx +283 -25
  136. package/template/runtime/framing.ts +29 -0
  137. package/template/runtime/helpers.tsx +2 -0
  138. package/template/runtime/types.ts +71 -4
  139. package/template/skill/SKILL.md +132 -6
  140. package/template/skill/references/broll.md +2 -1
  141. package/template/skill/references/color.md +79 -0
  142. package/template/skill/references/editing-styles.md +57 -0
  143. package/template/skill/references/footage.md +72 -73
  144. package/template/skill/references/format.md +142 -140
  145. package/template/skill/references/performance.md +14 -2
  146. package/template/skill/references/person-cutout.md +19 -0
  147. package/template/skill/references/person-framing.md +13 -0
  148. package/template/skill/references/presets.md +60 -56
  149. package/template/skill/references/sound.md +151 -151
  150. package/template/skill/references/style-editing.md +20 -0
  151. package/template/skill/references/transcription.md +15 -0
  152. package/template/skill/references/website-howto.md +41 -0
@@ -1,151 +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: 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).
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
+ ## 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).
@@ -0,0 +1,20 @@
1
+ # Style editing workflow
2
+
3
+ A selected style supplies visual defaults and an editing guide. Selection alone does not clean speech, find footage, improve source resolution or mix audio. Carry out these steps when the user sends an editing request.
4
+
5
+ 1. Inspect the source and the current timeline. Read the selected entry in .agentcut/components/STYLES.md. Preserve user edits. Record a short cue sheet in notes.md.
6
+ 2. Transcribe with agentcut_transcribe. Review timed words and listen to candidate cuts. Remove verified repeated takes, unnecessary silence and filler words only where the sentence still sounds natural. Keep meaningful pauses and breaths. If timing or listening is unavailable, do not guess the cuts; report the limit.
7
+ 3. Assemble speech first. Split and trim source clips, close gaps, and keep source files unchanged. Rebuild caption timings against the edited sequence. Move related graphics, B-roll and audio with their speech. Check every join for lost syllables and audio clicks.
8
+ 4. Review framing about every 4–6 seconds. Choose a new crop, wider reset or relevant B-roll at a change of idea, example or emphasis. This is a review interval, not a fixed cut interval. Preserve face and eye lines in each variant. Use supported clip boxes or an explicit scene transform; do not invent a zoom property. Keep camera:none on clips if a style camera would add an unwanted repeating move. The four new styles use a still camera by default.
9
+ 5. Add supplied or approved B-roll to explain the words. Use source labels on evidence. If needed footage is missing, use a useful card or diagram and report the missing asset. Do not invent quotes, statistics or product details.
10
+ 6. Apply the palette, type and restrained grade. Check skin tones, highlight clipping and text contrast. A filter cannot restore focus or upscale source detail. Keep music below speech, use sparse sounds on visible cues, and follow references/sound.md for measurement. Apply EQ or compression only through supported tools or a documented audio-processing step; a preset name does not apply them.
11
+ 7. Capture entrances, holds and exits in each size. Use a contact sheet for pacing. Listen to the final mix. Check caption sync after all cuts. Report what changed and any source or tool limits.
12
+
13
+ ## Research behind the four directions
14
+
15
+ These are original Agentcut styles inspired by editing principles. They are not creator replicas, endorsements or a ranking of current trends. Palettes, layouts and preview choreography are our design choices.
16
+
17
+ - Signal: direct business advice, evidence and a next action. Alex Hormozi's June 2024 note favors useful business content and less distracting production: https://www.acquisition.com/mozi-money-minute/i-made-a-youtube-video . His official workbook describes hook, retain and reward: https://shop.acquisition.com/products/workbook-3-pack-digital . This supports a clear message, not constant animated captions.
18
+ - Studyroom: lesson assembly, relevant supporting visuals, then sound and color polish. Ali Abdaal explains this three-stage workflow: https://aliabdaal.com/youtube/the-ultimate-guide-to-youtube/ . Preserve useful pauses rather than applying blanket silence removal.
19
+ - Afterglow: a product story with detail footage, a measured grade and music-led scene changes. Daniel Schiffer's own cooking B-roll editing breakdown is a visual reference: https://www.youtube.com/watch?v=qSMi0ygL--E . Actual footage and timeline edits are required; a look preset alone does not create that sequence.
20
+ - Fieldnote: documentary setup, question and resolution with traceable evidence. Colin and Samir discuss audience, story planning and a three-act structure in their first-person interview: https://www.musicbed.com/articles/filmmaking/youtube/the-biggest-mistake-filmmakers-make-with-colin-and-samir/ . Serif type and rust source markers are Agentcut design choices.
@@ -0,0 +1,15 @@
1
+ # Transcription providers
2
+
3
+ Use the built-in operation. Do not install a provider SDK, ask for keys in chat, or write upload scripts.
4
+
5
+ - `agentcut_transcription_options` lists preferred provider, configured status, models, capabilities and jobs, never credentials. Local Whisper is the initial default. Adding a cloud key does not select it. The user selects a preference under Transcription in either editor view.
6
+ - `agentcut_transcribe` accepts `path`, optional `project`, `provider`, `model`, `language`, `speakerLabels` and a unique optional `job` ID. Use the preference unless the user explicitly asks for an override, such as `provider: "local"`. Never silently switch after an error. For unconfigured providers ask the user to open settings; never ask them to paste a key in chat.
7
+ - Local Whisper retains tiny/base/small models and word timings. Language defaults to en; it needs an explicit language code and does not supply speaker labels. Filler recognition is not guaranteed. Its files stay local, though model downloads may be needed.
8
+ - AssemblyAI uses the user's API key in the helper. Audio is extracted locally, then uploaded to AssemblyAI. Provider charges and provider data handling apply. It uses Universal-2 and always requests `disfluencies: true` for editing. That model's filler support is English only; other languages and automatic language detection do not guarantee filler recognition. Speaker labels are optional. A key does not imply permission to run unsolicited paid test jobs.
9
+ - Results use seconds (`start`, `end`) and project frames (`fromFrame`, `toFrame`) from the original source, not edited timeline positions. Preserve trims and map words through cuts. Results include provider/model/options/source provenance, a cache key, segments and speaker labels when available. Cached results are separated by source content, provider, options and fps. Raw recognized filler words and their timings are retained. A transcript that omits fillers is not evidence that the audio was edited.
10
+ - Pass a unique `job` ID if you need progress or cancellation. Discover stages with `agentcut_transcription_options`, cancel with `agentcut_cancel_transcription`. Transcription settings also shows active jobs and Cancel. Cancellation stops local processing or cloud polling; remote work and charges may already have begun. No other provider is used as fallback.
11
+ - Listen before making silence/filler cuts. ASR timings and words can be wrong, especially with music, overlap, accents or poor audio. Do not equate a cleaner text result with edited speech.
12
+
13
+ Implementation extension points are separate: `src/studio/transcription/registry.ts` for recognition and `src/studio/voice/registry.ts` for synthesis. An adapter owns metadata, capabilities and provider calls. Both use helper-only provider settings/secret storage. Adding a synthesis provider does not make it a transcription provider.
14
+
15
+ Primary references: https://www.assemblyai.com/docs/pre-recorded-audio/getting-started/transcribe-an-audio-file , https://www.assemblyai.com/docs/pre-recorded-audio/include-filler-words , https://www.assemblyai.com/docs/pre-recorded-audio/select-the-speech-model .
@@ -0,0 +1,41 @@
1
+ # Website how-to execution
2
+
3
+ Use this reference to prevent stalled work during website walkthroughs, setup tutorials and
4
+ feature videos. Keep the main skill's creative process and full review. Do not reduce formats,
5
+ UI detail, animation, voice, music, sound design or review coverage to save time. User instructions
6
+ and existing project choices take priority.
7
+
8
+ ## Reuse working setup
9
+
10
+ - Start from the known app URL, source folder and existing project notes. Reuse a working
11
+ preview, app build, captured evidence and generated assets when they are still current.
12
+ - Ask for a missing source location instead of searching the entire home folder and GitHub.
13
+ - When source-based UI work improves the result, keep it. Check that it matches the current
14
+ app, and do not invent product behavior. Preserve approved demo disclosures.
15
+ - Keep the script and shot list within the requested duration. Preserve the craft steps for
16
+ both formats, music selection, sound design, voice checks and visual review.
17
+
18
+ ## Recover from stalled tools
19
+
20
+ - Run page-heavy checks one at a time: frame captures, contact sheets, playback checks,
21
+ audio analysis/listening and exports. Do not launch wide and mobile sheets and audio
22
+ critique concurrently. Complete the same checks in sequence.
23
+ - A tool timeout does not prove the browser stopped the work. Check
24
+ `agentcut_status.page.activeWork` before retrying. If the earlier task remains active,
25
+ do not add another request, even with fewer frames. Status calls remain available.
26
+ - If `activeWork` is unavailable on an older editor, treat timed-out work as possibly active.
27
+ Inspect the page and report the stall. Save pending edits before a reload to clear stuck work.
28
+ Do not repeatedly open and close browser windows.
29
+ - After recovery, run one small frame probe. This checks that rendering works; it does not
30
+ replace full-resolution inspection, contact sheets, both-format review or playback checks.
31
+ Resume the full review once the probe succeeds. Keep final render quality unchanged.
32
+ - If the probe also stalls, preserve the project and report the blocked check. Do not add
33
+ another series of five- or ten-minute waits. The review remains incomplete until it passes.
34
+ - An unknown `studio.local.*` method can mean that the MCP server and running helper differ.
35
+ Report the required update or restart rather than repeating the same failed method. The
36
+ release-job prototype supports announcement only; how-to uses the direct studio workflow.
37
+ - Give a clear progress update when a phase stalls. State which check is blocked and what
38
+ is complete. Do not claim that a build proves the video is ready.
39
+
40
+ The goal is to remove idle waits, duplicate setup and competing checks while preserving the
41
+ quality of the final video. These changes do not promise a fixed completion time.