sonilo-cli 0.5.0__tar.gz → 0.8.0__tar.gz

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonilo-cli
-Version: 0.5.0
+Version: 0.8.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.8,>=0.7.0
+Requires-Dist: sonilo<0.12,>=0.11.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -52,8 +52,8 @@ or pass `--api-key sk-...` on any command.
 ### Notes
 
 - `text-to-music` / `video-to-music` stream a short `.m4a` by default. `--format wav`,
-  `--preserve-speech`, and its legacy alias `--isolate-vocals` each switch to the async
-  submit-and-poll path.
+  `--preserve-speech`, `--variants` above 1, 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`.
 
@@ -88,6 +88,24 @@ The two segment shapes are **not** interchangeable:
 - `text-to-sfx` takes no segments (its output is a single effect, not a timeline).
 - `video-to-video-music` takes no segments either — the API scores the whole clip in one pass.
 
+### Variants
+
+`--variants N` (1-10, default 1) generates that many distinct variants in one request instead of
+one, on `text-to-music`, `video-to-music`, `video-to-video-music`, `video-to-sound`, and
+`video-to-video-sound`. Cost scales linearly — `--variants 3` costs three times a single-variant
+request — and values above 1 are never covered by the free trial.
+
+    sonilo text-to-music --prompt "warm lo-fi piano" --duration 30 --variants 3 --output take.m4a
+    # writes take.0.m4a, take.1.m4a, take.2.m4a
+
+- `--variants` above 1 forces the async submit-and-poll path (see [Notes](#notes) above).
+- With `--variants` unset (or `1`), a command writes the single `--output` file exactly as before
+  this flag existed. Above 1, it instead writes one file per variant, with the variant index
+  spliced before the extension: `take.m4a` becomes `take.0.m4a`, `take.1.m4a`, etc. — the same
+  naming `--stem` and dubbing's per-language output already use.
+- On `video-to-sound` / `video-to-video-sound`, `--stem` is applied per variant too, e.g.
+  `take.0.music.m4a`.
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -108,6 +126,8 @@ file (default `output.mp4`):
   [Segments](#segments).
 - Neither command exposes `--format`: the output is a video, not an audio file.
 - For music *and* effects in one call, use `video-to-video-sound` below.
+- `video-to-video-music` also takes `--variants` — see [Variants](#variants) above.
+  `video-to-video-sfx` does not.
 
 ### Combined soundtracks
 
@@ -132,6 +152,7 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
   the combined output, so you can re-balance the mix yourself. With `--output soundtrack.wav`, the
   music stem lands at `soundtrack.music.m4a`. `music_processed` exists only when `--preserve-speech`
   or ducking altered the music bed.
+- Both also take `--variants` — see [Variants](#variants) above.
 
 ### Dubbing
 

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/README.md

@@ -36,8 +36,8 @@ or pass `--api-key sk-...` on any command.
 ### Notes
 
 - `text-to-music` / `video-to-music` stream a short `.m4a` by default. `--format wav`,
-  `--preserve-speech`, and its legacy alias `--isolate-vocals` each switch to the async
-  submit-and-poll path.
+  `--preserve-speech`, `--variants` above 1, 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`.
 
@@ -72,6 +72,24 @@ The two segment shapes are **not** interchangeable:
 - `text-to-sfx` takes no segments (its output is a single effect, not a timeline).
 - `video-to-video-music` takes no segments either — the API scores the whole clip in one pass.
 
