sonilo-cli 0.12.0__tar.gz → 0.14.0__tar.gz

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sonilo-cli
-Version: 0.12.0
+Version: 0.14.0
 Summary: Command-line interface for the Sonilo API: generate music and sound effects from text or video
 Project-URL: Repository, https://github.com/sonilo-ai/sonilo-python
 Author: Sonilo AI
@@ -8,7 +8,7 @@ License-Expression: MIT
 License-File: LICENSE
 Keywords: ai,cli,music,sfx,sonilo,text-to-music,video-to-music
 Requires-Python: >=3.9
-Requires-Dist: sonilo<0.14,>=0.13.0
+Requires-Dist: sonilo<0.16,>=0.15.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -98,6 +98,8 @@ production sign-in coexist without overwriting each other.
     sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
     # ducks the existing music bed under the voice; a video voice comes back
     # as a new .mp4 with the ducked mix muxed in
+    sonilo video-analysis --video clip.mp4 --variants 2
+    # prints a creative brief as JSON; generates nothing
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
     sonilo tasks get <task-id>
@@ -106,8 +108,8 @@ production sign-in coexist without overwriting each other.
 ### Notes
 
 - `text-to-music` / `video-to-music` stream a short `.m4a` by default. `--format wav`,
-  `--preserve-speech`, `--variants` above 1, and the legacy alias `--isolate-vocals` each switch
-  to the async submit-and-poll path.
+  `--preserve-speech`, `--variants` above 1, `--stems`, and the legacy alias `--isolate-vocals`
+  each switch to the async submit-and-poll path.
 - `text-to-sfx` / `video-to-sfx` are always async; `--format` accepts `wav|mp3|aac|flac`.
 - Output defaults to `./output.<ext>`; override with `--output`.
 
@@ -171,6 +173,27 @@ not sent at all and the API's own 0.5 default applies; `--prompt-influence 0` is
 
     sonilo video-to-music --video clip.mp4 --prompt "tense synths" --prompt-influence 0.8
 
+### Music stems
+
+`--stems` on `text-to-music` and `video-to-music` also splits the generated music into four
+stems — drums, bass, vocals, other — saved next to the main output with the stem name spliced
+before the extension (`take.m4a` → `take.drums.m4a`, and per variant with `--variants` above 1:
+`take.0.drums.m4a`). It is free of charge, and forces the async path. On `video-to-music` it
+splits the *generated* music, never the video's own audio.
+
+    sonilo text-to-music --prompt "warm lo-fi piano" --duration 60 --stems --output take.m4a
+    # writes take.m4a, take.drums.m4a, take.bass.m4a, take.vocals.m4a, take.other.m4a
+
+- Separation runs **after** generation and typically adds 2-6 minutes to the wait; the CLI
+  waits up to 2400 seconds on these runs (covering the separation service's own 30-minute
+  ceiling, the way dubbing's `--timeout` covers its backend's). If the wait still times out,
+  the task keeps running server-side — resume it with `sonilo tasks wait <task-id>`.
+- Separation can also come up short without failing the run: streams that did not separate are
+  reported on stderr (the API's `stems_error`), while the stems that did come back are still
+  saved — a partial result is not an error exit, and the main output is always written.
+- Not the same flag as `--stem` on the sound commands, which saves layers those endpoints
+  already return; `--stems` *requests* a separation the API would not otherwise run.
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -241,6 +264,23 @@ call instead.)
   there, so the CLI rejects a local video file up front rather than let it be mishandled silently.
 - Each input is capped at 360 seconds server-side.
 
+### Video analysis
+
+`video-analysis` analyzes a video and prints a **creative brief** for scoring it. It is the one
+command that produces no media file — nothing is generated:
+
+    sonilo video-analysis --video clip.mp4 --prompt "focus on the chase" --variants 2
+
+- The brief goes to **stdout as JSON** so it can be piped into another tool: `segments` (a
+  time-aligned section plan) and `variations` (one ready-to-use generation prompt each). Pass
+  `--output brief.json` to write it to a file instead.
+- `--variants` is 1-5 (default 1) and is **billed per brief**.
+- Source videos may be at most 600 seconds long, and billing has a 10-second floor.
+- Feed a variation's prompt straight into the next command:
+
+      sonilo video-analysis --video clip.mp4 --output brief.json
+      sonilo video-to-music --video clip.mp4 --prompt "$(jq -r '.variations[0].prompt' brief.json)"
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:
@@ -267,7 +307,7 @@ required:
 
 | Free runs | Endpoints |
 | --- | --- |
-| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 2 each | text-to-music, text-to-sfx, audio-ducking, video-analysis |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
 | 0 | dubbing |
 

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/README.md

@@ -82,6 +82,8 @@ production sign-in coexist without overwriting each other.
     sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
     # ducks the existing music bed under the voice; a video voice comes back
     # as a new .mp4 with the ducked mix muxed in
+    sonilo video-analysis --video clip.mp4 --variants 2
+    # prints a creative brief as JSON; generates nothing
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
     sonilo tasks get <task-id>
@@ -90,8 +92,8 @@ production sign-in coexist without overwriting each other.
 ### Notes
 
 - `text-to-music` / `video-to-music` stream a short `.m4a` by default. `--format wav`,
-  `--preserve-speech`, `--variants` above 1, and the legacy alias `--isolate-vocals` each switch
-  to the async submit-and-poll path.
+  `--preserve-speech`, `--variants` above 1, `--stems`, and the legacy alias `--isolate-vocals`
+  each switch to the async submit-and-poll path.
 - `text-to-sfx` / `video-to-sfx` are always async; `--format` accepts `wav|mp3|aac|flac`.
 - Output defaults to `./output.<ext>`; override with `--output`.
 
@@ -155,6 +157,27 @@ not sent at all and the API's own 0.5 default applies; `--prompt-influence 0` is
 
     sonilo video-to-music --video clip.mp4 --prompt "tense synths" --prompt-influence 0.8
 
+### Music stems
+
+`--stems` on `text-to-music` and `video-to-music` also splits the generated music into four
+stems — drums, bass, vocals, other — saved next to the main output with the stem name spliced
+before the extension (`take.m4a` → `take.drums.m4a`, and per variant with `--variants` above 1:
+`take.0.drums.m4a`). It is free of charge, and forces the async path. On `video-to-music` it
+splits the *generated* music, never the video's own audio.
+
+    sonilo text-to-music --prompt "warm lo-fi piano" --duration 60 --stems --output take.m4a
+    # writes take.m4a, take.drums.m4a, take.bass.m4a, take.vocals.m4a, take.other.m4a
+
+- Separation runs **after** generation and typically adds 2-6 minutes to the wait; the CLI
+  waits up to 2400 seconds on these runs (covering the separation service's own 30-minute
+  ceiling, the way dubbing's `--timeout` covers its backend's). If the wait still times out,
+  the task keeps running server-side — resume it with `sonilo tasks wait <task-id>`.
+- Separation can also come up short without failing the run: streams that did not separate are
+  reported on stderr (the API's `stems_error`), while the stems that did come back are still
+  saved — a partial result is not an error exit, and the main output is always written.
+- Not the same flag as `--stem` on the sound commands, which saves layers those endpoints
+  already return; `--stems` *requests* a separation the API would not otherwise run.
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -225,6 +248,23 @@ call instead.)
   there, so the CLI rejects a local video file up front rather than let it be mishandled silently.
 - Each input is capped at 360 seconds server-side.
 
+### Video analysis
+
+`video-analysis` analyzes a video and prints a **creative brief** for scoring it. It is the one
+command that produces no media file — nothing is generated:
+
+    sonilo video-analysis --video clip.mp4 --prompt "focus on the chase" --variants 2
+
+- The brief goes to **stdout as JSON** so it can be piped into another tool: `segments` (a
+  time-aligned section plan) and `variations` (one ready-to-use generation prompt each). Pass
+  `--output brief.json` to write it to a file instead.
+- `--variants` is 1-5 (default 1) and is **billed per brief**.
+- Source videos may be at most 600 seconds long, and billing has a 10-second floor.
+- Feed a variation's prompt straight into the next command:
+
+      sonilo video-analysis --video clip.mp4 --output brief.json
+      sonilo video-to-music --video clip.mp4 --prompt "$(jq -r '.variations[0].prompt' brief.json)"
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:
@@ -251,7 +291,7 @@ required:
 
 | Free runs | Endpoints |
 | --- | --- |
-| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 2 each | text-to-music, text-to-sfx, audio-ducking, video-analysis |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
 | 0 | dubbing |
 

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.12.0"
+version = "0.14.0"
 description = "Command-line interface for the Sonilo API: generate music and sound effects from text or video"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.9"
 authors = [{ name = "Sonilo AI" }]
-dependencies = ["sonilo>=0.13.0,<0.14"]
+dependencies = ["sonilo>=0.15.0,<0.16"]
 keywords = ["sonilo", "cli", "music", "sfx", "text-to-music", "video-to-music", "ai"]
 
 [project.urls]

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/src/sonilo_cli/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.12.0"
+__version__ = "0.14.0"
 
 __all__ = ["__version__"]

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/src/sonilo_cli/__main__.py

@@ -11,6 +11,7 @@ from urllib.parse import urlparse
 
 from sonilo import Sonilo
 from sonilo.errors import APIError, SoniloError
+from sonilo.resources.tasks import DEFAULT_WAIT_TIMEOUT
 
 from sonilo_cli import __version__, credentials
 from sonilo_cli.login import LoginError, cmd_login, cmd_logout, cmd_whoami
@@ -291,10 +292,53 @@ def _save_music_variants(result: Any, out: str) -> None:
         _wrote(path, path.stat().st_size)
 
 
+# Matched to the separation service's own ceiling on top of the generation
+# wait: separation runs after generation, typically adds 2-6 minutes and gives
+# up after 30 (1800s), so the SDK's generic DEFAULT_WAIT_TIMEOUT of 600s would
+# abandon a stems task the user has already been charged the generation for —
+# the same reasoning as DUBBING_WAIT_TIMEOUT below.
+STEMS_WAIT_TIMEOUT = 2400.0
+
+_MUSIC_STEMS = ("drums", "bass", "vocals", "other")
+
+
+def _save_music_stems(result: Any, out: str) -> None:
+    """Save the separated stems of an async music result next to `out`,
+    `take.m4a` becoming `take.drums.m4a` etc. — the same transform --stem
+    applies on the sound commands. With several variants the stem files pick
+    up the entry's own stream_index (`take.0.drums.m4a`), matching the
+    indexed file _save_music_variants wrote for that stream.
+
+    Entries are matched by stream_index, never list position — the list can
+    be shorter than `audio`. `stems_error` is a warning, not a failure, and
+    never suppresses the partial stems that did come back: the music itself
+    succeeded and separation is free, so incomplete stems must not turn the
+    whole command into an error exit."""
+    if result.stems_error:
+        sys.stderr.write(f"sonilo: stem separation incomplete: {result.stems_error}\n")
+    entries = result.stems or []
+    if not entries:
+        if not result.stems_error:
+            sys.stderr.write("sonilo: task succeeded but returned no stems\n")
+        return
+    multi = len(result.audio or []) > 1
+    for entry in entries:
+        base = _variant_path(out, entry.stream_index) if multi else out
+        for stem in _MUSIC_STEMS:
+            media = getattr(entry, stem, None)
+            if media is None:
+                continue
+            path = result.save_stem(
+                _stem_path(base, stem, media),
+                which=stem, stream_index=entry.stream_index,
+            )
+            _wrote(path, path.stat().st_size)
+
+
 def cmd_text_to_music(client: Sonilo, args: argparse.Namespace) -> None:
     fmt = args.format
     multi = args.variants is not None and args.variants > 1
-    use_async = args.use_async or fmt != "m4a" or multi
+    use_async = args.use_async or fmt != "m4a" or multi or args.stems
     out = _music_output(args, fmt)
     segments = _segments(args)
     if use_async:
@@ -304,8 +348,12 @@ def cmd_text_to_music(client: Sonilo, args: argparse.Namespace) -> None:
             segments=segments,
             output_format=fmt if fmt != "m4a" else None,
             variants_num=args.variants,
+            stems=True if args.stems else None,
+            timeout=STEMS_WAIT_TIMEOUT if args.stems else DEFAULT_WAIT_TIMEOUT,
         )
         _save_music_variants(result, out)
