@sogni-ai/sogni-protocol 1.0.0-alpha.46 → 1.0.0-alpha.47

package/catalogs/audio-models.json

@@ -1,41 +1,7 @@
 {
-  "description": "Audio / music generation model catalog. ACE-Step 1.5 family plus MiniMax Music 3. Each entry lists per-parameter ranges so SDKs can validate user input and render sliders without round-tripping to the server. Cross-cutting audio constraints (duration, BPM, time signatures) live in the top-level `constraints` block; models with different limits carry a per-model `constraints` override.",
-  "default": "turbo",
+  "description": "Audio / music generation model catalog. MiniMax Music 3 (the default) plus the ACE-Step 1.5 family. Each entry lists per-parameter ranges so SDKs can validate user input and render sliders without round-tripping to the server. Cross-cutting audio constraints (duration, BPM, time signatures) live in the top-level `constraints` block; models with different limits carry a per-model `constraints` override.",
+  "default": "music3",
   "models": {
-    "turbo": {
-      "id": "ace_step_1.5_turbo",
-      "name": "ACE-Step 1.5 Turbo",
-      "steps": {
-        "min": 4,
-        "max": 16,
-        "default": 8
-      },
-      "shift": {
-        "min": 1,
-        "max": 5,
-        "default": 3
-      },
-      "guidance": null
-    },
-    "sft": {
-      "id": "ace_step_1.5_sft",
-      "name": "ACE-Step 1.5 SFT",
-      "steps": {
-        "min": 10,
-        "max": 200,
-        "default": 50
-      },
-      "shift": {
-        "min": 1,
-        "max": 5,
-        "default": 3
-      },
-      "guidance": {
-        "min": 1,
-        "max": 15,
-        "default": 5
-      }
-    },
     "music3": {
       "id": "minimax_music3",
       "name": "MiniMax Music 3",
@@ -71,6 +37,40 @@
         "bpm": null,
         "timeSignatures": null
       }
+    },
+    "turbo": {
+      "id": "ace_step_1.5_turbo",
+      "name": "ACE-Step 1.5 Turbo",
+      "steps": {
+        "min": 4,
+        "max": 16,
+        "default": 8
+      },
+      "shift": {
+        "min": 1,
+        "max": 5,
+        "default": 3
+      },
+      "guidance": null
+    },
+    "sft": {
+      "id": "ace_step_1.5_sft",
+      "name": "ACE-Step 1.5 SFT",
+      "steps": {
+        "min": 10,
+        "max": 200,
+        "default": 50
+      },
+      "shift": {
+        "min": 1,
+        "max": 5,
+        "default": 3
+      },
+      "guidance": {
+        "min": 1,
+        "max": 15,
+        "default": 5
+      }
     }
   },
   "constraints": {

package/manifests/generation-tools.json

@@ -355,19 +355,19 @@
             },
             "duration": {
               "type": "number",
-              "description": "Duration in seconds. Default: 30. Range: 10-600 (10 seconds to 10 minutes). Short clips: 10-30s. Standard songs: 120-300s.",
+              "description": "Duration in seconds. music3 (the default model): 10-300, default 60, and a ceiling — the song may end earlier at a musical resolution. ACE-Step turbo/sft: 10-600, default 30. Short clips: 10-30s. Standard songs: 120-300s.",
               "minimum": 10,
               "maximum": 600
             },
             "bpm": {
               "type": "number",
-              "description": "Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the tempo in the prompt instead. Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
               "minimum": 30,
               "maximum": 300
             },
             "keyscale": {
               "type": "string",
-              "description": "Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the key in the prompt instead. Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
             },
             "lyrics": {
               "type": "string",
@@ -390,7 +390,7 @@
                 4,
                 6
               ],