+### Variants
+
+`--variants N` (1-10, default 1) generates that many distinct variants in one request instead of
+one, on `text-to-music`, `video-to-music`, `video-to-video-music`, `video-to-sound`, and
+`video-to-video-sound`. Cost scales linearly — `--variants 3` costs three times a single-variant
+request — and values above 1 are never covered by the free trial.
+
+    sonilo text-to-music --prompt "warm lo-fi piano" --duration 30 --variants 3 --output take.m4a
+    # writes take.0.m4a, take.1.m4a, take.2.m4a
+
+- `--variants` above 1 forces the async submit-and-poll path (see [Notes](#notes) above).
+- With `--variants` unset (or `1`), a command writes the single `--output` file exactly as before
+  this flag existed. Above 1, it instead writes one file per variant, with the variant index
+  spliced before the extension: `take.m4a` becomes `take.0.m4a`, `take.1.m4a`, etc. — the same
+  naming `--stem` and dubbing's per-language output already use.
+- On `video-to-sound` / `video-to-video-sound`, `--stem` is applied per variant too, e.g.
+  `take.0.music.m4a`.
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -92,6 +110,8 @@ file (default `output.mp4`):
   [Segments](#segments).
 - Neither command exposes `--format`: the output is a video, not an audio file.
 - For music *and* effects in one call, use `video-to-video-sound` below.
+- `video-to-video-music` also takes `--variants` — see [Variants](#variants) above.
+  `video-to-video-sfx` does not.
 
 ### Combined soundtracks
 
@@ -116,6 +136,7 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
   the combined output, so you can re-balance the mix yourself. With `--output soundtrack.wav`, the
   music stem lands at `soundtrack.music.m4a`. `music_processed` exists only when `--preserve-speech`
   or ducking altered the music bed.
+- Both also take `--variants` — see [Variants](#variants) above.
 
 ### Dubbing
 

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.5.0"
+version = "0.8.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.7.0,<0.8"]
+dependencies = ["sonilo>=0.11.0,<0.12"]
 keywords = ["sonilo", "cli", "music", "sfx", "text-to-music", "video-to-music", "ai"]
 
 [project.urls]

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/src/sonilo_cli/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.5.0"
+__version__ = "0.8.0"
 
 __all__ = ["__version__"]

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/src/sonilo_cli/__main__.py

@@ -221,9 +221,33 @@ def _music_output(args: argparse.Namespace, fmt: str) -> str:
     return args.output if args.output is not None else f"output.{fmt}"
 
 
+def _variant_path(out: str, index: int) -> str:
+    """Turn one --output value into a per-variant path: `clip.mp4` + `1`
+    becomes `clip.1.mp4`. Same transform as _stem_path/_language_path, used
+    whenever --variants > 1 fans a single --output into one file per variant."""
+    base = Path(out)
+    return str(base.with_name(f"{base.stem}.{index}{base.suffix}"))
+
+
+def _save_music_variants(result: Any, out: str) -> None:
+    """Save every entry of an async music result's `audio` list. With
+    --variants unset (or 1) this is a single file at `out`, byte-identical
+    to the pre-variants behaviour; with --variants > 1 it fans out to
+    `out.0.ext`, `out.1.ext`, etc."""
+    count = len(result.audio or [])
+    if count <= 1:
+        path = result.save(out)
+        _wrote(path, path.stat().st_size)
+        return
+    for index in range(count):
+        path = result.save(_variant_path(out, index), index=index)
+        _wrote(path, path.stat().st_size)
+
+
 def cmd_text_to_music(client: Sonilo, args: argparse.Namespace) -> None:
     fmt = args.format
-    use_async = args.use_async or fmt == "wav"
+    multi = args.variants is not None and args.variants > 1
+    use_async = args.use_async or fmt != "m4a" or multi
     out = _music_output(args, fmt)
     segments = _segments(args)
     if use_async:
@@ -231,10 +255,10 @@ def cmd_text_to_music(client: Sonilo, args: argparse.Namespace) -> None:
             prompt=args.prompt,
             duration=args.duration,
             segments=segments,
-            output_format="wav" if fmt == "wav" else None,
+            output_format=fmt if fmt != "m4a" else None,
+            variants_num=args.variants,
         )
-        path = result.save(out)
-        _wrote(path, path.stat().st_size)
+        _save_music_variants(result, out)
     else:
         track = client.text_to_music.generate(
             prompt=args.prompt, duration=args.duration, segments=segments
@@ -245,7 +269,10 @@ def cmd_text_to_music(client: Sonilo, args: argparse.Namespace) -> None:
 
 def cmd_video_to_music(client: Sonilo, args: argparse.Namespace) -> None:
     fmt = args.format
-    use_async = args.use_async or fmt == "wav" or args.isolate_vocals or args.preserve_speech
+    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
+    )
     out = _music_output(args, fmt)
     segments = _segments(args)
     if use_async:
@@ -256,10 +283,10 @@ def cmd_video_to_music(client: Sonilo, args: argparse.Namespace) -> None:
             segments=segments,
             isolate_vocals=args.isolate_vocals or None,
             preserve_speech=args.preserve_speech or None,
-            output_format="wav" if fmt == "wav" else None,
+            output_format=fmt if fmt != "m4a" else None,
+            variants_num=args.variants,
         )
-        path = result.save(out)
-        _wrote(path, path.stat().st_size)
+        _save_music_variants(result, out)
     else:
         track = client.video_to_music.generate(
             video=args.video, video_url=args.video_url, prompt=args.prompt,
@@ -304,6 +331,13 @@ def _stem_path(out: str, stem: str, media: Any) -> str:
 
 def _run_sound(client: Sonilo, args: argparse.Namespace, resource: Any, default_ext: str) -> None:
     out = args.output if args.output is not None else f"output.{default_ext}"
+    # video-to-video-sound only. Its parser is the only one that defines the
+    # flag, and video_to_sound.generate() does not accept the keyword at all,
+    # so it has to be omitted here rather than forwarded as None — the same
+    # split the SDK enforces by never passing it from the audio resource.
+    extra: Dict[str, Any] = {}
+    if getattr(args, "keep_original_sound", False):
+        extra["keep_original_sound"] = True
     result = resource.generate(
         video=args.video,
         video_url=args.video_url,
@@ -312,13 +346,26 @@ def _run_sound(client: Sonilo, args: argparse.Namespace, resource: Any, default_
         segments=_segments(args),
         preserve_speech=True if args.preserve_speech else None,
         ducking=False if args.no_ducking else None,
+        variants_num=args.variants,
+        **extra,
     )
-    path = result.save(out)
-    _wrote(path, path.stat().st_size)
-    for stem in args.stems or []:
-        stem_path = _stem_path(out, stem, getattr(result, stem, None))
-        saved = result.save_stem(stem_path, which=stem)
-        _wrote(saved, saved.stat().st_size)
+    multi = args.variants is not None and args.variants > 1 and len(result.outputs) > 1
+    if not multi:
+        path = result.save(out)
+        _wrote(path, path.stat().st_size)
+        for stem in args.stems or []:
+            stem_path = _stem_path(out, stem, getattr(result, stem, None))
+            saved = result.save_stem(stem_path, which=stem)
+            _wrote(saved, saved.stat().st_size)
+        return
+    for index, entry in enumerate(result.outputs):
+        variant_out = _variant_path(out, index)
+        path = result.save(variant_out, index=index)
+        _wrote(path, path.stat().st_size)
+        for stem in args.stems or []:
+            stem_path = _stem_path(variant_out, stem, getattr(entry, stem, None))
+            saved = result.save_stem(stem_path, which=stem, index=index)
+            _wrote(saved, saved.stat().st_size)
 
 
 def cmd_video_to_sound(client: Sonilo, args: argparse.Namespace) -> None:
@@ -330,14 +377,22 @@ def cmd_video_to_video_sound(client: Sonilo, args: argparse.Namespace) -> None:
 
 
 def _run_video(args: argparse.Namespace, resource: Any, **params: Any) -> None:
-    """Run one of the video-returning endpoints and save the single result.
+    """Run one of the video-returning endpoints and save the result.
 
-    These return the source picture with the generated audio muxed in — one
-    file, no stems — so the default destination is an `.mp4`, matching
-    video-to-video-sound.
+    These return the source picture with the generated audio muxed in — no
+    stems — so the default destination is an `.mp4`, matching
+    video-to-video-sound. A `variants_num` in `params` fans out into one
+    indexed file per variant when it is greater than 1; otherwise this stays
+    the single-file save from before variants existed.
     """
     out = args.output if args.output is not None else "output.mp4"
     result = resource.generate(video=args.video, video_url=args.video_url, **params)
+    variants = params.get("variants_num")
+    if variants is not None and variants > 1 and len(result.videos) > 1:
+        for index in range(len(result.videos)):
+            path = result.save(_variant_path(out, index), index=index)
+            _wrote(path, path.stat().st_size)
+        return
     path = result.save(out)
     _wrote(path, path.stat().st_size)
 
@@ -348,9 +403,15 @@ def cmd_video_to_video_music(client: Sonilo, args: argparse.Namespace) -> None:
         client.video_to_video_music,
         prompt=args.prompt,
         # Unset flags forward None, not False, so the server default stands —
-        # same reasoning as --no-ducking on the sound commands.
+        # same reasoning as --no-ducking on the sound commands. The two
+        # defaults run opposite ways: ducking is default-ON server-side and
+        # keep_original_sound default-OFF, so each is only ever sent to change
+        # the default, never to restate it.
+        keep_original_sound=True if args.keep_original_sound else None,
+        ducking=False if args.no_ducking else None,
         preserve_speech=True if args.preserve_speech else None,
         isolate_vocals=True if args.isolate_vocals else None,
+        variants_num=args.variants,
     )
 
 
@@ -459,6 +520,17 @@ def _add_segments(parser: argparse.ArgumentParser, shape: _SegmentShape) -> None
     parser.set_defaults(segments_shape=shape)
 
 
+def _add_variants(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--variants", type=int, default=None,
+        help="How many distinct variants to generate in one request, 1-10 "
+             "(default 1). Cost scales linearly, and values above 1 are never "
+             "covered by the free trial. Values above 1 force async and write "
+             "one indexed file per variant (output.0.ext, output.1.ext, ...) "
+             "instead of a single --output.",
+    )
+
+
 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__)
@@ -480,10 +552,11 @@ def build_parser() -> argparse.ArgumentParser:
     p_t2m.add_argument("--duration", type=int, required=True, help="Track length in seconds.")
     _add_segments(p_t2m, MUSIC_SHAPE)
     p_t2m.add_argument("--output", default=None, help="Where to save the audio.")
-    p_t2m.add_argument("--format", choices=["m4a", "wav"], default="m4a",
-                       help="Output container. wav forces async. Default: m4a")
+    p_t2m.add_argument("--format", choices=["m4a", "wav", "mp3"], default="m4a",
+                       help="Output container. Anything but m4a forces async. mp3 is 320 kbps. Default: m4a")
     p_t2m.add_argument("--async", dest="use_async", action="store_true",
                        help="Submit and poll instead of streaming.")
+    _add_variants(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")
@@ -492,8 +565,8 @@ def build_parser() -> argparse.ArgumentParser:
     p_v2m.add_argument("--prompt", default=None, help="Optional creative direction.")
     _add_segments(p_v2m, MUSIC_SHAPE)
     p_v2m.add_argument("--output", default=None, help="Where to save the audio.")
-    p_v2m.add_argument("--format", choices=["m4a", "wav"], default="m4a",
-                       help="Output container. wav forces async.")
+    p_v2m.add_argument("--format", choices=["m4a", "wav", "mp3"], default="m4a",
+                       help="Output container. Anything but m4a forces async. mp3 is 320 kbps.")
     p_v2m.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
                        help="Keep source speech in the mix. Forces async.")
     # The API ORs isolate_vocals into preserve_speech (video_to_music.py:
@@ -504,6 +577,7 @@ def build_parser() -> argparse.ArgumentParser:
                        help="Legacy alias for --preserve-speech. Forces async.")
     p_v2m.add_argument("--async", dest="use_async", action="store_true",
                        help="Submit and poll instead of streaming.")
+    _add_variants(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")
@@ -542,6 +616,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_v2sd.add_argument("--stem", dest="stems", action="append", choices=_SOUND_STEMS,
                         default=None, help="Also save an individual stem. Repeatable.")
     p_v2sd.add_argument("--output", default=None, help="Where to save the combined audio.")
+    _add_variants(p_v2sd)
     p_v2sd.set_defaults(func=cmd_video_to_sound)
 
     p_v2vm = sub.add_parser(
@@ -550,8 +625,18 @@ def build_parser() -> argparse.ArgumentParser:
     _add_global(p_v2vm)
     _add_video_source(p_v2vm)
     p_v2vm.add_argument("--prompt", default=None, help="Optional creative direction.")
+    p_v2vm.add_argument("--keep-original-sound", dest="keep_original_sound",
+                        action="store_true",
+                        help="Keep the source video's whole original audio, with the "
+                             "generated music under it. Off by default, so by default "
+                             "the result's audio is the generated music alone. "
+                             "Supersedes --preserve-speech.")
+    p_v2vm.add_argument("--no-ducking", dest="no_ducking", action="store_true",
+                        help="Combine the voice and the music as a static mix instead "
+                             "of a dynamic duck. No effect without "
+                             "--keep-original-sound or --preserve-speech.")
     p_v2vm.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
-                        help="Keep source speech in the mix.")
+                        help="Keep only the source's isolated speech in the mix.")
     # Same aliasing as video-to-music, and here the endpoint collapses the two
     # into a single boolean before it reaches the model (video_to_video.py:
     # `keep_speech = bool(preserve_speech) or bool(isolate_vocals)`), with no
@@ -559,6 +644,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_v2vm.add_argument("--isolate-vocals", dest="isolate_vocals", action="store_true",
                         help="Legacy alias for --preserve-speech; no separate stem.")
     p_v2vm.add_argument("--output", default=None, help="Where to save the scored video.")
+    _add_variants(p_v2vm)
     p_v2vm.set_defaults(func=cmd_video_to_video_music)
 
     p_v2vfx = sub.add_parser(
@@ -581,13 +667,23 @@ def build_parser() -> argparse.ArgumentParser:
     p_v2vsd.add_argument("--sfx-prompt", dest="sfx_prompt", default=None,
                          help="Optional creative direction for the sound effects.")
     _add_segments(p_v2vsd, SFX_SHAPE)
+    p_v2vsd.add_argument("--keep-original-sound", dest="keep_original_sound",
+                         action="store_true",
+                         help="Keep the source video's whole original audio, with the "
+                              "generated music and effects under it. Off by default, so "
+                              "by default the result's audio is the generated audio "
+                              "alone and there is no music_processed stem. Supersedes "
+                              "--preserve-speech. This command only.")
     p_v2vsd.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
-                         help="Keep source speech in the mix.")
+                         help="Keep only the source's isolated speech in the mix.")
     p_v2vsd.add_argument("--no-ducking", dest="no_ducking", action="store_true",
-                         help="Disable automatic ducking (on by default server-side).")
+                         help="Combine the voice and the generated bed as a static mix "
+                              "instead of a dynamic duck. No effect without "
+                              "--keep-original-sound or --preserve-speech.")
     p_v2vsd.add_argument("--stem", dest="stems", action="append", choices=_SOUND_STEMS,
                          default=None, help="Also save an individual stem. Repeatable.")
     p_v2vsd.add_argument("--output", default=None, help="Where to save the combined video.")
+    _add_variants(p_v2vsd)
     p_v2vsd.set_defaults(func=cmd_video_to_video_sound)
 
     p_dub = sub.add_parser("dubbing", help="Dub a video into other languages")

{sonilo_cli-0.5.0 → sonilo_cli-0.8.0}/tests/test_cli.py

@@ -161,6 +161,39 @@ def test_text_to_music_wav_forces_async(tmp_path):
     assert out.read_bytes() == b"RIF"
 
 
+@respx.mock
+def test_text_to_music_variants_forces_async_and_writes_indexed_files(tmp_path):
+    submit = respx.post(f"{BASE}/v1/text-to-music").mock(
+        return_value=httpx.Response(200, json={"task_id": "tv1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/tv1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "tv1", "type": "text_to_music", "status": "succeeded",
+            "variants_num": 2,
+            "audio": [
+                {"stream_index": 0, "url": "https://r2.example.com/tv1.0.m4a"},
+                {"stream_index": 1, "url": "https://r2.example.com/tv1.1.m4a"},
+            ],
+        })
+    )
+    respx.get("https://r2.example.com/tv1.0.m4a").mock(
+        return_value=httpx.Response(200, content=b"A0")
+    )
+    respx.get("https://r2.example.com/tv1.1.m4a").mock(
+        return_value=httpx.Response(200, content=b"A1")
+    )
+    out = tmp_path / "take.m4a"
+    run(["text-to-music", "--prompt", "lofi", "--duration", "10",
+         "--variants", "2", "--output", str(out)])
+    # --variants > 1 must force the async submit-and-poll path, same as --format wav.
+    assert submit.called
+    body = submit.calls.last.request.content.decode()
+    assert "variants_num=2" in body
+    assert (tmp_path / "take.0.m4a").read_bytes() == b"A0"
+    assert (tmp_path / "take.1.m4a").read_bytes() == b"A1"
+    assert not out.exists()
+
+
 def test_video_to_music_requires_a_video_source():
     with pytest.raises(SystemExit) as exc:
         run(["video-to-music", "--prompt", "x"])  # neither --video nor --video-url
@@ -394,6 +427,54 @@ def test_video_to_sound_preserve_speech_flag_sets_true(tmp_path):
     assert "preserve_speech=true" in body
 
 
+@respx.mock
+def test_video_to_sound_variants_writes_indexed_files_and_stems(tmp_path):
+    respx.post(f"{BASE}/v1/video-to-sound").mock(
+        return_value=httpx.Response(200, json={"task_id": "sv1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/sv1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "sv1", "type": "video_to_sound", "status": "succeeded",
+            "variants_num": 2,
+            "output_url": "https://r2.example.com/sv1.0.wav",
+            "output_type": "audio", "output_bytes": 5,
+            "music": {"url": "https://r2.example.com/sv1.0.music.m4a"},
+            "sfx": {"url": "https://r2.example.com/sv1.0.sfx.wav"},
+            "outputs": [
+                {
+                    "variant_index": 0,
+                    "output_url": "https://r2.example.com/sv1.0.wav",
+                    "output_type": "audio", "output_bytes": 5,
+                    "music": {"url": "https://r2.example.com/sv1.0.music.m4a"},
+                    "sfx": {"url": "https://r2.example.com/sv1.0.sfx.wav"},
+                },
+                {
+                    "variant_index": 1,
+                    "output_url": "https://r2.example.com/sv1.1.wav",
+                    "output_type": "audio", "output_bytes": 6,
+                    "music": {"url": "https://r2.example.com/sv1.1.music.m4a"},
+                    "sfx": {"url": "https://r2.example.com/sv1.1.sfx.wav"},
+                },
+            ],
+        })
+    )
+    for url, content in [
+        ("https://r2.example.com/sv1.0.wav", b"O0"),
+        ("https://r2.example.com/sv1.1.wav", b"O1"),
+        ("https://r2.example.com/sv1.0.music.m4a", b"M0"),
+        ("https://r2.example.com/sv1.1.music.m4a", b"M1"),
+    ]:
+        respx.get(url).mock(return_value=httpx.Response(200, content=content))
+    out = tmp_path / "s.wav"
+    run(["video-to-sound", "--video-url", "http://x/y.mp4", "--variants", "2",
+         "--output", str(out), "--stem", "music"])
+    assert (tmp_path / "s.0.wav").read_bytes() == b"O0"
+    assert (tmp_path / "s.1.wav").read_bytes() == b"O1"
+    assert (tmp_path / "s.0.music.m4a").read_bytes() == b"M0"
+    assert (tmp_path / "s.1.music.m4a").read_bytes() == b"M1"
+    assert not out.exists()
+
+
 @respx.mock
 def test_video_to_video_sound_defaults_to_mp4(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
@@ -875,6 +956,38 @@ def test_video_to_video_music_rejects_both_sources():
     assert exc.value.code == 1
 
 
+@respx.mock
+def test_video_to_video_music_variants_writes_indexed_files(tmp_path):
+    route = respx.post(f"{BASE}/v1/video-to-video-music").mock(
+        return_value=httpx.Response(202, json={"task_id": "vm5", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/vm5").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "vm5", "type": "video_to_video_music", "status": "succeeded",
+            "variants_num": 2,
+            "videos": [
+                {"url": "https://r2.example.com/vm5.0.mp4"},
+                {"url": "https://r2.example.com/vm5.1.mp4"},
+            ],
+            "video": {"url": "https://r2.example.com/vm5.0.mp4"},
+        })
+    )
+    respx.get("https://r2.example.com/vm5.0.mp4").mock(
+        return_value=httpx.Response(200, content=b"V0")
+    )
+    respx.get("https://r2.example.com/vm5.1.mp4").mock(
+        return_value=httpx.Response(200, content=b"V1")
+    )
+    out = tmp_path / "scored.mp4"
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--variants", "2", "--output", str(out)])
+    assert (tmp_path / "scored.0.mp4").read_bytes() == b"V0"
+    assert (tmp_path / "scored.1.mp4").read_bytes() == b"V1"
+    assert not out.exists()
+    body = route.calls.last.request.content.decode()
+    assert "variants_num=2" in body
+
+
 def test_video_to_video_music_rejects_segments(capsys):
     """The endpoint scores the whole clip in one pass — the SDK resource takes
     no `segments`, so the CLI must not offer the flag."""