+        if args.stems:
+            _save_music_stems(result, out)
     else:
         track = client.text_to_music.generate(
             prompt=args.prompt, duration=args.duration, segments=segments
@@ -318,7 +366,8 @@ def cmd_video_to_music(client: Sonilo, args: argparse.Namespace) -> None:
     fmt = args.format
     multi = args.variants is not None and args.variants > 1
     use_async = (
-        args.use_async or fmt != "m4a" or args.isolate_vocals or args.preserve_speech or multi
+        args.use_async or fmt != "m4a" or args.isolate_vocals or args.preserve_speech
+        or multi or args.stems
     )
     out = _music_output(args, fmt)
     segments = _segments(args)
@@ -333,8 +382,12 @@ def cmd_video_to_music(client: Sonilo, args: argparse.Namespace) -> None:
             output_format=fmt if fmt != "m4a" else None,
             variants_num=args.variants,
             prompt_influence=args.prompt_influence,
+            stems=True if args.stems else None,
+            timeout=STEMS_WAIT_TIMEOUT if args.stems else DEFAULT_WAIT_TIMEOUT,
         )
         _save_music_variants(result, out)
+        if args.stems:
+            _save_music_stems(result, out)
     else:
         # prompt_influence rides the streaming path too — it is a generation
         # parameter, not a finalize-time one, so it never forces async.
@@ -510,6 +563,51 @@ def cmd_audio_ducking(client: Sonilo, args: argparse.Namespace) -> None:
     _wrote(path, path.stat().st_size)
 
 