-              "description": "Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the time signature in the prompt instead. Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
             },
             "numberOfVariations": {
               "type": "number",

package/manifests/openai-tools.json

@@ -326,27 +326,27 @@
           "properties": {
             "prompt": {
               "type": "string",
-              "description": "Genre, mood, and style description for the music. Be specific about musical characteristics.\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing.\n\nExamples:\n- \"upbeat electronic dance music with driving bass and synth arpeggios\"\n- \"mellow jazz ballad with soft piano, brushed drums, and walking bass\"\n- \"epic orchestral soundtrack with soaring strings and powerful brass\"\n- \"lo-fi hip hop beat with vinyl crackle, muted keys, and chill vibes\"\n- \"acoustic folk song with fingerpicked guitar and warm harmonies\"\n\nInclude:\n- Genre (rock, jazz, electronic, classical, hip-hop, etc.)\n- Mood (happy, melancholic, energetic, relaxing, epic, etc.)\n- Instruments (piano, guitar, drums, synth, strings, etc.)\n- Style descriptors (driving, mellow, atmospheric, punchy, etc.)\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary ONE dimension across separate tracks. Lock in any genre/mood/instruments the user specified, vary the rest. Example: \"{lo-fi hip hop beat with muted keys|jazz piano trio with brushed drums|ambient electronic with soft pads} with warm reverb and vinyl texture\"."
+              "description": "Genre, mood, and style description for the music. Be specific about musical characteristics.\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing.\n\nExamples:\n- \"upbeat electronic dance music with driving bass and synth arpeggios\"\n- \"mellow jazz ballad with soft piano, brushed drums, and walking bass\"\n- \"epic orchestral soundtrack with soaring strings and powerful brass\"\n- \"lo-fi hip hop beat with vinyl crackle, muted keys, and chill vibes\"\n- \"acoustic folk song with fingerpicked guitar and warm harmonies\"\n\nInclude:\n- Genre (rock, jazz, electronic, classical, hip-hop, etc.)\n- Mood (happy, melancholic, energetic, relaxing, epic, etc.)\n- Instruments (piano, guitar, drums, synth, strings, etc.)\n- Style descriptors (driving, mellow, atmospheric, punchy, etc.)\n\nMODEL \"music3\": MiniMax Music 3 wants a structured caption instead of a tag list — write the prompt as one paragraph in three labeled parts: \"Global Metadata: genre, BPM, key, emotional progression across the song, production profile. Vocal Details: gender, timbre, delivery, harmonies (or: none, purely instrumental). Arrangement: primary and secondary instruments, groove, bass, percussion, textures, how sections evolve.\" The more specific, the closer the result. Fold tempo and key into this caption — music3 ignores the bpm/keyscale/timesig args.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary ONE dimension across separate tracks. This is one Sogni project with multiple jobs, so prefer it when all tracks share the same duration, BPM, key, lyrics, model, and generation parameters and only prompt text varies. Lock in any genre/mood/instruments the user specified, vary the rest. Example: \"{lo-fi hip hop beat with muted keys|jazz piano trio with brushed drums|ambient electronic with soft pads} with warm reverb and vinyl texture\"."
             },
             "duration": {
               "type": "number",
-              "description": "Duration in seconds. Default: 30. Range: 10-600 (10 seconds to 10 minutes). Short clips: 10-30s. Standard songs: 120-300s.",
+              "description": "Duration in seconds. music3 (the default model): 10-300, default 60, and a ceiling — the song may end earlier at a musical resolution. ACE-Step turbo/sft: 10-600, default 30. Short clips: 10-30s. Standard songs: 120-300s.",
               "minimum": 10,
               "maximum": 600
             },
             "bpm": {
               "type": "number",
-              "description": "Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the tempo in the prompt instead. Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
               "minimum": 30,
               "maximum": 300
             },
             "keyscale": {
               "type": "string",
-              "description": "Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the key in the prompt instead. Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
             },
             "lyrics": {
               "type": "string",
-              "description": "Song lyrics. Optional — omit for instrumental music. Format: write lyrics naturally with line breaks. The model will attempt to sing these lyrics with the generated music. Works best with clear, rhythmic phrasing that matches the BPM."
+              "description": "Song lyrics. Optional — omit for instrumental music. Format: write lyrics naturally with line breaks. The model will attempt to sing these lyrics with the generated music. Works best with clear, rhythmic phrasing that matches the BPM. For model \"music3\", structure lyrics with plain section tags on their own lines ([Intro], [Verse], [Pre-Chorus], [Chorus], [Post-Chorus], [Bridge], [Solo], [Outro]) — no modifiers inside brackets, and write enough sections to fill the requested duration since the composer ends the song when the lyric sheet runs out. For instrumental music3 tracks, pass ONLY a skeleton of those tags one per line (e.g. [Intro] [Verse] [Chorus] [Verse] [Solo] [Chorus] [Outro]) — bare instrumental pieces end early without it."
             },
             "model": {
               "type": "string",
@@ -355,7 +355,7 @@
                 "sft",
                 "music3"
               ],
-              "description": "Music model. \"turbo\" (default): ACE-Step 1.5 Turbo — fast 4-16 step drafts at half cost. \"sft\": ACE-Step 1.5 SFT — experimental, strong lyric handling, 10-200 steps, full cost. \"music3\": MiniMax Music 3 — premium autoregressive composer with the best vocals, lyric adherence and song structure; 30 steps, up to 5 minutes, ~20x turbo cost, and it treats duration as a ceiling (may end the song early at a musical resolution). Use music3 when the user asks for the best quality, realistic vocals, or full songs; otherwise default to \"turbo\"."
+              "description": "Music model. \"music3\" (default): MiniMax Music 3 — premium autoregressive composer with the best vocals, lyric adherence and song structure; 30 steps, up to 5 minutes, and it treats duration as a ceiling (may end the song early at a musical resolution). BPM/key/timesig args are ignored by music3 — fold tempo and key into the prompt instead. \"turbo\": ACE-Step 1.5 Turbo — fast 4-16 step drafts at roughly 1/20 the music3 cost; use only when the user asks for a quick, cheap, or draft track, or names ACE-Step. \"sft\": ACE-Step 1.5 SFT — experimental, strong lyric handling, 10-200 steps; use only when the user names it. Default to \"music3\" whenever the user does not ask for a draft or a specific model."
             },
             "timesig": {
               "type": "number",
@@ -365,11 +365,11 @@
                 4,
                 6
               ],
-              "description": "Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
+              "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the time signature in the prompt instead. Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
             },
             "numberOfVariations": {
               "type": "number",
-              "description": "Number of variations (1-16). Use 1 unless user requests multiple. Default: 1.",
+              "description": "Number of variations (1-16). Use with one Dynamic Prompt branch when the user requests multiple prompt-only music variations that share the same duration, BPM, key, lyrics, model, and parameters. This creates one Sogni project with multiple jobs. Default: 1.",
               "minimum": 1,
               "maximum": 16
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-protocol",
-  "version": "1.0.0-alpha.46",
+  "version": "1.0.0-alpha.47",
   "description": "Language-neutral protocol artifacts for the Sogni ecosystem: tool schemas, prompts, OpenAI tool manifests, and enums. Consumed by every Sogni SDK (TypeScript, Swift, and future Python/Kotlin/Rust SDKs) so contracts stay in lockstep across languages.",
   "keywords": [
     "sogni",

package/schemas/tools/generate_music.schema.json

@@ -9,27 +9,27 @@
   "properties": {
     "prompt": {
       "type": "string",
-      "description": "Genre, mood, and style description for the music. Be specific about musical characteristics.\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing.\n\nExamples:\n- \"upbeat electronic dance music with driving bass and synth arpeggios\"\n- \"mellow jazz ballad with soft piano, brushed drums, and walking bass\"\n- \"epic orchestral soundtrack with soaring strings and powerful brass\"\n- \"lo-fi hip hop beat with vinyl crackle, muted keys, and chill vibes\"\n- \"acoustic folk song with fingerpicked guitar and warm harmonies\"\n\nInclude:\n- Genre (rock, jazz, electronic, classical, hip-hop, etc.)\n- Mood (happy, melancholic, energetic, relaxing, epic, etc.)\n- Instruments (piano, guitar, drums, synth, strings, etc.)\n- Style descriptors (driving, mellow, atmospheric, punchy, etc.)\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary ONE dimension across separate tracks. Lock in any genre/mood/instruments the user specified, vary the rest. Example: \"{lo-fi hip hop beat with muted keys|jazz piano trio with brushed drums|ambient electronic with soft pads} with warm reverb and vinyl texture\"."
+      "description": "Genre, mood, and style description for the music. Be specific about musical characteristics.\n\nLITERAL PROMPT OVERRIDE: If the user explicitly says not to modify the prompt, or to use it exactly/verbatim/as-is, copy the identified prompt text verbatim instead of applying these construction rules unless a hard requirement is missing.\n\nExamples:\n- \"upbeat electronic dance music with driving bass and synth arpeggios\"\n- \"mellow jazz ballad with soft piano, brushed drums, and walking bass\"\n- \"epic orchestral soundtrack with soaring strings and powerful brass\"\n- \"lo-fi hip hop beat with vinyl crackle, muted keys, and chill vibes\"\n- \"acoustic folk song with fingerpicked guitar and warm harmonies\"\n\nInclude:\n- Genre (rock, jazz, electronic, classical, hip-hop, etc.)\n- Mood (happy, melancholic, energetic, relaxing, epic, etc.)\n- Instruments (piano, guitar, drums, synth, strings, etc.)\n- Style descriptors (driving, mellow, atmospheric, punchy, etc.)\n\nMODEL \"music3\": MiniMax Music 3 wants a structured caption instead of a tag list — write the prompt as one paragraph in three labeled parts: \"Global Metadata: genre, BPM, key, emotional progression across the song, production profile. Vocal Details: gender, timbre, delivery, harmonies (or: none, purely instrumental). Arrangement: primary and secondary instruments, groove, bass, percussion, textures, how sections evolve.\" The more specific, the closer the result. Fold tempo and key into this caption — music3 ignores the bpm/keyscale/timesig args.\n\nBATCH VARIATIONS: When numberOfVariations > 1, use Dynamic Prompt syntax to vary ONE dimension across separate tracks. This is one Sogni project with multiple jobs, so prefer it when all tracks share the same duration, BPM, key, lyrics, model, and generation parameters and only prompt text varies. Lock in any genre/mood/instruments the user specified, vary the rest. Example: \"{lo-fi hip hop beat with muted keys|jazz piano trio with brushed drums|ambient electronic with soft pads} with warm reverb and vinyl texture\"."
     },
     "duration": {
       "type": "number",
-      "description": "Duration in seconds. Default: 30. Range: 10-600 (10 seconds to 10 minutes). Short clips: 10-30s. Standard songs: 120-300s.",
+      "description": "Duration in seconds. music3 (the default model): 10-300, default 60, and a ceiling — the song may end earlier at a musical resolution. ACE-Step turbo/sft: 10-600, default 30. Short clips: 10-30s. Standard songs: 120-300s.",
       "minimum": 10,
       "maximum": 600
     },
     "bpm": {
       "type": "number",
-      "description": "Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
+      "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the tempo in the prompt instead. Beats per minute / tempo. Default: 120. Range: 30-300. Slow ballad: 60-80. Mid-tempo: 90-120. Upbeat: 120-140. Fast dance: 140-180. Very fast: 180+.",
       "minimum": 30,
       "maximum": 300
     },
     "keyscale": {
       "type": "string",
-      "description": "Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
+      "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the key in the prompt instead. Musical key and scale. E.g., \"C major\", \"A minor\", \"F# minor\", \"Bb major\". Default: \"C major\". Only set when the user specifies a key or when a particular mood calls for it (minor keys for sad/dark, major for happy/bright)."
     },
     "lyrics": {
       "type": "string",
-      "description": "Song lyrics. Optional — omit for instrumental music. Format: write lyrics naturally with line breaks. The model will attempt to sing these lyrics with the generated music. Works best with clear, rhythmic phrasing that matches the BPM."
+      "description": "Song lyrics. Optional — omit for instrumental music. Format: write lyrics naturally with line breaks. The model will attempt to sing these lyrics with the generated music. Works best with clear, rhythmic phrasing that matches the BPM. For model \"music3\", structure lyrics with plain section tags on their own lines ([Intro], [Verse], [Pre-Chorus], [Chorus], [Post-Chorus], [Bridge], [Solo], [Outro]) — no modifiers inside brackets, and write enough sections to fill the requested duration since the composer ends the song when the lyric sheet runs out. For instrumental music3 tracks, pass ONLY a skeleton of those tags one per line (e.g. [Intro] [Verse] [Chorus] [Verse] [Solo] [Chorus] [Outro]) — bare instrumental pieces end early without it."
     },
     "model": {
       "type": "string",
@@ -38,7 +38,7 @@
         "sft",
         "music3"
       ],
-      "description": "Music model. \"turbo\" (default): ACE-Step 1.5 Turbo — fast 4-16 step drafts at half cost. \"sft\": ACE-Step 1.5 SFT — experimental, strong lyric handling, 10-200 steps, full cost. \"music3\": MiniMax Music 3 — premium autoregressive composer with the best vocals, lyric adherence and song structure; 30 steps, up to 5 minutes, ~20x turbo cost, and it treats duration as a ceiling (may end the song early at a musical resolution). Use music3 when the user asks for the best quality, realistic vocals, or full songs; otherwise default to \"turbo\"."
+      "description": "Music model. \"music3\" (default): MiniMax Music 3 — premium autoregressive composer with the best vocals, lyric adherence and song structure; 30 steps, up to 5 minutes, and it treats duration as a ceiling (may end the song early at a musical resolution). BPM/key/timesig args are ignored by music3 — fold tempo and key into the prompt instead. \"turbo\": ACE-Step 1.5 Turbo — fast 4-16 step drafts at roughly 1/20 the music3 cost; use only when the user asks for a quick, cheap, or draft track, or names ACE-Step. \"sft\": ACE-Step 1.5 SFT — experimental, strong lyric handling, 10-200 steps; use only when the user names it. Default to \"music3\" whenever the user does not ask for a draft or a specific model."
     },
     "timesig": {
       "type": "number",
@@ -48,11 +48,11 @@
         4,
         6
       ],
-      "description": "Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
+      "description": "ACE-Step (turbo, sft) only — music3 does not use it; for music3 put the time signature in the prompt instead. Time signature (beats per measure). 4 = 4/4 time (default, most common). 3 = 3/4 time (waltz). 2 = 2/4 time (march). 6 = 6/8 time (compound). Default: 4."
     },
     "numberOfVariations": {
       "type": "number",
-      "description": "Number of variations (1-16). Use 1 unless user requests multiple. Default: 1.",
+      "description": "Number of variations (1-16). Use with one Dynamic Prompt branch when the user requests multiple prompt-only music variations that share the same duration, BPM, key, lyrics, model, and parameters. This creates one Sogni project with multiple jobs. Default: 1.",
       "minimum": 1,
       "maximum": 16
     }

package/version.json

@@ -1,4 +1,4 @@
 {
-  "protocolVersion": "7.5.0",
+  "protocolVersion": "7.6.0",
   "description": "Sogni protocol artifact version. SDKs may refuse to operate against a protocolVersion they were not built for. Bump the major when removing or renaming any schema / enum / manifest field; bump the minor when adding new optional fields or new tools; bump the patch for description / prose changes only."
 }