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

sonilo_cli-0.13.0/README.md → sonilo_cli-0.14.0/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.5
+Name: sonilo-cli
+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
+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.16,>=0.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # sonilo-cli
 
 Command-line interface for the [Sonilo API](https://github.com/sonilo-ai/sonilo-python) — generate music and sound effects from text or video.
@@ -92,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`.
 
@@ -157,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`

sonilo_cli-0.13.0/PKG-INFO → sonilo_cli-0.14.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.5
-Name: sonilo-cli
-Version: 0.13.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
-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.15,>=0.14.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == 'dev'
-Requires-Dist: respx>=0.21; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # sonilo-cli
 
 Command-line interface for the [Sonilo API](https://github.com/sonilo-ai/sonilo-python) — generate music and sound effects from text or video.
@@ -108,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`.
 
@@ -173,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`

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

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.13.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.14.0,<0.15"]
+dependencies = ["sonilo>=0.15.0,<0.16"]
 keywords = ["sonilo", "cli", "music", "sfx", "text-to-music", "video-to-music", "ai"]
 
 [project.urls]

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

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

{sonilo_cli-0.13.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.
@@ -675,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__)
@@ -728,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")
@@ -750,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")

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

@@ -1435,3 +1435,175 @@ def test_video_analysis_requires_a_video_source(capsys):
     # 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