+def _analysis_payload(result: Any) -> dict:
+    """Flatten a VideoAnalysisResult back into the API's own envelope shape.
+
+    Deliberately re-emits the wire format rather than dumping the dataclass:
+    this output is meant to be piped into another tool (or read by an agent),
+    and it should look identical to what GET /v1/tasks returned. None-valued
+    accounting fields are dropped so a brief stays readable.
+    """
+    payload: dict = {
+        "task_id": result.task_id,
+        "status": result.status,
+        "segments": [
+            {"start": s.start, "end": s.end, "label": s.label, "prompt": s.prompt}
+            for s in result.segments
+        ],
+        "variations": [{"prompt": v.prompt} for v in result.variations],
+    }
+    for key in ("variants_num", "duration_seconds", "cost"):
+        value = getattr(result, key, None)
+        if value is not None:
+            payload[key] = value
+    return payload
+
+
+def cmd_video_analysis(client: Sonilo, args: argparse.Namespace) -> None:
+    """video-analysis is the one command that produces no media file. The
+    brief goes to stdout so it can be piped straight into the next tool;
+    --output is the opt-in for keeping a copy on disk."""
+    result = client.video_analysis.analyze(
+        video=args.video, video_url=args.video_url,
+        prompt=args.prompt, variants_num=args.variants,
+        timeout=args.timeout,
+    )
+    if not result.variations:
+        _fail("task succeeded but returned no creative brief")
+    payload = _analysis_payload(result)
+    if args.output is None:
+        _print_json(payload)
+        return
+    path = Path(args.output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+    _wrote(path, path.stat().st_size)
+
+
 # Matched to the dubbing backend's own ceiling: it polls its pipeline for up
 # to 7200s (2 hours), so anything shorter abandons a job the user has already
 # been charged for. The SDK's generic DEFAULT_WAIT_TIMEOUT of 600s is far too
@@ -630,6 +728,21 @@ def _add_variants(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _add_stems(parser: argparse.ArgumentParser) -> None:
+    # Only the two music-generation commands take this — the API accepts it
+    # nowhere else. Not to be confused with --stem on the sound commands,
+    # which saves layers those endpoints already return; --stems *requests*
+    # a separation the API would not otherwise run.
+    parser.add_argument(
+        "--stems", action="store_true",
+        help="Also split the generated music into drums/bass/vocals/other "
+             "stems, saved next to the output (output.drums.m4a, ...). Free "
+             "of charge. Forces async, and separation typically adds 2-6 "
+             "minutes to the wait. Streams that fail to separate are "
+             "reported on stderr; the rest are still saved.",
+    )
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = _Parser(prog="sonilo", description="Command-line interface for the Sonilo API")
     parser.add_argument("--version", action="version", version=__version__)
@@ -683,6 +796,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_t2m.add_argument("--async", dest="use_async", action="store_true",
                        help="Submit and poll instead of streaming.")
     _add_variants(p_t2m)
+    _add_stems(p_t2m)
     p_t2m.set_defaults(func=cmd_text_to_music)
 
     p_v2m = sub.add_parser("video-to-music", help="Generate music matched to a video")
@@ -705,6 +819,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Submit and poll instead of streaming.")
     _add_variants(p_v2m)
     _add_prompt_influence(p_v2m)
+    _add_stems(p_v2m)
     p_v2m.set_defaults(func=cmd_video_to_music)
 
     p_t2s = sub.add_parser("text-to-sfx", help="Generate a sound effect from a text prompt")
@@ -858,6 +973,32 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_duck.set_defaults(func=cmd_audio_ducking)
 
+    p_va = sub.add_parser(
+        "video-analysis",
+        help="Analyze a video and print a creative brief for scoring it",
+    )
+    _add_global(p_va)
+    _add_video_source(p_va)
+    p_va.add_argument(
+        "--prompt", default=None,
+        help="Optional guidance for the analysis, e.g. 'focus on the chase'.",
+    )
+    p_va.add_argument(
+        "--variants", type=int, default=None,
+        help="How many independent briefs to author for the same video (1-5). "
+             "Billed per brief. Default: 1",
+    )
+    p_va.add_argument(
+        "--output", default=None,
+        help="Write the brief to this .json file instead of printing it to stdout.",
+    )
+    p_va.add_argument(
+        "--timeout", type=float, default=600.0,
+        help="Give up waiting after this many seconds. Default: 600. A timed-out "
+             "task may still finish — resume it with `sonilo tasks get <task-id>`.",
+    )
+    p_va.set_defaults(func=cmd_video_analysis)
+
     p_dub = sub.add_parser("dubbing", help="Dub a video into other languages")
     _add_global(p_dub)
     _add_video_source(p_dub)

{sonilo_cli-0.12.0 → sonilo_cli-0.14.0}/tests/test_cli.py

@@ -1346,3 +1346,264 @@ def test_empty_env_var_falls_through_to_the_credential(monkeypatch):
     )
     main(["account"])
     assert route.calls.last.request.headers["authorization"] == "Bearer sk-stored"
+
+
+ANALYSIS_ACK = {"task_id": "va1", "status": "processing"}
+ANALYSIS_BODY = {
+    "task_id": "va1",
+    "type": "video_analysis",
+    "status": "succeeded",
+    "variants_num": 2,
+    "segments": [
+        {"start": 0, "end": 12, "label": "intro", "prompt": "sparse piano"},
+    ],
+    "variations": [
+        {"prompt": "cinematic strings, 90bpm"},
+        {"prompt": "lo-fi hip hop, warm keys"},
+    ],
+    "duration_seconds": 30.0,
+    "cost": 0.24,
+}
+
+
+def _mock_analysis():
+    respx.post(f"{BASE}/v1/video-analysis").mock(
+        return_value=httpx.Response(202, json=ANALYSIS_ACK)
+    )
+    respx.get(f"{BASE}/v1/tasks/va1").mock(
+        return_value=httpx.Response(200, json=ANALYSIS_BODY)
+    )
+
+
+@respx.mock
+def test_video_analysis_prints_the_brief_as_json(capsys):
+    """The result is a brief, not a file: it goes to stdout so it can be
+    piped, and nothing is written to disk unless --output says so."""
+    _mock_analysis()
+    run(["video-analysis", "--video-url", "https://x/v.mp4"])
+    out = json.loads(capsys.readouterr().out)
+    assert out["task_id"] == "va1"
+    assert out["segments"] == [
+        {"start": 0, "end": 12, "label": "intro", "prompt": "sparse piano"}
+    ]
+    assert [v["prompt"] for v in out["variations"]] == [
+        "cinematic strings, 90bpm",
+        "lo-fi hip hop, warm keys",
+    ]
+
+
+@respx.mock
+def test_video_analysis_sends_prompt_and_variants():
+    _mock_analysis()
+    route = respx.routes[0]
+    run([
+        "video-analysis",
+        "--video-url", "https://x/v.mp4",
+        "--prompt", "focus on the chase",
+        "--variants", "2",
+    ])
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "prompt=focus on the chase" in body
+    assert "variants_num=2" in body
+
+
+@respx.mock
+def test_video_analysis_omits_unset_optionals():
+    _mock_analysis()
+    route = respx.routes[0]
+    run(["video-analysis", "--video-url", "https://x/v.mp4"])
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "prompt" not in body
+    assert "variants_num" not in body
+
+
+@respx.mock
+def test_video_analysis_output_writes_the_brief_to_a_file(tmp_path, capsys):
+    _mock_analysis()
+    out = tmp_path / "brief.json"
+    run(["video-analysis", "--video-url", "https://x/v.mp4", "--output", str(out)])
+    written = json.loads(out.read_text())
+    assert written["variations"][0]["prompt"] == "cinematic strings, 90bpm"
+    # With --output the brief goes to the file, not to stdout.
+    assert "Wrote" in capsys.readouterr().out
+
+
+def test_video_analysis_requires_a_video_source(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--api-key", "sk-test", "video-analysis"])
+    assert exc.value.code == 1
+    # Asserted on the message, not just the exit code: an unknown command
+    # also exits 1, so the code alone would pass before the command exists.
+    assert "--video" in capsys.readouterr().err
+
+
+# ---------- --stems (music stem separation) ----------
+
+
+def _stems_entry(i, base="https://r2.example.com"):
+    return {
+        "stream_index": i,
+        "drums": {"url": f"{base}/s{i}.drums.m4a"},
+        "bass": {"url": f"{base}/s{i}.bass.m4a"},
+        "vocals": {"url": f"{base}/s{i}.vocals.m4a"},
+        "other": {"url": f"{base}/s{i}.other.m4a"},
+    }
+
+
+def _mock_stem_downloads(*indices):
+    for i in indices:
+        for stem in ("drums", "bass", "vocals", "other"):
+            respx.get(f"https://r2.example.com/s{i}.{stem}.m4a").mock(
+                return_value=httpx.Response(200, content=f"{stem}{i}".encode())
+            )
+
+
+@respx.mock
+def test_text_to_music_stems_forces_async_and_saves_stem_files(tmp_path, capsys):
+    submit = respx.post(f"{BASE}/v1/text-to-music").mock(
+        return_value=httpx.Response(200, json={"task_id": "ts1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/ts1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "ts1", "type": "text_to_music", "status": "succeeded",
+            "audio": [{"stream_index": 0, "url": "https://r2.example.com/ts1.m4a"}],
+            "stems": [_stems_entry(0)],
+        })
+    )
+    respx.get("https://r2.example.com/ts1.m4a").mock(
+        return_value=httpx.Response(200, content=b"MIX")
+    )
+    _mock_stem_downloads(0)
+    out = tmp_path / "take.m4a"
+    run(["text-to-music", "--prompt", "lofi", "--duration", "10",
+         "--stems", "--output", str(out)])
+    # --stems must force the async submit-and-poll path, same as --format wav.
+    assert submit.called
+    body = submit.calls.last.request.content.decode()
+    assert "stems=true" in body
+    assert out.read_bytes() == b"MIX"
+    for stem in ("drums", "bass", "vocals", "other"):
+        assert (tmp_path / f"take.{stem}.m4a").read_bytes() == f"{stem}0".encode()
+    # A clean separation warns about nothing.
+    assert capsys.readouterr().err == ""
+
+
+@respx.mock
+def test_text_to_music_omits_stems_when_flag_unset(tmp_path):
+    # Async for another reason (--format wav): the field must stay off the
+    # wire entirely rather than pinning an explicit false.
+    submit = respx.post(f"{BASE}/v1/text-to-music").mock(
+        return_value=httpx.Response(200, json={"task_id": "tn1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/tn1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "tn1", "type": "text_to_music", "status": "succeeded",
+            "audio": [{"stream_index": 0, "url": "https://r2.example.com/tn1.wav"}],
+        })
+    )
+    respx.get("https://r2.example.com/tn1.wav").mock(
+        return_value=httpx.Response(200, content=b"RIF")
+    )
+    run(["text-to-music", "--prompt", "lofi", "--duration", "10",
+         "--format", "wav", "--output", str(tmp_path / "t.wav")])
+    assert b"stems" not in submit.calls.last.request.content
+
+
+@respx.mock
+def test_video_to_music_stems_partial_failure_warns_but_saves_the_rest(tmp_path, capsys):
+    """stems_error accompanies a PARTIAL stems list: the warning goes to
+    stderr, the stems that DID come back are still written (named by their
+    own stream_index, not list position), and the run is not an error —
+    the music itself succeeded and separation is free."""
+    submit = respx.post(f"{BASE}/v1/video-to-music").mock(
+        return_value=httpx.Response(200, json={"task_id": "vs1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/vs1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "vs1", "type": "video_to_music", "status": "succeeded",
+            "variants_num": 2,
+            "audio": [
+                {"stream_index": 0, "url": "https://r2.example.com/vs1.0.m4a"},
+                {"stream_index": 1, "url": "https://r2.example.com/vs1.1.m4a"},
+            ],
+            # Only stream 1 separated; positional lookup would misfile these.
+            "stems": [_stems_entry(1)],
+            "stems_error": "stream 0 failed to separate",
+        })
+    )
+    respx.get("https://r2.example.com/vs1.0.m4a").mock(
+        return_value=httpx.Response(200, content=b"A0")
+    )
+    respx.get("https://r2.example.com/vs1.1.m4a").mock(
+        return_value=httpx.Response(200, content=b"A1")
+    )
+    _mock_stem_downloads(1)
+    out = tmp_path / "take.m4a"
+    run(["video-to-music", "--video-url", "http://x/y.mp4",
+         "--variants", "2", "--stems", "--output", str(out)])
+    assert "stems=true" in submit.calls.last.request.content.decode()
+    assert (tmp_path / "take.0.m4a").read_bytes() == b"A0"
+    assert (tmp_path / "take.1.m4a").read_bytes() == b"A1"
+    # Stem files carry stream 1's index; stream 0 has none.
+    assert (tmp_path / "take.1.drums.m4a").read_bytes() == b"drums1"
+    assert (tmp_path / "take.1.other.m4a").read_bytes() == b"other1"
+    assert not (tmp_path / "take.0.drums.m4a").exists()
+    err = capsys.readouterr().err
+    assert "stream 0 failed to separate" in err
+
+
+def test_stems_passes_the_long_timeout_and_tri_state(tmp_path, monkeypatch):
+    """--stems switches the wait to STEMS_WAIT_TIMEOUT — the SDK's 600s
+    default would abandon a separation that legitimately runs up to 30
+    minutes past generation — while a stems-less async run keeps the
+    default and sends no stems field at all."""
+    from sonilo.resources.text_to_music import TextToMusic
+    from sonilo.types import MusicAudioMedia, MusicResult
+
+    calls = []
+
+    def fake_generate_async(self, **kwargs):
+        calls.append(kwargs)
+        return MusicResult(
+            task_id="t", status="succeeded",
+            audio=[MusicAudioMedia(stream_index=0, url="https://r2.example.com/t.m4a")],
+            stems=kwargs.get("stems") and [],
+            stems_error="separation skipped" if kwargs.get("stems") else None,
+        )
+
+    monkeypatch.setattr(TextToMusic, "generate_async", fake_generate_async)
+    with respx.mock:
+        respx.get("https://r2.example.com/t.m4a").mock(
+            return_value=httpx.Response(200, content=b"A")
+        )
+        run(["text-to-music", "--prompt", "x", "--duration", "10",
+             "--stems", "--output", str(tmp_path / "a.m4a")])
+        run(["text-to-music", "--prompt", "x", "--duration", "10",
+             "--format", "wav", "--output", str(tmp_path / "b.wav")])
+    assert calls[0]["stems"] is True
+    assert calls[0]["timeout"] == 2400.0
+    assert calls[1]["stems"] is None
+    assert calls[1]["timeout"] == 600.0
+
+
+def test_stems_warns_when_none_come_back(tmp_path, monkeypatch, capsys):
+    from sonilo.resources.text_to_music import TextToMusic
+    from sonilo.types import MusicAudioMedia, MusicResult
+
+    def fake_generate_async(self, **kwargs):
+        return MusicResult(
+            task_id="t", status="succeeded",
+            audio=[MusicAudioMedia(stream_index=0, url="https://r2.example.com/t.m4a")],
+        )
+
+    monkeypatch.setattr(TextToMusic, "generate_async", fake_generate_async)
+    with respx.mock:
+        respx.get("https://r2.example.com/t.m4a").mock(
+            return_value=httpx.Response(200, content=b"A")
+        )
+        run(["text-to-music", "--prompt", "x", "--duration", "10",
+             "--stems", "--output", str(tmp_path / "a.m4a")])
+    # The main output was written and the absence of stems is a warning,
+    # never a failure exit.
+    assert (tmp_path / "a.m4a").read_bytes() == b"A"
+    assert "no stems" in capsys.readouterr().err