soundroo 0.0.0-stage → 0.7.0

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 (281) hide show
  1. package/AGENTS.md +143 -0
  2. package/CLAUDE.md +1 -0
  3. package/LICENSE +21 -0
  4. package/README.md +168 -2
  5. package/THIRD_PARTY_NOTICES.md +9 -0
  6. package/assets/samples/SOURCES.md +366 -0
  7. package/assets/samples/brass/39-1-1.wav +0 -0
  8. package/assets/samples/brass/41-1-1.wav +0 -0
  9. package/assets/samples/brass/45-1-1.wav +0 -0
  10. package/assets/samples/brass/46-1-1.wav +0 -0
  11. package/assets/samples/brass/50-1-1.wav +0 -0
  12. package/assets/samples/brass/53-1-1.wav +0 -0
  13. package/assets/samples/brass/57-1-1.wav +0 -0
  14. package/assets/samples/brass/60-1-1.wav +0 -0
  15. package/assets/samples/brass/63-1-1.wav +0 -0
  16. package/assets/samples/brass/67-1-1.wav +0 -0
  17. package/assets/samples/brass/70-1-1.wav +0 -0
  18. package/assets/samples/brass/74-1-1.wav +0 -0
  19. package/assets/samples/brass/77-1-1.wav +0 -0
  20. package/assets/samples/brass/81-1-1.wav +0 -0
  21. package/assets/samples/closed-hat/42-1-1.wav +0 -0
  22. package/assets/samples/closed-hat/42-1-2.wav +0 -0
  23. package/assets/samples/closed-hat/42-2-1.wav +0 -0
  24. package/assets/samples/closed-hat/42-2-2.wav +0 -0
  25. package/assets/samples/closed-hat/42-3-1.wav +0 -0
  26. package/assets/samples/closed-hat/42-3-2.wav +0 -0
  27. package/assets/samples/crash/49-1-1.wav +0 -0
  28. package/assets/samples/crash/49-2-1.wav +0 -0
  29. package/assets/samples/electric-bass/24-1-1.wav +0 -0
  30. package/assets/samples/electric-bass/24-2-1.wav +0 -0
  31. package/assets/samples/electric-bass/26-1-1.wav +0 -0
  32. package/assets/samples/electric-bass/26-2-1.wav +0 -0
  33. package/assets/samples/electric-bass/29-1-1.wav +0 -0
  34. package/assets/samples/electric-bass/29-2-1.wav +0 -0
  35. package/assets/samples/electric-bass/32-1-1.wav +0 -0
  36. package/assets/samples/electric-bass/32-2-1.wav +0 -0
  37. package/assets/samples/electric-bass/35-1-1.wav +0 -0
  38. package/assets/samples/electric-bass/35-2-1.wav +0 -0
  39. package/assets/samples/electric-bass/38-1-1.wav +0 -0
  40. package/assets/samples/electric-bass/38-2-1.wav +0 -0
  41. package/assets/samples/electric-bass/41-1-1.wav +0 -0
  42. package/assets/samples/electric-bass/41-2-1.wav +0 -0
  43. package/assets/samples/electric-bass/44-1-1.wav +0 -0
  44. package/assets/samples/electric-bass/44-2-1.wav +0 -0
  45. package/assets/samples/electric-bass/47-1-1.wav +0 -0
  46. package/assets/samples/electric-bass/47-2-1.wav +0 -0
  47. package/assets/samples/electric-bass/50-1-1.wav +0 -0
  48. package/assets/samples/electric-bass/50-2-1.wav +0 -0
  49. package/assets/samples/electric-bass/53-1-1.wav +0 -0
  50. package/assets/samples/electric-bass/53-2-1.wav +0 -0
  51. package/assets/samples/electric-bass/56-1-1.wav +0 -0
  52. package/assets/samples/electric-bass/56-2-1.wav +0 -0
  53. package/assets/samples/electric-bass/59-1-1.wav +0 -0
  54. package/assets/samples/electric-bass/59-2-1.wav +0 -0
  55. package/assets/samples/electric-bass/62-1-1.wav +0 -0
  56. package/assets/samples/electric-bass/62-2-1.wav +0 -0
  57. package/assets/samples/guitar-clean/40-1-1.wav +0 -0
  58. package/assets/samples/guitar-clean/41-1-1.wav +0 -0
  59. package/assets/samples/guitar-clean/45-1-1.wav +0 -0
  60. package/assets/samples/guitar-clean/48-1-1.wav +0 -0
  61. package/assets/samples/guitar-clean/50-1-1.wav +0 -0
  62. package/assets/samples/guitar-clean/52-1-1.wav +0 -0
  63. package/assets/samples/guitar-clean/55-1-1.wav +0 -0
  64. package/assets/samples/guitar-clean/59-1-1.wav +0 -0
  65. package/assets/samples/guitar-clean/61-1-1.wav +0 -0
  66. package/assets/samples/guitar-clean/64-1-1.wav +0 -0
  67. package/assets/samples/guitar-clean/67-1-1.wav +0 -0
  68. package/assets/samples/guitar-clean/71-1-1.wav +0 -0
  69. package/assets/samples/guitar-clean/72-1-1.wav +0 -0
  70. package/assets/samples/guitar-clean/74-1-1.wav +0 -0
  71. package/assets/samples/guitar-clean/77-1-1.wav +0 -0
  72. package/assets/samples/guitar-clean/80-1-1.wav +0 -0
  73. package/assets/samples/guitar-clean/82-1-1.wav +0 -0
  74. package/assets/samples/guitar-clean/85-1-1.wav +0 -0
  75. package/assets/samples/guitar-crunch/40-1-1.wav +0 -0
  76. package/assets/samples/guitar-crunch/41-1-1.wav +0 -0
  77. package/assets/samples/guitar-crunch/45-1-1.wav +0 -0
  78. package/assets/samples/guitar-crunch/48-1-1.wav +0 -0
  79. package/assets/samples/guitar-crunch/50-1-1.wav +0 -0
  80. package/assets/samples/guitar-crunch/52-1-1.wav +0 -0
  81. package/assets/samples/guitar-crunch/55-1-1.wav +0 -0
  82. package/assets/samples/guitar-crunch/59-1-1.wav +0 -0
  83. package/assets/samples/guitar-crunch/61-1-1.wav +0 -0
  84. package/assets/samples/guitar-crunch/64-1-1.wav +0 -0
  85. package/assets/samples/guitar-crunch/67-1-1.wav +0 -0
  86. package/assets/samples/guitar-crunch/71-1-1.wav +0 -0
  87. package/assets/samples/guitar-crunch/72-1-1.wav +0 -0
  88. package/assets/samples/guitar-crunch/74-1-1.wav +0 -0
  89. package/assets/samples/guitar-crunch/77-1-1.wav +0 -0
  90. package/assets/samples/guitar-crunch/80-1-1.wav +0 -0
  91. package/assets/samples/guitar-crunch/82-1-1.wav +0 -0
  92. package/assets/samples/guitar-crunch/85-1-1.wav +0 -0
  93. package/assets/samples/open-hat/46-1-1.wav +0 -0
  94. package/assets/samples/open-hat/46-2-1.wav +0 -0
  95. package/assets/samples/piano/102-1-1.wav +0 -0
  96. package/assets/samples/piano/102-2-1.wav +0 -0
  97. package/assets/samples/piano/105-1-1.wav +0 -0
  98. package/assets/samples/piano/105-2-1.wav +0 -0
  99. package/assets/samples/piano/108-1-1.wav +0 -0
  100. package/assets/samples/piano/108-2-1.wav +0 -0
  101. package/assets/samples/piano/21-1-1.wav +0 -0
  102. package/assets/samples/piano/21-2-1.wav +0 -0
  103. package/assets/samples/piano/24-1-1.wav +0 -0
  104. package/assets/samples/piano/24-2-1.wav +0 -0
  105. package/assets/samples/piano/27-1-1.wav +0 -0
  106. package/assets/samples/piano/27-2-1.wav +0 -0
  107. package/assets/samples/piano/30-1-1.wav +0 -0
  108. package/assets/samples/piano/30-2-1.wav +0 -0
  109. package/assets/samples/piano/33-1-1.wav +0 -0
  110. package/assets/samples/piano/33-2-1.wav +0 -0
  111. package/assets/samples/piano/36-1-1.wav +0 -0
  112. package/assets/samples/piano/36-2-1.wav +0 -0
  113. package/assets/samples/piano/39-1-1.wav +0 -0
  114. package/assets/samples/piano/39-2-1.wav +0 -0
  115. package/assets/samples/piano/42-1-1.wav +0 -0
  116. package/assets/samples/piano/42-2-1.wav +0 -0
  117. package/assets/samples/piano/45-1-1.wav +0 -0
  118. package/assets/samples/piano/45-2-1.wav +0 -0
  119. package/assets/samples/piano/48-1-1.wav +0 -0
  120. package/assets/samples/piano/48-2-1.wav +0 -0
  121. package/assets/samples/piano/51-1-1.wav +0 -0
  122. package/assets/samples/piano/51-2-1.wav +0 -0
  123. package/assets/samples/piano/54-1-1.wav +0 -0
  124. package/assets/samples/piano/54-2-1.wav +0 -0
  125. package/assets/samples/piano/57-1-1.wav +0 -0
  126. package/assets/samples/piano/57-2-1.wav +0 -0
  127. package/assets/samples/piano/60-1-1.wav +0 -0
  128. package/assets/samples/piano/60-2-1.wav +0 -0
  129. package/assets/samples/piano/63-1-1.wav +0 -0
  130. package/assets/samples/piano/63-2-1.wav +0 -0
  131. package/assets/samples/piano/66-1-1.wav +0 -0
  132. package/assets/samples/piano/66-2-1.wav +0 -0
  133. package/assets/samples/piano/69-1-1.wav +0 -0
  134. package/assets/samples/piano/69-2-1.wav +0 -0
  135. package/assets/samples/piano/72-1-1.wav +0 -0
  136. package/assets/samples/piano/72-2-1.wav +0 -0
  137. package/assets/samples/piano/75-1-1.wav +0 -0
  138. package/assets/samples/piano/75-2-1.wav +0 -0
  139. package/assets/samples/piano/78-1-1.wav +0 -0
  140. package/assets/samples/piano/78-2-1.wav +0 -0
  141. package/assets/samples/piano/81-1-1.wav +0 -0
  142. package/assets/samples/piano/81-2-1.wav +0 -0
  143. package/assets/samples/piano/84-1-1.wav +0 -0
  144. package/assets/samples/piano/84-2-1.wav +0 -0
  145. package/assets/samples/piano/87-1-1.wav +0 -0
  146. package/assets/samples/piano/87-2-1.wav +0 -0
  147. package/assets/samples/piano/90-1-1.wav +0 -0
  148. package/assets/samples/piano/90-2-1.wav +0 -0
  149. package/assets/samples/piano/93-1-1.wav +0 -0
  150. package/assets/samples/piano/93-2-1.wav +0 -0
  151. package/assets/samples/piano/96-1-1.wav +0 -0
  152. package/assets/samples/piano/96-2-1.wav +0 -0
  153. package/assets/samples/piano/99-1-1.wav +0 -0
  154. package/assets/samples/piano/99-2-1.wav +0 -0
  155. package/assets/samples/ride/51-1-1.wav +0 -0
  156. package/assets/samples/ride/51-2-1.wav +0 -0
  157. package/assets/samples/rock-kick/36-1-1.wav +0 -0
  158. package/assets/samples/rock-kick/36-1-2.wav +0 -0
  159. package/assets/samples/rock-kick/36-2-1.wav +0 -0
  160. package/assets/samples/rock-kick/36-2-2.wav +0 -0
  161. package/assets/samples/rock-kick/36-3-1.wav +0 -0
  162. package/assets/samples/rock-kick/36-3-2.wav +0 -0
  163. package/assets/samples/rock-kick/36-4-1.wav +0 -0
  164. package/assets/samples/rock-kick/36-4-2.wav +0 -0
  165. package/assets/samples/rock-snare/38-1-1.wav +0 -0
  166. package/assets/samples/rock-snare/38-1-2.wav +0 -0
  167. package/assets/samples/rock-snare/38-2-1.wav +0 -0
  168. package/assets/samples/rock-snare/38-2-2.wav +0 -0
  169. package/assets/samples/rock-snare/38-3-1.wav +0 -0
  170. package/assets/samples/rock-snare/38-3-2.wav +0 -0
  171. package/assets/samples/rock-snare/38-4-1.wav +0 -0
  172. package/assets/samples/rock-snare/38-4-2.wav +0 -0
  173. package/assets/samples/samples.json +367 -0
  174. package/assets/samples/strings/36-1-1.wav +0 -0
  175. package/assets/samples/strings/40-1-1.wav +0 -0
  176. package/assets/samples/strings/43-1-1.wav +0 -0
  177. package/assets/samples/strings/47-1-1.wav +0 -0
  178. package/assets/samples/strings/50-1-1.wav +0 -0
  179. package/assets/samples/strings/53-1-1.wav +0 -0
  180. package/assets/samples/strings/55-1-1.wav +0 -0
  181. package/assets/samples/strings/59-1-1.wav +0 -0
  182. package/assets/samples/strings/62-1-1.wav +0 -0
  183. package/assets/samples/strings/65-1-1.wav +0 -0
  184. package/assets/samples/strings/69-1-1.wav +0 -0
  185. package/assets/samples/strings/72-1-1.wav +0 -0
  186. package/assets/samples/strings/76-1-1.wav +0 -0
  187. package/assets/samples/strings/79-1-1.wav +0 -0
  188. package/assets/samples/strings/83-1-1.wav +0 -0
  189. package/assets/samples/strings/86-1-1.wav +0 -0
  190. package/assets/samples/tom/41-1-1.wav +0 -0
  191. package/assets/samples/tom/41-2-1.wav +0 -0
  192. package/assets/samples/tom/45-1-1.wav +0 -0
  193. package/assets/samples/tom/45-2-1.wav +0 -0
  194. package/assets/samples/tom/48-1-1.wav +0 -0
  195. package/assets/samples/tom/48-2-1.wav +0 -0
  196. package/assets/samples/tom/50-1-1.wav +0 -0
  197. package/assets/samples/tom/50-2-1.wav +0 -0
  198. package/assets/voices/city-never-sleeps.wav +0 -0
  199. package/assets/voices/in-the-rhythm.wav +0 -0
  200. package/assets/voices/let-it-change.wav +0 -0
  201. package/assets/voices/made-of-light.wav +0 -0
  202. package/assets/voices/phrases.json +44 -0
  203. package/assets/voices/slow-down.wav +0 -0
  204. package/assets/voices/stay-a-little.wav +0 -0
  205. package/bin/soundroo.js +109 -0
  206. package/docs/composing.md +135 -0
  207. package/docs/grooves.md +45 -0
  208. package/docs/headless.md +98 -0
  209. package/docs/musical-directions.md +40 -0
  210. package/docs/sharing.md +153 -0
  211. package/docs/studio.jpg +0 -0
  212. package/examples/README.md +59 -0
  213. package/examples/collection.js +260 -0
  214. package/examples/paper-satellites.json +61 -0
  215. package/examples/pixel-grand-prix.json +57 -0
  216. package/examples/streetlight-funk.json +63 -0
  217. package/examples/variety.js +1674 -0
  218. package/package.json +46 -4
  219. package/src/archive.js +54 -0
  220. package/src/arrangement.js +64 -0
  221. package/src/artwork.js +79 -0
  222. package/src/audio/analysis.js +52 -0
  223. package/src/audio/dsp.js +72 -0
  224. package/src/audio/instruments.js +193 -0
  225. package/src/audio/loudness.js +51 -0
  226. package/src/audio/master.js +50 -0
  227. package/src/audio/midi.js +59 -0
  228. package/src/audio/pcm.js +93 -0
  229. package/src/audio/rng.js +40 -0
  230. package/src/audio/sampler.js +62 -0
  231. package/src/audio/sfx.js +287 -0
  232. package/src/audio/synth.js +786 -0
  233. package/src/audio/theory.js +105 -0
  234. package/src/audio/voice-effects.js +108 -0
  235. package/src/audio/wav.js +47 -0
  236. package/src/catalog.js +52 -0
  237. package/src/cloud/binary.js +225 -0
  238. package/src/cloud/cli.js +205 -0
  239. package/src/cloud/errors.js +31 -0
  240. package/src/cloud/importer.js +119 -0
  241. package/src/cloud/origin.js +39 -0
  242. package/src/cloud/payload.js +219 -0
  243. package/src/cloud/runner.js +72 -0
  244. package/src/cloud/share.js +273 -0
  245. package/src/cloud/state.js +63 -0
  246. package/src/cloud/studio.js +124 -0
  247. package/src/compose.js +50 -0
  248. package/src/headless.js +126 -0
  249. package/src/identity.js +77 -0
  250. package/src/notation.js +104 -0
  251. package/src/project.js +229 -0
  252. package/src/render-worker.js +18 -0
  253. package/src/render.js +312 -0
  254. package/src/score.js +211 -0
  255. package/src/server.js +210 -0
  256. package/src/speech.js +111 -0
  257. package/src/version.js +2 -0
  258. package/src/voice.js +42 -0
  259. package/web/favicon.svg +7 -0
  260. package/web/index.html +311 -0
  261. package/web/js/actions.js +234 -0
  262. package/web/js/api.js +74 -0
  263. package/web/js/app.js +312 -0
  264. package/web/js/dialogs.js +103 -0
  265. package/web/js/dom.js +146 -0
  266. package/web/js/jobs.js +86 -0
  267. package/web/js/logic.js +579 -0
  268. package/web/js/menu.js +117 -0
  269. package/web/js/nowplaying.js +376 -0
  270. package/web/js/player.js +539 -0
  271. package/web/js/queue.js +88 -0
  272. package/web/js/share.js +489 -0
  273. package/web/js/store.js +121 -0
  274. package/web/js/theme.js +10 -0
  275. package/web/js/transport.js +153 -0
  276. package/web/js/views/home.js +146 -0
  277. package/web/js/views/make.js +243 -0
  278. package/web/js/views/track.js +711 -0
  279. package/web/js/views/tracks.js +164 -0
  280. package/web/js/wave.js +190 -0
  281. package/web/styles.css +1636 -0
package/AGENTS.md ADDED
@@ -0,0 +1,143 @@
1
+ # Soundroo for AI agents
2
+
3
+ This file tells you, the AI agent, how to make music with Soundroo. The person gives you an idea, maybe only a few words. You compose the music as an editable score. Soundroo renders it into audio on this computer and opens a small music player in the browser, where the person listens.
4
+
5
+ Soundroo needs Node.js 22 or newer and nothing else: no account, no API key, no music software, no model download. Speech is optional.
6
+
7
+ The documentation for people is at https://www.soundroo.com/docs.
8
+
9
+ ## Before you start
10
+
11
+ Maybe the person pasted the prompt from soundroo.com or the README, and you are not in a Soundroo folder yet. Then clone it into the current folder first. If they named another place, use that.
12
+
13
+ ```bash
14
+ git clone https://github.com/vincentsch/soundroo.git
15
+ cd soundroo
16
+ node bin/soundroo.js doctor
17
+ ```
18
+
19
+ `doctor` checks Node. If Node is missing or older than 22, tell the person and help them install Node 22 (for example from https://nodejs.org or with nvm). Nothing else needs installing.
20
+
21
+ If you can't run commands on a real computer at all (for example in a chat app), stop and send the person to https://www.soundroo.com/connect. That page explains the Soundroo connector for ChatGPT and Claude.
22
+
23
+ ## What to make
24
+
25
+ Read the person's words and decide the normal things yourself: style, tempo, instruments, length, title. Ask only when the request contradicts itself or you can't go on without an answer.
26
+
27
+ - **One track first.** Unless they ask for more ("an album", "five tracks", "a collection"), make one track of about two to three minutes. A first track they can hear in a few minutes beats ten tracks they wait for. After they've listened, offer more.
28
+ - **"Surprise me", or the brackets are still there.** If the request still contains the placeholder in square brackets, or says "surprise me" or nothing specific, pick a lively style yourself. Choose something with energy, like funk, house, rock, synthwave, disco or drum and bass.
29
+ - **Lively by default.** Unless they ask for something calm, the music is rhythm-led and fun: about 100 to 140 BPM, drums and bass from the first bars, a hook within the first eight bars, chords in rhythm, a build and a chorus or drop. [docs/musical-directions.md](docs/musical-directions.md) explains this, and [docs/grooves.md](docs/grooves.md) has drum and bass patterns for each style. Calm, ambient and focus music are fine when someone asks for them. Don't fall back to soft piano, slow pads and long quiet intros.
30
+ - **A collection.** When they ask for several tracks, give each its own hook, groove, key, tempo and instruments. A new seed or tempo on the same loop is not a new track. For an open request, mix styles: rock, pop, dance, funk, and maybe one focused groove.
31
+ - **Original music only.** Write new motifs and develop them. Never recreate a melody someone would recognize. An artist name in a request describes a broad sound, not a tune to copy.
32
+ - **No singing.** Soundroo is instrumental, with optional spoken words as rhythmic chops, textures or a vocoder hook. If someone wants vocals, say that Soundroo speaks words but can't sing, and offer a spoken or vocoder part.
33
+
34
+ ## Making a track, step by step
35
+
36
+ 1. **Learn the format.** Read [docs/composing.md](docs/composing.md) and [docs/musical-directions.md](docs/musical-directions.md). Run `node bin/soundroo.js catalog` for the instruments and their settings. Run `node bin/soundroo.js example` to list the example tracks by genre, then print the one closest to the request (`node bin/soundroo.js example hotwire-boogie`) and study how it opens, builds and ends. Write your own music; soundroo.com refuses copies of the examples.
37
+
38
+ 2. **Create a library.** One library per collection, under `library/`:
39
+
40
+ ```bash
41
+ node bin/soundroo.js init library/<name> --title "Collection title"
42
+ ```
43
+
44
+ Never overwrite or delete an existing library. The built-in example collection (Turn It Up) is a demonstration, not the person's music.
45
+
46
+ 3. **Write the score.** Use version 2 scores with compact `steps` and `line` patterns placed with `clips`, or write a small script in the library that builds the score with the helpers in `src/compose.js`. Plan the sections and where the energy goes before writing notes. Keep the score and any script in the library so the music stays editable.
47
+
48
+ 4. **Check and add it.**
49
+
50
+ ```bash
51
+ node bin/soundroo.js validate library/<name>/<track>.json --json
52
+ node bin/soundroo.js add library/<name>/<track>.json --library library/<name>
53
+ ```
54
+
55
+ Use `--replace` to revise a track. Earlier rendered versions stay available.
56
+
57
+ 5. **Render it.**
58
+
59
+ ```bash
60
+ node bin/soundroo.js render --all --library library/<name> --json
61
+ ```
62
+
63
+ Read the report. Fix every warning. Act on the `suggestions` too (drums that come in late, four bars that repeat unchanged for too long, sections that all sound the same, a long silent ending) unless the person asked for exactly that. Every render is mastered to the same loudness, so don't raise the master volume to make it louder. These checks find technical and arrangement problems; they can't tell you whether it sounds good. You can't hear the music, so don't claim it sounds great.
64
+
65
+ 6. **Open the player.** Start the studio in a session that keeps running, and don't stop it while the person listens:
66
+
67
+ ```bash
68
+ node bin/soundroo.js start library/<name> --json
69
+ ```
70
+
71
+ It prints a local address, usually `http://127.0.0.1:4317`. Don't force autoplay.
72
+
73
+ 7. **Tell the person.** Give them the address, the track title and one or two plain sentences about what you made (style, tempo, what to listen for). Say they can leave notes in the player or tell you what to change. Then ask the sharing question below in the same message.
74
+
75
+ ## Always offer soundroo.com
76
+
77
+ When the person has music to listen to, ask once whether to put it on soundroo.com. Use your own words, along these lines:
78
+
79
+ > Want me to put it on soundroo.com too? You'd get a link that plays in any browser, to send to friends. No account needed. Anyone with the link can listen, and others can download and remix it with credit unless you'd like it listen-only. Only say yes if you're fine sharing it.
80
+
81
+ Their yes also confirms they're fine sharing the music. Don't ask twice, and don't push if they say no.
82
+
83
+ When they say yes:
84
+
85
+ 1. Render everything you share, then preview with `node bin/soundroo.js share --library library/<name> --dry-run --json`.
86
+ 2. Share: `node bin/soundroo.js share --library library/<name> --rights-accepted --json`. Add `--access listen-only` if they wanted that. The first share downloads soundroo-cloud, a small helper that does the network part, and creates an artist page without an owner. Its music is unlisted: it plays for anyone with the link.
87
+ 3. Give them the collection link and the track links. The tracks play once soundroo.com has rendered them, usually within a minute or two.
88
+ 4. Offer to keep the page: "If you give me your email address, I'll send you a link. Confirm it and the artist page is yours, so you can list your music on Soundroo and share more than 10 tracks." If they give one, run `node bin/soundroo.js claim --email <address> --json` and tell them to open the email and press the button. It works once and expires in an hour.
89
+ 5. The share output also has a private claim link. Give it to the person and say that whoever opens it can take over the artist page, so they should keep it to themselves.
90
+ 6. Once they've confirmed the email, their music can be listed on soundroo.com. If they want that, run the share command again with `--visibility public`. The key on this computer keeps working after the claim, so sharing needs no login.
91
+
92
+ An artist page without an owner holds up to 10 tracks. If sharing fails with `claim_required`, explain that and offer the email step. Never create another guest page or log out to get around it. Throwaway email addresses (Mailinator and the like) are refused.
93
+
94
+ Never share the built-in example collections or present them as the person's music. Never present music as verified human or AI work; soundroo.com only checks that a score renders with an official engine.
95
+
96
+ ## When the person can't open the player
97
+
98
+ If you run somewhere the person's browser can't reach, like a cloud sandbox, a remote container or a server over SSH, a `127.0.0.1` address is useless to them. Say so, and offer to put the music on soundroo.com instead (same question as above), or point them to the rendered WAV file in `library/<name>/tracks/<id>/renders/` if they can download files from you. If your environment forwards ports, give the forwarded address.
99
+
100
+ ## Listening notes and revisions
101
+
102
+ The player saves notes in `tracks/<id>/feedback.json` and new requests in `requests/`. Read them when the person comes back. `node bin/soundroo.js requests --library library/<name> --json` lists open requests. After you finish one, set its status to `done` with the resulting track ids. Keep the original request and its timestamps.
103
+
104
+ When they ask for a change, change only what they asked for and keep what they liked: the melody, the groove, the sections that work. Render again; the earlier version stays in the player for comparison. Keep their `mix.json` unless they ask for a new mix. After a change to shared music, ask whether to share the update; sharing again updates the same links.
105
+
106
+ ## More music
107
+
108
+ After the first track, offer more: more tracks in the same style, a contrasting one, or a whole collection. Add new tracks to the same library so they share a player and a collection page.
109
+
110
+ ## Words and voices
111
+
112
+ A `sample` part plays short spoken phrases. Built-in phrases like `builtin:made-of-light` work right away (see `catalog`). For the person's own words, a score can name them in a speech recipe, `"sample": { "speech": { "text": "...", "voice": "af_heart" }, "effect": "vocoder", "pitch": 60 }`. That needs the optional local voice model, installed once from the Soundroo folder:
113
+
114
+ ```bash
115
+ npm install --no-save --package-lock=false kokoro-js@1.2.1 @huggingface/transformers@3.8.1
116
+ ```
117
+
118
+ The first spoken render downloads the model. Don't make an instrumental track wait for it. Effects are `dry`, `tape`, `granular`, `vocoder` and `chop`. Use speech as rhythm, texture or a robot hook. Never promise singing.
119
+
120
+ A part can't share a WAV from the library's `assets/` folder on soundroo.com. Use a speech recipe instead, or leave that part out of the shared version.
121
+
122
+ ## Remixing an open track
123
+
124
+ ```bash
125
+ node bin/soundroo.js import <track page link or short link> --library library/<name> --json
126
+ ```
127
+
128
+ This adds the exact shared score with its credit in `tracks/<id>/source.json`. Change the music before sharing the remix; an unchanged copy is refused. A shared remix links back to the original.
129
+
130
+ ## Accounts and keys
131
+
132
+ - Keys live in soundroo-cloud's own configuration, never in a library. Never print, ask for or store them.
133
+ - `node bin/soundroo.js login --start --json` returns a link and a code for the person to open; finish with `login --wait --json`. Never open a browser for them. Sharing never needs it, not even after a claim. Log in only to edit or delete shared tracks from the command line, or to share as an existing account from another computer.
134
+ - Edit or delete shared music only when the person asks for that change. Preview with `--dry-run` first.
135
+ - [docs/sharing.md](docs/sharing.md) has every sharing command, option and exit code.
136
+
137
+ ## Headless use
138
+
139
+ `src/headless.js` validates, renders and identifies scores for servers and other tools without the studio. See [docs/headless.md](docs/headless.md).
140
+
141
+ ## Development
142
+
143
+ These notes are for people changing Soundroo itself. Use small topical commits. Run `npm run check` and `npm test` after changes, and check full renders, playback in the browser, saving and exports when you touch those. Keep dependencies minimal. Soundroo never calls a model or sends music anywhere on its own; only the sharing commands use the network, and only when the person asks.
package/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vincent Schmalbach
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,169 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://www.soundroo.com">
3
+ <img src="web/favicon.svg" alt="" width="72">
4
+ </a>
5
+ </p>
2
6
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
7
+ <h1 align="center">Soundroo</h1>
8
+
9
+ <p align="center">
10
+ <b>Music made by your AI agent.</b><br>
11
+ Free and open source. Composing, rendering and playback run on your computer.
12
+ </p>
13
+
14
+ <p align="center">
15
+ <a href="https://www.soundroo.com">Website</a> &nbsp;·&nbsp;
16
+ <a href="https://www.soundroo.com/docs">Docs</a> &nbsp;·&nbsp;
17
+ <a href="https://www.soundroo.com/make/custom">Prompt builder</a> &nbsp;·&nbsp;
18
+ <a href="AGENTS.md">AGENTS.md</a>
19
+ </p>
20
+
21
+ ![The Soundroo music player with the Turn It Up example collection](docs/studio.jpg)
22
+
23
+ **Listen first:** the [Turn It Up](https://www.soundroo.com/@soundroo/collections/turn-it-up)
24
+ collection was written with this toolkit, from the
25
+ [rock and roll boogie](https://www.soundroo.com/@soundroo/hotwire-boogie) to the
26
+ [nu-disco funk](https://www.soundroo.com/@soundroo/mirrorball-shift) and
27
+ [hyperpop](https://www.soundroo.com/@soundroo/pixel-riot).
28
+
29
+ ## Make a track
30
+
31
+ > [!TIP]
32
+ > **Give your AI agent this repo and say what you'd like to hear.**
33
+ > It works with Claude Code, Codex and other coding agents that can run
34
+ > commands. ChatGPT and Claude use the Soundroo connector instead.
35
+
36
+ Copy this into your agent and put your idea where the brackets are:
37
+
38
+ ```text
39
+ Make me a track: [what it should sound like, or "surprise me"].
40
+ Use Soundroo for it. If you have Soundroo tools, use them. If you can run commands, clone https://github.com/vincentsch/soundroo, read its AGENTS.md and follow the steps. If you can't do either, send me to https://www.soundroo.com/connect
41
+ ```
42
+
43
+ A few words are enough, like "a fast funk track for a summer road trip" or
44
+ "something that sounds like an 80s arcade game". The agent sets up Soundroo,
45
+ writes the track and opens a small music player in your browser. You listen,
46
+ tell it what to change, and ask for more when you like it.
47
+
48
+ Unless you ask for something calm, the music is lively: drums and bass from
49
+ the first bars, a hook early on and a chorus or a drop.
50
+
51
+ ## How does it work?
52
+
53
+ The agent writes the music as a score, a small JSON file with the tempo,
54
+ the instruments and the notes. Drum patterns look like `X...x...X...x...`, and
55
+ melodies like `G4/.5 Bb4 C5/1`. Soundroo's engine reads the score, plays each
56
+ note, then mixes and masters the parts into a stereo track.
57
+
58
+ The engine has 32 instrument types. Grand piano, string and brass sections,
59
+ clean and overdriven electric guitars, electric bass and an acoustic drum kit
60
+ play recordings of real instruments (all public domain; see
61
+ [assets/samples/SOURCES.md](assets/samples/SOURCES.md)). Electric piano, organ,
62
+ analog and FM synthesizers, pads, synth basses, bells, marimba, a drum machine
63
+ and 8-bit chip sounds for video game music are synthesized. Short spoken phrases can become rhythmic chops, tape and grain
64
+ textures or a vocoder robot voice. The words come from
65
+ [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), a small voice model that
66
+ runs on your computer. It speaks, it doesn't sing.
67
+
68
+ An agent can't hear music, so Soundroo checks each render for clipping,
69
+ silence, squashed levels and big jumps in loudness. It can't tell whether the
70
+ music is good. Because the track is a score, the agent can change one part and
71
+ keep the others. "Keep the melody, make the drums softer" works.
72
+
73
+ None of this needs an account, an API key, music software or a graphics card,
74
+ and none of it leaves your computer. Your AI agent is a separate service with
75
+ its own terms and prices.
76
+
77
+ ## The music player
78
+
79
+ The player has generated cover art, collections, a queue, favorites and a
80
+ full-screen view that moves with the music. Open a track to see its sections,
81
+ leave notes at a moment in the track or compare versions. The mixer changes
82
+ levels, panning, mute and solo and saves the mix as a new version. Keyboard
83
+ controls and light and dark themes are built in.
84
+
85
+ You can download each track as WAV, the editable score, MIDI for other music
86
+ programs, separate instrument tracks (stems) and a small listening page that
87
+ works offline.
88
+
89
+ ## Share it on soundroo.com
90
+
91
+ When your music is ready, the agent asks whether to put it on
92
+ [soundroo.com](https://www.soundroo.com). If you say yes, it sends the score, and
93
+ soundroo.com renders the audio with the same engine. You get links that play
94
+ in any browser, to send to friends.
95
+
96
+ The first share needs no account. Soundroo makes an artist page for you with a
97
+ made-up name, and its music is unlisted. That page holds up to 10 tracks. To
98
+ keep it and list your music publicly, give the agent your email address. It
99
+ runs `node bin/soundroo.js claim --email you@example.com`, and you open the
100
+ email and press the button. [Sharing](docs/sharing.md) explains what is sent
101
+ and every option.
102
+
103
+ ## ChatGPT and Claude
104
+
105
+ Chat apps can't run this toolkit, so soundroo.com has a connector for them, a
106
+ remote MCP server. Add it once and sign in, then paste the same prompt into a
107
+ chat. You get a link to a private preview of your track.
108
+ [soundroo.com/connect](https://www.soundroo.com/connect) shows the steps.
109
+
110
+ ## Install it yourself
111
+
112
+ You need [Node.js](https://nodejs.org) 22 or newer. I develop Soundroo on
113
+ Linux, and its tests run on Linux, macOS and Windows.
114
+
115
+ ```bash
116
+ git clone https://github.com/vincentsch/soundroo.git
117
+ cd soundroo
118
+ node bin/soundroo.js start
119
+ ```
120
+
121
+ Open the address it prints, usually `http://127.0.0.1:4317`. The first start
122
+ renders **Turn It Up**, ten example tracks from rock and roll to dance-pop,
123
+ UK garage and hyperpop. Then start your agent in the `soundroo` folder and ask
124
+ for a track. It follows [AGENTS.md](AGENTS.md).
125
+
126
+ To only listen and play with the studio, you can skip the clone:
127
+ `npx soundroo start` keeps its music in a `library` folder where you run it.
128
+ Agents work best with the cloned folder, because they read AGENTS.md and the
129
+ docs there.
130
+
131
+ Useful commands:
132
+
133
+ ```bash
134
+ node bin/soundroo.js --help
135
+ node bin/soundroo.js doctor
136
+ node bin/soundroo.js catalog
137
+ node bin/soundroo.js init library/my-music --title "After Hours"
138
+ node bin/soundroo.js validate my-track.json --json
139
+ node bin/soundroo.js add my-track.json --library library/my-music
140
+ node bin/soundroo.js render --all --library library/my-music
141
+ node bin/soundroo.js start library/my-music
142
+ ```
143
+
144
+ For spoken words, install the optional voice model once:
145
+
146
+ ```bash
147
+ npm install --no-save --package-lock=false kokoro-js@1.2.1 @huggingface/transformers@3.8.1
148
+ node bin/soundroo.js voice create "We are made of light" --out library/assets/phrase.wav
149
+ ```
150
+
151
+ The first spoken render downloads the model once. Instrumental music never needs it.
152
+
153
+ ## Write music yourself
154
+
155
+ [The composing guide](docs/composing.md) has the score format and a complete
156
+ example track. [Musical directions](docs/musical-directions.md) and
157
+ [Grooves](docs/grooves.md) cover hooks, sections and drum and bass patterns
158
+ for many styles. [The headless engine](docs/headless.md) validates and renders
159
+ scores for servers and other tools.
160
+
161
+ ## Credits and license
162
+
163
+ Soundroo is MIT licensed. Copyright (c) 2026 Vincent Schmalbach. Spoken words
164
+ come from [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) through
165
+ [kokoro-js](https://github.com/hexgrad/kokoro) and
166
+ [Transformers.js](https://github.com/huggingface/transformers.js), both
167
+ optional. The sharing helper is built with
168
+ [rungrad](https://github.com/vincentsch/rungrad). Licenses of the optional
169
+ parts are in [Third party notices](THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,9 @@
1
+ # Third party notices
2
+
3
+ The synthesis foundation in `src/audio/` includes code from [Explainroo](https://github.com/vincentsch/explainroo), copyright 2026 Vincent Schmalbach, under the MIT license. Its source and license are retained in this project.
4
+
5
+ Optional speech synthesis uses [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) and [kokoro-js](https://github.com/hexgrad/kokoro). Kokoro's model and kokoro-js use Apache License 2.0. The runtime uses [Transformers.js](https://github.com/huggingface/transformers.js) under Apache License 2.0 and ONNX Runtime under MIT. Speech model and runtime files keep their upstream licenses.
6
+
7
+ The recorded instruments in `assets/samples/` come from public-domain and CC0 sample libraries: Salamander Grand Piano V3 by Alexander Holm (public domain since 2022), Big Rusty Drums and Fashionbass by Karoryfer Lecolds (CC0 1.0), FreePats Electric Guitar FSBS by the FreePats project (CC0 1.0), and VSCO 2 Community Edition by Versilian Studios and Ivy Audio (CC0 1.0). [assets/samples/SOURCES.md](assets/samples/SOURCES.md) lists every source file and how it was processed. No attribution is required, but it is gladly given.
8
+
9
+ Soundroo contains no Apple Music, GarageBand or Ableton artwork, fonts, logos or application code. Those applications informed interaction and layout choices only.